@agent-native/core 0.169.1 → 0.170.0

package/dist/agent/production-agent.js

@@ -2,8 +2,8 @@ import { randomUUID } from "node:crypto";
 import Ajv from "ajv";
 import { defineEventHandler, getHeader, setResponseHeader, setResponseStatus, getMethod, } from "h3";
 import { parseA2AAgentActivityPart } from "../a2a/activity.js";
-import { describeToolParameterSignature, isAgentActionStopError, stripUnsupportedSchemaKeywords, } from "../action.js";
-import { ACTION_PREPARATION_NO_PROGRESS_TIMEOUT_MS, MAX_BACKGROUND_RUN_CONTINUATIONS, MAX_CONSECUTIVE_NO_PROGRESS_CONTINUATIONS, MAX_TURN_WALL_CLOCK_MS, MODEL_STREAM_NO_PROGRESS_TIMEOUT_MS, } from "../app-config/run-lifecycle-invariants.js";
+import { describeToolParameterSignature, isActionHiddenFromEveryAgentSurface, isAgentActionStopError, stripUnsupportedSchemaKeywords, } from "../action.js";
+import { MAX_BACKGROUND_RUN_CONTINUATIONS, MAX_CONSECUTIVE_NO_PROGRESS_CONTINUATIONS, MAX_TURN_WALL_CLOCK_MS, } from "../app-config/run-lifecycle-invariants.js";
 import { readAppState } from "../application-state/script-helpers.js";
 import { isReadOnlyShellCommand } from "../coding-tools/index.js";
 import { getDbExec, isTransientDatabaseError } from "../db/client.js";
@@ -746,7 +746,6 @@ function maxRetriesForError(err) {
     return MAX_RETRIES;
 }
 const TOOL_INPUT_ACTIVITY_INTERVAL_MS = 1500;
