docs: document runner attempt helpers

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;
 }

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";

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 = {

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";

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,

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";
 
 /**

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";

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";

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. */

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,

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<

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";

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";

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";

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";