From e6f85453dc3c0570f7ed4bef0062764321e636f8 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 20:07:13 -0400
Subject: [PATCH] docs: document llm helpers

---
 src/llm/providers/anthropic.test.ts                              | 1 +
 src/llm/providers/anthropic.ts                                   | 1 +
 src/llm/providers/azure-deployment-map.test.ts                   | 1 +
 src/llm/providers/azure-openai-responses.ts                      | 1 +
 src/llm/providers/cloudflare.ts                                  | 1 +
 src/llm/providers/github-copilot-headers.ts                      | 1 +
 src/llm/providers/google-shared.convert.test.ts                  | 1 +
 src/llm/providers/google-shared.test-helpers.ts                  | 1 +
 src/llm/providers/google-shared.test.ts                          | 1 +
 src/llm/providers/google-vertex.ts                               | 1 +
 src/llm/providers/google.ts                                      | 1 +
 src/llm/providers/mistral.test.ts                                | 1 +
 src/llm/providers/mistral.ts                                     | 1 +
 src/llm/providers/openai-chatgpt-responses.test.ts               | 1 +
 src/llm/providers/openai-chatgpt-responses.ts                    | 1 +
 src/llm/providers/openai-compatible-auth.test.ts                 | 1 +
 src/llm/providers/openai-completions.test.ts                     | 1 +
 src/llm/providers/openai-completions.ts                          | 1 +
 src/llm/providers/openai-responses-shared.test.ts                | 1 +
 src/llm/providers/openai-responses-shared.ts                     | 1 +
 src/llm/providers/openai-responses-tools.ts                      | 1 +
 src/llm/providers/openai-responses.ts                            | 1 +
 src/llm/providers/register-builtins.ts                           | 1 +
 src/llm/providers/simple-options.ts                              | 1 +
 .../stream-wrappers/anthropic-cache-control-payload.test.ts      | 1 +
 .../stream-wrappers/anthropic-family-cache-semantics.ts          | 1 +
 .../stream-wrappers/anthropic-family-tool-payload-compat.ts      | 1 +
 src/llm/providers/stream-wrappers/google.test.ts                 | 1 +
 src/llm/providers/stream-wrappers/minimax.test.ts                | 1 +
 src/llm/providers/stream-wrappers/minimax.ts                     | 1 +
 src/llm/providers/stream-wrappers/moonshot-thinking.ts           | 1 +
 src/llm/providers/stream-wrappers/moonshot.ts                    | 1 +
 src/llm/providers/stream-wrappers/openai.test.ts                 | 1 +
 src/llm/providers/stream-wrappers/openai.ts                      | 1 +
 src/llm/providers/stream-wrappers/proxy.test.ts                  | 1 +
 src/llm/providers/stream-wrappers/proxy.ts                       | 1 +
 src/llm/providers/stream-wrappers/reasoning-effort-utils.test.ts | 1 +
 src/llm/providers/stream-wrappers/reasoning-effort-utils.ts      | 1 +
 src/llm/providers/stream-wrappers/stream-payload-utils.ts        | 1 +
 src/llm/providers/stream-wrappers/zai.ts                         | 1 +
 src/llm/providers/transform-messages.ts                          | 1 +
 src/llm/utils/json-parse.test.ts                                 | 1 +
 src/llm/utils/json-parse.ts                                      | 1 +
 src/llm/utils/node-http-proxy.test.ts                            | 1 +
 src/llm/utils/node-http-proxy.ts                                 | 1 +
 src/llm/utils/oauth/abort.test.ts                                | 1 +
 src/llm/utils/oauth/anthropic.test.ts                            | 1 +
 src/llm/utils/oauth/github-copilot.test.ts                       | 1 +
 src/llm/utils/oauth/openai-chatgpt-jwt.ts                        | 1 +
 src/llm/utils/oauth/openai-chatgpt.test.ts                       | 1 +
 src/llm/utils/oauth/openai-chatgpt.ts                            | 1 +
 src/llm/utils/oauth/pkce.test.ts                                 | 1 +
 src/llm/utils/overflow.ts                                        | 1 +
 53 files changed, 53 insertions(+)

