@agent-native/core 0.168.12 → 0.169.0

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

@@ -20,6 +20,7 @@
  * Both paths route through `appendAgentLoopContinuation` so the agent sees a
  * 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 { 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";
@@ -171,29 +172,6 @@ function internalContinuationReasonForAttempt(events) {
     }
     return undefined;
 }
-/**
- * Cap on continuation iterations inside a single
- * `runAgentLoopDirectWithSoftTimeout` invocation. The host's hard function
- * timeout usually bounds this naturally — but a defensive cap prevents an
- * instant-error spiral from looping forever inside hosting environments with a
- * generous budget.
- *
- * 6 leaves room for: 1 normal completion + a few resume rounds for design
- * generation (prompt + 3 variants ≈ 4 LLM calls), with a small safety margin.
- */
-export const MAX_RUN_LOOP_CONTINUATIONS = 6;
-/**
- * A delegated turn that is proven to be running inside a durable background
- * function has the same 15-minute host budget as main chat, but this wrapper
- * historically kept the foreground-sized six-continuation cap. A healthy
- * child A2A call can consume several minutes and the receiving model may then
- * need more than six recovery/model-stream boundaries to finish its own tool
- * work. Keep a hard cap, but give the proven background path the same bounded
- * continuation allowance as the durable main-chat runner. The cumulative
- * soft-timeout below still prevents these rounds from exceeding the one real
- * background-function wall-clock budget.
- */
-export const MAX_BACKGROUND_RUN_LOOP_CONTINUATIONS = 20;
 /**
  * The engine already performs its own short provider retries. After those are
  * exhausted, a proven durable background A2A/MCP run gets one cooled-down
@@ -216,6 +194,45 @@ 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;
+}
 /** 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
@@ -240,7 +257,15 @@ export const RUN_BUDGET_EXHAUSTED_MESSAGE = "I ran out of time before finishing
  * an appropriate inner budget. Setting it to <= 0 disables both layers — the
  * call goes straight to `runAgentLoop` with no wrapping.
  */
