docs: document runner failover helpers

src/agents/embedded-agent-runner/run/auth-controller.ts

@@ -1,3 +1,6 @@
+/**
+ * Coordinates provider auth, profile rotation, and runtime auth refresh.
+ */
 import type { ThinkLevel } from "../../../auto-reply/thinking.js";
 import { formatErrorMessage } from "../../../infra/errors.js";
 import type { Model } from "../../../llm/types.js";

src/agents/embedded-agent-runner/run/auth-profile-failure-policy.ts

@@ -1,3 +1,6 @@
+/**
+ * Resolves why an auth profile failed during provider auth selection.
+ */
 import type { AuthProfileFailureReason } from "../../auth-profiles/types.js";
 import type { FailoverReason } from "../../embedded-agent-helpers/types.js";
 import type { AuthProfileFailurePolicy } from "./auth-profile-failure-policy.types.js";

src/agents/embedded-agent-runner/run/backend.ts

@@ -1,3 +1,6 @@
+/**
+ * Dispatches embedded attempts to native harness or OpenClaw backend execution.
+ */
 import { runAgentHarnessAttempt } from "../../harness/selection.js";
 import type { EmbeddedRunAttemptParams, EmbeddedRunAttemptResult } from "./types.js";
 

src/agents/embedded-agent-runner/run/codex-app-server-recovery.ts

@@ -1,3 +1,6 @@
+/**
+ * Detects Codex app-server failures that should retry with recovery.
+ */
 import type { EmbeddedRunAttemptResult } from "./types.js";
 
 /**

src/agents/embedded-agent-runner/run/compaction-retry-aggregate-timeout.ts

@@ -1,3 +1,6 @@
+/**
+ * Caps compaction retry waits against the aggregate run timeout.
+ */
 import { resolveTimerTimeoutMs } from "@openclaw/normalization-core/number-coercion";
 
 /**

src/agents/embedded-agent-runner/run/compaction-timeout.ts

@@ -1,3 +1,6 @@
+/**
+ * Computes run timeout behavior while compaction is in progress.
+ */
 import type { AgentMessage } from "../../runtime/index.js";
 
 /** Timeout state used to distinguish normal run deadlines from compaction stalls. */

src/agents/embedded-agent-runner/run/failover-observation.ts

@@ -1,3 +1,6 @@
+/**
+ * Logs redacted failover decisions for embedded-agent attempts.
+ */
 import { redactIdentifier } from "../../../logging/redact-identifier.js";
 import type { AuthProfileFailureReason } from "../../auth-profiles.js";
 import {

src/agents/embedded-agent-runner/run/failover-policy.ts

@@ -1,3 +1,6 @@
+/**
+ * Resolves retry, fallback, and terminal failover decisions for a run.
+ */
 import type { FailoverReason } from "../../embedded-agent-helpers.js";
 
 /** Failover action selected for one embedded run failure decision point. */

src/agents/embedded-agent-runner/run/fallbacks.ts

@@ -1,3 +1,6 @@
+/**
+ * Reads configured embedded-run model fallback availability.
+ */
 import type { OpenClawConfig } from "../../../config/types.openclaw.js";
 import { hasConfiguredModelFallbacks } from "../../agent-scope.js";
 

src/agents/embedded-agent-runner/run/helpers.ts

@@ -1,3 +1,6 @@
+/**
+ * Shared run helpers for retry limits, model reporting, and final text.
+ */
 import type { OpenClawConfig } from "../../../config/types.openclaw.js";
 import { generateSecureToken } from "../../../infra/secure-random.js";
 import type { AssistantMessage } from "../../../llm/types.js";

src/agents/embedded-agent-runner/run/history-image-prune.ts

@@ -1,3 +1,6 @@
+/**
+ * Prunes already-processed image payloads from replayed prompt history.
+ */
 import type { AgentMessage } from "../../runtime/index.js";
 
 /** Replacement text for old image blocks that were already available to the model. */

src/agents/embedded-agent-runner/run/images.ts

@@ -1,3 +1,6 @@
+/**
+ * Detects, resolves, and loads prompt image references for model input.
+ */
 import path from "node:path";
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import { formatErrorMessage } from "../../../infra/errors.js";

src/agents/embedded-agent-runner/run/incomplete-turn.ts

@@ -1,3 +1,6 @@
+/**
+ * Classifies incomplete terminal assistant turns and retry instructions.
+ */
 import { asFiniteNumber } from "@openclaw/normalization-core/number-coercion";
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import { normalizeStringEntries } from "@openclaw/normalization-core/string-normalization";

src/agents/embedded-agent-runner/run/llm-idle-timeout.ts

@@ -1,3 +1,6 @@
+/**
+ * Wraps LLM streams with idle-timeout detection and diagnostics.
+ */
 import {
   finiteSecondsToTimerSafeMilliseconds,
   clampTimerTimeoutMs,