diff --git a/src/llm/providers/anthropic.test.ts b/src/llm/providers/anthropic.test.ts
index 42ce4b298fc3..3bce15a266c6 100644
--- a/src/llm/providers/anthropic.test.ts
+++ b/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";
diff --git a/src/llm/providers/anthropic.ts b/src/llm/providers/anthropic.ts
index 20da72d5286a..60a5d6c1aae8 100644
--- a/src/llm/providers/anthropic.ts
+++ b/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,
diff --git a/src/llm/providers/azure-deployment-map.test.ts b/src/llm/providers/azure-deployment-map.test.ts
index a96607e37bbe..2816a1091661 100644
--- a/src/llm/providers/azure-deployment-map.test.ts
+++ b/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,
diff --git a/src/llm/providers/azure-openai-responses.ts b/src/llm/providers/azure-openai-responses.ts
index 04127e1568cd..a034e1ec7ec6 100644
--- a/src/llm/providers/azure-openai-responses.ts
+++ b/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";
diff --git a/src/llm/providers/cloudflare.ts b/src/llm/providers/cloudflare.ts
index b4225daa1ead..bc3a541166a2 100644
--- a/src/llm/providers/cloudflare.ts
+++ b/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. */
diff --git a/src/llm/providers/github-copilot-headers.ts b/src/llm/providers/github-copilot-headers.ts
index 3be6e075a06c..7151c5683969 100644
--- a/src/llm/providers/github-copilot-headers.ts
+++ b/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
diff --git a/src/llm/providers/google-shared.convert.test.ts b/src/llm/providers/google-shared.convert.test.ts
index 1e35a38be218..8501598f81b8 100644
--- a/src/llm/providers/google-shared.convert.test.ts
+++ b/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";
diff --git a/src/llm/providers/google-shared.test-helpers.ts b/src/llm/providers/google-shared.test-helpers.ts
index 6ef57f3e78f4..2364755c89e9 100644
--- a/src/llm/providers/google-shared.test-helpers.ts
+++ b/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";
 