-export async function runAgentLoopDirectWithSoftTimeout(opts, softTimeoutMs, timeoutOptions) {
+export async function runAgentLoopDirectWithSoftTimeout(opts, softTimeoutMs, timeoutOptions, 
+/**
+ * Chunk control from `startRun`, for a caller that owns continuation inside
+ * this invocation. Without it `opts.signal` is the only signal there is, so a
+ * checkpoint fired from ABOVE this loop reads as a Stop and the recovery
+ * below — which already accepts `no_progress` and already has a 20-round
+ * background budget — is unreachable.
+ */
+control) {
     const finalResponseGuardRequestText = opts.finalResponseGuardRequestText ??
         resolveFinalResponseGuardRequestText(opts.messages);
     const stableOpts = { ...opts, finalResponseGuardRequestText };
@@ -260,6 +285,40 @@ export async function runAgentLoopDirectWithSoftTimeout(opts, softTimeoutMs, tim
     // Disabling continuation recovery must not disable terminal classification.
     // Keep the same outcome boundary around a direct loop so A2A/MCP callers
     // never infer success from a rejected or canceled run.
+    const turnSignal = control?.turnSignal ?? opts.signal;
+    /**
+     * A turn someone pressed Stop on is `canceled`. A turn that ended because a
+     * SERVER bound fired is not: nobody cancelled it, it ran out of something,
+     * and the abort reason says which.
+     *
+     * Reporting both as `canceled` made a hard-timed-out automation
+     * byte-identical to a user Stop in every consumer, `$ai_error` included, and
+     * contradicted the no-timeout path above, which has always reported an
+     * unfinished reason as `failed` with that reason as its code.
+     *
+     * Allowlisted rather than "anything that isn't `user`", because the abort
+     * route accepts a client-supplied reason string: an inverted test would
+     * relabel a genuine Stop the moment a caller sent its own word for it.
+     */
+    const turnAbortOutcome = () => {
+        const reason = typeof turnSignal.reason === "string" ? turnSignal.reason.trim() : "";
+        if (!SERVER_OWNED_ABORT_REASONS.has(reason)) {
+            return { state: "canceled", message: "Agent run was aborted." };
+        }
+        return {
+            state: "failed",
+            code: reason,
+            retryable: false,
+            message: `Agent run was aborted (${reason}).`,
+        };
+    };
+    let chunkSignal = control?.chunkSignal ?? opts.signal;
+    const recoverableChunkBoundary = () => {
+        if (!control || turnSignal.aborted)
+            return null;
+        const reason = control.chunkBoundaryReason();
+        return reason === "no_progress" || reason === "run_timeout" ? reason : null;
+    };
     if (timeoutMs <= 0) {
         const directEvents = [];
         let directOutcome;
@@ -275,11 +334,8 @@ export async function runAgentLoopDirectWithSoftTimeout(opts, softTimeoutMs, tim
                 },
             });
             const unfinishedReason = internalContinuationReasonForAttempt(directEvents);
-            if (opts.signal.aborted) {
-                reportFinalOutcome({
-                    state: "canceled",
-                    message: "Agent run was aborted.",
-                });
+            if (turnSignal.aborted) {
+                reportFinalOutcome(turnAbortOutcome());
             }
             else if (unfinishedReason) {
                 reportFinalOutcome({
@@ -296,8 +352,8 @@ export async function runAgentLoopDirectWithSoftTimeout(opts, softTimeoutMs, tim
         }
         catch (err) {
             const candidate = err;
-            reportFinalOutcome(opts.signal.aborted
-                ? { state: "canceled", message: "Agent run was aborted." }
+            reportFinalOutcome(turnSignal.aborted
+                ? turnAbortOutcome()
                 : {
                     state: "failed",
                     code: typeof candidate?.errorCode === "string" && candidate.errorCode
@@ -311,7 +367,10 @@ export async function runAgentLoopDirectWithSoftTimeout(opts, softTimeoutMs, tim
             throw err;
         }
     }
-    const upstreamSignal = opts.signal;
+    // `turnSignal` answers "is this turn over?"; `chunkSignal` answers "is this
+    // ROUND over?". They are the same object for every caller that does not pass
+    // a control, which is what keeps the foreground/HTTP paths byte-for-byte
+    // unchanged.
     const usage = {
         inputTokens: 0,
         outputTokens: 0,
@@ -333,6 +392,23 @@ export async function runAgentLoopDirectWithSoftTimeout(opts, softTimeoutMs, tim
         usage.firstEngineEventAtMs ??= next.firstEngineEventAtMs;
     };
     const localTurnEvents = [];
+    /**
+     * Recover a boundary the run manager decided from OUTSIDE this loop.
+     *
+     * Same treatment the loop's own `auto_continue` gets: drop partial text the
+     * client already saw (unless a side effect landed, whose tool card is the
+     * user's only proof), append the continuation context and tool-call journal,
+     * then open a fresh chunk. Not opening one would leave every later round
+     * running under an already-aborted signal, which fails instantly and looks
+     * exactly like the bug this replaces.
+     */
+    const continueFromChunkBoundary = async (reason, attemptEvents) => {
+        if ((await completedSideEffectInCurrentTurn(opts.threadId, opts.turnId, localTurnEvents)) === "none") {
+            opts.send({ type: "clear" });
+        }
+        await appendContinuationAndJournal(opts.messages, reason, opts.threadId, opts.turnId, localTurnEvents, [...attemptEvents]);
+        chunkSignal = control?.beginChunk() ?? chunkSignal;
+    };
     let attempts = 0;
     // Every current hosted caller of this function (A2A/MCP delegated turns)
     // runs inside ONE serverless invocation whose real platform hard-kill is
@@ -357,7 +433,7 @@ export async function runAgentLoopDirectWithSoftTimeout(opts, softTimeoutMs, tim
     // this is the silent give-up case: emit a loud terminal so the user sees an
     // unambiguous "stopped before finishing" instead of a bare done/"…".
     let lastAttemptWasUnfinishedContinuation = false;
-    while (!upstreamSignal.aborted && attempts < maxRunLoopContinuations) {
+    while (!turnSignal.aborted && attempts < maxRunLoopContinuations) {
         const roundTimeoutMs = attempts === 0 ? timeoutMs : timeoutMs - (Date.now() - loopEntryAt);
         if (attempts > 0 &&
             roundTimeoutMs < SELF_CHAIN_MIN_CONTINUATION_BUDGET_MS) {
@@ -372,11 +448,14 @@ export async function runAgentLoopDirectWithSoftTimeout(opts, softTimeoutMs, tim
         lastAttemptWasUnfinishedContinuation = false;
         const controller = new AbortController();
         const abortFromUpstream = () => controller.abort();
-        if (upstreamSignal.aborted) {
+        // Bound to the CURRENT chunk. A turn abort still reaches it — the run
+        // manager ends the live chunk whenever the turn ends.
+        const roundChunkSignal = chunkSignal;
+        if (roundChunkSignal.aborted) {
             controller.abort();
         }
         else {
-            upstreamSignal.addEventListener("abort", abortFromUpstream, {
+            roundChunkSignal.addEventListener("abort", abortFromUpstream, {
                 once: true,
             });
         }
@@ -404,8 +483,14 @@ export async function runAgentLoopDirectWithSoftTimeout(opts, softTimeoutMs, tim
             });
             addUsage(nextUsage);
             const attemptEvents = localTurnEvents.slice(attemptStartIndex);
+            const chunkBoundaryReason = recoverableChunkBoundary();
+            if (chunkBoundaryReason) {
+                lastAttemptWasUnfinishedContinuation = true;
+                await continueFromChunkBoundary(chunkBoundaryReason, attemptEvents);
+                continue;
+            }
             const internalContinuationReason = internalContinuationReasonForAttempt(attemptEvents);
-            if (internalContinuationReason && !upstreamSignal.aborted) {
+            if (internalContinuationReason && !turnSignal.aborted) {
                 lastAttemptWasUnfinishedContinuation = true;
                 const continuationEvents = [...localTurnEvents];
                 if ((await completedSideEffectInCurrentTurn(opts.threadId, opts.turnId, continuationEvents)) === "none") {
@@ -414,18 +499,24 @@ export async function runAgentLoopDirectWithSoftTimeout(opts, softTimeoutMs, tim
                 await appendContinuationAndJournal(opts.messages, internalContinuationReason, opts.threadId, opts.turnId, continuationEvents, attemptEvents);
                 continue;
             }
-            if (softTimedOut && !upstreamSignal.aborted) {
+            if (softTimedOut && !turnSignal.aborted) {
                 lastAttemptWasUnfinishedContinuation = true;
                 await appendContinuationAndJournal(opts.messages, "run_timeout", opts.threadId, opts.turnId, localTurnEvents, attemptEvents);
                 continue;
             }
-            reportFinalOutcome(upstreamSignal.aborted
-                ? { state: "canceled", message: "Agent run was aborted." }
+            reportFinalOutcome(turnSignal.aborted
+                ? turnAbortOutcome()
                 : (attemptOutcome ?? { state: "completed" }));
             return usage;
         }
         catch (err) {
-            if (softTimedOut && !upstreamSignal.aborted) {
+            const chunkBoundaryReason = recoverableChunkBoundary();
+            if (chunkBoundaryReason) {
+                lastAttemptWasUnfinishedContinuation = true;
+                await continueFromChunkBoundary(chunkBoundaryReason, localTurnEvents.slice(attemptStartIndex));
+                continue;
+            }
+            if (softTimedOut && !turnSignal.aborted) {
                 // Clear partial text the client received before the abort so the
                 // resumed model doesn't re-emit it and produce duplicated output.
                 lastAttemptWasUnfinishedContinuation = true;
@@ -443,7 +534,7 @@ export async function runAgentLoopDirectWithSoftTimeout(opts, softTimeoutMs, tim
                     (Date.now() - loopEntryAt) -
                     BACKGROUND_RATE_LIMIT_CONTINUATION_DELAY_MS >=
                     SELF_CHAIN_MIN_CONTINUATION_BUDGET_MS;
-            if (!upstreamSignal.aborted &&
+            if (!turnSignal.aborted &&
                 transientRateLimit &&
                 rateLimitRetryFitsBudget) {
                 lastAttemptWasUnfinishedContinuation = true;
@@ -452,7 +543,7 @@ export async function runAgentLoopDirectWithSoftTimeout(opts, softTimeoutMs, tim
                     opts.send({ type: "clear" });
                 }
                 await appendContinuationAndJournal(opts.messages, "rate_limited", opts.threadId, opts.turnId, localTurnEvents, localTurnEvents.slice(attemptStartIndex));
-                await waitForBackgroundRateLimitCooldown(upstreamSignal);
+                await waitForBackgroundRateLimitCooldown(turnSignal);
                 continue;
             }
             // Resumable transport / gateway interruptions: the LLM call was cut off
@@ -468,7 +559,7 @@ export async function runAgentLoopDirectWithSoftTimeout(opts, softTimeoutMs, tim
             // from scratch and the fold produces duplicated text in one message
             // (the partial text was already sent to the client but is now retained
             // only as an internal checkpoint so the next attempt can finish it).
-            if (!upstreamSignal.aborted && isResumableEngineError(err)) {
+            if (!turnSignal.aborted && isResumableEngineError(err)) {
                 lastAttemptWasUnfinishedContinuation = true;
                 if ((await completedSideEffectInCurrentTurn(opts.threadId, opts.turnId, localTurnEvents)) === "none") {
                     opts.send({ type: "clear" });
@@ -476,11 +567,8 @@ export async function runAgentLoopDirectWithSoftTimeout(opts, softTimeoutMs, tim
                 await appendContinuationAndJournal(opts.messages, continuationReasonForResumableError(err), opts.threadId, opts.turnId, localTurnEvents, localTurnEvents.slice(attemptStartIndex));
                 continue;
             }
-            if (upstreamSignal.aborted) {
-                reportFinalOutcome({
-                    state: "canceled",
-                    message: "Agent run was aborted.",
-                });
+            if (turnSignal.aborted) {
+                reportFinalOutcome(turnAbortOutcome());
                 throw err;
             }
             const candidate = err;
@@ -498,7 +586,7 @@ export async function runAgentLoopDirectWithSoftTimeout(opts, softTimeoutMs, tim
         }
         finally {
             clearTimeout(timer);
-            upstreamSignal.removeEventListener("abort", abortFromUpstream);
+            roundChunkSignal.removeEventListener("abort", abortFromUpstream);
         }
     }
     // The loop exited without a clean return. If the user aborted, that's a Stop —
@@ -508,7 +596,7 @@ export async function runAgentLoopDirectWithSoftTimeout(opts, softTimeoutMs, tim
     // give-up the run-manager would otherwise report as a clean `done`: emit a
     // loud, non-auto-continuing terminal so the user knows the turn stopped
     // before finishing and nothing was partially saved by the run itself.
-    if (!upstreamSignal.aborted && lastAttemptWasUnfinishedContinuation) {
+    if (!turnSignal.aborted && lastAttemptWasUnfinishedContinuation) {
         // Discard any partial text already streamed for the unfinished attempt so
         // the terminal message stands alone instead of trailing a half sentence.
         // Preserve completed tool cards: they are the user's only durable proof
@@ -529,11 +617,8 @@ export async function runAgentLoopDirectWithSoftTimeout(opts, softTimeoutMs, tim
             message: RUN_BUDGET_EXHAUSTED_MESSAGE,
         });
     }
-    else if (upstreamSignal.aborted) {
-        reportFinalOutcome({
-            state: "canceled",
-            message: "Agent run was aborted.",
-        });
+    else if (turnSignal.aborted) {
+        reportFinalOutcome(turnAbortOutcome());
     }
     return usage;
 }

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

@@ -68,68 +68,6 @@ export declare const DEFAULT_HOSTED_RUN_SOFT_TIMEOUT_MS = 40000;
  * function (no ~60s wall, 15-min budget) and therefore can safely outlast 40s.
  */
 export declare const HOSTED_SOFT_TIMEOUT_CEILING_MS = 40000;
-/**
- * Hard ceiling for the soft timeout when a run executes inside a Netlify
- * background function (any deployed function whose name ends in `-background`).
- * Background functions return 202 immediately and run detached for up to 15
- * minutes, so the ~60s synchronous function wall that 40s defends against does
- * NOT apply. 13 minutes leaves ~2 min of headroom under Netlify's 15-min hard
- * kill to abort, persist the partial turn, write the terminal event, and (for
- * the rare >13-min turn) self-fire another background continuation.
- *
- * This ceiling is used ONLY when a caller explicitly opts in with
- * `backgroundFunction: true`. It does not change the foreground/interactive
- * ceiling and does not fire unless the durable-background path dispatched the
- * run into a background function. Per the design doc Guardrail, the 40s
- * interactive clamp stays correct for every non-background run.
- */
-export declare const BACKGROUND_SOFT_TIMEOUT_CEILING_MS: number;
-/**
- * Default soft-timeout budget for a background-function run when the caller
- * does not pass an explicit `softTimeoutMs`. Same value as the ceiling — we
- * want a background turn to use nearly its whole 15-min budget before handing
- * off to a chained background continuation.
- */
-export declare const DEFAULT_BACKGROUND_RUN_SOFT_TIMEOUT_MS: number;
-/**
- * AUTHORITATIVE no-progress backstop for a run, enforced by the run manager
- * itself (timer-driven, independent of any layer below).
- *
- * The finer-grained watchdogs inside the agent loop (model-stream and
- * action-preparation no-progress, both 90s) only guard the model event stream
- * — a stall in any segment OUTSIDE that guarded loop (engine-call
- * establishment, worker setup between continuation chunks, a wedged transport
- * that emits keepalives while the loop never runs) previously hung forever
- * with the client watching keepalives. This backstop covers every segment by
- * construction: if no REAL progress event (see `shouldBumpProgressForEvent`;
- * keepalives and zero-byte prep activity don't count) lands for this long —
- * and no unit of work is in flight (see `inFlightWorkDelta`: tool calls,
- * cross-app calls, and the model stream all legitimately emit nothing for
- * minutes and each carry a bound of their own) — the run manager emits
- * `auto_continue { reason: "no_progress" }` and aborts the chunk, exactly
- * like the soft timeout, so the normal continuation machinery recovers it.
- *
- * Being numerically larger than the in-loop watchdogs is NOT what keeps this
- * from killing a healthy run, and treating it that way is what made it do so:
- * this clock and the loop's `lastModelStreamProgressAt` measure DIFFERENT
- * events. An extended-thinking phase bumps the inner clock on every engine
- * frame while forwarding nothing, so the inner watchdog correctly stayed quiet
- * and this one saw pure silence — runs whose worst gap crossed 150s died while
- * still streaming, some by a single second. Ordering between two clocks only
- * means something when they watch the same events; suspending on in-flight
- * work is what actually makes the two agree.
- *
- * This is now only the CEILING, not the value: `resolveRunNoProgressTimeoutMs`
- * clamps the foreground backstop to a fraction of the chunk's soft timeout
- * (~30s at a 40s chunk), which is BELOW the 90s in-loop watchdogs rather than
- * above them. That ordering is deliberate — the in-loop watchdogs could never
- * fire inside a hosted foreground chunk anyway, since the serverless wall
- * (~57-59s) arrives first. Proven durable-background chunks keep the full
- * `DEFAULT_BACKGROUND_NO_PROGRESS_TIMEOUT_MS` so large outputs can use the
- * background budget. Only armed when a soft-timeout regime is active (hosted
- * runs); local dev stays unbounded.
- */
-export declare const RUN_NO_PROGRESS_HARD_TIMEOUT_MS = 150000;
 /**
  * Default no-progress window for a run executing inside a proven durable
  * background function. A background worker that is heartbeating but has no
@@ -296,9 +234,18 @@ export interface StartRunOptions {
      */
     backgroundNoProgressTimeoutMs?: number;
     /**
-     * Lifecycle metadata persisted to `agent_runs.dispatch_mode` and surfaced to
-     * clients through `/runs/active`. This does not change run-manager behavior;
-     * callers use it to describe who owns continuation at hosted chunk boundaries.
+     * Lifecycle metadata persisted to `agent_runs.dispatch_mode`, surfaced to
+     * clients through `/runs/active`, and carried on the terminal/boundary
+     * analytics events. This does not change run-manager behavior; callers use it
+     * to describe who owns continuation at hosted chunk boundaries.
+     *
+     * Unset is reported as ABSENT, never as `"foreground"`. The analytics events
+     * used to default it, and the default was wrong every single time it applied:
+     * the interactive handler is the one caller that passes this, so the default
+     * only ever labelled the callers that are NOT foreground — automations, agent
+     * teams, webhooks, harness runs. It made a 6-of-7 no-progress failure rate on
+     * the automation path indistinguishable from chat in the one place anybody
+     * would have looked.
      */
     dispatchMode?: "foreground" | "foreground-self-chain" | "background";
     /**
@@ -315,6 +262,53 @@ export interface StartRunOptions {
     /** Continuation/redispatch attempt number for this logical turn, if the
      *  caller is tracking one. */
     attemptCount?: number;
+    /**
+     * The `runFn` recovers chunk boundaries INSIDE this invocation — it threads
+     * the `RunChunkControl` it is handed into
+     * `runAgentLoopDirectWithSoftTimeout`.
+     *
+     * When true a checkpoint aborts only the current CHUNK; the turn-scoped
+     * controller (what a user Stop, a hard timeout, and the cross-isolate abort
+     * check use) is left alone so the loop can append its continuation context
+     * and keep going. Off by default, and it must stay off for every caller that
+     * hands continuation to a FRESH invocation: those need the turn to end here
+     * so the next invocation can pick it up.
+     *
+     * This is the fix for the in-process automation runner, whose checkpoints
+     * were aborting the turn for a continuation nobody was going to run.
+     */
+    recoverChunkBoundaries?: boolean;
+}
+/**
+ * Handed to `runFn` so an in-invocation runner can tell a recoverable CHUNK
+ * boundary from a turn-ending abort.
+ *
+ * Without this distinction there is only one signal, and a checkpoint fired
+ * from above the agent loop is indistinguishable from a user pressing Stop —
+ * which is why `no_progress` was an accepted continuation reason with a
+ * 20-round budget that could never be reached.
+ */
+export interface RunChunkControl {
+    /**
+     * Aborted only when the TURN must end: user Stop, cross-isolate abort, the
+     * caller's own hard timeout, or a checkpoint on a run that did not opt into
+     * `recoverChunkBoundaries`. Never fires for a recoverable chunk boundary.
+     */
+    readonly turnSignal: AbortSignal;
+    /** Signal for the chunk currently executing. Replaced by `beginChunk()`. */
+    readonly chunkSignal: AbortSignal;
+    /**
+     * Reason the CURRENT chunk was checkpointed, or `null` while it is live.
+     * Distinct from "the turn was aborted": a caller that cannot tell them apart
+     * turns every planned boundary into a terminal failure.
+     */
+    chunkBoundaryReason(): string | null;
+    /**
+     * Open a fresh chunk after a recoverable boundary and return its signal.
+     * Returns the already-aborted turn signal when the turn is over, so a caller
+     * that races a Stop cannot accidentally start another chunk.
+     */
+    beginChunk(): AbortSignal;
 }
 export interface ResolveRunSoftTimeoutOptions {
     useHostedDefault?: boolean;
@@ -322,8 +316,9 @@ export interface ResolveRunSoftTimeoutOptions {
      * Resolve the soft timeout for a run executing inside a Netlify background
      * function. Lifts the hosted clamp to `BACKGROUND_SOFT_TIMEOUT_CEILING_MS`
      * (~13min) for this invocation only and, when no override/env is supplied,
-     * defaults to `DEFAULT_BACKGROUND_RUN_SOFT_TIMEOUT_MS`. Does NOT change the
-     * foreground ceiling. Off by default.
+     * defaults to that same ceiling — a background turn should use nearly its
+     * whole budget before handing off to a chained continuation. Does NOT change
+     * the foreground ceiling. Off by default.
      */
     backgroundFunction?: boolean;
 }
@@ -339,6 +334,26 @@ export declare function isHostedRuntime(): boolean;
 export declare function resolveRunSoftTimeoutMs(overrideMs?: number, options?: ResolveRunSoftTimeoutOptions): number;
 export declare function resolveCompletedRunRetentionMs(): number;
 export declare function resolveErroredRunRetentionMs(): number;
+/**
+ * Hard abort for one in-process background automation run.
+ *
+ * This is the host's real function budget for scheduled work, which is exactly
+ * the kind of number that differs between deployments — so it is configuration,
+ * not a module constant nobody outside this package can see.
+ */
+export declare function resolveBackgroundRunHardTimeoutMs(): number;
+/**
+ * Chunk budget for a background automation, derived from the runner's OWN hard
+ * abort rather than from the durable-chat background ceiling.
+ *
+ * The shipped build took the 13-minute chat ceiling for a path whose process is
+ * killed at 10 minutes, which made the recoverable soft-timeout boundary dead
+ * code and left the terminal no-progress backstop as the only boundary an
+ * automation could ever reach. Deriving from the hard abort keeps
+ * `soft timeout < hard abort` true by construction; the invariant check asserts
+ * the headroom still fits.
+ */
+export declare function resolveBackgroundAutomationSoftTimeoutMs(overrideMs?: number): number;
 /**
  * A completed tool with no later assistant text is an unfinished turn, not a
  * successful terminal response. Keep this predicate beside the run-manager's
@@ -353,7 +368,7 @@ export declare function endsAfterCompletedToolWithoutAssistantFinal(run: ActiveR
  *
  * Events are persisted to SQL for cross-isolate access (Cloudflare Workers).
  */
-export declare function startRun(runId: string, threadId: string, runFn: (send: (event: AgentChatEvent) => void, signal: AbortSignal) => Promise<void>, onComplete?: (run: ActiveRun) => void | Promise<void>, options?: StartRunOptions): StartedRun;
+export declare function startRun(runId: string, threadId: string, runFn: (send: (event: AgentChatEvent) => void, signal: AbortSignal, control: RunChunkControl) => Promise<void>, onComplete?: (run: ActiveRun) => void | Promise<void>, options?: StartRunOptions): StartedRun;
 /**
  * Subscribe to a run's events starting from `fromSeq`.
  * Returns a ReadableStream that replays buffered events then live-tails.