@agent-native/core 0.88.0 → 0.90.1

package/dist/agent/production-agent.js

@@ -1,5 +1,5 @@
 import Ajv from "ajv";
-import { defineEventHandler, setResponseHeader, setResponseStatus, getMethod, } from "h3";
+import { defineEventHandler, getHeader, setResponseHeader, setResponseStatus, getMethod, } from "h3";
 import { isAgentActionStopError } from "../action.js";
 import { readAppState } from "../application-state/script-helpers.js";
 import { isReadOnlyShellCommand } from "../coding-tools/index.js";
@@ -8,6 +8,7 @@ import { redactDemoData, redactDemoString } from "../demo/redact.js";
 import { extensionIdFromPathname } from "../extensions/path.js";
 import { preUploadAttachments } from "../file-upload/pre-upload-attachments.js";
 import { isMcpActionResult } from "../mcp-client/app-result.js";
+import { extractMcpToolResultImages } from "../mcp-client/index.js";
 import { isMcpToolAllowedForRequest } from "../mcp-client/visibility.js";
 import { completeRun as completeProgressRun, startRun as startProgressRun, updateRunProgress, } from "../progress/registry.js";
 import { getFrontmatterValue, parseFrontmatter, } from "../resources/metadata.js";
@@ -21,7 +22,7 @@ import { applyContextDirectives } from "./context-xray/apply-directives.js";
 import { loadContextDirectives } from "./context-xray/directives-store.js";
 import { buildManifest, writeContextManifest, } from "./context-xray/manifest.js";
 import { computeProtectedSegmentIds } from "./context-xray/segments.js";
-import { AGENT_CHAT_BACKGROUND_RUN_FIELD, backgroundRuntimeDiagnosticDetail, dispatchPathTargetsNetlifyBackgroundFunction, isAgentChatDurableBackgroundEnabled, resolveAgentChatProcessRunDispatchPath, shouldUseBackgroundFunctionTimeoutForWorker, } from "./durable-background.js";
+import { AGENT_CHAT_BACKGROUND_RUN_FIELD, AGENT_CHAT_PROCESS_RUN_PATH, backgroundRuntimeDiagnosticDetail, dispatchPathTargetsNetlifyBackgroundFunction, isAgentChatDurableBackgroundEnabled, isAgentChatForegroundSelfChainEnabled, resolveAgentChatProcessRunDispatchPath, shouldUseBackgroundFunctionTimeoutForWorker, } from "./durable-background.js";
 import { LLM_MISSING_CREDENTIALS_ERROR_CODE, LLM_MISSING_CREDENTIALS_MESSAGE, userFacingLlmCredentialError, } from "./engine/credential-errors.js";
 import { resolveEngine, registerBuiltinEngines, getStoredModelForEngine, normalizeModelForEngine, isResolvedEngineUsableForRequest, } from "./engine/index.js";
 import { resolveMaxOutputTokensForEngine } from "./engine/output-tokens.js";
