From 48557cecff3c214d55d34cebc04849904bd61eb9 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Wed, 3 Jun 2026 23:41:43 -0400
Subject: [PATCH] docs: document model tool helpers

---
 src/agents/google-simple-completion-stream.ts | 8 ++++++++
 src/agents/model-selection-resolve.ts         | 8 ++++++++
 src/agents/tool-schema-quarantine.ts          | 9 +++++++++
 3 files changed, 25 insertions(+)

diff --git a/src/agents/google-simple-completion-stream.ts b/src/agents/google-simple-completion-stream.ts
index 14a78f023618..fd6139721c50 100644
--- a/src/agents/google-simple-completion-stream.ts
+++ b/src/agents/google-simple-completion-stream.ts
@@ -1,3 +1,9 @@
+/**
+ * Google simple-completion stream adapter.
+ *
+ * This registers a patched Google stream API that keeps the normal Google
+ * backend but sanitizes unsupported thinking payload options for simple models.
+ */
 import { streamSimple } from "../llm/stream.js";
 import type { Api, Model } from "../llm/types.js";
 import {
@@ -8,6 +14,7 @@ import {
 import { ensureCustomApiRegistered } from "./custom-api-registry.js";
 import type { StreamFn } from "./runtime/index.js";
 
+/** Custom API id for the Google simple-completion stream adapter. */
 export const GOOGLE_SIMPLE_COMPLETION_API: Api = "openclaw-google-generative-ai-simple";
 
 const SOURCE_API: Api = "google-generative-ai";
@@ -51,6 +58,7 @@ function buildGoogleSimpleCompletionStreamFn(): StreamFn {
   };
 }
 
+/** Rewrites Google generative-ai models to the simple-completion adapter when needed. */
 export function prepareGoogleSimpleCompletionModel<TApi extends Api>(model: Model<TApi>): Model {
   if (model.api !== SOURCE_API) {
     return model;
diff --git a/src/agents/model-selection-resolve.ts b/src/agents/model-selection-resolve.ts
index 58cd3f140202..b1fc914fa2f0 100644
--- a/src/agents/model-selection-resolve.ts
+++ b/src/agents/model-selection-resolve.ts
@@ -1,3 +1,9 @@
+/**
+ * Model selection resolution facade.
+ *
+ * This module exposes model-selection helpers that need default fallback model
+ * handling before checking aliases, allowlists, catalogs, and plugin manifests.
+ */
 import { resolveAgentModelFallbackValues } from "../config/model-input.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type { ModelCatalogEntry } from "./model-catalog.types.js";
@@ -23,6 +29,7 @@ function resolveDefaultFallbackModels(cfg: OpenClawConfig): string[] {
   return resolveAgentModelFallbackValues(cfg.agents?.defaults?.model);
 }
 
+/** Returns whether a normalized model ref is available, allowed, or fallback-backed. */
 export function getModelRefStatus(
   params: {
     cfg: OpenClawConfig;
@@ -44,6 +51,7 @@ export function getModelRefStatus(
   });
 }
 
+/** Resolves a raw model string into an allowed model ref or an explanatory error. */
 export function resolveAllowedModelRef(
   params: {
     cfg: OpenClawConfig;
diff --git a/src/agents/tool-schema-quarantine.ts b/src/agents/tool-schema-quarantine.ts
index 1eca6b6a8ca3..83e796d36f9d 100644
--- a/src/agents/tool-schema-quarantine.ts
+++ b/src/agents/tool-schema-quarantine.ts
@@ -1,3 +1,9 @@
+/**
+ * Runtime tool-schema quarantine logging.
+ *
+ * Model providers can reject unsupported schema shapes, so runtime projection
+ * reports quarantined tools with trusted diagnostics before the model call.
+ */
 import { emitTrustedDiagnosticEvent } from "../infra/diagnostic-events.js";
 import { createSubsystemLogger } from "../logging/subsystem.js";
 import { getPluginToolMeta } from "../plugins/tools.js";
@@ -18,6 +24,7 @@ function readDiagnosticPluginId(params: {
   }
 }
 
+/** Emits diagnostics and logs for tools removed from runtime schema projection. */
 export function logRuntimeToolSchemaQuarantine(params: {
   diagnostics: readonly RuntimeToolSchemaDiagnostic[];
   tools: readonly AnyAgentTool[];
@@ -32,6 +39,8 @@ export function logRuntimeToolSchemaQuarantine(params: {
     .map((diagnostic) => {
       const pluginId = readDiagnosticPluginId({ tools: params.tools, diagnostic });
       const owner = pluginId ? ` plugin=${pluginId}` : "";
+      // Emit structured evidence per quarantined tool; the warning below is
+      // compact for operator logs.
       emitTrustedDiagnosticEvent({
         type: "tool.execution.blocked",
         runId: params.runId,