@agent-native/core 0.161.2 → 0.161.6

package/dist/agent/engine/builder-engine.js

@@ -226,6 +226,17 @@ class BuilderEngine {
                 }
                 : {}),
         };
+        // Measured once, from the exact string that goes on the wire, and carried
+        // on every error stop below. A gateway rejection tells us nothing about
+        // what we sent, so without this an oversized or malformed request and a
+        // gateway outage are the same capture.
+        const payload = JSON.stringify(body);
+        const requestShape = {
+            model: opts.model,
+            payloadBytes: new TextEncoder().encode(payload).length,
+            toolCount: cachedTools.length,
+            messageCount: cachedMessages.length,
+        };
         const gatewayBaseUrl = getBuilderGatewayBaseUrl();
         const gatewayUrl = new URL("messages", gatewayBaseUrl.endsWith("/") ? gatewayBaseUrl : `${gatewayBaseUrl}/`);
         gatewayUrl.searchParams.set("apiKey", spaceId);
@@ -246,7 +257,7 @@ class BuilderEngine {
                         ...getBuilderGatewayRequestHeaders(),
                         ...(builderUserId ? { "x-builder-user-id": builderUserId } : {}),
                     },
-                    body: JSON.stringify(body),
+                    body: payload,
                     signal: gatewayAbort.signal,
                 });
             }
@@ -265,12 +276,12 @@ class BuilderEngine {
                         elapsedMs: Date.now() - tStart,
                     });
                 }
-                yield createBuilderGatewayTimeoutStop(err, timedOut, gatewayAbort.effectiveTimeoutMs(), creditsLane);
+                yield createBuilderGatewayTimeoutStop(err, timedOut, gatewayAbort.effectiveTimeoutMs(), creditsLane, requestShape);
                 return;
             }
             console.log(`[builder-engine] ← ${response.status} ${response.statusText} in ${Date.now() - tStart}ms`);
             if (!response.ok) {
-                yield* emitHttpError(response, { creditsLane });
+                yield* emitHttpError(response, { creditsLane, requestShape });
                 return;
             }
             // A successful gateway call proves the connected credentials are valid
@@ -302,7 +313,7 @@ class BuilderEngine {
                     ...(isTransientGatewayFailure(error, status)
                         ? { providerRetryable: true }
                         : {}),
-                }, creditsLane);
+                }, creditsLane, requestShape);
                 return;
             }
             const reader = response.body?.getReader();
