From f5ccfb73193eedf8735f1ef438a07f937ec18ae4 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 4 Jun 2026 09:32:25 -0400 Subject: [PATCH] docs: document runner attempt helpers --- src/agents/embedded-agent-runner/run/abortable.ts | 3 +++ src/agents/embedded-agent-runner/run/assistant-failover.ts | 3 +++ src/agents/embedded-agent-runner/run/attempt-abort.ts | 3 +++ .../embedded-agent-runner/run/attempt-bootstrap-routing.ts | 3 +++ src/agents/embedded-agent-runner/run/attempt-http-runtime.ts | 3 +++ src/agents/embedded-agent-runner/run/attempt-session.ts | 3 +++ src/agents/embedded-agent-runner/run/attempt-system-prompt.ts | 3 +++ .../run/attempt-tool-construction-plan.ts | 3 +++ .../run/attempt-trajectory-flush-cleanup.ts | 3 +++ .../embedded-agent-runner/run/attempt-trajectory-status.ts | 3 +++ .../embedded-agent-runner/run/attempt.abort-settle-timeout.ts | 3 +++ src/agents/embedded-agent-runner/run/attempt.async-tasks.ts | 3 +++ .../embedded-agent-runner/run/attempt.bootstrap-context.ts | 3 +++ .../run/attempt.context-engine-helpers.ts | 3 +++ src/agents/embedded-agent-runner/run/attempt.llm-boundary.ts | 3 +++ 15 files changed, 45 insertions(+) diff --git a/src/agents/embedded-agent-runner/run/abortable.ts b/src/agents/embedded-agent-runner/run/abortable.ts index 4d5d275c8280..9ed2c3c847a7 100644 --- 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 index a27f33122ec8..250f35f3bde9 100644 --- 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 index ce67cbcb9583..4d69b7496409 100644 --- 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 index 70bfa63b2ec8..378737f34bb6 100644 --- 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 index 21d7a1081353..427e60e373bd 100644 --- 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 index afab90998e21..4f7997124412 100644 --- 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 index ca67e19977b9..7c7113da9116 100644 --- 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 index b0106b999aae..126f471f493f 100644 --- 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 index 24ad8f17b250..ac702a457c14 100644 --- 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 index f8d6f79a521f..4f0f025ebde7 100644 --- 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 index be45d592bc00..182c6a3c20b9 100644 --- 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 index 250c7dc78ac2..e2efe71bce9d 100644 --- 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 index 596536c8eafd..1d974d353cc0 100644 --- 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 index 30707958b8c2..084053cf9408 100644 --- 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 index 90d962f25429..0d83b1c847a3 100644 --- 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";