docs: document agent runtime utility helpers

steipete · steipete · commit 0d0632d88d0c · 2026-06-03T22:11:33.000-04:00
diff --git a/src/agents/content-blocks.ts b/src/agents/content-blocks.ts
@@ -1,3 +1,4 @@
+/** Collects text block payloads from provider-style structured content arrays. */
 export function collectTextContentBlocks(content: unknown): string[] {
   if (!Array.isArray(content)) {
     return [];
diff --git a/src/agents/embedded-agent-subscribe.handlers.compaction.ts b/src/agents/embedded-agent-subscribe.handlers.compaction.ts
@@ -25,6 +25,8 @@ type CompactionEndEvent =
       aborted?: unknown;
     };
 
+// Unknown reasons come from external runtimes or older sessions. Treat them as
+// threshold compaction so logs and event payloads stay on the closed reason set.
 function normalizeCompactionReason(reason: unknown): CompactionReason {
   return reason === "manual" || reason === "threshold" || reason === "overflow"
     ? reason
@@ -35,6 +37,7 @@ function compactionLogKind(reason: CompactionReason): string {
   return reason === "manual" ? "manual compaction" : "auto-compaction";
 }
 
+/** Handles compaction start events from an embedded agent session. */
 export function handleCompactionStart(
   ctx: EmbeddedAgentSubscribeContext,
   evt: CompactionStartEvent,
@@ -60,7 +63,8 @@ export function handleCompactionStart(
     data: { phase: "start" },
   });
 
-  // Run before_compaction plugin hook (fire-and-forget)
+  // Hooks are fire-and-forget so compaction state updates and liveness pauses
+  // cannot be delayed by plugin work.
   const hookRunner = getGlobalHookRunner();
   if (hookRunner?.hasHooks("before_compaction")) {
     void hookRunner
@@ -80,15 +84,15 @@ export function handleCompactionStart(
   }
 }
 
+/** Handles compaction completion, retry, and incomplete events. */
 export function handleCompactionEnd(ctx: EmbeddedAgentSubscribeContext, evt: CompactionEndEvent) {
   const reason = normalizeCompactionReason(evt.reason);
   const kind = compactionLogKind(reason);
   ctx.state.compactionInFlight = false;
   const willRetry = Boolean(evt.willRetry);
-  // Increment counter whenever compaction actually produced a result,
-  // regardless of willRetry.  Overflow-triggered compaction sets willRetry=true
-  // (the framework retries the LLM request), but the compaction itself succeeded
-  // and context was trimmed — the counter must reflect that.  (#38905)
+  // Increment counter whenever compaction actually produced a result, regardless
+  // of willRetry. Overflow-triggered compaction retries the LLM request after
+  // trimming context, and the persisted count must reflect that successful trim.
   const hasResult = evt.result != null;
   const wasAborted = Boolean(evt.aborted);
   if (hasResult && !wasAborted) {
@@ -149,7 +153,8 @@ export function handleCompactionEnd(ctx: EmbeddedAgentSubscribeContext, evt: Com
     data: { phase: "end", willRetry, completed: hasResult && !wasAborted },
   });
 
-  // Run after_compaction plugin hook (fire-and-forget)
+  // after_compaction runs only once the run will not retry, matching the visible
+  // post-compaction session state plugin authors observe.
   if (!willRetry) {
     const hookRunnerEnd = getGlobalHookRunner();
     if (hookRunnerEnd?.hasHooks("after_compaction")) {
@@ -169,6 +174,7 @@ export function handleCompactionEnd(ctx: EmbeddedAgentSubscribeContext, evt: Com
   }
 }
 
+/** Lazily reconciles persisted compaction count after a successful compaction. */
 export async function reconcileSessionStoreCompactionCountAfterSuccess(params: {
   sessionKey?: string;
   agentId?: string;
@@ -181,6 +187,8 @@ export async function reconcileSessionStoreCompactionCountAfterSuccess(params: {
   return reconcile(params);
 }
 
+// Compaction rewrites history, so assistant usage snapshots can refer to the
+// old context. Keep the usage field shape but zero it for fresh accounting.
 function clearStaleAssistantUsageOnSessionMessages(ctx: EmbeddedAgentSubscribeContext): void {
   const messages = ctx.params.session.messages;
   if (!Array.isArray(messages)) {
@@ -194,8 +202,6 @@ function clearStaleAssistantUsageOnSessionMessages(ctx: EmbeddedAgentSubscribeCo
     if (candidate.role !== "assistant") {
       continue;
     }
-    // session runtime expects assistant usage to exist when computing context usage.
-    // Reset stale snapshots to zeros instead of deleting the field.
     candidate.usage = makeZeroUsageSnapshot();
   }
 }
diff --git a/src/agents/local-model-lean.ts b/src/agents/local-model-lean.ts
@@ -4,8 +4,12 @@ import { resolveAgentConfig, resolveDefaultAgentId } from "./agent-scope-config.
 import type { AnyAgentTool } from "./agent-tools.types.js";
 import { expandToolGroups, normalizeToolName } from "./tool-policy.js";
 
+// Local-model lean mode removes high-latency or channel-dependent tools unless
+// the caller explicitly preserves them for the current delivery path.
 const LOCAL_MODEL_LEAN_DENY_TOOL_NAMES = new Set(["browser", "cron", "message"]);
 
+// Preserve lists accept tool groups; normalize them to concrete tool names so
+// filtering stays aligned with the normal tool-policy path.
 function resolvePreservedLocalModelLeanToolNames(names?: Iterable<string>): Set<string> {
   if (!names) {
     return new Set();
@@ -17,6 +21,7 @@ function resolvePreservedLocalModelLeanToolNames(names?: Iterable<string>): Set<
   );
 }
 
+/** Resolves tool names that must survive local-model lean filtering. */
 export function resolveLocalModelLeanPreserveToolNames(params?: {
   toolNames?: Iterable<string>;
   forceMessageTool?: boolean;
@@ -29,6 +34,8 @@ export function resolveLocalModelLeanPreserveToolNames(params?: {
   return [...new Set(names)];
 }
 
+// Agent id may arrive explicitly, through the session key, or via config default.
+// Resolve once so default/agent experimental flags use the same scope.
 function resolveLocalModelLeanAgentId(params: {
   config?: OpenClawConfig;
   agentId?: string;
@@ -48,6 +55,7 @@ function resolveLocalModelLeanAgentId(params: {
   return params.config ? resolveDefaultAgentId(params.config) : undefined;
 }
 
+/** Returns true when local-model lean mode is enabled for the selected agent. */
 export function isLocalModelLeanEnabled(params: {
   config?: OpenClawConfig;
   agentId?: string;
@@ -62,6 +70,7 @@ export function isLocalModelLeanEnabled(params: {
   return resolvedExperimental?.localModelLean ?? false;
 }
 
+/** Filters tools for local-model lean mode while preserving required delivery tools. */
 export function filterLocalModelLeanTools(params: {
   tools: AnyAgentTool[];
   config?: OpenClawConfig;
diff --git a/src/agents/provider-model-normalization.runtime.ts b/src/agents/provider-model-normalization.runtime.ts
@@ -6,6 +6,8 @@ type ProviderRuntimeModule = Pick<
 >;
 
 const require = createRequire(import.meta.url);
+// Built code loads .js while source/test paths may still resolve .ts. Try both
+// once, then cache the absence to avoid repeated require work on hot paths.
 const PROVIDER_RUNTIME_CANDIDATES = [
   "../plugins/provider-runtime.js",
   "../plugins/provider-runtime.ts",
@@ -33,6 +35,7 @@ function loadProviderRuntime(): ProviderRuntimeModule | null {
   return null;
 }
 
+/** Normalizes provider model ids through plugin runtime hooks when available. */
 export function normalizeProviderModelIdWithRuntime(params: {
   provider: string;
   context: {
diff --git a/src/agents/subagent-session-cleanup.ts b/src/agents/subagent-session-cleanup.ts
@@ -3,6 +3,7 @@ import type { SpawnSubagentMode } from "./subagent-spawn.types.js";
 
 type CallGateway = typeof defaultCallGateway;
 
+/** Deletes a child subagent session and optionally emits session-mode lifecycle hooks. */
 export async function deleteSubagentSessionForCleanup(params: {
   callGateway: CallGateway;
   childSessionKey: string;

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+/** Collects text block payloads from provider-style structured content arrays. */`
`1`	`2`	`export function collectTextContentBlocks(content: unknown): string[] {`
`2`	`3`	`if (!Array.isArray(content)) {`
`3`	`4`	`return [];`