-const ACTION_PREPARATION_ZERO_BYTE_RESTART_LIMIT = 2;
 /**
  * How long an attempt must have run before its retry is worth narrating.
  *
@@ -2187,7 +2186,10 @@ export function actionsToEngineTools(actions) {
  */
 export async function executeAgentToolCall(options) {
     const entry = options.actions[options.name];
-    if (!entry || entry.agentTool === false) {
+    // The caller's registry is the surface: A2A hands this the external one, so
+    // reject only what no surface may run — an MCP-only action is `agentTool:
+    // false` and still legitimately callable here.
+    if (!entry || isActionHiddenFromEveryAgentSurface(entry)) {
         return {
             status: "failed",
             output: `Unknown or unavailable tool: ${options.name}`,
@@ -3286,12 +3288,22 @@ export async function runAgentLoop(opts) {
         : 0;
     // A per-tool timeout above the chunk's own soft timeout can never fire — the
     // chunk boundary always wins — so the 12-minute default is dead code on a
-    // ~40s hosted foreground chunk. Background-function runs resolve to a ~13min
-    // ceiling and keep the default unchanged.
-    const runToolTimeoutCeilingMs = resolveRunToolTimeoutCeilingMs(resolveRunSoftTimeoutMs(undefined, {
-        useHostedDefault: true,
-        backgroundFunction: isInBackgroundFunctionRuntime(),
-    }));
+    // ~40s hosted foreground chunk.
+    //
+    // TAKEN FROM THE CALLER'S ACTUAL BUDGET, not re-derived. Re-deriving it asked
+    // `resolveRunSoftTimeoutMs` for the generic background ceiling (13 min) even
+    // when the caller was a background AUTOMATION, whose real budget is its own
+    // hard abort minus headroom (10 min − 20s = 9m40s via
+    // `resolveBackgroundAutomationSoftTimeoutMs`). The ceiling came out ABOVE the
+    // run budget, so every per-tool timeout on that path was dead code and the
+    // chunk boundary won instead — which is the exact failure
+    // `RUN_TOOL_TIMEOUT_HEADROOM_MS` exists to prevent, reintroduced by guessing
+    // at a number the caller already knew.
+    const runToolTimeoutCeilingMs = resolveRunToolTimeoutCeilingMs(opts.runSoftTimeoutMs ??
+        resolveRunSoftTimeoutMs(undefined, {
+            useHostedDefault: true,
+            backgroundFunction: isInBackgroundFunctionRuntime(),
+        }));
     const toolCallHistory = [];
     const sourceSweepToolCallHistory = seedSourceSweepToolCallsFromHistory(messages, actions);
     let sourceSweepDelegationGuardActive = hasExhaustedSourceSweepBudget({
@@ -3495,7 +3507,6 @@ export async function runAgentLoop(opts) {
                 const toolInputBytes = new Map();
                 let lastToolInputActivityAt = 0;
                 const activeToolInputs = new Map();
-                let zeroByteToolInputRestart;
                 let endedForNoProgress = false;
                 // Bracket the engine call for the run manager's no-progress backstop
                 // (`inFlightWorkDelta` in run-manager.ts). That backstop measures the
@@ -3547,48 +3558,55 @@ export async function runAgentLoop(opts) {
                         ...(typeof progressBytes === "number" ? { progressBytes } : {}),
                     });
                 };
-                const actionPreparationDeadlineAt = () => {
-                    let deadlineAt = Number.POSITIVE_INFINITY;
-                    if (zeroByteToolInputRestart) {
-                        deadlineAt = Math.min(deadlineAt, zeroByteToolInputRestart.firstStartedAt +
-                            ACTION_PREPARATION_NO_PROGRESS_TIMEOUT_MS);
-                    }
-                    let earliestStartedAt = Number.POSITIVE_INFINITY;
-                    let latestPositiveProgressAt = 0;
-                    for (const active of activeToolInputs.values()) {
-                        if (active.startedAt < earliestStartedAt) {
-                            earliestStartedAt = active.startedAt;
-                        }
-                        if (active.bytes > 0 &&
-                            active.lastProgressAt > latestPositiveProgressAt) {
-                            latestPositiveProgressAt = active.lastProgressAt;
-                        }
-                    }
-                    const progressAt = latestPositiveProgressAt > 0
-                        ? latestPositiveProgressAt
-                        : earliestStartedAt;
-                    if (Number.isFinite(progressAt)) {
-                        deadlineAt = Math.min(deadlineAt, progressAt + ACTION_PREPARATION_NO_PROGRESS_TIMEOUT_MS);
-                    }
-                    return Number.isFinite(deadlineAt) ? deadlineAt : undefined;
-                };
-                const modelStreamNoProgressDeadlineAt = () => {
-                    const baseDeadlineAt = lastModelStreamProgressAt + MODEL_STREAM_NO_PROGRESS_TIMEOUT_MS;
-                    // FIX 2: cap the FIRST event's deadline tighter on the clamped
-                    // foreground runtime — see FOREGROUND_FIRST_MODEL_EVENT_TIMEOUT_MS
-                    // for the ordering invariant this protects.
+                /**
+                 * The ONLY in-loop stall bound left, and it covers exactly one thing:
+                 * a model call whose stream opened and produced NOTHING AT ALL.
+                 *
+                 * WHAT WAS HERE, AND WHY IT IS GONE. Two 90s watchdogs used to run for
+                 * the whole stream — one on silence between engine frames, one on a
+                 * tool input whose byte count stopped growing — plus a zero-byte
+                 * restart tripwire. Each inferred death from the ABSENCE of a
+                 * particular event, and that inference is unsound on this transport:
+                 * the Anthropic SDK drops the provider's `ping` keepalives before they
+                 * reach any consumer (`core/streaming.js`: `if (sse.event === 'ping')
+                 * continue;`, with no opt-out), so a healthy stream mid-generation is
+                 * byte-for-byte indistinguishable from a wedged one.
+                 *
+                 * That is not an edge case, it is normal operation. A tool whose input
+                 * is not eagerly streamed emits no `input_json_delta` at all while the
+                 * provider composes its arguments, so writing a large file or filing a
+                 * long structured result is a content-silent window whose length is set
+                 * by the size of the argument. Production bore it out: of 27 one-shot
+                 * analyst runs, 2 completed. Guards added for reliability were the
+                 * thing taking it away.
+                 *
+                 * WHAT STILL CATCHES A REAL WEDGE — none of which can fire on
+                 * slow-but-healthy work:
+                 *   • the engine's own first-event abort
+                 *     (`FIRST_STREAM_EVENT_TIMEOUT_MS`, 120s): a connection that opens
+                 *     and never speaks
+                 *   • the engine's total-stream deadline (`STREAM_TOTAL_TIMEOUT_MS`,
+                 *     14min): one model call end to end, which is what bounds a socket
+                 *     that wedges MID-stream on the runtimes with no outer budget
+                 *     (local dev and self-hosted resolve the soft timeout to 0)
+                 *   • the run-manager backstop, for the segments OUTSIDE the stream
+                 *     (`inFlightWorkDelta` suspends it while the stream is open)
+                 *   • the per-tool timeout, which bounds tool EXECUTION at the tool
+                 *   • the chunk / run budget, which bounds COST rather than health
+                 *   • the stale reaper, which bounds worker liveness
+                 *
+                 * The cap below survives only because it guards the "nothing has
+                 * happened yet" window on the clamped hosted FOREGROUND runtime, where
+                 * the ~57s platform wall arrives before the engine's 120s bound could.
+                 * The first real frame releases it, so long thinking, long tool inputs
+                 * and long outputs are all past it by construction.
+                 */
+                const noProgressDeadlineAt = () => {
                     if (hasReceivedFirstEngineEvent ||
                         !isClampedForegroundRuntimeForThisCall) {
-                        return baseDeadlineAt;
+                        return Number.POSITIVE_INFINITY;
                     }
-                    return Math.min(baseDeadlineAt, lastModelStreamProgressAt + FOREGROUND_FIRST_MODEL_EVENT_TIMEOUT_MS);
-                };
-                const noProgressDeadlineAt = () => {
-                    const actionDeadlineAt = actionPreparationDeadlineAt();
-                    const modelDeadlineAt = modelStreamNoProgressDeadlineAt();
-                    return actionDeadlineAt === undefined
-                        ? modelDeadlineAt
-                        : Math.min(actionDeadlineAt, modelDeadlineAt);
+                    return (lastModelStreamProgressAt + FOREGROUND_FIRST_MODEL_EVENT_TIMEOUT_MS);
                 };
                 const hasNoProgressStalled = () => Date.now() >= noProgressDeadlineAt();
                 const checkpointNoProgress = () => {
@@ -3624,6 +3642,14 @@ export async function runAgentLoop(opts) {
                 };
                 const nextEngineEventWithNoProgressTimeout = async (iterator) => {
                     const deadlineAt = noProgressDeadlineAt();
+                    // No deadline at all is the COMMON case now — every runtime except a
+                    // clamped hosted foreground call that has not yet seen its first
+                    // frame. Await the iterator directly rather than racing it: a
+                    // `setTimeout` of Infinity is coerced to 1ms by Node and would
+                    // checkpoint instantly, turning "no bound" into "the tightest bound
+                    // there is".
+                    if (!Number.isFinite(deadlineAt))
+                        return iterator.next();
                     const timeoutMs = Math.max(0, deadlineAt - Date.now());
                     if (timeoutMs <= 0) {
                         checkpointNoProgress();
@@ -3662,37 +3688,6 @@ export async function runAgentLoop(opts) {
                         bytes,
                     });
                 };
-                const resetZeroByteToolInputRestart = (toolName) => {
-                    if (!zeroByteToolInputRestart)
-                        return;
-                    if (!toolName || zeroByteToolInputRestart.toolName === toolName) {
-                        zeroByteToolInputRestart = undefined;
-                    }
-                };
-                const noteZeroByteToolInputStart = (toolName) => {
-                    if (!toolName)
-                        return false;
-                    const now = Date.now();
-                    if (zeroByteToolInputRestart?.toolName === toolName) {
-                        zeroByteToolInputRestart = {
-                            ...zeroByteToolInputRestart,
-                            lastStartedAt: now,
-                            count: zeroByteToolInputRestart.count + 1,
-                        };
-                    }
-                    else {
-                        zeroByteToolInputRestart = {
-                            toolName,
-                            firstStartedAt: now,
-                            lastStartedAt: now,
-                            count: 1,
-                        };
-                    }
-                    return (zeroByteToolInputRestart.count >=
-                        ACTION_PREPARATION_ZERO_BYTE_RESTART_LIMIT &&
-                        now - zeroByteToolInputRestart.firstStartedAt >=
-                            ACTION_PREPARATION_NO_PROGRESS_TIMEOUT_MS);
-                };
                 const eventIterator = eventStream[Symbol.asyncIterator]();
                 let eventIteratorDone = false;
                 openModelStreamBracket();
@@ -3734,7 +3729,6 @@ export async function runAgentLoop(opts) {
                             }
                         }
                         if (event.type === "text-delta") {
-                            resetZeroByteToolInputRestart();
                             streamedAssistantText += event.text;
                             send({ type: "text", text: event.text });
                         }
@@ -3758,17 +3752,12 @@ export async function runAgentLoop(opts) {
                                 ...(event.id ? { id: event.id } : {}),
                             });
                             sendToolInputActivity(event.name, key, undefined, true);
-                            if (noteZeroByteToolInputStart(event.name)) {
-                                checkpointNoProgress();
-                                break;
-                            }
                         }
                         else if (event.type === "tool-input-delta") {
                             const key = event.id ?? event.name;
                             const toolName = event.name ??
                                 (event.id ? toolInputNames.get(event.id) : undefined);
                             let progressBytes;
-                            let startedZeroByteInput = false;
                             if (key) {
                                 const hadByteRecord = toolInputBytes.has(key);
                                 const previous = hadByteRecord
@@ -3780,12 +3769,6 @@ export async function runAgentLoop(opts) {
                                 toolInputBytes.set(key, progressBytes);
                                 if (!hadByteRecord || progressBytes > previous) {
                                     trackActiveToolInput(key, toolName, progressBytes);
-                                    if (progressBytes > 0) {
-                                        resetZeroByteToolInputRestart();
-                                    }
-                                    else if (!hadByteRecord) {
-                                        startedZeroByteInput = true;
-                                    }
                                 }
                             }
                             if (event.text) {
@@ -3797,12 +3780,6 @@ export async function runAgentLoop(opts) {
                                 });
                             }
                             sendToolInputActivity(toolName, key, progressBytes);
-                            if (startedZeroByteInput &&
-                                toolName &&
-                                noteZeroByteToolInputStart(toolName)) {
-                                checkpointNoProgress();
-                                break;
-                            }
                         }
                         else if (event.type === "gateway-heartbeat") {
                             send({ type: "stream_keepalive" });
@@ -7801,6 +7778,20 @@ export function createProductionAgentHandler(options) {
                 backgroundFunction: false,
             }))
             : null;
+        // The budget this run ACTUALLY executes inside, resolved once and used by
+        // both `startRun` (which arms the chunk timer with it) and the agent loop
+        // (which clamps per-tool timeouts under it). Resolving it only inside
+        // `startRun` left the loop to re-derive a generic hosted/background
+        // ceiling, so an app-configured chunk shorter than that ceiling got
+        // per-tool timeouts longer than the chunk containing them — dead code, and
+        // the chunk boundary won instead. `resolveRunSoftTimeoutMs` clamps an
+        // already-resolved number to itself, so passing it back in is a no-op.
+        const resolvedRunSoftTimeoutMs = resolveRunSoftTimeoutMs(selfChainBudget && !selfChainBudget.skipToBoundary
+            ? selfChainBudget.softTimeoutMs
+            : options.runSoftTimeoutMs, {
+            useHostedDefault: true,
+            backgroundFunction: runsInBackgroundFunction,
+        });
         const startedRun = startRun(runId, effectiveThreadId, async (rawSend, signal) => {
             const send = (event) => {
                 rawSend(event);
@@ -7895,6 +7886,15 @@ export function createProductionAgentHandler(options) {
                             providerOptions: options.providerOptions,
                             executionMode: requestMode,
                             maxIterations: loopSettings.maxIterations,
+                            // Same `startRun` chunk and same signal as the main loop, so
+                            // the same budget. Left off, the loop re-derives the generic
+                            // hosted/background ceiling, which can sit above the chunk
+                            // these nested calls actually run inside — and then the
+                            // per-tool timeout is unreachable and the chunk boundary
+                            // preempts it.
+                            ...(resolvedRunSoftTimeoutMs > 0
+                                ? { runSoftTimeoutMs: resolvedRunSoftTimeoutMs }
+                                : {}),
                         });
                         // Attribute custom-agent sub-calls under their own label
                         // so the Usage panel separates them from the main chat.
@@ -8054,6 +8054,13 @@ export function createProductionAgentHandler(options) {
                 priorTurnInputTokens: turnInputTokens,
                 finalResponseGuard: options.finalResponseGuard,
                 finalResponseGuardRequestText: messageToPersist,
+                // The chunk this loop is running inside, so a per-tool timeout is
+                // clamped under the budget it can actually spend rather than under a
+                // re-derived generic ceiling. `0` (local dev) keeps the loop's own
+                // fallback.
+                ...(resolvedRunSoftTimeoutMs > 0
+                    ? { runSoftTimeoutMs: resolvedRunSoftTimeoutMs }
+                    : {}),
                 ...(options.toolLimits ? { toolLimits: options.toolLimits } : {}),
                 ...(threadId
                     ? { threadId: effectiveThreadId, turnId: effectiveTurnId }
@@ -8216,9 +8223,7 @@ export function createProductionAgentHandler(options) {
             // (durable-background worker, plain foreground POST) is unaffected:
             // `selfChainBudget` is `null` for them and this falls through to the
             // exact prior value.
-            softTimeoutMs: selfChainBudget && !selfChainBudget.skipToBoundary
-                ? selfChainBudget.softTimeoutMs
-                : options.runSoftTimeoutMs,
+            softTimeoutMs: resolvedRunSoftTimeoutMs,
             useHostedSoftTimeoutDefault: true,
             // Lift the soft-timeout clamp to ~13min ONLY when this run is actually
             // executing inside a real Netlify `-background` function (15-min budget,

package/dist/agent/run-loop-with-resume.d.ts

@@ -20,6 +20,7 @@
  * Both paths route through `appendAgentLoopContinuation` so the agent sees a
  * uniform "continue" instruction regardless of which recovery fired.
  */
+import { SERVER_OWNED_ABORT_REASONS, clientAbortReason } from "./abort-reasons.js";
 import type { EngineMessage } from "./engine/types.js";
 import { runAgentLoop, type AgentLoopContinuationReason } from "./production-agent.js";
 import type { ResolveRunSoftTimeoutOptions, RunChunkControl } from "./run-manager.js";
@@ -38,34 +39,7 @@ export declare function appendDurableContinuationContext(messages: EngineMessage
  */
 export declare const MAX_BACKGROUND_RATE_LIMIT_CONTINUATIONS = 1;
 export declare const BACKGROUND_RATE_LIMIT_CONTINUATION_DELAY_MS = 20000;
-/**
- * Abort reasons the SERVER sets on a run's own controller. Everything else —
- * including any reason a client passes to the abort route — is a user Stop.
- *
- * Kept deliberately short. Each entry is a bound this package owns and can name
- * in a terminal outcome; if you are adding a fourth, check first whether the
- * bound belongs in `run-manager.ts` at all.
- *
- * Exported so the abort route can refuse these words from a client. That check
- * belongs at the boundary where untrusted input enters, not here: by the time a
- * reason reaches an `AbortSignal` it is just a string, and nothing downstream
- * can tell who wrote it.
- */
-export declare const SERVER_OWNED_ABORT_REASONS: Set<string>;
-/**
- * The abort reason to record for a client-initiated Stop.
- *
- * A caller reaching the abort route is a person pressing Stop, so it must not
- * be able to name a bound only the server can reach: the terminal outcome keys
- * off the abort reason, and a client sending `background_automation_hard_timeout`
- * would file its own Stop as a server-side failure. Anything unrecognised,
- * malformed, or reserved falls back to `"user"`.
- *
- * Normalised here rather than in the route because this is where the meaning of
- * the string is decided — downstream it is just a string, and nothing can tell
- * who wrote it.
- */
-export declare function clientAbortReason(raw: unknown): string;
+export { SERVER_OWNED_ABORT_REASONS, clientAbortReason };
 /** Machine-readable code carried on the give-up terminal `error` event so the
  * client renders a loud "stopped before finishing" terminal instead of an
  * ambiguous silent stall. Deliberately NOT in the client's auto-recoverable

package/dist/agent/run-loop-with-resume.js

@@ -21,6 +21,7 @@
  * uniform "continue" instruction regardless of which recovery fired.
  */
 import { MAX_BACKGROUND_RUN_LOOP_CONTINUATIONS, MAX_RUN_LOOP_CONTINUATIONS, } from "../app-config/run-lifecycle-invariants.js";
+import { SERVER_OWNED_ABORT_REASONS, clientAbortReason, } from "./abort-reasons.js";
 import { runAgentLoop, appendAgentLoopContinuation, isResumableEngineError, isTransientProviderRateLimitError, continuationReasonForResumableError, lastUnfinishedPreparingActionToolFromEvents, resolveFinalResponseGuardRequestText, SELF_CHAIN_MIN_CONTINUATION_BUDGET_MS, } from "./production-agent.js";
 import { resolveRunSoftTimeoutMs } from "./run-manager.js";
 import { getCurrentTurnEventsForThread } from "./run-store.js";
@@ -194,45 +195,10 @@ function waitForBackgroundRateLimitCooldown(signal) {
         signal.addEventListener("abort", finish, { once: true });
     });
 }
-/**
- * Abort reasons the SERVER sets on a run's own controller. Everything else —
- * including any reason a client passes to the abort route — is a user Stop.
- *
- * Kept deliberately short. Each entry is a bound this package owns and can name
- * in a terminal outcome; if you are adding a fourth, check first whether the
- * bound belongs in `run-manager.ts` at all.
- *
- * Exported so the abort route can refuse these words from a client. That check
- * belongs at the boundary where untrusted input enters, not here: by the time a
- * reason reaches an `AbortSignal` it is just a string, and nothing downstream
- * can tell who wrote it.
- */
-export const SERVER_OWNED_ABORT_REASONS = new Set([
-    "no_progress",
-    "run_timeout",
-    "background_automation_hard_timeout",
-]);
-/**
- * The abort reason to record for a client-initiated Stop.
- *
- * A caller reaching the abort route is a person pressing Stop, so it must not
- * be able to name a bound only the server can reach: the terminal outcome keys
- * off the abort reason, and a client sending `background_automation_hard_timeout`
- * would file its own Stop as a server-side failure. Anything unrecognised,
- * malformed, or reserved falls back to `"user"`.
- *
- * Normalised here rather than in the route because this is where the meaning of
- * the string is decided — downstream it is just a string, and nothing can tell
- * who wrote it.
- */
-export function clientAbortReason(raw) {
-    if (typeof raw !== "string")
-        return "user";
-    const reason = raw.trim();
-    if (!/^[a-z0-9_-]{1,64}$/i.test(reason))
-        return "user";
-    return SERVER_OWNED_ABORT_REASONS.has(reason.toLowerCase()) ? "user" : reason;
-}
+// Re-exported from the leaf module so existing importers keep working. Callers
+// that need ONLY these two symbols must import `./abort-reasons.js` directly —
+// reaching them through this module drags the whole run loop into their graph.
+export { SERVER_OWNED_ABORT_REASONS, clientAbortReason };
 /** Machine-readable code carried on the give-up terminal `error` event so the
  * client renders a loud "stopped before finishing" terminal instead of an
  * ambiguous silent stall. Deliberately NOT in the client's auto-recoverable
@@ -268,8 +234,19 @@ export async function runAgentLoopDirectWithSoftTimeout(opts, softTimeoutMs, tim
 control) {
     const finalResponseGuardRequestText = opts.finalResponseGuardRequestText ??
         resolveFinalResponseGuardRequestText(opts.messages);
-    const stableOpts = { ...opts, finalResponseGuardRequestText };
     const timeoutMs = resolveRunSoftTimeoutMs(softTimeoutMs, timeoutOptions);
+    // Hand the loop the budget it is ACTUALLY running inside, so a per-tool
+    // timeout is clamped under this chunk rather than under a re-derived generic
+    // ceiling. A background automation's budget is its own hard abort minus
+    // headroom and is materially smaller than the background chat ceiling; the
+    // loop had no way to know that and guessed high, which made every per-tool
+    // timeout on that path unreachable. `0` means "no soft-timeout regime"
+    // (local dev), where the loop's own fallback is the right answer.
+    const stableOpts = {
+        ...opts,
+        finalResponseGuardRequestText,
+        ...(timeoutMs > 0 ? { runSoftTimeoutMs: timeoutMs } : {}),
+    };
     let finalOutcomeReported = false;
     const reportFinalOutcome = (outcome) => {
         if (finalOutcomeReported)
@@ -475,6 +452,14 @@ control) {
             let attemptOutcome;
             const nextUsage = await runAgentLoop({
                 ...stableOpts,
+                // THIS round's budget, not the invocation's. `stableOpts` carries the
+                // full `timeoutMs`, but round 2+ runs inside `roundTimeoutMs` — what
+                // is left after the earlier rounds spent wall-clock. Clamping a
+                // per-tool timeout against the full window puts it above the round
+                // that contains it, so the round timer wins and the per-tool timeout
+                // is unreachable — the same inversion `RUN_TOOL_TIMEOUT_HEADROOM_MS`
+                // exists to prevent, one scope down.
+                runSoftTimeoutMs: roundTimeoutMs,
                 send,
                 signal: controller.signal,
                 onOutcome: (outcome) => {

package/dist/agent/run-manager.js

@@ -140,10 +140,11 @@ export function resolveRunNoProgressTimeoutMs(params) {
  * Every pair listed here suspends the no-progress backstop for as long as it is
  * open, so each one MUST be bounded by a watchdog of its own — tool calls by
  * the per-tool timeout, cross-app calls by the A2A poll timeout, the model
- * stream by `MODEL_STREAM_NO_PROGRESS_TIMEOUT_MS`, which the agent loop races
- * against every wait for the next engine frame. A pair added here without such
- * a bound turns the backstop off for the rest of the run, which is strictly
- * worse than the stall it was meant to catch.
+ * stream by the engine's own first-event abort plus the chunk budget (the 90s
+ * in-loop watchdog that used to sit here is gone — see
+ * run-lifecycle-invariants.ts). A pair added here without SOME bound turns the
+ * backstop off for the rest of the run, which is strictly worse than the stall
+ * it was meant to catch.
  *
  * Note what that leaves: the model-stream bound covers waiting for the engine,
  * not a hang while the loop processes a frame it already has. Nothing here

package/dist/agent/run-store.d.ts

@@ -268,6 +268,43 @@ export declare function insertRun(id: string, threadId: string, turnId?: string,
      */
     dispatchPayload?: string;
 }): Promise<void>;
+/**
+ * Which stale window the reaper applied to a row, in ms.
+ *
+ * MIRRORS `backgroundAwareStaleCutoffSql`, which decides the same thing in SQL
+ * because it has to run inside the conditional UPDATE. Kept beside it and
+ * covered by a test asserting the three cases agree — a drift here reports the
+ * wrong window on a real incident, which is worse than reporting none.
+ */
+export declare function staleWindowMsForRow(row: {
+    dispatchMode?: string | null;
+    hasDispatchPayload?: boolean;
+    maxStaleMs?: number;
+}): number;
+/**
+ * The liveness forensics for one reap, as a compact `key=value` line.
+ *
+ * THE FIELD THAT MATTERS IS `hbAheadOfProgress`. A worker that died takes its
+ * heartbeat with it, so heartbeat and last-progress stop together and this is
+ * ~0. A worker still running while the agent loop stops producing keeps
+ * heartbeating, and this grows without bound — those are opposite bugs that
+ * look identical in `agent_runs` today. Production showed runs where the
+ * heartbeat ran 3,000s past the last progress; nothing recorded that, so
+ * nothing could act on it.
+ *
+ * Numbers, booleans and an enum only — no prompt, no result, no user content —
+ * so this obeys the same privacy rule as event properties and log lines.
+ */
+export declare function describeStaleReap(row: {
+    startedAt?: number | null;
+    heartbeatAt?: number | null;
+    lastProgressAt?: number | null;
+    inFlightSince?: number | null;
+    dispatchMode?: string | null;
+    hasDispatchPayload?: boolean;
+    maxStaleMs?: number;
+    now: number;
+}): string;
 /**
  * Atomically claim a background-dispatched run for processing. The foreground
  * POST inserts the run row with `dispatch_mode = 'background'`; the FIRST
@@ -480,6 +517,24 @@ export declare const RUN_DIAG_STAGE: {
      * no boundary previously recorded anywhere.
      */
     readonly runBoundaryReached: "run_boundary_reached";
+    /**
+     * A stale reaper flipped this run to `errored`. Detail carries the liveness
+     * forensics — see `describeStaleReap`.
+     *
+     * WHY THIS EXISTS. `stale_run` is the single largest terminal outcome on the
+     * one-shot automation path (14 of 27 runs in one production deployment) and
+     * the row records nothing about WHY: `error_detail` is a fixed sentence for
+     * every reap, so a correct reap and a false one are indistinguishable after
+     * the fact. Every question worth asking needed a number nobody stored — was
+     * the worker dead, or was it heartbeating happily while the loop stopped
+     * producing? which of the three stale windows fired? was the in-flight grace
+     * in play? One production run heartbeated 3,309s past a 600s hard abort and
+     * there is no way to tell from the row what kept it alive.
+     *
+     * Diagnostics only: nothing reads this to make a decision, and it cannot
+     * change whether a row is reaped.
+     */
+    readonly staleRunReaped: "stale_run_reaped";
 };
 export type RunDiagStage = (typeof RUN_DIAG_STAGE)[keyof typeof RUN_DIAG_STAGE];
 /**