docs: document provider error helpers

steipete · steipete · commit 059277f83b63 · 2026-06-03T23:35:55.000-04:00
diff --git a/src/agents/live-model-errors.ts b/src/agents/live-model-errors.ts
@@ -1,3 +1,10 @@
+/**
+ * Live-provider model error classifiers.
+ *
+ * Probe and fallback code uses these string checks to distinguish missing or
+ * deprecated model ids from generic provider/runtime failures.
+ */
+/** Returns whether a provider error message indicates a missing or retired model id. */
 export function isModelNotFoundErrorMessage(raw: string): boolean {
   const msg = raw.trim();
   if (!msg) {
@@ -45,6 +52,7 @@ export function isModelNotFoundErrorMessage(raw: string): boolean {
   return false;
 }
 
+/** Returns whether a MiniMax HTML-style 404 body is a model-not-found signal. */
 export function isMiniMaxModelNotFoundErrorMessage(raw: string): boolean {
   const msg = raw.trim();
   if (!msg) {
diff --git a/src/agents/model-tool-support.ts b/src/agents/model-tool-support.ts
@@ -1,3 +1,10 @@
+/**
+ * Model capability helper for tool-use support.
+ *
+ * Provider catalogs can opt a model out via `compat.supportsTools === false`;
+ * absent metadata remains permissive for older catalog entries.
+ */
+/** Returns whether a catalog model should be offered tool calls. */
 export function supportsModelTools(model: { compat?: unknown }): boolean {
   const compat =
     model.compat && typeof model.compat === "object"
diff --git a/src/agents/model-transport-debug.ts b/src/agents/model-transport-debug.ts
@@ -1,10 +1,18 @@
+/**
+ * Environment-driven debug controls for model transport logging.
+ *
+ * Model adapters share these helpers so payload, SSE, and transport diagnostics
+ * interpret OpenClaw debug environment variables consistently.
+ */
 import type { createSubsystemLogger } from "../logging/subsystem.js";
 
 type SubsystemLogger = ReturnType<typeof createSubsystemLogger>;
 
 type ModelTransportDebugEnv = NodeJS.ProcessEnv;
 
+/** Payload debug detail levels accepted by `OPENCLAW_DEBUG_MODEL_PAYLOAD`. */
 export type ModelPayloadDebugMode = "off" | "summary" | "tools" | "full-redacted";
+/** SSE debug detail levels accepted by `OPENCLAW_DEBUG_SSE`. */
 export type ModelSseDebugMode = "off" | "events" | "peek";
 
 function normalizeEnv(value: unknown): string {
@@ -22,6 +30,7 @@ function isTruthyEnv(value: unknown): boolean {
   );
 }
 
+/** Resolves model payload debug verbosity from `OPENCLAW_DEBUG_MODEL_PAYLOAD`. */
 export function resolveModelPayloadDebugMode(
   env: ModelTransportDebugEnv = process.env,
 ): ModelPayloadDebugMode {
@@ -35,6 +44,7 @@ export function resolveModelPayloadDebugMode(
   return "off";
 }
 
+/** Resolves SSE stream debug verbosity from `OPENCLAW_DEBUG_SSE`. */
 export function resolveModelSseDebugMode(
   env: ModelTransportDebugEnv = process.env,
 ): ModelSseDebugMode {
@@ -48,6 +58,7 @@ export function resolveModelSseDebugMode(
   return "off";
 }
 
+/** Returns whether any model transport debug channel is enabled. */
 export function isModelTransportDebugEnabled(env: ModelTransportDebugEnv = process.env): boolean {
   return (
     isTruthyEnv(env.OPENCLAW_DEBUG_MODEL_TRANSPORT) ||
@@ -57,6 +68,7 @@ export function isModelTransportDebugEnabled(env: ModelTransportDebugEnv = proce
   );
 }
 
+/** Emits transport diagnostics at info level only when debug env explicitly enables them. */
 export function emitModelTransportDebug(log: SubsystemLogger, message: string): void {
   if (isModelTransportDebugEnabled()) {
     log.info(message);
diff --git a/src/agents/provider-http-errors.ts b/src/agents/provider-http-errors.ts
@@ -1,3 +1,9 @@
+/**
+ * Shared provider HTTP error normalization helpers.
+ *
+ * Transport adapters use this module to turn provider-specific response bodies,
+ * request ids, and binary payload guardrails into stable OpenClaw error shapes.
+ */
 export { asFiniteNumber } from "../../packages/normalization-core/src/number-coercion.js";
 import { readResponseWithLimit } from "@openclaw/media-core/read-response-with-limit";
 import { normalizeOptionalString as trimToUndefined } from "../../packages/normalization-core/src/string-coerce.js";
@@ -8,20 +14,24 @@ export { normalizeOptionalString as trimToUndefined } from "../../packages/norma
 const ERROR_BODY_METADATA_LIMIT = 500;
 const PROVIDER_BINARY_RESPONSE_MAX_BYTES = 16 * 1024 * 1024;
 
+/** Returns a plain object view for provider JSON payloads when one exists. */
 export function asObject(value: unknown): Record<string, unknown> | undefined {
   return typeof value === "object" && value !== null && !Array.isArray(value)
     ? (value as Record<string, unknown>)
     : undefined;
 }
 
+/** Trims provider error details to a log- and prompt-safe preview length. */
 export function truncateErrorDetail(detail: string, limit = 220): string {
   return detail.length <= limit ? detail : `${detail.slice(0, limit - 1)}…`;
 }
 
+/** Redacts secrets before preserving a bounded provider error body preview. */
 export function redactProviderErrorBody(body: string): string {
   return truncateErrorDetail(redactSensitiveText(body), ERROR_BODY_METADATA_LIMIT);
 }
 
+/** Reads at most `limitBytes` from a response body without buffering provider-sized failures. */
 export async function readResponseTextLimited(
   response: Response,
   limitBytes = 16 * 1024,
@@ -64,13 +74,15 @@ export async function readResponseTextLimited(
     text += decoder.decode();
   } finally {
     if (reachedLimit) {
+      // Stop the upstream body once the diagnostic budget is full.
       await reader.cancel().catch(() => {});
     }
   }
 
   return text;
 }
 
+/** Formats common provider JSON error payload shapes into one readable detail string. */
 export function formatProviderErrorPayload(payload: unknown): string | undefined {
   const root = asObject(payload);
   const detailObject = asObject(root?.detail);
@@ -132,6 +144,7 @@ function extractProviderErrorPayloadMetadata(payload: unknown): ProviderErrorPay
   };
 }
 
+/** Metadata extracted from a non-2xx provider response body and headers. */
 export type ProviderHttpErrorInfo = {
   detail?: string;
   code?: string;
@@ -140,6 +153,7 @@ export type ProviderHttpErrorInfo = {
   requestId?: string;
 };
 
+/** Extracts normalized provider error metadata while keeping the raw body bounded and redacted. */
 export async function extractProviderErrorInfo(response: Response): Promise<ProviderHttpErrorInfo> {
   const rawBody = trimToUndefined(await readResponseTextLimited(response).catch(() => ""));
   const requestId = extractProviderRequestId(response);
@@ -165,17 +179,20 @@ export async function extractProviderErrorInfo(response: Response): Promise<Prov
   }
 }
 
+/** Returns only the normalized provider detail string for callers that do not need metadata. */
 export async function extractProviderErrorDetail(response: Response): Promise<string | undefined> {
   return (await extractProviderErrorInfo(response)).detail;
 }
 
+/** Reads the provider request id header variants used across model and media APIs. */
 export function extractProviderRequestId(response: Response): string | undefined {
   return (
     trimToUndefined(response.headers.get("x-request-id")) ??
     trimToUndefined(response.headers.get("request-id"))
   );
 }
 
+/** Error type carrying normalized provider status, request id, code, type, and body metadata. */
 export class ProviderHttpError extends Error {
   readonly status: number;
   readonly statusCode: number;
@@ -207,6 +224,7 @@ export class ProviderHttpError extends Error {
   }
 }
 
+/** Builds the human-facing provider HTTP error message from normalized metadata. */
 export function formatProviderHttpErrorMessage(params: {
   label: string;
   status: number;
@@ -222,6 +240,7 @@ export function formatProviderHttpErrorMessage(params: {
   );
 }
 
+/** Creates a normalized provider HTTP error from a failed response. */
 export async function createProviderHttpError(
   response: Response,
   label: string,
@@ -246,6 +265,7 @@ export async function createProviderHttpError(
   );
 }
 
+/** Throws a normalized provider error when a fetch response is not OK. */
 export async function assertOkOrThrowProviderError(
   response: Response,
   label: string,
@@ -256,13 +276,15 @@ export async function assertOkOrThrowProviderError(
   throw await createProviderHttpError(response, label);
 }
 
+/** Throws a normalized generic HTTP error when a fetch response is not OK. */
 export async function assertOkOrThrowHttpError(response: Response, label: string): Promise<void> {
   if (response.ok) {
     return;
   }
   throw await createProviderHttpError(response, label, { statusPrefix: "HTTP " });
 }
 
+/** Parses a provider JSON response and wraps malformed JSON with the caller's label. */
 export async function readProviderJsonResponse<T>(response: Response, label: string): Promise<T> {
   try {
     return (await response.json()) as T;
@@ -271,6 +293,7 @@ export async function readProviderJsonResponse<T>(response: Response, label: str
   }
 }
 
+/** Parses a provider JSON response that must be a top-level object. */
 export async function readProviderJsonObjectResponse(
   response: Response,
   label: string,
@@ -283,6 +306,7 @@ export async function readProviderJsonObjectResponse(
   return object;
 }
 
+/** Parses a provider JSON object response and returns an array field. */
 export async function readProviderJsonArrayFieldResponse(
   response: Response,
   label: string,
@@ -301,6 +325,7 @@ function normalizeContentType(response: Response): string | undefined {
   return contentType || undefined;
 }
 
+/** Rejects text or JSON responses on provider endpoints that should return binary bytes. */
 export function assertProviderBinaryResponseContent(
   response: Response,
   label: string,
@@ -319,6 +344,7 @@ export function assertProviderBinaryResponseContent(
   }
 }
 
+/** Reads a bounded non-empty binary provider response after content-type validation. */
 export async function readProviderBinaryResponse(
   response: Response,
   label: string,