diff --git a/src/llm/providers/google-shared.test.ts b/src/llm/providers/google-shared.test.ts
index 98c38d8b8934..acd0c7c47506 100644
--- a/src/llm/providers/google-shared.test.ts
+++ b/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";
diff --git a/src/llm/providers/google-vertex.ts b/src/llm/providers/google-vertex.ts
index 52bfecb49ba4..e9008886dc3c 100644
--- a/src/llm/providers/google-vertex.ts
+++ b/src/llm/providers/google-vertex.ts
@@ -1,3 +1,4 @@
+// Google Vertex provider wires Google shared streaming through Vertex credentials.
 import {
   type GenerateContentParameters,
   GoogleGenAI,
diff --git a/src/llm/providers/google.ts b/src/llm/providers/google.ts
index 4a1f8e37ec5f..3dd6393da7ee 100644
--- a/src/llm/providers/google.ts
+++ b/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";
diff --git a/src/llm/providers/mistral.test.ts b/src/llm/providers/mistral.test.ts
index e80a8743b01d..42226124c311 100644
--- a/src/llm/providers/mistral.test.ts
+++ b/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";
 
diff --git a/src/llm/providers/mistral.ts b/src/llm/providers/mistral.ts
index 135bc1f29923..7f3f2b1ecbab 100644
--- a/src/llm/providers/mistral.ts
+++ b/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,
diff --git a/src/llm/providers/openai-chatgpt-responses.test.ts b/src/llm/providers/openai-chatgpt-responses.test.ts
index bb6986ba0cdf..344801cc2b78 100644
--- a/src/llm/providers/openai-chatgpt-responses.test.ts
+++ b/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";
diff --git a/src/llm/providers/openai-chatgpt-responses.ts b/src/llm/providers/openai-chatgpt-responses.ts
index 77cc3866074e..1aa4a8805569 100644
--- a/src/llm/providers/openai-chatgpt-responses.ts
+++ b/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,
diff --git a/src/llm/providers/openai-compatible-auth.test.ts b/src/llm/providers/openai-compatible-auth.test.ts
index 4b335b0a2363..7a2bb07f6380 100644
--- a/src/llm/providers/openai-compatible-auth.test.ts
+++ b/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";
diff --git a/src/llm/providers/openai-completions.test.ts b/src/llm/providers/openai-completions.test.ts
index 13895a809ecc..3d6f07565b87 100644
--- a/src/llm/providers/openai-completions.test.ts
+++ b/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";
diff --git a/src/llm/providers/openai-completions.ts b/src/llm/providers/openai-completions.ts
index 13a0229ee348..2a829d7b5066 100644
--- a/src/llm/providers/openai-completions.ts
+++ b/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,
diff --git a/src/llm/providers/openai-responses-shared.test.ts b/src/llm/providers/openai-responses-shared.test.ts
index 17d1896942ea..f1f9edd1b0c1 100644
--- a/src/llm/providers/openai-responses-shared.test.ts
+++ b/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";
diff --git a/src/llm/providers/openai-responses-shared.ts b/src/llm/providers/openai-responses-shared.ts
index b0fc65e34e5d..936f22a103c1 100644
--- a/src/llm/providers/openai-responses-shared.ts
+++ b/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,
diff --git a/src/llm/providers/openai-responses-tools.ts b/src/llm/providers/openai-responses-tools.ts
index 996a0592f7f7..a9b398da2bf3 100644
--- a/src/llm/providers/openai-responses-tools.ts
+++ b/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";
diff --git a/src/llm/providers/openai-responses.ts b/src/llm/providers/openai-responses.ts
index 5c4e129a7cb2..a49db54c6cdf 100644
--- a/src/llm/providers/openai-responses.ts
+++ b/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";
diff --git a/src/llm/providers/register-builtins.ts b/src/llm/providers/register-builtins.ts
index 1a660cc8c4a7..432cbb4332fc 100644
--- a/src/llm/providers/register-builtins.ts
+++ b/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,
diff --git a/src/llm/providers/simple-options.ts b/src/llm/providers/simple-options.ts
index ad1ff49ea049..a3caeb2143df 100644
--- a/src/llm/providers/simple-options.ts
+++ b/src/llm/providers/simple-options.ts
@@ -1,3 +1,4 @@
+// Simple provider option helpers normalize lightweight provider configuration.
 import type {
   Model,
   SimpleStreamOptions,
diff --git a/src/llm/providers/stream-wrappers/anthropic-cache-control-payload.test.ts b/src/llm/providers/stream-wrappers/anthropic-cache-control-payload.test.ts
index e17a9cda294f..915cb2d00962 100644
--- a/src/llm/providers/stream-wrappers/anthropic-cache-control-payload.test.ts
+++ b/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";
 
diff --git a/src/llm/providers/stream-wrappers/anthropic-family-cache-semantics.ts b/src/llm/providers/stream-wrappers/anthropic-family-cache-semantics.ts
index e0923eaca055..9b1d519d7420 100644
--- a/src/llm/providers/stream-wrappers/anthropic-family-cache-semantics.ts
+++ b/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,
diff --git a/src/llm/providers/stream-wrappers/anthropic-family-tool-payload-compat.ts b/src/llm/providers/stream-wrappers/anthropic-family-tool-payload-compat.ts
index b6d762991a8c..bf3b0a763225 100644
--- a/src/llm/providers/stream-wrappers/anthropic-family-tool-payload-compat.ts
+++ b/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";
diff --git a/src/llm/providers/stream-wrappers/google.test.ts b/src/llm/providers/stream-wrappers/google.test.ts
index f60316d75167..d24a8662aac8 100644
--- a/src/llm/providers/stream-wrappers/google.test.ts
+++ b/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";
 
diff --git a/src/llm/providers/stream-wrappers/minimax.test.ts b/src/llm/providers/stream-wrappers/minimax.test.ts
index 79e1f22baf71..cc1613f110f7 100644
--- a/src/llm/providers/stream-wrappers/minimax.test.ts
+++ b/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";
diff --git a/src/llm/providers/stream-wrappers/minimax.ts b/src/llm/providers/stream-wrappers/minimax.ts
index d3c30a9d83bd..678df71a7910 100644
--- a/src/llm/providers/stream-wrappers/minimax.ts
+++ b/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";
 
diff --git a/src/llm/providers/stream-wrappers/moonshot-thinking.ts b/src/llm/providers/stream-wrappers/moonshot-thinking.ts
index a33b6a606f1c..09830236335d 100644
--- a/src/llm/providers/stream-wrappers/moonshot-thinking.ts
+++ b/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";
diff --git a/src/llm/providers/stream-wrappers/moonshot.ts b/src/llm/providers/stream-wrappers/moonshot.ts
index c0fd99aee9ec..1e3fecea1ad5 100644
--- a/src/llm/providers/stream-wrappers/moonshot.ts
+++ b/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";
diff --git a/src/llm/providers/stream-wrappers/openai.test.ts b/src/llm/providers/stream-wrappers/openai.test.ts
index 44183b35a2d2..2a5f3302763e 100644
--- a/src/llm/providers/stream-wrappers/openai.test.ts
+++ b/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";
diff --git a/src/llm/providers/stream-wrappers/openai.ts b/src/llm/providers/stream-wrappers/openai.ts
index 608deaa80271..787b5a49b741 100644
--- a/src/llm/providers/stream-wrappers/openai.ts
+++ b/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,
diff --git a/src/llm/providers/stream-wrappers/proxy.test.ts b/src/llm/providers/stream-wrappers/proxy.test.ts
index 4badb12256b5..f32467785147 100644
--- a/src/llm/providers/stream-wrappers/proxy.test.ts
+++ b/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";
diff --git a/src/llm/providers/stream-wrappers/proxy.ts b/src/llm/providers/stream-wrappers/proxy.ts
index 31015b9080ba..4024bd1e1abc 100644
--- a/src/llm/providers/stream-wrappers/proxy.ts
+++ b/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,
diff --git a/src/llm/providers/stream-wrappers/reasoning-effort-utils.test.ts b/src/llm/providers/stream-wrappers/reasoning-effort-utils.test.ts
index 5cf8c3101e44..33660925a755 100644
--- a/src/llm/providers/stream-wrappers/reasoning-effort-utils.test.ts
+++ b/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";
 
diff --git a/src/llm/providers/stream-wrappers/reasoning-effort-utils.ts b/src/llm/providers/stream-wrappers/reasoning-effort-utils.ts
index dc77dbb3b945..dffd74ebec22 100644
--- a/src/llm/providers/stream-wrappers/reasoning-effort-utils.ts
+++ b/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. */
diff --git a/src/llm/providers/stream-wrappers/stream-payload-utils.ts b/src/llm/providers/stream-wrappers/stream-payload-utils.ts
index 3f585c2f8af8..900f6401430f 100644
--- a/src/llm/providers/stream-wrappers/stream-payload-utils.ts
+++ b/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. */
diff --git a/src/llm/providers/stream-wrappers/zai.ts b/src/llm/providers/stream-wrappers/zai.ts
index 058c97a11d56..1b75c7ad7f15 100644
--- a/src/llm/providers/stream-wrappers/zai.ts
+++ b/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";
diff --git a/src/llm/providers/transform-messages.ts b/src/llm/providers/transform-messages.ts
index b262c0c047c9..63bdeb274d48 100644
--- a/src/llm/providers/transform-messages.ts
+++ b/src/llm/providers/transform-messages.ts
@@ -1,3 +1,4 @@
+// Provider message transform helpers convert runtime messages to provider payloads.
 import type {
   Api,
   AssistantMessage,
diff --git a/src/llm/utils/json-parse.test.ts b/src/llm/utils/json-parse.test.ts
index f49b37741184..57ee116c6351 100644
--- a/src/llm/utils/json-parse.test.ts
+++ b/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";
 
diff --git a/src/llm/utils/json-parse.ts b/src/llm/utils/json-parse.ts
index 0edd95e5d9d4..4aab23cf9afc 100644
--- a/src/llm/utils/json-parse.ts
+++ b/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"]);
diff --git a/src/llm/utils/node-http-proxy.test.ts b/src/llm/utils/node-http-proxy.test.ts
index 4c3eb05c4b14..9cbf648aa4bc 100644
--- a/src/llm/utils/node-http-proxy.test.ts
+++ b/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,
diff --git a/src/llm/utils/node-http-proxy.ts b/src/llm/utils/node-http-proxy.ts
index bb97554a18e2..0816cf9e21df 100644
--- a/src/llm/utils/node-http-proxy.ts
+++ b/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 {
diff --git a/src/llm/utils/oauth/abort.test.ts b/src/llm/utils/oauth/abort.test.ts
index 459221c09230..e0676b5ae5a6 100644
--- a/src/llm/utils/oauth/abort.test.ts
+++ b/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";
diff --git a/src/llm/utils/oauth/anthropic.test.ts b/src/llm/utils/oauth/anthropic.test.ts
index 39b6cd58aaa6..3033260b480b 100644
--- a/src/llm/utils/oauth/anthropic.test.ts
+++ b/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";
 
diff --git a/src/llm/utils/oauth/github-copilot.test.ts b/src/llm/utils/oauth/github-copilot.test.ts
index 03d2bf6ac175..dae984578b1c 100644
--- a/src/llm/utils/oauth/github-copilot.test.ts
+++ b/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";
diff --git a/src/llm/utils/oauth/openai-chatgpt-jwt.ts b/src/llm/utils/oauth/openai-chatgpt-jwt.ts
index fcc0b1de4c6f..01155083b3d3 100644
--- a/src/llm/utils/oauth/openai-chatgpt-jwt.ts
+++ b/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 = {
diff --git a/src/llm/utils/oauth/openai-chatgpt.test.ts b/src/llm/utils/oauth/openai-chatgpt.test.ts
index 0dedd358bd41..73cc7a54147c 100644
--- a/src/llm/utils/oauth/openai-chatgpt.test.ts
+++ b/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 =
diff --git a/src/llm/utils/oauth/openai-chatgpt.ts b/src/llm/utils/oauth/openai-chatgpt.ts
index 094bcc2df8e8..554b677b5f8f 100644
--- a/src/llm/utils/oauth/openai-chatgpt.ts
+++ b/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";
diff --git a/src/llm/utils/oauth/pkce.test.ts b/src/llm/utils/oauth/pkce.test.ts
index 046fdec74cd9..75aebada45c3 100644
--- a/src/llm/utils/oauth/pkce.test.ts
+++ b/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";
 
diff --git a/src/llm/utils/overflow.ts b/src/llm/utils/overflow.ts
index 7ada96da7e8a..640cab54bc96 100644
--- a/src/llm/utils/overflow.ts
+++ b/src/llm/utils/overflow.ts
@@ -1,3 +1,4 @@
+// Overflow helpers classify provider overflow errors and retryable responses.
 import type { AssistantMessage } from "../types.js";
 
 /**