docs: document built-in tool helpers

src/agents/tool-mutation.ts

@@ -1,3 +1,8 @@
+/**
+ * Tool mutation classification and fingerprinting.
+ *
+ * Identifies mutating tool calls and file targets so retry/recovery logic can reason about side effects.
+ */
 import {
   normalizeLowercaseStringOrEmpty,
   normalizeOptionalLowercaseString,

src/agents/tool-policy-shared.ts

@@ -1,3 +1,8 @@
+/**
+ * Shared runtime tool policy normalization.
+ *
+ * Keeps aliases, groups, profile expansion, and prefix matching consistent across allow/deny paths.
+ */
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import { uniqueStrings } from "@openclaw/normalization-core/string-normalization";
 import {
@@ -6,12 +11,6 @@ import {
   type ToolProfileId,
 } from "./tool-catalog.js";
 
-/**
- * Shared normalization helpers for runtime tool policy.
- *
- * Aliases and groups live here so allowlist parsing, prefix matching, and
- * profile expansion resolve names consistently.
- */
 type ToolProfilePolicy = {
   allow?: string[];
   deny?: string[];

src/agents/tools/agent-step.ts

@@ -1,3 +1,8 @@
+/**
+ * Nested agent-step executor.
+ *
+ * Sends annotated inter-session messages through in-process or Gateway execution and reads the assistant reply.
+ */
 import crypto from "node:crypto";
 import { callGateway } from "../../gateway/call.js";
 import { annotateInterSessionPromptText } from "../../sessions/input-provenance.js";
@@ -6,12 +11,6 @@ import { retireSessionMcpRuntimeForSessionKey } from "../agent-bundle-mcp-tools.
 import { resolveNestedAgentLaneForSession } from "../lanes.js";
 import { waitForAgentRunAndReadUpdatedAssistantReply } from "../run-wait.js";
 
-/**
- * Runs a single nested agent step for sessions_send and related inter-session flows.
- *
- * The helper supports both in-process command execution and Gateway execution,
- * then waits for the updated assistant reply when the Gateway path is used.
- */
 export { readLatestAssistantReply } from "../run-wait.js";
 
 type GatewayCaller = typeof callGateway;

src/agents/tools/agents-list-tool.ts

@@ -1,3 +1,8 @@
+/**
+ * agents_list built-in tool.
+ *
+ * Lists configured or allowed agent ids plus model/runtime metadata for subagent spawn decisions.
+ */
 import { Type } from "typebox";
 import { getRuntimeConfig } from "../../config/config.js";
 import {

src/agents/tools/chat-history-text.ts

@@ -1,3 +1,8 @@
+/**
+ * Chat-history text helpers for session tools.
+ *
+ * Removes tool messages and extracts sanitized assistant-visible text from stored messages.
+ */
 import { extractAssistantTextForPhase } from "../../shared/chat-message-content.js";
 import { sanitizeAssistantVisibleTextWithProfile } from "../../shared/text/assistant-visible-text.js";
 import { sanitizeUserFacingText } from "../embedded-agent-helpers/sanitize-user-facing-text.js";

src/agents/tools/common.ts

@@ -1,3 +1,8 @@
+/**
+ * Shared built-in tool contracts and helpers.
+ *
+ * Defines erased tool types, parameter readers, JSON results, progress blocks, and media sanitization.
+ */
 import { detectMime } from "@openclaw/media-core/mime";
 import {
   asPositiveSafeInteger,

src/agents/tools/cron-tool-canonicalize.ts

@@ -1,3 +1,8 @@
+/**
+ * Cron tool argument canonicalization.
+ *
+ * Recovers flat or partial model/tool inputs into the structured cron job/patch shape.
+ */
 import { timestampMsToIsoString } from "@openclaw/normalization-core/number-coercion";
 import { isRecord } from "../../utils.js";
 

src/agents/tools/cron-tool.ts

@@ -1,3 +1,8 @@
+/**
+ * cron built-in tool.
+ *
+ * Manages scheduled jobs, wake/run actions, delivery context, and reminder-style payload normalization.
+ */
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import { Type, type TSchema } from "typebox";
 import { getRuntimeConfig } from "../../config/config.js";
@@ -34,8 +39,8 @@ import { gatewayCallOptionSchemaProperties } from "./gateway-schema.js";
 import { callGatewayTool, readGatewayCallOptions, type GatewayCallOptions } from "./gateway.js";
 import { resolveInternalSessionKey, resolveMainSessionAlias } from "./sessions-helpers.js";
 
-// We spell out job/patch properties so that LLMs know what fields to send.
-// Nested unions are avoided; runtime validation happens in normalizeCronJob*.
+// Spell out job/patch properties for model-facing schema; runtime validation
+// still happens in normalizeCronJob* to avoid nested union schemas.
 
 const CRON_ACTIONS = [
   "status",

src/agents/tools/embedded-gateway-stub.ts

@@ -1,3 +1,8 @@
+/**
+ * Embedded-mode Gateway method stub.
+ *
+ * Implements only the Gateway calls needed by session tools and rejects unsupported methods.
+ */
 import type {
   SessionsListParams,
   SessionsResolveParams,
@@ -10,12 +15,6 @@ import type { SessionsResolveResult } from "../../gateway/sessions-resolve.js";
 import { parseAgentSessionKey } from "../../routing/session-key.js";
 import { readPositiveIntegerParam } from "./common.js";
 
-/**
- * Local Gateway method stub used when session tools run in embedded mode.
- *
- * It implements only the Gateway methods needed by session tools and rejects
- * everything else so callers do not accidentally depend on partial behavior.
- */
 type EmbeddedCallGateway = <T = Record<string, unknown>>(opts: CallGatewayOptions) => Promise<T>;
 
 interface EmbeddedGatewayRuntime {

src/agents/tools/gateway-schema.ts

@@ -1,12 +1,11 @@
+/**
+ * Shared Gateway tool schema fragments.
+ *
+ * Keeps gateway URL/token/timeout parameters aligned across tools that call Gateway methods.
+ */
 import { Type } from "typebox";
 import { optionalPositiveIntegerSchema } from "../schema/typebox.js";
 
-/**
- * Shared TypeBox schema fragments for tools that call the Gateway.
- *
- * Keeping gateway options centralized prevents drift between tool schemas and
- * gateway call option parsing.
- */
 /** Returns optional gateway URL/token/timeout schema properties for tool params. */
 export function gatewayCallOptionSchemaProperties() {
   return {

src/agents/tools/gateway-tool.ts

@@ -1,3 +1,8 @@
+/**
+ * gateway built-in tool.
+ *
+ * Exposes selected Gateway control/config/update actions with fail-closed config mutation boundaries.
+ */
 import { isDeepStrictEqual } from "node:util";
 import { isRecord as isPlainObject } from "@openclaw/normalization-core/record-coerce";
 import {

src/agents/tools/goal-tools.ts

@@ -1,3 +1,8 @@
+/**
+ * Model-facing thread goal tools.
+ *
+ * Provides create/get/update goal operations scoped to the current session store.
+ */
 import { Type } from "typebox";
 import {
   createSessionGoal,
@@ -17,12 +22,6 @@ import {
   readStringParam,
 } from "./common.js";
 
-/**
- * Model-facing thread goal tools.
- *
- * Goal state is scoped to the current session store so agents can inspect,
- * create, or close a persistent objective without direct store access.
- */
 type GoalToolOptions = {
   agentSessionKey?: string;
   runSessionKey?: string;

src/agents/tools/image-generate-background.ts

@@ -1,3 +1,8 @@
+/**
+ * Image generation background task facade.
+ *
+ * Binds shared detached media-task lifecycle behavior to image_generate labels and completion messages.
+ */
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import type { AgentGeneratedAttachment } from "../generated-attachments.js";
 import { IMAGE_GENERATION_TASK_KIND } from "../image-generation-task-status.js";
@@ -6,12 +11,6 @@ import {
   type MediaGenerationTaskHandle,
 } from "./media-generate-background-shared.js";
 
-/**
- * Image-generation-specific facade over the shared media generation task lifecycle.
- *
- * This binds shared detached-task behavior to image task labels, event source,
- * and completion wording used by image_generate.
- */
 /** Detached image generation task handle. */
 export type ImageGenerationTaskHandle = MediaGenerationTaskHandle;
 

src/agents/tools/image-generate-tool.actions.ts

@@ -1,3 +1,8 @@
+/**
+ * image_generate action helpers.
+ *
+ * Handles provider listing, task status, and duplicate-guard output for the image generation tool.
+ */
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import { listRuntimeImageGenerationProviders } from "../../image-generation/runtime.js";
 import type { ImageGenerationProvider } from "../../image-generation/types.js";
@@ -17,9 +22,6 @@ import {
   type MediaGenerateActionResult,
 } from "./media-generate-tool-actions-shared.js";
 
-/**
- * Image-generation list/status/duplicate-guard action helpers.
- */
 export type ImageGenerateActionResult = MediaGenerateActionResult;
 
 /** Formats provider auth setup hints for the image generation `list` action. */

src/agents/tools/image-generate-tool.ts

@@ -1,3 +1,8 @@
+/**
+ * image_generate built-in tool.
+ *
+ * Loads references, resolves providers/options, saves generated images, and supports detached background runs.
+ */
 import { Type } from "typebox";
 import { getRuntimeConfig } from "../../config/config.js";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";

src/agents/tools/image-tool.helpers.ts

@@ -1,3 +1,8 @@
+/**
+ * Image/media understanding helper functions.
+ *
+ * Handles model config, data URL decoding, provider lookup, and reasoning-only response validation.
+ */
 import { estimateBase64DecodedBytes } from "@openclaw/media-core/base64";
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
@@ -7,11 +12,6 @@ import { isMinimaxVlmProvider } from "../minimax-vlm.js";
 import { findNormalizedProviderValue, normalizeProviderId } from "../model-selection.js";
 import { coerceToolModelConfig, type ToolModelConfig } from "./model-config.helpers.js";
 
-/**
- * Shared image-tool helpers for model selection, data URL decoding, and response validation.
- *
- * These helpers are reused by image, PDF, and media factory paths.
- */
 /** Image tool model config uses the shared tool model config shape. */
 export type ImageModelConfig = ToolModelConfig;
 

src/agents/tools/image-tool.ts

@@ -1,3 +1,8 @@
+/**
+ * image built-in tool.
+ *
+ * Describes local, staged, web, and generated media through configured media-understanding providers.
+ */
 import { resolve, isAbsolute } from "node:path";
 import { Type } from "typebox";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";

src/agents/tools/manifest-capability-availability.ts

@@ -1,3 +1,8 @@
+/**
+ * Manifest capability availability checks.
+ *
+ * Combines plugin contracts, availability, config signals, auth profiles, env candidates, and base URL guards.
+ */
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import { getCurrentPluginMetadataSnapshot } from "../../plugins/current-plugin-metadata-snapshot.js";
 import { isManifestPluginAvailableForControlPlane } from "../../plugins/manifest-contract-eligibility.js";
@@ -14,12 +19,6 @@ import { getActivePluginRegistryWorkspaceDirFromState } from "../../plugins/runt
 import { listProfilesForProvider } from "../auth-profiles/profile-list.js";
 import type { AuthProfileStore } from "../auth-profiles/types.js";
 
-/**
- * Manifest capability availability checks for media/web-style tools.
- *
- * These helpers combine plugin contracts, plugin availability, config signals,
- * auth profiles, env candidates, and provider base URL guards.
- */
 /** Manifest contract keys that represent provider-backed tool capabilities. */
 export type CapabilityContractKey =
   | "imageGenerationProviders"