@@ -33,8 +34,10 @@ import { maybeCompactThread, buildObservationalContext, hasObservationalMemory,
 import { ProcessorChain, TripWire, toolCallsFromContent, } from "./processors.js";
 import { startRun, subscribeToRun, getActiveRunForThread, getActiveRunForThreadAsync, getRun, abortRun, tryClaimRunSlot, } from "./run-manager.js";
 import { writeLedgerEntry, readLedgerEntry, clearLedgerForThread, getCurrentTurnEventsForThread, insertRun, updateRunHeartbeat, updateRunStatusIfRunning, setRunTerminalReason, claimBackgroundRun, readBackgroundRunClaim, recordRunDiagnostic, countRunsForTurn, RUN_DIAG_STAGE, UNCLAIMED_BACKGROUND_RUN_GRACE_MS, } from "./run-store.js";
+import { buildCurrentTimeUserContext } from "./runtime-context.js";
 import { classifyToolCallJournal, findCompletedJournalEntry, } from "./tool-call-journal.js";
 import { redactSensitiveFields, sanitizeToolErrorText, sanitizeToolErrorValue, } from "./tool-error-redaction.js";
+import { describeToolResultImages, extractAgentImagesFromActionResult, } from "./tool-result-images.js";
 import { createToolSearchEntry, TOOL_SEARCH_ACTION_NAME, } from "./tool-search.js";
 // Register built-in engines on first import
 registerBuiltinEngines();
@@ -299,10 +302,10 @@ export async function getOwnerActiveApiKey(ownerEmail) {
         const userKey = await getOwnerApiKey(provider, ownerEmail);
         if (userKey)
             return userKey;
-        if (!canUseDeployCredentialFallbackForRequest())
-            return undefined;
         const envVar = PROVIDER_TO_ENV[provider];
-        return envVar ? readDeployCredentialEnv(envVar) : undefined;
+        return envVar && canUseDeployCredentialFallbackForRequest(envVar)
+            ? readDeployCredentialEnv(envVar)
+            : undefined;
     }
     catch {
         return undefined;
@@ -1957,7 +1960,7 @@ export async function runAgentLoop(opts) {
                         ? restrictAgentTeamsAfterSourceSweep(activeTools)
                         : activeTools,
                     abortSignal: signal,
-                    maxOutputTokens: resolveMaxOutputTokensForEngine(engine.name, opts.maxOutputTokens),
+                    maxOutputTokens: resolveMaxOutputTokensForEngine(engine.name, opts.maxOutputTokens, model),
                     reasoningEffort: opts.reasoningEffort,
                     providerOptions: opts.providerOptions,
                 };
@@ -2900,6 +2903,7 @@ export async function runAgentLoop(opts) {
             let result;
             let isError = false;
             let mcpApp;
+            let toolResultImages;
             try {
                 // The run may have been aborted while we waited above for an
                 // interrupted tool's ledger result (the wait can poll for minutes).
@@ -3014,6 +3018,36 @@ export async function runAgentLoop(opts) {
                         redacted = redactDemoData(rawForAgent);
                     }
                 }
+                // Vision images for the model: MCP tools return standard `image`
+                // content parts; first-party actions opt in via the well-known
+                // `_agentImages` result field (stripped from the JSON the model
+                // reads, even in demo mode). Demo mode drops the images themselves —
+                // text redaction can't scrub pixels, and a screenshot would leak the
+                // real names/emails the redaction exists to hide. The images array
+                // never touches the ledger — only the compact text notes appended
+                // below are persisted.
+                let imageNotes = [];
+                if (mcpResult) {
+                    if (!demoMode) {
+                        const mcpImages = extractMcpToolResultImages(mcpResult.raw);
+                        if (mcpImages.length > 0)
+                            toolResultImages = mcpImages;
+                    }
+                }
+                else {
+                    const extracted = extractAgentImagesFromActionResult(redacted);
+                    redacted = extracted.value;
+                    imageNotes = extracted.notes;
+                    if (extracted.images.length > 0 && !demoMode) {
+                        toolResultImages = extracted.images;
+                    }
+                }
+                if (toolResultImages) {
+                    imageNotes = [
+                        ...describeToolResultImages(toolResultImages),
+                        ...imageNotes,
+                    ];
+                }
                 let resultStr = typeof redacted === "string"
                     ? redacted
                     : JSON.stringify(redacted, null, 2);
@@ -3021,6 +3055,11 @@ export async function runAgentLoop(opts) {
                     const truncated = resultStr.slice(0, toolMaxResultChars);
                     resultStr = `${truncated}\n\n...[truncated — full result was ${resultStr.length.toLocaleString()} chars; only first ${toolMaxResultChars.toLocaleString()} shown]`;
                 }
+                // Image notes go after truncation so they always survive into the
+                // persisted result string (the durable record that an image existed).
+                if (imageNotes.length > 0) {
+                    resultStr = `${resultStr}\n\n${imageNotes.join("\n")}`;
+                }
                 result = resultStr;
                 if (toolCall.name === TOOL_SEARCH_ACTION_NAME && !isError) {
                     const added = expandActiveTools(extractToolSearchResultNames(rawForAgent));
@@ -3100,6 +3139,9 @@ export async function runAgentLoop(opts) {
                 toolInput: wireToolInput,
                 content: result,
                 ...(isError ? { isError } : {}),
+                ...(!isError && toolResultImages && toolResultImages.length > 0
+                    ? { images: toolResultImages }
+                    : {}),
             };
         };
         const getParallelBatchKind = (toolCall) => {
@@ -3449,13 +3491,26 @@ function endsAtContinuationBoundary(run) {
  */
 export const MAX_BACKGROUND_RUN_CONTINUATIONS = 20;
 /**
- * Whether the background worker should self-fire the next server-driven
- * continuation chunk. True only when this is a background worker run that ended
- * at a recoverable unfinished boundary (not aborted/stopped) and the chain is
- * still under its budget. Aborted / user-stopped runs do NOT chain.
+ * 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
+ * either of two independently-gated cases, both requiring a recoverable
+ * unfinished boundary (not aborted/stopped) and a chain still under its
+ * budget:
+ *   - a durable-background WORKER run (`isBackgroundWorker`) — unconditional,
+ *     unchanged from before; or
+ *   - a FOREGROUND run when the opt-in `foregroundSelfChainEligible` flag is
+ *     set (see `isAgentChatForegroundSelfChainEnabled` in
+ *     `durable-background.ts`) AND this specific run was never dispatched to
+ *     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.
  */
 export function shouldChainBackgroundContinuation(opts) {
-    return (opts.isBackgroundWorker &&
+    const eligible = opts.isBackgroundWorker ||
+        (opts.foregroundSelfChainEligible === true &&
+            opts.dispatchedToBackground !== true);
+    return (eligible &&
         opts.run.status !== "aborted" &&
         endsAtContinuationBoundary(opts.run) &&
         opts.continuationCount < MAX_BACKGROUND_RUN_CONTINUATIONS);
@@ -3503,6 +3558,258 @@ export async function claimBackgroundWorkerRunEarly(opts) {
     await heartbeat(opts.runId).catch(() => { });
     return { claimed: true };
 }
+/**
+ * Server-driven continuation handoff for a chunk that hit its soft-timeout
+ * boundary still unfinished: mint the next chunk's runId, PRE-INSERT its run
+ * row (so `/runs/active` never shows an idle gap and a lost dispatch is
+ * reaped loudly instead of hanging silently), fire the HMAC-signed
+ * `_process-run` self-dispatch carrying ids only (the body is persisted on
+ * the row as `dispatch_payload`), fully AWAIT the dispatch acknowledgment
+ * with retries, and mark this chunk terminal only after the handoff landed.
+ * On failure every path is loud: the successor row is errored, the failure
+ * is recorded as the run's diag stage, and this chunk is flipped to errored
+ * with a terminal reason — never a silent loss. (For a FOREGROUND self-chain
+ * the client additionally still receives the terminal `auto_continue` event
+ * — run-manager emits it after this callback — so the existing client
+ * re-POST path takes over as the fallback.)
+ *
+ * `chainViaDurableBackground` selects the dispatch target:
+ *   - true  → the durable-background worker chain (unchanged behavior): the
+ *     resolved background-function url on hosted Netlify (15-min budget), 3
+ *     attempts, 15s response timeout (Netlify async functions 202 on enqueue).
+ *   - false → the OPT-IN foreground self-chain: the framework `_process-run`
+ *     route on the REGULAR function. With `AGENT_CHAT_DURABLE_BACKGROUND`
+ *     off the `-background` function is never emitted into the deploy
+ *     output, so the regular function is the only guaranteed target; the
+ *     successor keeps the 40s chunk clamp (`backgroundFunctionRuntimeExpected`
+ *     is false for this path). The regular function responds only after the
+ *     successor chunk FINISHES (~40s), so a response timeout is NOT proof of
+ *     a dead handoff — after a failed/timed-out attempt the successor's
+ *     ATOMIC CLAIM is consulted (`readBackgroundRunClaim`): a row that
+ *     flipped to `background-processing` (or already went terminal) proves
+ *     the handoff landed, so no retry is fired. 2 attempts, ~10s settle.
+ *
+ * Never throws — all failure paths are handled (recorded + marked) inside.
+ */
+export async function chainServerDrivenContinuation(opts) {
+    const d = {
+        countRunsForTurn: opts.deps?.countRunsForTurn ?? countRunsForTurn,
+        insertRun: opts.deps?.insertRun ?? insertRun,
+        fireInternalDispatch: opts.deps?.fireInternalDispatch ?? fireInternalDispatch,
+        readBackgroundRunClaim: opts.deps?.readBackgroundRunClaim ?? readBackgroundRunClaim,
+        updateRunHeartbeat: opts.deps?.updateRunHeartbeat ?? updateRunHeartbeat,
+        updateRunStatusIfRunning: opts.deps?.updateRunStatusIfRunning ?? updateRunStatusIfRunning,
+        setRunTerminalReason: opts.deps?.setRunTerminalReason ?? setRunTerminalReason,
+        recordRunDiagnostic: opts.deps?.recordRunDiagnostic ?? recordRunDiagnostic,
+        markBackgroundContinuationChunkTerminal: opts.deps?.markBackgroundContinuationChunkTerminal ??
+            markBackgroundContinuationChunkTerminal,
+        generateRunId: opts.deps?.generateRunId ?? generateRunId,
+        sleep: opts.deps?.sleep ??
+            ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
+    };
+    const { run, effectiveThreadId, effectiveTurnId } = opts;
+    const runId = run.runId;
+    // DURABLE PER-TURN LEDGER: bound the total number of runs one logical turn
+    // may consume, counted in SQL. The in-marker `continuationCount` resets
+    // whenever a fresh POST starts a new chain for the same turn (client
+    // recovery, duplicate delivery), so it cannot bound cross-chain loops — the
+    // SQL count survives every recovery path and is what actually kills a
+    // pathological turn (the "dozens of runs on one prompt" incident class).
+    const turnRunCount = await d
+        .countRunsForTurn(effectiveThreadId, effectiveTurnId)
+        .catch(() => null);
+    if (turnRunCount !== null &&
+        turnRunCount > MAX_BACKGROUND_RUN_CONTINUATIONS + 5) {
+        console.error(`[agent-chat] turn ${effectiveTurnId} consumed ${turnRunCount} runs — refusing to chain further`, runId);
+        const statusUpdated = await d
+            .updateRunStatusIfRunning(runId, "errored")
+            .catch(() => false);
+        if (statusUpdated) {
+            await d
+                .setRunTerminalReason(runId, "turn_continuation_budget_exhausted")
+                .catch(() => { });
+        }
+        return;
+    }
+    // Mint the next chunk's runId here and sign the dispatch token over it, so
+    // the `_process-run` route's HMAC check and the worker's run identity
+    // agree. Fresh runId (not this chunk's) so its seq log starts clean; same
+    // turnId folds the assistant message across chunks.
+    const nextRunId = d.generateRunId();
+    const actionPreparationTool = lastUnfinishedPreparingActionTool(run);
+    const continuationReason = backgroundContinuationReasonForRun(run);
+    const continuationDispatchPath = opts.chainViaDurableBackground
+        ? resolveAgentChatProcessRunDispatchPath()
+        : AGENT_CHAT_PROCESS_RUN_PATH;
+    const continuationExpectsNetlifyBackgroundFunction = dispatchPathTargetsNetlifyBackgroundFunction(continuationDispatchPath);
+    const maxDispatchAttempts = opts.chainViaDurableBackground ? 3 : 2;
+    const dispatchResponseTimeoutMs = opts.chainViaDurableBackground
+        ? 15_000
+        : 10_000;
+    const continuationMarker = {
+        runId: nextRunId,
+        turnId: effectiveTurnId,
+        continuationCount: opts.backgroundContinuationCount + 1,
+        continuationReason,
+        ...(actionPreparationTool ? { actionPreparationTool } : {}),
+        backgroundFunctionRuntimeExpected: continuationExpectsNetlifyBackgroundFunction,
+    };
+    // Strip this chunk's own marker before persisting/forwarding — the next
+    // chunk gets the fresh marker above.
+    const continuationBody = {
+        ...opts.requestBody,
+        internalContinuation: true,
+    };
+    delete continuationBody[AGENT_CHAT_BACKGROUND_RUN_FIELD];
+    try {
+        await d
+            .recordRunDiagnostic(runId, RUN_DIAG_STAGE.workerSetupStep, `chain_dispatch_start nextRunId=${nextRunId} reason=${continuationReason} path=${continuationDispatchPath}`)
+            .catch(() => { });
+        // ── TRANSACTIONAL HANDOFF ──────────────────────────────────────────────
+        // 1. Insert the successor row (with its rehydration payload) BEFORE
+        //    firing the dispatch, so:
+        //    - /runs/active shows an active run continuously across the chunk
+        //      boundary (no idle gap for the client to misread as "the turn
+        //      ended"), and
+        //    - a lost dispatch leaves a row the unclaimed-run sweep reaps into a
+        //      LOUD error instead of a silent hang.
+        // 2. Await the dispatch response fully (`awaitResponse`) — this
+        //    invocation is about to finish, and the old 250ms settle race let a
+        //    still-in-flight handoff fetch be killed by the post-return freeze
+        //    WITHOUT rejecting: the turn just stopped, silently. A Netlify
+        //    background function 202s on enqueue (normally well under a second);
+        //    a regular-function target instead responds only after the successor
+        //    chunk finishes, so its timeout falls back to the claim check below.
+        //    Retried with backoff for transient network blips.
+        let nextRowInserted = false;
+        try {
+            await d.insertRun(nextRunId, effectiveThreadId, effectiveTurnId, {
+                dispatchMode: "background",
+                dispatchPayload: JSON.stringify(continuationBody),
+            });
+            nextRowInserted = true;
+        }
+        catch (insertErr) {
+            await d
+                .recordRunDiagnostic(runId, RUN_DIAG_STAGE.workerSetupStep, `chain_successor_insert_failed nextRunId=${nextRunId} ${insertErr instanceof Error ? insertErr.message : String(insertErr)}`)
+                .catch(() => { });
+            console.error("[agent-chat] continuation insertRun failed; dispatching with inline body:", insertErr instanceof Error ? insertErr.message : insertErr);
+        }
+        const dispatchBody = nextRowInserted
+            ? {
+                internalContinuation: true,
+                [AGENT_CHAT_BACKGROUND_RUN_FIELD]: {
+                    ...continuationMarker,
+                    payloadRef: true,
+                },
+            }
+            : {
+                ...continuationBody,
+                [AGENT_CHAT_BACKGROUND_RUN_FIELD]: continuationMarker,
+            };
+        let dispatched = false;
+        let lastDispatchErr;
+        for (let attempt = 0; attempt < maxDispatchAttempts && !dispatched; attempt++) {
+            try {
+                if (attempt > 0) {
+                    await d.sleep(500 * 2 ** attempt);
+                    // Keep the pre-inserted successor row visibly alive while we
+                    // retry: the awaited attempts + backoff can outlast
+                    // UNCLAIMED_BACKGROUND_RUN_GRACE_MS (25s), and without a fresh
+                    // heartbeat the unclaimed-run reaper / sweep could error a handoff
+                    // we are still delivering.
+                    if (nextRowInserted) {
+                        await d.updateRunHeartbeat(nextRunId).catch(() => { });
+                    }
+                }
+                await d.fireInternalDispatch({
+                    event: opts.event,
+                    // Durable chain: same path resolution as the initial dispatch —
+                    // on hosted Netlify the background function's DEFAULT url (no
+                    // custom config.path; async via background:true; never shadowed
+                    // because /.netlify/* is excluded from the /* catch-all) so each
+                    // chunk keeps the 15-min budget; off-Netlify the in-process
+                    // framework route. Foreground self-chain: always the framework
+                    // `_process-run` route on the regular function (see the fn doc).
+                    path: continuationDispatchPath,
+                    taskId: nextRunId,
+                    body: dispatchBody,
+                    awaitResponse: true,
+                    responseTimeoutMs: dispatchResponseTimeoutMs,
+                });
+                dispatched = true;
+            }
+            catch (dispatchErr) {
+                lastDispatchErr = dispatchErr;
+                // Regular-function targets (foreground self-chain) respond only
+                // after the successor chunk FINISHES, so an await timeout is not
+                // proof of a dead handoff. The successor's ATOMIC CLAIM is: a row
+                // that left `dispatch_mode='background'` (claimed) or is already
+                // terminal proves the handoff landed — stop retrying. A duplicate
+                // delivery would lose the claim and no-op anyway; skipping it saves
+                // wall-clock this close to the invocation deadline.
+                if (!opts.chainViaDurableBackground && nextRowInserted) {
+                    const claim = await d
+                        .readBackgroundRunClaim(nextRunId)
+                        .catch(() => null);
+                    if (claim &&
+                        ((claim.dispatchMode && claim.dispatchMode !== "background") ||
+                            (claim.status && claim.status !== "running"))) {
+                        dispatched = true;
+                        break;
+                    }
+                }
+                console.error(`[agent-chat] background continuation dispatch attempt ${attempt + 1} failed:`, dispatchErr instanceof Error ? dispatchErr.message : dispatchErr);
+            }
+        }
+        if (!dispatched) {
+            // The pre-inserted successor row would otherwise sit unclaimed until
+            // the sweep reaps it — error it now so the failure is immediate and
+            // truthful.
+            if (nextRowInserted) {
+                const nextStatusUpdated = await d
+                    .updateRunStatusIfRunning(nextRunId, "errored")
+                    .catch(() => false);
+                if (nextStatusUpdated) {
+                    await d
+                        .setRunTerminalReason(nextRunId, "background_continuation_dispatch_failed")
+                        .catch(() => { });
+                }
+            }
+            throw lastDispatchErr instanceof Error
+                ? lastDispatchErr
+                : new Error(String(lastDispatchErr));
+        }
+        await d
+            .recordRunDiagnostic(runId, RUN_DIAG_STAGE.workerSetupStep, `chain_dispatch_sent nextRunId=${nextRunId} reason=${continuationReason}`)
+            .catch(() => { });
+        await d
+            .markBackgroundContinuationChunkTerminal({
+            runId,
+            continuationReason,
+        })
+            .catch(() => { });
+    }
+    catch (chainErr) {
+        // Chain dispatch failed — fail loud so the held row goes terminal
+        // instead of spinning. The reaper would also catch it, but this is
+        // immediate and truthful. (Foreground self-chain: the client still
+        // receives the terminal auto_continue after this returns, so its
+        // existing re-POST continuation path takes over.)
+        await d
+            .recordRunDiagnostic(runId, RUN_DIAG_STAGE.workerThrew, `chain_dispatch_failed nextRunId=${nextRunId} ${chainErr instanceof Error ? chainErr.message : String(chainErr)}`)
+            .catch(() => { });
+        console.error("[agent-chat] background continuation dispatch failed:", chainErr instanceof Error ? chainErr.message : chainErr);
+        const statusUpdated = await d
+            .updateRunStatusIfRunning(runId, "errored")
+            .catch(() => false);
+        if (statusUpdated) {
+            await d
+                .setRunTerminalReason(runId, "background_continuation_dispatch_failed")
+                .catch(() => { });
+        }
+    }
+}
 function progressStepFromAgentChatEvent(event) {
     switch (event.type) {
         case "activity":
@@ -3759,14 +4066,15 @@ export function createProductionAgentHandler(options) {
         // for that provider instead of the global active engine's provider.
         // DIAGNOSTIC-ONLY: bracket per-owner API-key resolution (settings/app_secrets reads).
         workerStep("apikey_start");
-        const allowDeployCredentialFallback = canUseDeployCredentialFallbackForRequest();
         let userApiKey;
         if (requestEngine) {
             const provider = engineToProvider(requestEngine);
             userApiKey = await getOwnerApiKey(provider, ownerEmail);
-            if (!userApiKey && allowDeployCredentialFallback) {
+            const envVar = PROVIDER_TO_ENV[provider];
+            if (!userApiKey &&
+                envVar &&
+                canUseDeployCredentialFallbackForRequest(envVar)) {
                 // Read-only env fallback for the requested provider.
-                const envVar = PROVIDER_TO_ENV[provider];
                 userApiKey = envVar ? readDeployCredentialEnv(envVar) : undefined;
             }
         }
@@ -3778,7 +4086,7 @@ export function createProductionAgentHandler(options) {
         // `options.apiKey` is the value the template constructed the plugin with
         // (often wired from a deployment env var). Honor it as host-provided
         // read-only configuration after scoped keys when deploy fallback is safe.
-        const hostApiKey = allowDeployCredentialFallback
+        const hostApiKey = canUseDeployCredentialFallbackForRequest("ANTHROPIC_API_KEY")
             ? (options.apiKey ?? readDeployCredentialEnv("ANTHROPIC_API_KEY"))
             : undefined;
         const effectiveApiKey = userApiKey ?? hostApiKey;
@@ -3876,6 +4184,26 @@ export function createProductionAgentHandler(options) {
                 setupMarks.sysPromptMs = Date.now() - sysPromptStart;
             }
         })();
+        // Precise current time is volatile (changes every request) and must never
+        // live in the cached system-prompt prefix — see buildRuntimeContextPrompt
+        // in runtime-context.ts. It is injected here, per-turn, into the user
+        // message instead, following the same pattern as the screen/url/selection
+        // context below. This keeps "what time is it" answerable while leaving
+        // the system prompt's runtime-context block stable at day granularity.
+        const timeContextThunk = () => (async () => {
+            try {
+                const tzRaw = getHeader(event, "x-user-timezone");
+                const timezone = typeof tzRaw === "string" &&
+                    tzRaw.trim().length > 0 &&
+                    tzRaw.trim().length < 64
+                    ? tzRaw.trim()
+                    : undefined;
+                return buildCurrentTimeUserContext({ timezone });
+            }
+            catch {
+                return buildCurrentTimeUserContext();
+            }
+        })();
         const screenContextThunk = () => (async () => {
             const screenStart = Date.now();
             try {
@@ -4088,8 +4416,9 @@ export function createProductionAgentHandler(options) {
             scope: "default",
             source: "default",
         };
-        const [systemPrompt, screenBlock, urlBlock, selectionBlock, filesContext, loopSettings, enrichedMessage,] = await Promise.all([
+        const [systemPrompt, timeBlock, screenBlock, urlBlock, selectionBlock, filesContext, loopSettings, enrichedMessage,] = await Promise.all([
             presendCap("systemPrompt", systemPromptThunk, "", 13000),
+            presendCap("time", timeContextThunk, "", 9000),
             presendCap("screen", screenContextThunk, "", 9000),
             presendCap("url", urlContextThunk, "", 9000),
             presendCap("selection", selectionContextThunk, "", 9000),
@@ -4113,7 +4442,7 @@ export function createProductionAgentHandler(options) {
                 },
             });
         }
-        const screenContext = screenBlock + urlBlock + selectionBlock;
+        const screenContext = timeBlock + screenBlock + urlBlock + selectionBlock;
         const requestActions = requestMode === "plan"
             ? createPlanModeActionRegistry(resolvedActions)
             : resolvedActions;
@@ -4399,10 +4728,27 @@ export function createProductionAgentHandler(options) {
                 turnId: effectiveTurnId,
             }
             : null;
+        // Opt-in (default-OFF) foreground self-chain: gated on the env flag AND
+        // this specific run never having been routed to the durable background
+        // worker. A run that WAS dispatched to background (`dispatchToBackground`)
+        // already has its recovery owned by the background circuit-breaker /
+        // `isBackgroundWorker` chain above — this flag must never double up with
+        // that path, only stand in for it on plain foreground turns. A persistent
+        // threadId is required: the client discovers the pre-inserted successor
+        // via `/runs/active?threadId` and the successor chunk resumes from the
+        // thread's persisted thread_data — without a thread there is neither a
+        // discovery channel nor durable progress to resume from.
+        const foregroundSelfChainEligible = !isBackgroundWorker &&
+            !dispatchToBackground &&
+            typeof threadId === "string" &&
+            threadId.trim().length > 0 &&
+            isAgentChatForegroundSelfChainEnabled();
         const willChainBackgroundContinuation = (run) => shouldChainBackgroundContinuation({
             isBackgroundWorker,
             run,
             continuationCount: backgroundContinuationCount,
+            foregroundSelfChainEligible,
+            dispatchedToBackground: dispatchToBackground,
         });
         const completeTrackedProgressRun = async (run, completionError) => {
             if (!trackedProgressRunId || !trackedProgressOwner)
@@ -4480,8 +4826,10 @@ export function createProductionAgentHandler(options) {
             }
             : undefined;
         // Wrap so the background worker is unblocked even when there is no app
-        // onRunComplete / tracked-progress callback configured.
-        const handleRunComplete = isBackgroundWorker || baseHandleRunComplete
+        // onRunComplete / tracked-progress callback configured. Also installed for
+        // a foreground run eligible for the opt-in self-chain — that path needs
+        // this same wrapper to fire the continuation dispatch below.
+        const handleRunComplete = isBackgroundWorker || foregroundSelfChainEligible || baseHandleRunComplete
             ? async (run) => {
                 try {
                     // DIAGNOSTIC: a background worker that completed in an errored
@@ -4531,167 +4879,28 @@ export function createProductionAgentHandler(options) {
                     // foreground fallback, which is not a worker and rides the
                     // connected client's auto_continue instead.)
                     if (willChainBackgroundContinuation(run)) {
-                        // DURABLE PER-TURN LEDGER: bound the total number of runs one
-                        // logical turn may consume, counted in SQL. The in-marker
-                        // `continuationCount` resets whenever a fresh POST starts a new
-                        // chain for the same turn (client recovery, duplicate delivery),
-                        // so it cannot bound cross-chain loops — the SQL count survives
-                        // every recovery path and is what actually kills a pathological
-                        // turn (the "dozens of runs on one prompt" incident class).
-                        const turnRunCount = await countRunsForTurn(effectiveThreadId, effectiveTurnId).catch(() => null);
-                        if (turnRunCount !== null &&
-                            turnRunCount > MAX_BACKGROUND_RUN_CONTINUATIONS + 5) {
-                            console.error(`[agent-chat] turn ${effectiveTurnId} consumed ${turnRunCount} runs — refusing to chain further`, runId);
-                            const statusUpdated = await updateRunStatusIfRunning(runId, "errored").catch(() => false);
-                            if (statusUpdated) {
-                                await setRunTerminalReason(runId, "turn_continuation_budget_exhausted").catch(() => { });
-                            }
-                            return;
-                        }
-                        // Mint the next chunk's runId here and sign the dispatch token
-                        // over it, so the `_process-run` route's HMAC check and the
-                        // worker's run identity agree. Fresh runId (not this chunk's) so
-                        // its seq log starts clean; same turnId folds the assistant
-                        // message across chunks.
-                        const nextRunId = generateRunId();
-                        const actionPreparationTool = lastUnfinishedPreparingActionTool(run);
-                        const continuationReason = backgroundContinuationReasonForRun(run);
-                        const continuationDispatchPath = resolveAgentChatProcessRunDispatchPath();
-                        const continuationExpectsNetlifyBackgroundFunction = dispatchPathTargetsNetlifyBackgroundFunction(continuationDispatchPath);
-                        const continuationMarker = {
-                            runId: nextRunId,
-                            turnId: effectiveTurnId,
-                            continuationCount: backgroundContinuationCount + 1,
-                            continuationReason,
-                            ...(actionPreparationTool ? { actionPreparationTool } : {}),
-                            backgroundFunctionRuntimeExpected: continuationExpectsNetlifyBackgroundFunction,
-                        };
-                        // Strip this chunk's own marker before persisting/forwarding —
-                        // the next chunk gets the fresh marker above.
-                        const continuationBody = {
-                            ...body,
-                            internalContinuation: true,
-                        };
-                        delete continuationBody[AGENT_CHAT_BACKGROUND_RUN_FIELD];
-                        try {
-                            await recordRunDiagnostic(run.runId, RUN_DIAG_STAGE.workerSetupStep, `chain_dispatch_start nextRunId=${nextRunId} reason=${continuationReason} path=${continuationDispatchPath}`).catch(() => { });
-                            // ── TRANSACTIONAL HANDOFF ──────────────────────────────────
-                            // 1. Insert the successor row (with its rehydration payload)
-                            //    BEFORE firing the dispatch, so:
-                            //    - /runs/active shows an active run continuously across
-                            //      the chunk boundary (no idle gap for the client to
-                            //      misread as "the turn ended"), and
-                            //    - a lost dispatch leaves a row the unclaimed-run sweep
-                            //      reaps into a LOUD error instead of a silent hang.
-                            // 2. Await the dispatch response fully (`awaitResponse`) —
-                            //    this worker's Lambda is about to finish, and the old
-                            //    250ms settle race let a still-in-flight handoff fetch be
-                            //    killed by the post-return freeze WITHOUT rejecting: the
-                            //    turn just stopped, silently. A Netlify background
-                            //    function 202s on enqueue (normally well under a second),
-                            //    and this chunk has minutes of budget headroom left, so
-                            //    awaiting is cheap. Retried with backoff for transient
-                            //    network blips.
-                            let nextRowInserted = false;
-                            try {
-                                await insertRun(nextRunId, effectiveThreadId, effectiveTurnId, {
-                                    dispatchMode: "background",
-                                    dispatchPayload: JSON.stringify(continuationBody),
-                                });
-                                nextRowInserted = true;
-                            }
-                            catch (insertErr) {
-                                await recordRunDiagnostic(run.runId, RUN_DIAG_STAGE.workerSetupStep, `chain_successor_insert_failed nextRunId=${nextRunId} ${insertErr instanceof Error
-                                    ? insertErr.message
-                                    : String(insertErr)}`).catch(() => { });
-                                console.error("[agent-chat] continuation insertRun failed; dispatching with inline body:", insertErr instanceof Error
-                                    ? insertErr.message
-                                    : insertErr);
-                            }
-                            const dispatchBody = nextRowInserted
-                                ? {
-                                    internalContinuation: true,
-                                    [AGENT_CHAT_BACKGROUND_RUN_FIELD]: {
-                                        ...continuationMarker,
-                                        payloadRef: true,
-                                    },
-                                }
-                                : {
-                                    ...continuationBody,
-                                    [AGENT_CHAT_BACKGROUND_RUN_FIELD]: continuationMarker,
-                                };
-                            let dispatched = false;
-                            let lastDispatchErr;
-                            for (let attempt = 0; attempt < 3 && !dispatched; attempt++) {
-                                try {
-                                    if (attempt > 0) {
-                                        await new Promise((resolve) => setTimeout(resolve, 500 * 2 ** attempt));
-                                        // Keep the pre-inserted successor row visibly alive
-                                        // while we retry: the awaited attempts + backoff can
-                                        // outlast UNCLAIMED_BACKGROUND_RUN_GRACE_MS (25s), and
-                                        // without a fresh heartbeat the unclaimed-run reaper /
-                                        // sweep could error a handoff we are still delivering.
-                                        if (nextRowInserted) {
-                                            await updateRunHeartbeat(nextRunId).catch(() => { });
-                                        }
-                                    }
-                                    await fireInternalDispatch({
-                                        event,
-                                        // Continuation chunks use the same path resolution as
-                                        // the initial dispatch: on hosted Netlify the background
-                                        // function's DEFAULT url (no custom config.path; async
-                                        // via background:true; never shadowed because
-                                        // /.netlify/* is excluded from the /* catch-all) so each
-                                        // chunk keeps the 15-min budget; off-Netlify the
-                                        // in-process framework route.
-                                        path: continuationDispatchPath,
-                                        taskId: nextRunId,
-                                        body: dispatchBody,
-                                        awaitResponse: true,
-                                        responseTimeoutMs: 15_000,
-                                    });
-                                    dispatched = true;
-                                }
-                                catch (dispatchErr) {
-                                    lastDispatchErr = dispatchErr;
-                                    console.error(`[agent-chat] background continuation dispatch attempt ${attempt + 1} failed:`, dispatchErr instanceof Error
-                                        ? dispatchErr.message
-                                        : dispatchErr);
-                                }
-                            }
-                            if (!dispatched) {
-                                // The pre-inserted successor row would otherwise sit
-                                // unclaimed until the sweep reaps it — error it now so the
-                                // failure is immediate and truthful.
-                                if (nextRowInserted) {
-                                    const nextStatusUpdated = await updateRunStatusIfRunning(nextRunId, "errored").catch(() => false);
-                                    if (nextStatusUpdated) {
-                                        await setRunTerminalReason(nextRunId, "background_continuation_dispatch_failed").catch(() => { });
-                                    }
-                                }
-                                throw lastDispatchErr instanceof Error
-                                    ? lastDispatchErr
-                                    : new Error(String(lastDispatchErr));
-                            }
-                            await recordRunDiagnostic(run.runId, RUN_DIAG_STAGE.workerSetupStep, `chain_dispatch_sent nextRunId=${nextRunId} reason=${continuationReason}`).catch(() => { });
-                            await markBackgroundContinuationChunkTerminal({
-                                runId: run.runId,
-                                continuationReason,
-                            }).catch(() => { });
-                        }
-                        catch (chainErr) {
-                            // Chain dispatch failed — fail loud so the held row goes
-                            // terminal instead of spinning. The reaper would also catch
-                            // it, but this is immediate and truthful.
-                            await recordRunDiagnostic(run.runId, RUN_DIAG_STAGE.workerThrew, `chain_dispatch_failed nextRunId=${nextRunId} ${chainErr instanceof Error
-                                ? chainErr.message
-                                : String(chainErr)}`).catch(() => { });
-                            console.error("[agent-chat] background continuation dispatch failed:", chainErr instanceof Error ? chainErr.message : chainErr);
-                            const statusUpdated = await updateRunStatusIfRunning(runId, "errored").catch(() => false);
-                            if (statusUpdated) {
-                                await setRunTerminalReason(runId, "background_continuation_dispatch_failed").catch(() => { });
-                            }
-                        }
+                        // Full handoff discipline lives in
+                        // `chainServerDrivenContinuation` (exported + unit-tested):
+                        // per-turn SQL run budget, successor row PRE-INSERTED before
+                        // the dispatch, fully awaited dispatch with retries, loud
+                        // diag/terminal marking on failure. Never throws.
+                        await chainServerDrivenContinuation({
+                            event,
+                            run,
+                            effectiveThreadId,
+                            effectiveTurnId,
+                            requestBody: body,
+                            backgroundContinuationCount,
+                            // Re-evaluate the durable gate rather than keying off
+                            // isBackgroundWorker: a successor chunk of a FOREGROUND
+                            // self-chain re-enters as a worker too, and must keep
+                            // chaining via the regular function — the Netlify
+                            // `-background` function is only emitted into the deploy
+                            // output when the durable flag is on.
+                            chainViaDurableBackground: isAgentChatDurableBackgroundEnabled({
+                                appOptIn: options.durableBackgroundRuns === true,
+                            }),
+                        });
                     }
                 }
                 finally {