docs: document runtime system helpers

src/agents/mcp-http.ts

@@ -1,9 +1,16 @@
+/**
+ * HTTP MCP launch config normalization.
+ *
+ * MCP server setup uses this to validate SSE/streamable HTTP server records,
+ * sanitize headers, and redact sensitive URLs in diagnostics.
+ */
 import {
   redactSensitiveUrl,
   redactSensitiveUrlLikeString,
 } from "@openclaw/net-policy/redact-sensitive-url";
 import { isMcpConfigRecord, toMcpStringRecord } from "./mcp-config-shared.js";
 
+/** Supported HTTP-based MCP transport flavors. */
 export type HttpMcpTransportType = "sse" | "streamable-http";
 
 type HttpMcpServerLaunchConfig = {
@@ -16,6 +23,7 @@ type HttpMcpServerLaunchResult =
   | { ok: true; config: HttpMcpServerLaunchConfig }
   | { ok: false; reason: string };
 
+/** Normalizes an HTTP MCP server config record into a launchable transport config. */
 export function resolveHttpMcpServerLaunchConfig(
   raw: unknown,
   options?: {
@@ -68,6 +76,7 @@ export function resolveHttpMcpServerLaunchConfig(
   };
 }
 
+/** Describes an HTTP MCP server launch config without leaking URL credentials. */
 export function describeHttpMcpServerLaunchConfig(config: HttpMcpServerLaunchConfig): string {
   return redactSensitiveUrl(config.url);
 }

src/agents/run-termination.ts

@@ -1,6 +1,15 @@
+/**
+ * Shared agent run termination constants.
+ *
+ * Runtime and stream consumers use these stable literals to recognize user or
+ * controller aborts without matching free-form error text.
+ */
+/** Stop reason emitted when an agent run is aborted. */
 export const AGENT_RUN_ABORTED_STOP_REASON = "aborted" as const;
+/** Error text used for aborted agent runs. */
 export const AGENT_RUN_ABORTED_ERROR = "agent run aborted" as const;
 
+/** Returns whether a stop reason is the stable aborted-run reason. */
 export function isAbortedAgentStopReason(
   value: unknown,
 ): value is typeof AGENT_RUN_ABORTED_STOP_REASON {

src/agents/sandbox.ts

@@ -1,3 +1,9 @@
+/**
+ * Public sandbox barrel for agent runtime code.
+ *
+ * Keep sandbox implementation modules behind this export surface so callers use
+ * the same config, backend, Docker, SSH, filesystem, and policy contracts.
+ */
 export {
   resolveSandboxBrowserConfig,
   resolveSandboxConfigForAgent,

src/agents/system-prompt-config.ts

@@ -1,3 +1,9 @@
+/**
+ * Config-aware system prompt builder.
+ *
+ * This module gathers agent/config knobs before rendering the canonical system
+ * prompt so callers do not duplicate owner, TTS, alias, memory, or FS policy.
+ */
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { buildTtsSystemPromptHint } from "../tts/tts.js";
 import { resolveAgentConfig } from "./agent-scope.js";
@@ -8,6 +14,7 @@ import { resolveEffectiveToolFsWorkspaceOnly } from "./tool-fs-policy.js";
 
 type AgentSystemPromptRenderParams = Parameters<typeof buildAgentSystemPrompt>[0];
 
+/** Config-derived system prompt fields passed into the prompt renderer. */
 export type ResolvedAgentSystemPromptConfig = Pick<
   AgentSystemPromptRenderParams,
   | "ownerDisplay"
@@ -24,6 +31,7 @@ export type ConfiguredAgentSystemPromptParams = AgentSystemPromptRenderParams &
   agentId?: string;
 };
 
+/** Resolves all config-derived system prompt fields for an agent. */
 export function resolveAgentSystemPromptConfig(params: {
   config?: OpenClawConfig;
   agentId?: string;
@@ -46,6 +54,7 @@ export function resolveAgentSystemPromptConfig(params: {
   };
 }
 
+/** Builds the agent system prompt after applying config-derived prompt fields. */
 export function buildConfiguredAgentSystemPrompt(params: ConfiguredAgentSystemPromptParams) {
   const { config, agentId, ...renderParams } = params;
   const configParams = config ? resolveAgentSystemPromptConfig({ config, agentId }) : {};