docs: document runner attempt helpers

steipete · steipete · commit f5ccfb73193e · 2026-06-04T09:32:25.000-04:00
diff --git a/src/agents/embedded-agent-runner/run/abortable.ts b/src/agents/embedded-agent-runner/run/abortable.ts
@@ -1,3 +1,6 @@
+/**
+ * AbortSignal-aware promise racing helper for embedded-agent attempts.
+ */
 function getAbortReason(signal: AbortSignal): unknown {
   return "reason" in signal ? (signal as { reason?: unknown }).reason : undefined;
 }
diff --git a/src/agents/embedded-agent-runner/run/assistant-failover.ts b/src/agents/embedded-agent-runner/run/assistant-failover.ts
@@ -1,3 +1,6 @@
+/**
+ * Handles assistant-stage failover decisions during embedded-agent attempts.
+ */
 import { sanitizeForLog } from "../../../../packages/terminal-core/src/ansi.js";
 import type { OpenClawConfig } from "../../../config/types.openclaw.js";
 import type { AssistantMessage } from "../../../llm/types.js";
diff --git a/src/agents/embedded-agent-runner/run/attempt-abort.ts b/src/agents/embedded-agent-runner/run/attempt-abort.ts
@@ -1,3 +1,6 @@
+/**
+ * Releases attempt resources when an embedded-agent run aborts.
+ */
 import type { EmbeddedAttemptSessionLockController } from "./attempt.session-lock.js";
 
 type AbortLockReleaseLog = {
diff --git a/src/agents/embedded-agent-runner/run/attempt-bootstrap-routing.ts b/src/agents/embedded-agent-runner/run/attempt-bootstrap-routing.ts
@@ -1,3 +1,6 @@
+/**
+ * Resolves bootstrap context targets for one embedded-agent attempt.
+ */
 import type { BootstrapMode } from "../../bootstrap-mode.js";
 import { resolveBootstrapMode } from "../../bootstrap-mode.js";
 import { DEFAULT_BOOTSTRAP_FILENAME, type WorkspaceBootstrapFile } from "../../workspace.js";
diff --git a/src/agents/embedded-agent-runner/run/attempt-http-runtime.ts b/src/agents/embedded-agent-runner/run/attempt-http-runtime.ts
@@ -1,3 +1,6 @@
+/**
+ * Configures HTTP timeout defaults for embedded-agent attempt runtime calls.
+ */
 import {
   DEFAULT_UNDICI_STREAM_TIMEOUT_MS,
   ensureGlobalUndiciDispatcherStreamTimeouts,
diff --git a/src/agents/embedded-agent-runner/run/attempt-session.ts b/src/agents/embedded-agent-runner/run/attempt-session.ts
@@ -1,3 +1,6 @@
+/**
+ * Creates embedded-agent sessions with the runner resource loader installed.
+ */
 import type { CreateAgentSessionOptions } from "../../sessions/index.js";
 
 /**
diff --git a/src/agents/embedded-agent-runner/run/attempt-system-prompt.ts b/src/agents/embedded-agent-runner/run/attempt-system-prompt.ts
@@ -1,3 +1,6 @@
+/**
+ * Builds the system prompt inputs for a single embedded-agent attempt.
+ */
 import type { OpenClawConfig } from "../../../config/types.openclaw.js";
 import type { ProviderTransformSystemPromptContext } from "../../../plugins/types.js";
 import { buildEmbeddedSystemPrompt } from "../system-prompt.js";
diff --git a/src/agents/embedded-agent-runner/run/attempt-tool-construction-plan.ts b/src/agents/embedded-agent-runner/run/attempt-tool-construction-plan.ts
@@ -1,3 +1,6 @@
+/**
+ * Plans which core, bundle MCP, and bundle LSP tools an attempt should build.
+ */
 import { TOOL_NAME_SEPARATOR } from "../../agent-bundle-mcp-names.js";
 import type { OpenClawCodingToolConstructionPlan } from "../../agent-tools.js";
 import { isToolAllowedByPolicyName } from "../../tool-policy-match.js";
diff --git a/src/agents/embedded-agent-runner/run/attempt-trajectory-flush-cleanup.ts b/src/agents/embedded-agent-runner/run/attempt-trajectory-flush-cleanup.ts
@@ -1,3 +1,6 @@
+/**
+ * Flushes attempt trajectory recorders during cleanup.
+ */
 import { runAgentCleanupStep } from "../../run-cleanup-timeout.js";
 
 /** Minimal recorder surface needed to flush trajectory data during run cleanup. */
diff --git a/src/agents/embedded-agent-runner/run/attempt-trajectory-status.ts b/src/agents/embedded-agent-runner/run/attempt-trajectory-status.ts
@@ -1,3 +1,6 @@
+/**
+ * Resolves terminal attempt trajectory status and assistant-visible text.
+ */
 import {
   hasAcceptedSessionSpawn,
   type AcceptedSessionSpawn,
diff --git a/src/agents/embedded-agent-runner/run/attempt.abort-settle-timeout.ts b/src/agents/embedded-agent-runner/run/attempt.abort-settle-timeout.ts
@@ -1,3 +1,6 @@
+/**
+ * Resolves how long aborted attempts wait for cleanup to settle.
+ */
 import { parseStrictPositiveInteger } from "../../../infra/parse-finite-number.js";
 
 type AbortSettleTimeoutEnv = Partial<
diff --git a/src/agents/embedded-agent-runner/run/attempt.async-tasks.ts b/src/agents/embedded-agent-runner/run/attempt.async-tasks.ts
@@ -1,3 +1,6 @@
+/**
+ * Waits for completion-required async tasks before finalizing an attempt.
+ */
 import { isCronRunSessionKey } from "../../../sessions/session-key-utils.js";
 import { isTerminalTaskStatus } from "../../../tasks/task-executor-policy.js";
 import type { TaskRecord } from "../../../tasks/task-registry.types.js";
diff --git a/src/agents/embedded-agent-runner/run/attempt.bootstrap-context.ts b/src/agents/embedded-agent-runner/run/attempt.bootstrap-context.ts
@@ -1,3 +1,6 @@
+/**
+ * Maps bootstrap context files into the attempt workspace.
+ */
 import path from "node:path";
 import { isAcpSessionKey, isSubagentSessionKey } from "../../../routing/session-key.js";
 import type { EmbeddedContextFile } from "../../embedded-agent-helpers.js";
diff --git a/src/agents/embedded-agent-runner/run/attempt.context-engine-helpers.ts b/src/agents/embedded-agent-runner/run/attempt.context-engine-helpers.ts
@@ -1,3 +1,6 @@
+/**
+ * Bridges attempt bootstrap/history data to context-engine prompt-cache helpers.
+ */
 import type { ContextEngine } from "../../../context-engine/types.js";
 import type { AssistantMessage } from "../../../llm/types.js";
 import type { BootstrapMode } from "../../bootstrap-mode.js";
diff --git a/src/agents/embedded-agent-runner/run/attempt.llm-boundary.ts b/src/agents/embedded-agent-runner/run/attempt.llm-boundary.ts
@@ -1,3 +1,6 @@
+/**
+ * Installs runtime-context and prompt-transform boundaries before LLM calls.
+ */
 import { stripInboundMetadata } from "../../../auto-reply/reply/strip-inbound-meta.js";
 import { stripHistoricalRuntimeContextCustomMessages } from "../../internal-runtime-context.js";
 import type { AgentMessage } from "../../runtime/index.js";

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,6 @@`
	`1`	`+/**`
	`2`	`+ * AbortSignal-aware promise racing helper for embedded-agent attempts.`
	`3`	`+ */`
`1`	`4`	`function getAbortReason(signal: AbortSignal): unknown {`
`2`	`5`	`return "reason" in signal ? (signal as { reason?: unknown }).reason : undefined;`
`3`	`6`	`}`
-Original file line number
+Diff line change
@@ @@ -1,3 +1,6 @@ @@
 +/**
 + * Creates embedded-agent sessions with the runner resource loader installed.
 + */
 import type { CreateAgentSessionOptions } from "../../sessions/index.js";
 /**