docs: document llm helpers

src/llm/providers/anthropic.test.ts

@@ -1,3 +1,4 @@
+// Anthropic provider tests cover stream events, tools, and message mapping.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { SYSTEM_PROMPT_CACHE_BOUNDARY } from "../../agents/system-prompt-cache-boundary.js";
 import type { Context, Model } from "../types.js";

src/llm/providers/anthropic.ts

@@ -1,3 +1,4 @@
+// Anthropic provider adapts Anthropic streams and tool calls for the runtime.
 import Anthropic from "@anthropic-ai/sdk";
 import type {
   CacheControlEphemeral,

src/llm/providers/azure-deployment-map.test.ts

@@ -1,3 +1,4 @@
+// Azure deployment map tests cover model-to-deployment resolution.
 import { describe, expect, it } from "vitest";
 import {
   parseAzureDeploymentNameMap,

src/llm/providers/azure-openai-responses.ts

@@ -1,3 +1,4 @@
+// Azure OpenAI Responses provider adapts Azure deployments to Responses API streams.
 import { AzureOpenAI } from "openai";
 import type { ResponseCreateParamsStreaming } from "openai/resources/responses/responses.js";
 import { getEnvApiKey } from "../env-api-keys.js";

src/llm/providers/cloudflare.ts

@@ -1,3 +1,4 @@
+// Cloudflare provider metadata describes Cloudflare-hosted model capabilities.
 import type { Model } from "../types.js";
 
 /** Workers AI direct endpoint. */

src/llm/providers/github-copilot-headers.ts

@@ -1,3 +1,4 @@
+// GitHub Copilot header helpers build request headers for Copilot-backed providers.
 import type { Message } from "../types.js";
 
 // Copilot expects X-Initiator to indicate whether the request is user-initiated

src/llm/providers/google-shared.convert.test.ts

@@ -1,3 +1,4 @@
+// Google shared conversion tests cover runtime-to-Google payload conversion.
 import { describe, expect, it } from "vitest";
 import type { Context, Tool } from "../types.js";
 import { convertMessages, convertTools } from "./google-shared.js";

src/llm/providers/google-shared.test-helpers.ts

@@ -1,3 +1,4 @@
+// Google provider test helpers assert converted message and stream payloads.
 import { expect } from "vitest";
 import type { Model } from "../types.js";
 

src/llm/providers/google-shared.test.ts

@@ -1,3 +1,4 @@
+// Google shared provider tests cover response conversion and finish reasons.
 import { FinishReason, type GenerateContentResponse } from "@google/genai";
 import { describe, expect, it } from "vitest";
 import type { AssistantMessage, Model } from "../types.js";

src/llm/providers/google-vertex.ts

@@ -1,3 +1,4 @@
+// Google Vertex provider wires Google shared streaming through Vertex credentials.
 import {
   type GenerateContentParameters,
   GoogleGenAI,

src/llm/providers/google.ts

@@ -1,3 +1,4 @@
+// Google provider adapts Gemini streams and tools to the agent runtime.
 import { type GenerateContentParameters, GoogleGenAI } from "@google/genai";
 import { getEnvApiKey } from "../env-api-keys.js";
 import type { Context, Model, SimpleStreamOptions, StreamFunction } from "../types.js";

src/llm/providers/mistral.test.ts

@@ -1,3 +1,4 @@
+// Mistral provider tests cover request mapping and stream conversion.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { Context, Model } from "../types.js";
 

src/llm/providers/mistral.ts

@@ -1,3 +1,4 @@
+// Mistral provider adapts Mistral streams and tool calls to the runtime.
 import { Mistral } from "@mistralai/mistralai";
 import type {
   ChatCompletionStreamRequest,

src/llm/providers/openai-chatgpt-responses.test.ts

@@ -1,3 +1,4 @@
+// ChatGPT Responses provider tests cover stream handling and timeout behavior.
 import { MAX_TIMER_TIMEOUT_MS } from "@openclaw/normalization-core/number-coercion";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { Context, Model } from "../types.js";

src/llm/providers/openai-chatgpt-responses.ts

@@ -1,3 +1,4 @@
+// OpenAI ChatGPT Responses provider handles ChatGPT-authenticated response streams.
 import type * as NodeOs from "node:os";
 import type {
   Tool as OpenAITool,

src/llm/providers/openai-compatible-auth.test.ts

@@ -1,3 +1,4 @@
+// OpenAI-compatible auth tests cover API key and base URL normalization.
 import { afterEach, describe, expect, it } from "vitest";
 import type { Context, Model } from "../types.js";
 import { streamOpenAICompletions } from "./openai-completions.js";

src/llm/providers/openai-completions.test.ts

@@ -1,3 +1,4 @@
+// OpenAI completions tests cover chat completion stream adaptation.
 import type { ChatCompletionChunk } from "openai/resources/chat/completions.js";
 import { describe, expect, it, vi } from "vitest";
 import { SYSTEM_PROMPT_CACHE_BOUNDARY } from "../../agents/system-prompt-cache-boundary.js";

src/llm/providers/openai-completions.ts

@@ -1,3 +1,4 @@
+// OpenAI completions provider adapts chat completions to the agent runtime.
 import OpenAI from "openai";
 import type {
   ChatCompletionAssistantMessageParam,

src/llm/providers/openai-responses-shared.test.ts

@@ -1,3 +1,4 @@
+// OpenAI Responses shared tests cover tool conversion and response item mapping.
 import type { Tool as OpenAIResponsesTool } from "openai/resources/responses/responses.js";
 import { describe, expect, it } from "vitest";
 import type { Context, Model, Tool } from "../types.js";

src/llm/providers/openai-responses-shared.ts

@@ -1,3 +1,4 @@
+// OpenAI Responses shared helpers map runtime messages, tools, and stream events.
 import type OpenAI from "openai";
 import type {
   ResponseCreateParamsStreaming,

src/llm/providers/openai-responses-tools.ts

@@ -1,3 +1,4 @@
+// OpenAI Responses tool helpers convert runtime tools to Responses API schemas.
 import { createHash } from "node:crypto";
 import type { Tool as OpenAITool } from "openai/resources/responses/responses.js";
 import { resolveOpenAIStrictToolSetting } from "../../agents/openai-strict-tool-setting.js";

src/llm/providers/openai-responses.ts

@@ -1,3 +1,4 @@
+// OpenAI Responses provider adapts OpenAI response streams to the agent runtime.
 import OpenAI from "openai";
 import type { ResponseCreateParamsStreaming } from "openai/resources/responses/responses.js";
 import { getEnvApiKey } from "../env-api-keys.js";

src/llm/providers/register-builtins.ts

@@ -1,3 +1,4 @@
+// Built-in provider registration installs the bundled provider factories.
 import { registerApiProvider, unregisterApiProviders } from "../api-registry.js";
 import type {
   Api,

src/llm/providers/simple-options.ts

@@ -1,3 +1,4 @@
+// Simple provider option helpers normalize lightweight provider configuration.
 import type {
   Model,
   SimpleStreamOptions,

src/llm/providers/stream-wrappers/anthropic-cache-control-payload.test.ts

@@ -1,3 +1,4 @@
+// Anthropic cache-control payload tests cover cache metadata preservation.
 import { describe, expect, it } from "vitest";
 import { applyAnthropicEphemeralCacheControlMarkers } from "./anthropic-cache-control-payload.js";
 

src/llm/providers/stream-wrappers/anthropic-family-cache-semantics.ts

@@ -1,3 +1,4 @@
+// Anthropic-family cache wrapper preserves cache-control semantics in tool payloads.
 import {
   normalizeLowercaseStringOrEmpty,
   normalizeOptionalLowercaseString,

src/llm/providers/stream-wrappers/anthropic-family-tool-payload-compat.ts

@@ -1,3 +1,4 @@
+// Anthropic-family tool payload compatibility wraps provider tool payload shapes.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import type { StreamFn } from "../../../agents/runtime/index.js";
 import { streamSimple } from "../../stream.js";

src/llm/providers/stream-wrappers/google.test.ts

@@ -1,3 +1,4 @@
+// Google stream wrapper tests cover Gemini stream payload normalization.
 import { describe, expect, it } from "vitest";
 import { sanitizeGoogleThinkingPayload } from "./google.js";
 

src/llm/providers/stream-wrappers/minimax.test.ts

@@ -1,3 +1,4 @@
+// MiniMax stream wrapper tests cover streamed text and reasoning conversion.
 import type { StreamFn } from "openclaw/plugin-sdk/agent-core";
 import type { Context, Model } from "openclaw/plugin-sdk/llm";
 import { describe, expect, it } from "vitest";

src/llm/providers/stream-wrappers/minimax.ts

@@ -1,3 +1,4 @@
+// MiniMax stream wrapper normalizes MiniMax streamed text and reasoning output.
 import type { StreamFn } from "../../../agents/runtime/index.js";
 import { streamSimple } from "../../stream.js";
 

src/llm/providers/stream-wrappers/moonshot-thinking.ts

@@ -1,3 +1,4 @@
+// Moonshot thinking wrapper normalizes reasoning output from Moonshot streams.
 import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";
 import type { StreamFn } from "../../../agents/runtime/index.js";
 import type { ThinkLevel } from "../../../auto-reply/thinking.js";

src/llm/providers/stream-wrappers/moonshot.ts

@@ -1,3 +1,4 @@
+// Moonshot stream wrapper normalizes Moonshot streamed text and reasoning output.
 import type { StreamFn } from "../../../agents/runtime/index.js";
 import type { ThinkLevel } from "../../../auto-reply/thinking.js";
 import { streamSimple } from "../../stream.js";

src/llm/providers/stream-wrappers/openai.test.ts

@@ -1,3 +1,4 @@
+// OpenAI stream wrapper tests cover streamed text, tools, and reasoning fields.
 import type { StreamFn } from "openclaw/plugin-sdk/agent-core";
 import type { Model } from "openclaw/plugin-sdk/llm";
 import { createAssistantMessageEventStream } from "openclaw/plugin-sdk/llm";

src/llm/providers/stream-wrappers/openai.ts

@@ -1,3 +1,4 @@
+// OpenAI stream wrapper normalizes OpenAI-compatible streamed tool and text events.
 import {
   normalizeOptionalLowercaseString,
   readStringValue,

src/llm/providers/stream-wrappers/proxy.test.ts

@@ -1,3 +1,4 @@
+// Proxy stream wrapper tests cover wrapper selection and provider passthrough.
 import type { StreamFn } from "openclaw/plugin-sdk/agent-core";
 import type { Context, Model } from "openclaw/plugin-sdk/llm";
 import { createAssistantMessageEventStream } from "openclaw/plugin-sdk/llm";

src/llm/providers/stream-wrappers/proxy.ts

@@ -1,3 +1,4 @@
+// Proxy stream wrapper applies provider-specific wrappers around base stream functions.
 import {
   normalizeOptionalLowercaseString,
   readStringValue,

src/llm/providers/stream-wrappers/reasoning-effort-utils.test.ts

@@ -1,3 +1,4 @@
+// Reasoning effort utility tests cover provider reasoning effort normalization.
 import { describe, expect, it } from "vitest";
 import { mapThinkingLevelToReasoningEffort } from "./reasoning-effort-utils.js";
 

src/llm/providers/stream-wrappers/reasoning-effort-utils.ts

@@ -1,3 +1,4 @@
+// Reasoning effort utilities map provider thinking controls to runtime levels.
 import type { ThinkLevel } from "../../../auto-reply/thinking.js";
 
 /** Reasoning effort values accepted by OpenAI-compatible providers. */

src/llm/providers/stream-wrappers/stream-payload-utils.ts

@@ -1,3 +1,4 @@
+// Stream payload utilities normalize provider stream payload fields for wrappers.
 import type { StreamFn } from "../../../agents/runtime/index.js";
 
 /** Wraps a stream function and lets callers mutate outgoing provider payload objects. */

src/llm/providers/stream-wrappers/zai.ts

@@ -1,3 +1,4 @@
+// Z.ai stream wrapper normalizes Z.ai provider stream chunks.
 import type { StreamFn } from "../../../agents/runtime/index.js";
 import { streamSimple } from "../../stream.js";
 import { streamWithPayloadPatch } from "./stream-payload-utils.js";

src/llm/providers/transform-messages.ts

@@ -1,3 +1,4 @@
+// Provider message transform helpers convert runtime messages to provider payloads.
 import type {
   Api,
   AssistantMessage,

src/llm/utils/json-parse.test.ts

@@ -1,3 +1,4 @@
+// JSON parse tests cover tolerant parsing of partial model JSON output.
 import { describe, expect, it } from "vitest";
 import { parseJsonWithRepair, parseStreamingJson, repairJson } from "./json-parse.js";
 

src/llm/utils/json-parse.ts

@@ -1,3 +1,4 @@
+// JSON parse helpers recover structured values from partial model output.
 import { parse as partialParse } from "partial-json";
 
 const VALID_JSON_ESCAPES = new Set(['"', "\\", "/", "b", "f", "n", "r", "t", "u"]);

src/llm/utils/node-http-proxy.test.ts

@@ -1,3 +1,4 @@
+// Node HTTP proxy tests cover proxy agent creation for provider requests.
 import { afterEach, describe, expect, it, vi } from "vitest";
 import {
   createHttpProxyAgentsForTarget,

src/llm/utils/node-http-proxy.ts

@@ -1,3 +1,4 @@
+// Node HTTP proxy helpers build HTTP(S) agents from proxy settings.
 import type { Agent as HttpAgent } from "node:http";
 import type { Agent as HttpsAgent } from "node:https";
 import {

src/llm/utils/oauth/abort.test.ts

@@ -1,3 +1,4 @@
+// OAuth abort tests cover cancellation of pending OAuth flows.
 import { MAX_TIMER_TIMEOUT_MS } from "@openclaw/normalization-core/number-coercion";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { buildOAuthRequestSignal } from "./abort.js";

src/llm/utils/oauth/anthropic.test.ts

@@ -1,3 +1,4 @@
+// Anthropic OAuth tests cover token exchange and refresh behavior.
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { anthropicOAuthProvider, refreshAnthropicToken } from "./anthropic.js";
 

src/llm/utils/oauth/github-copilot.test.ts

@@ -1,3 +1,4 @@
+// GitHub Copilot OAuth tests cover device flow polling and timeout behavior.
 import { MAX_TIMER_TIMEOUT_MS } from "@openclaw/normalization-core/number-coercion";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { refreshGitHubCopilotToken, testing } from "./github-copilot.js";

src/llm/utils/oauth/openai-chatgpt-jwt.ts

@@ -1,3 +1,4 @@
+// OpenAI ChatGPT JWT helpers inspect auth claims for ChatGPT OAuth sessions.
 const OPENAI_CODEX_AUTH_CLAIM = "https://api.openai.com/auth";
 
 export type OpenAICodexJwtPayload = {

src/llm/utils/oauth/openai-chatgpt.test.ts

@@ -1,3 +1,4 @@
+// OpenAI ChatGPT OAuth tests cover login, token refresh, and auth persistence.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 type LoginOpenAICodexOAuth =

src/llm/utils/oauth/openai-chatgpt.ts

@@ -1,3 +1,4 @@
+// OpenAI ChatGPT OAuth helpers manage ChatGPT OAuth login and token refresh.
 import { loadActivatedBundledPluginPublicSurfaceModuleSync } from "../../../plugin-sdk/facade-runtime.js";
 import type { RuntimeEnv } from "../../../runtime.js";
 import type { WizardPrompter } from "../../../wizard/prompts.js";

src/llm/utils/oauth/pkce.test.ts

@@ -1,3 +1,4 @@
+// PKCE tests cover verifier and challenge generation for OAuth flows.
 import { describe, expect, it } from "vitest";
 import { generateOAuthState, generatePKCE } from "./pkce.js";
 

src/llm/utils/overflow.ts

@@ -1,3 +1,4 @@
+// Overflow helpers classify provider overflow errors and retryable responses.
 import type { AssistantMessage } from "../types.js";
 
 /**