@@ -311,7 +322,7 @@ class BuilderEngine {
                     error: "Builder gateway response has no body",
                     errorCode: "builder_gateway_error",
                     statusCode: response.status,
-                }, creditsLane);
+                }, creditsLane, requestShape);
                 return;
             }
             yield* parseJsonlStream(reader, opts.model, {
@@ -322,6 +333,7 @@ class BuilderEngine {
                 onFirstEvent: gatewayAbort.markFirstEvent,
                 gatewayUrl,
                 requestStartedAt: tStart,
+                requestShape,
             });
         }
         finally {
@@ -358,7 +370,7 @@ function isTransientGatewayFailure(rawMessage, status) {
  * signals downstream may read: keyword coupling to the message turns a retryable
  * throttle into a dead turn on credits sites alone.
  */
-function gatewayErrorStop(details, creditsLane) {
+function gatewayErrorStop(details, creditsLane, requestShape) {
     const { error, errorCode, upgradeUrl, ...retry } = details;
     return {
         type: "stop",
@@ -373,6 +385,9 @@ function gatewayErrorStop(details, creditsLane) {
         ...(isContextOverflowMessage(error) || isContextOverflowCode(errorCode)
             ? { contextOverflow: true }
             : {}),
+        // Absent before the request is built (missing credentials): a stop with no
+        // shape means nothing was sent, not that the payload measured zero.
+        ...(requestShape ? { requestShape } : {}),
         ...retry,
     };
 }
@@ -394,7 +409,7 @@ async function* emitHttpError(response, opts) {
     }
     const code = errBody.code ?? `http_${status}`;
     const message = errBody.message ?? `Builder gateway returned ${status}`;
-    const stop = (details) => gatewayErrorStop(details, opts.creditsLane);
+    const stop = (details) => gatewayErrorStop(details, opts.creditsLane, opts.requestShape);
     // Belt-and-suspenders: 402 without a structured `credits-limit` code
     // (e.g. bare proxy response) still means quota → show upgrade CTA.
     if (code.startsWith("credits-limit") || status === 402) {
@@ -543,7 +558,7 @@ async function* parseJsonlStream(reader, model, captureContext = {}) {
                     errorCode: "http_502",
                     statusCode: 502,
                     providerRetryable: true,
-                }, captureContext.creditsLane);
+                }, captureContext.creditsLane, captureContext.requestShape);
                 return;
             }
             // Heartbeats are transport-level keepalives, not proof the model is
@@ -624,7 +639,7 @@ async function* parseJsonlStream(reader, model, captureContext = {}) {
                     yield* recoverUndeliveredToolCalls();
                     yield { type: "assistant-content", parts };
                     const reason = event.reason ?? "end_turn";
-                    const stop = (details) => gatewayErrorStop(details, captureContext.creditsLane);
+                    const stop = (details) => gatewayErrorStop(details, captureContext.creditsLane, captureContext.requestShape);
                     if (reason === "rate_limited") {
                         yield stop({
                             error: `rate_limit exceeded: ${event.error ?? "upstream provider rate limited"}`,
@@ -744,7 +759,7 @@ async function* parseJsonlStream(reader, model, captureContext = {}) {
         yield gatewayErrorStop({
             error: "Builder gateway stream ended without a stop event",
             errorCode: BUILDER_GATEWAY_STREAM_ENDED_ERROR_CODE,
-        }, captureContext.creditsLane);
+        }, captureContext.creditsLane, captureContext.requestShape);
     }
     catch (err) {
         const timedOut = captureContext.didGatewayTimeout?.() ?? false;
@@ -762,7 +777,7 @@ async function* parseJsonlStream(reader, model, captureContext = {}) {
                     : undefined,
             });
         }
-        yield createBuilderGatewayTimeoutStop(err, timedOut, gatewayTimeoutMs, captureContext.creditsLane);
+        yield createBuilderGatewayTimeoutStop(err, timedOut, gatewayTimeoutMs, captureContext.creditsLane, captureContext.requestShape);
     }
     finally {
         // Release the reader on every exit path — early returns (invalid JSONL,
@@ -976,27 +991,27 @@ function normalizeBuilderGatewayFetchError(err, timedOut, timeoutMs) {
  * the credits lane run-manager has no text left to classify at persistence time,
  * and a run persisted as `unknown` reads as "do not attempt recovery".
  */
-function createBuilderGatewayTimeoutStop(err, timedOut, timeoutMs, creditsLane) {
+function createBuilderGatewayTimeoutStop(err, timedOut, timeoutMs, creditsLane, requestShape) {
     const error = normalizeBuilderGatewayFetchError(err, timedOut, timeoutMs);
     if (timedOut) {
         // Deliberately no `providerRetryable`: the timeout spent the whole request
         // budget, so the recovery is a fresh invocation (the client's
         // `builder_gateway_timeout` continuation), never an in-call retry.
-        return gatewayErrorStop({ error, errorCode: "builder_gateway_timeout" }, creditsLane);
+        return gatewayErrorStop({ error, errorCode: "builder_gateway_timeout" }, creditsLane, requestShape);
     }
     if (isBuilderGatewayNetworkError(err)) {
         return gatewayErrorStop({
             error,
             errorCode: BUILDER_GATEWAY_NETWORK_ERROR_CODE,
             providerRetryable: true,
-        }, creditsLane);
+        }, creditsLane, requestShape);
     }
     const errorCode = classifyTerminalErrorCode(error);
     return gatewayErrorStop({
         error,
         ...(errorCode ? { errorCode } : {}),
         ...(isTransientGatewayFailure(error) ? { providerRetryable: true } : {}),
-    }, creditsLane);
+    }, creditsLane, requestShape);
 }
 function formatTimeoutMs(timeoutMs) {
     if (timeoutMs < 1000)

package/dist/agent/engine/types.d.ts

@@ -36,6 +36,8 @@ export declare class EngineError extends Error {
      * one-shot trim-and-retry recovery.
      */
     readonly contextOverflow?: boolean;
+    /** Sizes and counts of the failed request; see {@link EngineRequestShape}. */
+    readonly requestShape?: EngineRequestShape;
     constructor(message: string, opts?: {
         errorCode?: string;
         upgradeUrl?: string;
@@ -43,6 +45,7 @@ export declare class EngineError extends Error {
         providerRetryable?: boolean;
         requestId?: string;
         contextOverflow?: boolean;
+        requestShape?: EngineRequestShape;
     });
 }
 /**
@@ -213,7 +216,23 @@ export type EngineEvent = {
      * the time the agent decides whether to trim and retry.
      */
     contextOverflow?: boolean;
+    /**
+     * Sizes and counts of the request that failed. Never prompt or user
+     * content — the point is to make "what did we send" answerable from a
+     * capture, which an opaque gateway 500 otherwise leaves unanswerable.
+     */
+    requestShape?: EngineRequestShape;
 };
+/**
+ * Shape-only description of what an engine put on the wire. Every field is a
+ * size, a count, or a model id, so it is safe to attach to an error capture.
+ */
+export interface EngineRequestShape {
+    model: string;
+    payloadBytes: number;
+    toolCount: number;
+    messageCount: number;
+}
 export interface EngineCapabilities {
     /** Extended / adaptive thinking support */
     thinking: boolean;

package/dist/agent/engine/types.js

@@ -35,6 +35,8 @@ export class EngineError extends Error {
      * one-shot trim-and-retry recovery.
      */
     contextOverflow;
+    /** Sizes and counts of the failed request; see {@link EngineRequestShape}. */
+    requestShape;
     constructor(message, opts) {
         super(message);
         this.name = "EngineError";
@@ -44,5 +46,6 @@ export class EngineError extends Error {
         this.providerRetryable = opts?.providerRetryable;
         this.requestId = opts?.requestId;
         this.contextOverflow = opts?.contextOverflow;
+        this.requestShape = opts?.requestShape;
     }
 }

package/dist/agent/production-agent.d.ts

@@ -935,6 +935,52 @@ export declare function runAgentLoopWithMainChatInternalContinuations(opts: Para
  * background invocations forever, mirroring `MAX_AGENT_TEAM_CONTINUATIONS`.
  */
 export declare const MAX_BACKGROUND_RUN_CONTINUATIONS = 20;
+/**
+ * Consecutive chunks allowed to end on the SAME terminal error code having
+ * produced nothing before the chain stops.
+ *
+ * Two, because two independent recovery layers multiply here and neither can
+ * see the other: the engine already retried this identical request 3x with
+ * backoff before the error was ever emitted, and a recoverable error is also a
+ * continuation boundary, so every chunk that fails costs 4 gateway attempts
+ * and dispatches a fresh one. A production turn spent 27 background runs and
+ * 15 minutes on one message this way. The first repeat is the retry this path
+ * exists for; a second identical failure that moved nothing is evidence the
+ * retrying itself is what is broken, not the request.
+ */
+export declare const MAX_CONSECUTIVE_NO_PROGRESS_CONTINUATIONS = 2;
+/** Consecutive-identical-failure state for one chunk of a background chain. */
+export interface BackgroundNoProgressRepeat {
+    /** This chunk's terminal error code, when it ended having produced nothing. */
+    errorCode?: string;
+    /** Chunks in a row that ended on that code with no forward progress. */
+    count: number;
+    /** True once the streak reaches `MAX_CONSECUTIVE_NO_PROGRESS_CONTINUATIONS`. */
+    tripped: boolean;
+}
+/**
+ * Advance the no-progress streak across a chunk boundary. A chunk that emitted
+ * any text or tool activity resets it even when it still ended in an error —
+ * that turn IS moving, and cutting it off is what would weaken recovery for
+ * truncated streams. So does a different error code, and so does a boundary
+ * with no error at all (a soft-timeout `auto_continue` is the run-manager's
+ * no-progress backstop to bound, not this one).
+ */
+export declare function resolveBackgroundNoProgressRepeat(opts: {
+    run: ActiveRun;
+    priorErrorCode?: string;
+    priorCount?: number;
+}): BackgroundNoProgressRepeat;
+/**
+ * The single honest failure the breaker leaves behind. Keeps the underlying
+ * code and the gateway's own message (which carries its `ERROR ID:` reference)
+ * so the failure stays diagnosable, and marks it non-recoverable so neither
+ * this chain nor the client's continuation path re-enters it.
+ */
+export declare function backgroundNoProgressTerminalEvent(run: ActiveRun, repeat: BackgroundNoProgressRepeat): Extract<AgentChatEvent, {
+    type: "error";
+}> | null;
+export declare function installBackgroundNoProgressTerminalEvent(run: ActiveRun, repeat: BackgroundNoProgressRepeat): boolean;
 /**
  * Whether this run should self-fire the next server-driven continuation chunk
  * instead of depending on the client to re-POST `auto_continue`. True for
@@ -949,7 +995,9 @@ export declare const MAX_BACKGROUND_RUN_CONTINUATIONS = 20;
  *     the durable background worker (`dispatchedToBackground` false) — a run
  *     already headed to the durable background path chains via the
  *     `isBackgroundWorker` branch above, never both.
- * Aborted / user-stopped runs do NOT chain either way.
+ * Aborted / user-stopped runs do NOT chain either way, and neither does a run
+ * whose no-progress streak has tripped
+ * (`MAX_CONSECUTIVE_NO_PROGRESS_CONTINUATIONS`).
  */
 export declare function shouldChainBackgroundContinuation(opts: {
     isBackgroundWorker: boolean;
@@ -970,6 +1018,10 @@ export declare function shouldChainBackgroundContinuation(opts: {
      * owned by the background circuit-breaker, not this path.
      */
     dispatchedToBackground?: boolean;
+    /** Streak state carried on the continuation marker — see
+     *  `resolveBackgroundNoProgressRepeat`. Absent on the first chunk. */
+    priorNoProgressErrorCode?: string;
+    priorNoProgressCount?: number;
 }): boolean;
 /**
  * Minimum remaining budget (ms) a synchronous self-chain continuation chunk
@@ -1275,6 +1327,9 @@ export declare function chainServerDrivenContinuation(opts: {
      *  is derived from it (marker stripped, `internalContinuation` set). */
     requestBody: Record<string, unknown>;
     backgroundContinuationCount: number;
+    /** This chunk's no-progress streak, carried to the successor so the breaker
+     *  can see a repeat across the invocation boundary. */
+    noProgressRepeat?: BackgroundNoProgressRepeat;
     /**
      * Input tokens this logical turn has consumed across every chunk so far,
      * carried on the successor's body so the per-turn token ceiling is a real

package/dist/agent/production-agent.js

@@ -3753,6 +3753,7 @@ export async function runAgentLoop(opts) {
                                     providerRetryable: event.providerRetryable,
                                     contextOverflow: event.contextOverflow,
                                     requestId: event.requestId,
+                                    requestShape: event.requestShape,
                                 });
                             }
                         }
@@ -5421,6 +5422,87 @@ function endsAtContinuationBoundary(run) {
  * background invocations forever, mirroring `MAX_AGENT_TEAM_CONTINUATIONS`.
  */
 export const MAX_BACKGROUND_RUN_CONTINUATIONS = 20;
+/**
+ * Consecutive chunks allowed to end on the SAME terminal error code having
+ * produced nothing before the chain stops.
+ *
+ * Two, because two independent recovery layers multiply here and neither can
+ * see the other: the engine already retried this identical request 3x with
+ * backoff before the error was ever emitted, and a recoverable error is also a
+ * continuation boundary, so every chunk that fails costs 4 gateway attempts
+ * and dispatches a fresh one. A production turn spent 27 background runs and
+ * 15 minutes on one message this way. The first repeat is the retry this path
+ * exists for; a second identical failure that moved nothing is evidence the
+ * retrying itself is what is broken, not the request.
+ */
+export const MAX_CONSECUTIVE_NO_PROGRESS_CONTINUATIONS = 2;
+/**
+ * Forward progress inside ONE chunk, read from the events it actually emitted:
+ * assistant text or tool activity. Same evidence the agent-teams no-progress
+ * budget counts (`agent-teams.ts`), and the same events
+ * `endsAfterCompletedToolWithoutAssistantFinal` reads to tell an unfinished
+ * turn from a finished one.
+ */
+function chunkMadeForwardProgress(run) {
+    return run.events.some(({ event }) => (event.type === "text" && event.text.trim().length > 0) ||
+        event.type === "tool_start" ||
+        event.type === "tool_done");
+}
+/**
+ * Advance the no-progress streak across a chunk boundary. A chunk that emitted
+ * any text or tool activity resets it even when it still ended in an error —
+ * that turn IS moving, and cutting it off is what would weaken recovery for
+ * truncated streams. So does a different error code, and so does a boundary
+ * with no error at all (a soft-timeout `auto_continue` is the run-manager's
+ * no-progress backstop to bound, not this one).
+ */
+export function resolveBackgroundNoProgressRepeat(opts) {
+    const last = opts.run.events.at(-1)?.event;
+    const errorCode = last?.type === "error" ? (last.errorCode ?? "").trim() : "";
+    if (!errorCode || chunkMadeForwardProgress(opts.run)) {
+        return { count: 0, tripped: false };
+    }
+    const prior = opts.priorErrorCode === errorCode &&
+        typeof opts.priorCount === "number" &&
+        Number.isFinite(opts.priorCount)
+        ? Math.max(0, Math.floor(opts.priorCount))
+        : 0;
+    const count = prior + 1;
+    return {
+        errorCode,
+        count,
+        tripped: count >= MAX_CONSECUTIVE_NO_PROGRESS_CONTINUATIONS,
+    };
+}
+/**
+ * The single honest failure the breaker leaves behind. Keeps the underlying
+ * code and the gateway's own message (which carries its `ERROR ID:` reference)
+ * so the failure stays diagnosable, and marks it non-recoverable so neither
+ * this chain nor the client's continuation path re-enters it.
+ */
+export function backgroundNoProgressTerminalEvent(run, repeat) {
+    const last = run.events.at(-1)?.event;
+    if (last?.type !== "error")
+        return null;
+    return {
+        ...last,
+        error: `${last.error}\n\nThis failed ${repeat.count} times in a row without ` +
+            `making any progress, so I stopped instead of retrying again.`,
+        recoverable: false,
+    };
+}
+export function installBackgroundNoProgressTerminalEvent(run, repeat) {
+    const terminalEvent = backgroundNoProgressTerminalEvent(run, repeat);
+    const lastRunEvent = run.events.at(-1);
+    if (!terminalEvent || lastRunEvent?.event.type !== "error")
+        return false;
+    run.events = [
+        ...run.events.slice(0, -1),
+        { ...lastRunEvent, event: terminalEvent },
+    ];
+    run.continuationTerminalEvent = terminalEvent;
+    return true;
+}
 /**
  * Whether this run should self-fire the next server-driven continuation chunk
  * instead of depending on the client to re-POST `auto_continue`. True for
@@ -5435,7 +5517,9 @@ export const MAX_BACKGROUND_RUN_CONTINUATIONS = 20;
  *     the durable background worker (`dispatchedToBackground` false) — a run
  *     already headed to the durable background path chains via the
  *     `isBackgroundWorker` branch above, never both.
- * Aborted / user-stopped runs do NOT chain either way.
+ * Aborted / user-stopped runs do NOT chain either way, and neither does a run
+ * whose no-progress streak has tripped
+ * (`MAX_CONSECUTIVE_NO_PROGRESS_CONTINUATIONS`).
  */
 export function shouldChainBackgroundContinuation(opts) {
     const eligible = opts.isBackgroundWorker ||
@@ -5444,7 +5528,12 @@ export function shouldChainBackgroundContinuation(opts) {
     return (eligible &&
         opts.run.status !== "aborted" &&
         endsAtContinuationBoundary(opts.run) &&
-        opts.continuationCount < MAX_BACKGROUND_RUN_CONTINUATIONS);
+        opts.continuationCount < MAX_BACKGROUND_RUN_CONTINUATIONS &&
+        !resolveBackgroundNoProgressRepeat({
+            run: opts.run,
+            priorErrorCode: opts.priorNoProgressErrorCode,
+            priorCount: opts.priorNoProgressCount,
+        }).tripped);
 }
 /**
  * Minimum remaining budget (ms) a synchronous self-chain continuation chunk
@@ -5884,6 +5973,12 @@ export async function chainServerDrivenContinuation(opts) {
         continuationCount: opts.backgroundContinuationCount + 1,
         continuationReason,
         ...(actionPreparationTool ? { actionPreparationTool } : {}),
+        ...(opts.noProgressRepeat?.errorCode
+            ? {
+                noProgressErrorCode: opts.noProgressRepeat.errorCode,
+                noProgressCount: opts.noProgressRepeat.count,
+            }
+            : {}),
         backgroundFunctionRuntimeExpected: continuationExpectsNetlifyBackgroundFunction,
     };
     // Strip this chunk's own marker before persisting/forwarding — the next
@@ -6236,6 +6331,15 @@ export function createProductionAgentHandler(options) {
             Number.isFinite(backgroundRunMarker.continuationCount)
             ? Math.max(0, Math.floor(backgroundRunMarker.continuationCount))
             : 0;
+        // No-progress streak so far, carried on the marker: this invocation has no
+        // other memory of what the previous chunk failed with.
+        const priorNoProgressErrorCode = typeof backgroundRunMarker?.noProgressErrorCode === "string"
+            ? backgroundRunMarker.noProgressErrorCode
+            : undefined;
+        const priorNoProgressCount = typeof backgroundRunMarker?.noProgressCount === "number" &&
+            Number.isFinite(backgroundRunMarker.noProgressCount)
+            ? Math.max(0, Math.floor(backgroundRunMarker.noProgressCount))
+            : 0;
         let backgroundRunClaimedEarly = false;
         if (isBackgroundWorker && bgRunId) {
             const earlyClaim = await claimBackgroundWorkerRunEarly({
@@ -7311,12 +7415,19 @@ export function createProductionAgentHandler(options) {
             typeof threadId === "string" &&
             threadId.trim().length > 0 &&
             isAgentChatForegroundSelfChainEnabled();
+        const noProgressRepeatForRun = (run) => resolveBackgroundNoProgressRepeat({
+            run,
+            priorErrorCode: priorNoProgressErrorCode,
+            priorCount: priorNoProgressCount,
+        });
         const willChainBackgroundContinuation = (run) => shouldChainBackgroundContinuation({
             isBackgroundWorker,
             run,
             continuationCount: backgroundContinuationCount,
             foregroundSelfChainEligible,
             dispatchedToBackground: dispatchToBackground,
+            priorNoProgressErrorCode,
+            priorNoProgressCount,
         });
         const completeTrackedProgressRun = async (run, completionError) => {
             if (!trackedProgressRunId || !trackedProgressOwner)
@@ -7403,6 +7514,14 @@ export function createProductionAgentHandler(options) {
                         ? `${errEvent.errorCode ?? ""} ${errEvent.error ?? ""}`.trim()
                         : "run ended in errored state").catch(() => { });
                 }
+                const noProgressRepeat = noProgressRepeatForRun(run);
+                if (noProgressRepeat.tripped) {
+                    // Install the replacement before the thread writer runs. The
+                    // writer builds durable thread_data from events, so changing
+                    // only continuationTerminalEvent afterwards leaves the original
+                    // recoverable error persisted and eligible for another retry.
+                    installBackgroundNoProgressTerminalEvent(run, noProgressRepeat);
+                }
                 // Persist the (partial) assistant turn to thread_data FIRST — the
                 // server-driven continuation below rebuilds from it, so it must be
                 // committed before we re-fire.
@@ -7433,7 +7552,14 @@ export function createProductionAgentHandler(options) {
                 // succeeded — a dispatch fast-fail degrades to the inline
                 // foreground fallback, which is not a worker and rides the
                 // connected client's auto_continue instead.)
-                if (willChainBackgroundContinuation(run)) {
+                if (noProgressRepeat.tripped) {
+                    if (run.continuationTerminalEvent?.type === "error") {
+                        console.error(`[agent-chat] stopping background chain: ${noProgressRepeat.errorCode} ` +
+                            `failed ${noProgressRepeat.count}x with no progress`, run.runId);
+                        await recordRunDiagnostic(run.runId, RUN_DIAG_STAGE.workerThrew, `chain_stopped_no_progress code=${noProgressRepeat.errorCode} count=${noProgressRepeat.count}`).catch(() => { });
+                    }
+                }
+                else if (willChainBackgroundContinuation(run)) {
                     // Full handoff discipline lives in
                     // `chainServerDrivenContinuation` (exported + unit-tested):
                     // per-turn SQL run budget, successor row PRE-INSERTED before
@@ -7446,6 +7572,7 @@ export function createProductionAgentHandler(options) {
                         effectiveTurnId,
                         requestBody: body,
                         backgroundContinuationCount,
+                        noProgressRepeat,
                         turnInputTokens,
                         // Re-evaluate the durable gate rather than keying off
                         // isBackgroundWorker: a successor chunk of a FOREGROUND

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

@@ -1,3 +1,4 @@
+import type { EngineRequestShape } from "./engine/types.js";
 import type { AgentChatEvent, RunEvent, RunStatus } from "./types.js";
 export interface ActiveRun {
     runId: string;
@@ -10,13 +11,18 @@ export interface ActiveRun {
     abort: AbortController;
     abortReason?: string;
     /**
-     * Terminal event to emit when a server-driven continuation has been handed
-     * off successfully. The continuation runs outside this process, so the
-     * normal loop-level auto_continue event is not sent through this run's
-     * `send` callback.
+     * Terminal event the completion callback installs in place of the one the
+     * loop stashed: `auto_continue` when a server-driven continuation has been
+     * handed off successfully (that continuation runs outside this process, so
+     * the loop-level auto_continue never goes through this run's `send`), or
+     * `error` when the callback decided the turn must stop here instead — the
+     * stashed error is recoverable by construction, so leaving it in place
+     * re-enters the very chain the callback just refused to continue.
      */
     continuationTerminalEvent?: Extract<AgentChatEvent, {
         type: "auto_continue";
+    } | {
+        type: "error";
     }>;
     startedAt: number;
 }
@@ -233,6 +239,11 @@ export declare function resolveSqlSubscriptionPollMs(now: number, activePollUnti
  */
 export declare function nextSqlSubscriptionEmptyPolls(current: number, hadEvents: boolean, now: number, activePollUntil: number): number;
 export declare function resolveSqlSubscriptionRetryMs(consecutiveFailures: number): number;
+/**
+ * Sentry tags are strings, and an absent shape must stay absent: a run that
+ * failed before the request was built did not send a zero-byte payload.
+ */
+export declare function engineRequestShapeTags(shape: EngineRequestShape | undefined): Record<string, string>;
 export interface StartRunOptions {
     /** Keep a request-scoped serverless invocation alive for this run. */
     waitUntil?: (promise: Promise<unknown>) => void;

package/dist/agent/run-manager.js

@@ -299,6 +299,20 @@ function getRunErrorCode(err) {
     // only when the run row is persisted.
     return classifyTerminalErrorCode(describeErrorWithCauses(err));
 }
+/**
+ * Sentry tags are strings, and an absent shape must stay absent: a run that
+ * failed before the request was built did not send a zero-byte payload.
+ */
+export function engineRequestShapeTags(shape) {
+    if (!shape)
+        return {};
+    return {
+        engineModel: shape.model,
+        enginePayloadBytes: String(shape.payloadBytes),
+        engineToolCount: String(shape.toolCount),
+        engineMessageCount: String(shape.messageCount),
+    };
+}
 function getEngineRunErrorDetails(err) {
     if (err.statusCode === 429)
         return err.message;
@@ -1078,6 +1092,11 @@ export function startRun(runId, threadId, runFn, onComplete, options) {
                 statusCode: engineError?.statusCode != null
                     ? String(engineError.statusCode)
                     : undefined,
+                // What we sent, in sizes and counts only. A gateway rejection describes
+                // nothing about the request behind it, so without these an oversized
+                // payload and an upstream outage produce the same capture — which is
+                // how one gateway 500 cost a night of guessing.
+                ...engineRequestShapeTags(engineError?.requestShape),
             },
             extra: {
                 runId,
@@ -1263,6 +1282,13 @@ export function startRun(runId, threadId, runFn, onComplete, options) {
                     }
                     : run;
                 await onComplete(completionRun);
+                // `completionRun` is a shallow COPY whenever the loop stashed a
+                // terminal event, so a callback that installs its own terminal
+                // event writes it to the copy and `resolveTerminalEventForCompletion`
+                // below never sees it — the run then emits the pre-callback event
+                // the callback was overriding.
+                run.continuationTerminalEvent ??=
+                    completionRun.continuationTerminalEvent;
             }
             catch (err) {
                 completionError = err;

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

@@ -715,11 +715,11 @@ export declare function getRunOutcomeCounters(options?: {
     terminalReason: string;
     count: number;
 }>>;
-/** Delete old runs and expire stale "running" rows that haven't had activity
- *  (e.g. worker crashed before updating status). Genuinely completed runs are
- *  pruned at `olderThanMs`; errored/aborted/truncated runs are kept until
- *  `erroredOlderThanMs` (a longer window, falling back to `olderThanMs`) so
- *  their event log survives for cut-off pattern analysis via listErroredRuns. */
+/**
+ * Run cleanup is scheduled after every completed run, including completions
+ * from several concurrent requests in one isolate. Share one sweep locally;
+ * Postgres additionally serializes the durable prune across isolates.
+ */
 export declare function cleanupOldRuns(olderThanMs: number, erroredOlderThanMs?: number): Promise<void>;
 /**
  * List recent unsuccessful runs (errored, aborted, and truncated) for cut-off