@agent-native/core 0.90.4 → 0.90.5

package/corpus/README.md

@@ -28,4 +28,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 ## Generated Counts
 
 - core files: 2144
-- template files: 4817
+- template files: 4822

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @agent-native/core
 
+## 0.90.5
+
+### Patch Changes
+
+- 3da78df: Classify BYO-provider rate limits (HTTP 429) as retryable. The native Anthropic and AI-SDK engines now forward the provider HTTP status as a structured `http_<status>` errorCode + `statusCode` for every failure (not just 401), so a bare "429 status code (no body)" surfaces as `http_429`. `isRetryableError` also matches `http_429` and bare `429` messages. Previously a directly-connected provider key that Anthropic rate-limited failed hard instead of backing off and retrying like the Builder gateway path does, and rate-limited runs can now auto-continue.
+- 3da78df: Fix localhost Design bridge self-registration so capability payloads match the Design server action and bridge tokens can be persisted.
+- 3da78df: Make hosted foreground agent turns continue from the server by default, so switching tabs or closing the browser no longer leaves long runs dependent on a client-side auto-continue POST.
+
 ## 0.90.4
 
 ### Patch Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.90.4",
+  "version": "0.90.5",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {

package/corpus/core/src/agent/durable-background.ts

@@ -340,17 +340,17 @@ export function isAgentChatDurableBackgroundEnabled(options?: {
 }
 
 /**
- * Env flag for the FOREGROUND server-driven self-chain. DEFAULT-OFF (opt-in):
- * unset means disabled; an app opts IN with an explicit truthy value
- * (`true`/`1`/`yes`/`on`) — same parsing convention as
- * `AGENT_CHAT_DURABLE_BACKGROUND`, deliberately kept as a separate flag so
- * this narrower capability can be enabled/disabled independently of the full
- * durable-background worker path.
+ * Env flag for the FOREGROUND server-driven self-chain. DEFAULT-ON for hosted
+ * deployments with `A2A_SECRET`: unset/empty/unknown means enabled, and an app
+ * opts OUT with an explicit falsy value (`false`/`0`/`no`/`off`). Deliberately
+ * kept separate from `AGENT_CHAT_DURABLE_BACKGROUND` so this narrower
+ * capability can be disabled independently of the full durable-background
+ * worker path.
  */
 export const AGENT_CHAT_FOREGROUND_SELF_CHAIN_ENV =
   "AGENT_CHAT_FOREGROUND_SELF_CHAIN";
 
-function isForegroundSelfChainFlagEnabled(): boolean {
+function isForegroundSelfChainExplicitlyDisabled(): boolean {
   // Read the literal key (not `process.env[CONST]`) so guard:no-env-credentials
   // can statically verify it against the allowlisted `AGENT_*` prefix. Keep this
   // in sync with AGENT_CHAT_FOREGROUND_SELF_CHAIN_ENV.
@@ -358,26 +358,26 @@ function isForegroundSelfChainFlagEnabled(): boolean {
   if (raw == null) return false;
   const normalized = raw.trim().toLowerCase();
   return (
-    normalized === "1" ||
-    normalized === "true" ||
-    normalized === "yes" ||
-    normalized === "on"
+    normalized === "0" ||
+    normalized === "false" ||
+    normalized === "no" ||
+    normalized === "off"
   );
 }
 
 /**
- * Gate for the OPT-IN foreground self-chain: a normal (non-durable-background)
+ * Gate for the foreground self-chain: a normal (non-durable-background)
  * agent-chat turn that hits its soft-timeout chunk boundary continues via a
  * server-side self-dispatch on the REGULAR function (not a Netlify
  * `-background` function) instead of depending on the client to re-POST
  * `auto_continue`. Composes exactly like `isAgentChatDurableBackgroundEnabled`:
- * true only when the env flag is explicitly truthy AND the runtime is hosted
- * AND `A2A_SECRET` is configured (the HMAC handoff authenticates the
- * self-dispatch). False otherwise — and false means the existing
- * client-driven `auto_continue` re-POST path is used unchanged, byte-for-byte.
+ * true when the runtime is hosted AND `A2A_SECRET` is configured (the HMAC
+ * handoff authenticates the self-dispatch), unless the env flag is explicitly
+ * falsy. False otherwise — and false means the existing client-driven
+ * `auto_continue` re-POST path is used unchanged, byte-for-byte.
  *
  * Deliberately independent of `isAgentChatDurableBackgroundEnabled`: an app can
- * enable this narrower capability without opting into the full 15-min
+ * use this narrower capability without opting into the full 15-min
  * background-function worker path, and the two gates never need to agree.
  * When BOTH would be true for a given run, the durable-background dispatch
  * decision in `production-agent.ts` is evaluated first and takes precedence —
@@ -386,7 +386,7 @@ function isForegroundSelfChainFlagEnabled(): boolean {
  */
 export function isAgentChatForegroundSelfChainEnabled(): boolean {
   return (
-    isForegroundSelfChainFlagEnabled() &&
+    !isForegroundSelfChainExplicitlyDisabled() &&
     isHostedRuntimeForDurableBackground() &&
     hasConfiguredA2ASecret()
   );

package/corpus/core/src/agent/engine/ai-sdk-engine.ts

@@ -384,8 +384,14 @@ class AISDKEngine implements AgentEngine {
         type: "stop",
         reason: "error",
         error: err?.message ?? String(err),
-        ...(statusCode === 401 ? { errorCode: "http_401" } : {}),
-        ...(statusCode !== undefined ? { statusCode } : {}),
+        // Tag every known status with `http_<status>` (not just 401) so a
+        // rate limit surfaces as `http_429`. The structured statusCode
+        // already drives turn-level retries, but the run-level continuation
+        // logic keys off the errorCode, so this lets a rate-limited turn
+        // auto-resume too — matching the Builder gateway path.
+        ...(statusCode !== undefined
+          ? { errorCode: `http_${statusCode}`, statusCode }
+          : {}),
         ...(providerRetryable !== undefined ? { providerRetryable } : {}),
       };
       throw err;

package/corpus/core/src/agent/engine/anthropic-engine.ts

@@ -227,7 +227,17 @@ class AnthropicEngine implements AgentEngine {
         type: "stop",
         reason: "error",
         error: err?.message ?? String(err),
-        ...(statusCode === 401 ? { errorCode: "http_401", statusCode } : {}),
+        // Forward the provider HTTP status for EVERY known status, not just
+        // 401. The Anthropic SDK reports empty-body failures as a bare
+        // "429 status code (no body)" message, so without a structured
+        // statusCode/errorCode `isRetryableError` couldn't classify a rate
+        // limit (it matches "529"/"502" substrings but not "429") and the
+        // run failed hard instead of backing off + retrying like the Builder
+        // gateway path does. `http_429`/`http_529` also let the run-level
+        // continuation logic auto-resume a rate-limited turn.
+        ...(statusCode !== undefined
+          ? { errorCode: `http_${statusCode}`, statusCode }
+          : {}),
       };
       throw err;
     }

package/corpus/core/src/agent/production-agent.ts

@@ -1132,6 +1132,7 @@ export function isRetryableError(err: unknown): boolean {
   return (
     code === "builder_gateway_error" ||
     code === "builder_gateway_network_error" ||
+    code === "http_429" ||
     code === "http_500" ||
     code === "http_502" ||
     code === "http_503" ||
@@ -1140,6 +1141,9 @@ export function isRetryableError(err: unknown): boolean {
     // Anthropic
     msg.includes("overloaded") ||
     msg.includes("rate_limit") ||
+    // Bare provider rate-limit messages that carry no structured status,
+    // e.g. the Anthropic/AI-SDK "429 status code (no body)" format.
+    /\b429\b/.test(msg) ||
     msg.includes("529") ||
     // OpenAI phrasing
     msg.includes("rate limit reached") ||
@@ -4620,8 +4624,8 @@ export const MAX_BACKGROUND_RUN_CONTINUATIONS = 20;
  * 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
+ *   - a FOREGROUND run when the resolved `foregroundSelfChainEligible` gate is
+ *     true (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
@@ -6189,12 +6193,12 @@ export function createProductionAgentHandler(
           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
+    // Foreground self-chain: gated on hosted runtime + A2A_SECRET, with an
+    // explicit env opt-out, 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
@@ -6302,8 +6306,8 @@ export function createProductionAgentHandler(
 
     // Wrap so the background worker is unblocked even when there is no app
     // 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.
+    // a foreground run eligible for self-chain — that path needs this same
+    // wrapper to fire the continuation dispatch below.
     const handleRunComplete =
       isBackgroundWorker || foregroundSelfChainEligible || baseHandleRunComplete
         ? async (run: ActiveRun) => {
@@ -6897,6 +6901,9 @@ export function createProductionAgentHandler(
         // assistant message. Falls back to the runId (turn == run) when the
         // client doesn't supply a turnId.
         turnId: effectiveTurnId,
+        dispatchMode: foregroundSelfChainEligible
+          ? "foreground-self-chain"
+          : "foreground",
       },
     );
 
@@ -6920,7 +6927,11 @@ export function createProductionAgentHandler(
     setResponseHeader(event, "Cache-Control", "no-cache");
     setResponseHeader(event, "Connection", "keep-alive");
     setResponseHeader(event, "X-Run-Id", runId);
-    setResponseHeader(event, "X-Dispatch-Mode", "foreground");
+    setResponseHeader(
+      event,
+      "X-Dispatch-Mode",
+      foregroundSelfChainEligible ? "foreground-self-chain" : "foreground",
+    );
 
     return stream;
   });

package/corpus/core/src/agent/run-manager.ts

@@ -264,6 +264,12 @@ export interface StartRunOptions {
    * and to disabled otherwise (local dev stays unbounded).
    */
   noProgressTimeoutMs?: 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.
+   */
+  dispatchMode?: "foreground" | "foreground-self-chain";
 }
 
 export interface ResolveRunSoftTimeoutOptions {
@@ -480,11 +486,16 @@ export function startRun(
   // Persist run to SQL without blocking the response. Keep the promise so
   // final status cannot race ahead of a slow initial INSERT and then get
   // overwritten by a late row stuck at status='running'.
-  const insertRunPromise = insertRun(runId, threadId, options?.turnId).catch(
-    (error) => {
-      captureRunPersistenceError(error, "insert-run");
-    },
-  );
+  const insertOptions = options?.dispatchMode
+    ? { dispatchMode: options.dispatchMode }
+    : undefined;
+  const insertRunPromise = (
+    insertOptions
+      ? insertRun(runId, threadId, options?.turnId, insertOptions)
+      : insertRun(runId, threadId, options?.turnId)
+  ).catch((error) => {
+    captureRunPersistenceError(error, "insert-run");
+  });
 
   // Per-run event persistence chain: events are chained so SQL inserts commit
   // in seq order. Without this, a fast seq=5 commit before a slow seq=4 means
@@ -1356,7 +1367,7 @@ export async function getActiveRunForThreadAsync(threadId: string): Promise<{
   status: string;
   heartbeatAt: number;
   lastProgressAt: number | null;
-  /** How the run was dispatched (NULL/foreground, background, background-processing). */
+  /** How the run was dispatched/continued (foreground, foreground-self-chain, background...). */
   dispatchMode?: string | null;
   /** Compact terminal classification, e.g. done, run_timeout, stale_run. */
   terminalReason?: string | null;

package/corpus/core/src/agent/run-store.ts

@@ -183,9 +183,11 @@ async function ensureRunTables(): Promise<void> {
           //                at completion so errored/cut-off runs are queryable for
           //                pattern analysis (see listErroredRuns).
           // dispatch_mode marks how a run was started: NULL/"foreground" for the
-          // normal synchronous path, "background" for a run dispatched into a
-          // Netlify background function. The reaper/claim widen the stale window
-          // for background rows so a slow cold-start isn't falsely reaped.
+          // normal client-continued synchronous path, "foreground-self-chain" for
+          // a foreground run whose continuation boundary is server-driven, and
+          // "background" for a run dispatched into a Netlify background function.
+          // The reaper/claim widen the stale window for background rows so a slow
+          // cold-start isn't falsely reaped.
           // diag_stage records the last reached pipeline stage (+ any error) for a
           // background-dispatched run so a silent worker death is DIAGNOSABLE from
           // the client (/runs/active surfaces it) without reading the unreadable
@@ -273,9 +275,11 @@ async function ensureRunTables(): Promise<void> {
       //                at completion so errored/cut-off runs are queryable for
       //                pattern analysis (see listErroredRuns).
       // dispatch_mode marks how a run was started: NULL/"foreground" for the
-      // normal synchronous path, "background" for a run dispatched into a
-      // Netlify background function. The reaper/claim widen the stale window
-      // for background rows so a slow cold-start isn't falsely reaped.
+      // normal client-continued synchronous path, "foreground-self-chain" for
+      // a foreground run whose continuation boundary is server-driven, and
+      // "background" for a run dispatched into a Netlify background function.
+      // The reaper/claim widen the stale window for background rows so a slow
+      // cold-start isn't falsely reaped.
       // diag_stage records the last reached pipeline stage (+ any error) for a
       // background-dispatched run so a silent worker death is DIAGNOSABLE from
       // the client (/runs/active surfaces it) without reading the unreadable
@@ -420,7 +424,7 @@ export async function insertRun(
   threadId: string,
   turnId?: string,
   options?: {
-    dispatchMode?: "foreground" | "background";
+    dispatchMode?: "foreground" | "foreground-self-chain" | "background";
     /**
      * JSON-serialized request body for a background dispatch. Persisted on the
      * run row so the self-POST to the background function carries only the
@@ -456,10 +460,11 @@ export async function insertRun(
  * subtracted by the resolved window so the comparison is
  * `COALESCE(heartbeat_at, started_at) < (now - window)`.
  *
- * `dispatch_mode` is one of NULL/"foreground" (normal sync path), "background"
- * (foreground inserted the row for a background dispatch), or
- * "background-processing" (the background worker claimed it). Both background
- * states get the wider window via a LIKE-prefix match.
+ * `dispatch_mode` is one of NULL/"foreground" (normal client-continued sync
+ * path), "foreground-self-chain" (server-driven continuation at the foreground
+ * chunk boundary), "background" (foreground inserted the row for a background
+ * dispatch), or "background-processing" (the background worker claimed it). Both
+ * background states get the wider window via a LIKE-prefix match.
  */
 function backgroundAwareStaleCutoffSql(): string {
   // `CAST(? AS BIGINT)` is required: without it Postgres infers the param as

package/corpus/core/src/cli/design-connect.ts

@@ -33,6 +33,16 @@ const BRIDGE_OPERATIONS = [
 
 type BridgeOperation = (typeof BRIDGE_OPERATIONS)[number];
 
+const SERVER_REGISTRATION_BRIDGE_OPERATIONS = new Set<BridgeOperation>([
+  "select",
+  "resolveNodeToFile",
+  "readFile",
+  "applyEdit",
+  "writeFile",
+  "captureSnapshot",
+  "captureState",
+]);
+
 /** Additive manifest capability flags advertised alongside the operation list. */
 const MANIFEST_CAPABILITIES = {
   listFiles: true,
@@ -1276,10 +1286,12 @@ export async function startDesignConnectBridge(
               manifest.devServerUrl,
               targetUrl,
             );
+            const includeEditorBridge =
+              requestUrl.searchParams.get("bridge") !== "0";
             const html = injectLiveEditBridge(
               snapshot.html,
               new URL("/", manifest.bridgeUrl).toString(),
-              liveEditBridgeScript,
+              includeEditorBridge ? liveEditBridgeScript : "",
             );
             sendText(
               res,
@@ -1680,7 +1692,9 @@ export async function registerConnectionWithServer(
     devServerUrl: manifest.devServerUrl,
     bridgeUrl: manifest.bridgeUrl,
     rootPath: manifest.rootPath,
-    capabilities: manifest.capabilities,
+    capabilities: manifest.capabilities.filter((capability) =>
+      SERVER_REGISTRATION_BRIDGE_OPERATIONS.has(capability.operation),
+    ),
     routeManifest: {
       version: 1 as const,
       sourceType: "localhost" as const,

package/corpus/core/src/client/KeepTabOpenNotice.tsx

@@ -9,23 +9,22 @@ import { cn } from "./utils.js";
 export const DEFAULT_KEEP_TAB_OPEN_AFTER_MS = 30_000;
 
 /**
- * Subtle, non-blocking notice that a long-running FOREGROUND agent turn
- * depends on this tab staying open.
+ * Subtle, non-blocking notice that a long-running client-continued foreground
+ * agent turn depends on this tab staying open.
  *
  * On hosted deployments a foreground turn runs in ~40s chunks and the CLIENT
- * re-POSTs `auto_continue` to start each next chunk — close the tab
- * mid-turn and the work silently stops at the next chunk boundary. Only
- * server-driven runs (`dispatchMode` starting with "background": the durable
- * background worker, or a server self-chained continuation) survive a closed
- * tab, and for those this notice never shows.
+ * may need to re-POST `auto_continue` to start each next chunk. Server-owned
+ * runs (`dispatchMode` starting with "background" or equal to
+ * "foreground-self-chain") survive a closed tab, and for those this notice
+ * never shows.
  *
  * Visibility rules (show only while the condition is true — no new
  * always-visible chrome):
- *   - a foreground-dispatched run for this thread has been continuously
+ *   - a client-continued foreground run for this thread has been continuously
  *     running for `showAfterMs` (default 30s — approaching the hosted ~40s
  *     chunk boundary where the client-driven continuation starts), and
- *   - the run is NOT background-dispatched (hidden immediately when the
- *     server owns recovery), and
+ *   - the run is not server-continued (hidden immediately when the server owns
+ *     recovery), and
  *   - this is a production client bundle (`hosted` auto-detect): local dev
  *     runs a turn unbounded in a single chunk that survives a closed tab,
  *     so the notice would be wrong there.
@@ -78,6 +77,13 @@ function isDevClientBundle(): boolean {
   }
 }
 
+function isServerContinuedDispatch(dispatchMode: string | null): boolean {
+  return (
+    dispatchMode === "foreground-self-chain" ||
+    dispatchMode?.startsWith("background") === true
+  );
+}
+
 export function KeepTabOpenNotice({
   threadId,
   enabled = true,
@@ -93,10 +99,9 @@ export function KeepTabOpenNotice({
     apiUrl,
     pollIntervalMs: NOTICE_POLL_INTERVAL_MS,
   });
-  const isBackgroundDispatch =
-    state.dispatchMode?.startsWith("background") === true;
+  const isServerContinued = isServerContinuedDispatch(state.dispatchMode);
   const foregroundRunning =
-    state.status === "running" && Boolean(state.runId) && !isBackgroundDispatch;
+    state.status === "running" && Boolean(state.runId) && !isServerContinued;
 
   const [visible, setVisible] = useState(false);
   const runningSinceRef = useRef<number | null>(null);
@@ -109,7 +114,7 @@ export function KeepTabOpenNotice({
   }, [threadId]);
 
   useEffect(() => {
-    if (!effectiveHosted || isBackgroundDispatch) {
+    if (!effectiveHosted || isServerContinued) {
       // Server-owned turn (or non-hosted client): the tab is not load-bearing.
       // Hide immediately and reset — no linger.
       runningSinceRef.current = null;
@@ -143,7 +148,7 @@ export function KeepTabOpenNotice({
   }, [
     effectiveHosted,
     foregroundRunning,
-    isBackgroundDispatch,
+    isServerContinued,
     showAfterMs,
     visible,
   ]);

package/corpus/core/src/client/RunStuckBanner.tsx

@@ -175,15 +175,16 @@ export function RunStuckBanner({
   }
   const ownerId = autoRetryOwnerId ?? generatedOwnerIdRef.current;
   const backgroundWorkerStillAlive = isFreshBackgroundWorker(state);
-  // Background-dispatched runs are recovered by the SERVER (chained
-  // continuation chunks + lost-handoff sweep); an automatic client abort
-  // would kill a live server-chained run. Auto-retry is therefore disabled
-  // unconditionally for ANY background dispatch mode — not just a
-  // fresh-heartbeat worker — and the localStorage/Web-Locks auto-retry claim
-  // below is never taken for these runs (the adapter's follow loop is
-  // read-only, so multiple tabs need no retry dedup). Only the manual banner
-  // remains, on the wider background threshold from useRunStuckDetection.
-  const isBackgroundDispatch =
+  // Server-continued runs are recovered by the SERVER (chained continuation
+  // chunks + lost-handoff sweep); an automatic client abort would kill a live
+  // server-chained run. Auto-retry is therefore disabled unconditionally for
+  // these modes — not just a fresh-heartbeat worker — and the
+  // localStorage/Web-Locks auto-retry claim below is never taken for them (the
+  // adapter's follow loop is read-only, so multiple tabs need no retry dedup).
+  // Only the manual banner remains, on the wider server-owned threshold from
+  // useRunStuckDetection.
+  const isServerContinuedDispatch =
+    state.dispatchMode === "foreground-self-chain" ||
     state.dispatchMode?.startsWith("background") === true;
 
   const lastReportedRef = useRef<{
@@ -224,9 +225,9 @@ export function RunStuckBanner({
   useEffect(() => {
     if (
       !autoRetry ||
-      // Server owns recovery for background dispatch modes — never auto-abort
-      // (see comment on isBackgroundDispatch above).
-      isBackgroundDispatch ||
+      // Server owns recovery for these dispatch modes — never auto-abort (see
+      // comment on isServerContinuedDispatch above).
+      isServerContinuedDispatch ||
       backgroundWorkerStillAlive ||
       !state.isStuck ||
       !state.runId ||
@@ -263,7 +264,7 @@ export function RunStuckBanner({
     autoRetry,
     backgroundWorkerStillAlive,
     busy,
-    isBackgroundDispatch,
+    isServerContinuedDispatch,
     onRetry,
     ownerId,
     state.isStuck,

package/corpus/core/src/client/agent-chat-adapter.ts

@@ -133,16 +133,15 @@ const MAX_HISTORY_LARGE_TOOL_ARGS_CHARS = 200_000;
 const STARTUP_RESPONSE_TIMEOUT_MS = 45_000;
 
 // ── Background follow mode ──────────────────────────────────────────────────
-// For background-dispatched runs (dispatchMode starts with "background") the
-// SERVER is the sole recovery brain: it chains continuation chunks itself
-// (fresh runId, same turnId), pre-inserts the successor run row BEFORE the old
-// chunk completes (so /runs/active shows an active run continuously across
-// chunk boundaries), and a server sweep reaps lost handoffs into loud terminal
-// errors. The client therefore never POSTs synthetic continuations for these
-// runs — it demotes itself to a READER of server state: poll /runs/active,
-// (re)attach to whichever run of this turn is live, and fold its events into
-// the same assistant message. Read-only, so multiple tabs following the same
-// run are safe (no localStorage/Web-Locks claim needed).
+// For server-continued runs (dispatchMode starts with "background" or equals
+// "foreground-self-chain") the SERVER normally chains continuation chunks
+// itself (fresh runId, same turnId), pre-inserts the successor run row BEFORE
+// the old chunk completes (so /runs/active shows an active run continuously
+// across chunk boundaries), and a server sweep reaps lost handoffs into loud
+// terminal errors. The client demotes itself to a READER of server state for
+// healthy handoffs. Foreground self-chain keeps one escape hatch: if the server
+// reports that the self-dispatch itself failed before a successor claimed the
+// run, the existing client auto-continue POST remains the fallback.
 const BACKGROUND_FOLLOW_POLL_INTERVAL_MS = 1_000;
 // How long the follow loop tolerates seeing NO active run for this turn before
 // treating the turn as ended. The server pre-inserts the successor row before
@@ -1687,12 +1686,24 @@ export function createAgentChatAdapter(
         if (mode) currentRunDispatchMode = mode;
       };
 
-      // Mode switch for recovery ownership: background-dispatched runs are
-      // recovered by the SERVER (chained continuations, sweeps); the client
-      // only follows. Foreground (null/"foreground"/unknown) keeps the full
-      // client-side continuation machinery unchanged.
-      const isBackgroundDispatch = () =>
+      // Mode switch for recovery ownership: durable/background-dispatched runs
+      // are always recovered by the server. Foreground self-chain follows the
+      // server on healthy handoffs, but a loud self-dispatch failure falls back
+      // to the client POST path because no successor run owns recovery yet.
+      const isDurableBackgroundDispatch = () =>
         currentRunDispatchMode?.startsWith("background") === true;
+      const isForegroundSelfChainDispatch = () =>
+        currentRunDispatchMode === "foreground-self-chain";
+      const shouldFollowServerContinuation = (
+        signal?: AgentAutoContinueSignal,
+      ) => {
+        if (isDurableBackgroundDispatch()) return true;
+        if (!isForegroundSelfChainDispatch()) return false;
+        return (
+          signal?.errorInfo?.errorCode !==
+          "background_continuation_dispatch_failed"
+        );
+      };
 
       const rememberRunSeq = (seq: number) => {
         lastSeq = seq;
@@ -2966,7 +2977,7 @@ export function createAgentChatAdapter(
               // following of server state instead. This is the fix for the
               // client/server recovery race: client watchdog signals here are
               // just "reattach", not "recover".
-              if (isBackgroundDispatch() && threadId) {
+              if (shouldFollowServerContinuation(err) && threadId) {
                 yield* followBackgroundTurn(err);
                 return;
               }
@@ -3145,7 +3156,7 @@ export function createAgentChatAdapter(
             // synthetic-continuation POST below. (An initial POST that failed
             // before any response headers arrived has no dispatch mode yet
             // and keeps the foreground startup-retry path.)
-            if (isBackgroundDispatch() && threadId) {
+            if (shouldFollowServerContinuation() && threadId) {
               yield* followBackgroundTurn(
                 new AgentAutoContinueSignal({ reason: "stream_ended" }),
               );

package/corpus/core/src/client/use-run-stuck-detection.ts

@@ -26,7 +26,7 @@ export interface RunStuckState {
   heartbeatAt: number | null;
   /** Milliseconds since `heartbeatAt`, computed against the server clock. */
   heartbeatSinceMs: number | null;
-  /** How the run was dispatched, e.g. foreground or background-processing. */
+  /** How the run was dispatched/continued, e.g. foreground-self-chain or background-processing. */
   dispatchMode: string | null;
 }
 
@@ -133,10 +133,13 @@ export function useRunStuckDetection({
             heartbeatAt != null ? nowMs - heartbeatAt : null;
           const dispatchMode =
             typeof data.dispatchMode === "string" ? data.dispatchMode : null;
-          // Background-dispatched runs get the wider threshold: the server's
-          // own recovery (150s no-progress backstop + chained continuations)
-          // must get its chance before the user sees a "stuck" affordance.
-          const effectiveThresholdMs = dispatchMode?.startsWith("background")
+          // Server-continued runs get the wider threshold: the server's own
+          // recovery (150s no-progress backstop + chained continuations) must
+          // get its chance before the user sees a "stuck" affordance.
+          const serverContinued =
+            dispatchMode === "foreground-self-chain" ||
+            dispatchMode?.startsWith("background") === true;
+          const effectiveThresholdMs = serverContinued
             ? backgroundStuckThresholdMs
             : stuckThresholdMs;
           const isStuck = Boolean(

package/corpus/templates/content/AGENTS.md

@@ -121,6 +121,7 @@ cd templates/content && pnpm action <name> [args]
 | `set-content-database-source-write-mode`    | `--databaseId <id>` or `--documentId <id> --liveWritesEnabled true\|false [--allowedWriteModes <json>]`                                                        | Enable/disable per-source Builder live writes; enabling is allowed only for `agent-native-blog-article-test` with explicit modes                         |
 | `stage-builder-revision`                    | `--databaseId <id>` or `--documentId <id>`                                                                                                                     | Stage pending local Builder CMS changes as a local-only save-revision record; never calls Builder                                                        |
 | `review-content-database-source-change-set` | `--databaseId <id>` or `--documentId <id> --changeSetId <id> --decision approve\|reject [--note]`                                                              | Approve or reject a local source change-set review record without provider writes                                                                        |
+| `stage-builder-source-bulk-update`          | `--databaseId <id>` or `--documentId <id> --itemIds <json-array>` or `--documentIds <json-array> --field <json> [--sourceId <id>] [--dryRun true\|false]`      | Preview or stage one bounded field update across selected source-backed Builder rows; apply still goes through Builder review/execution                  |
 | `prepare-builder-source-execution`          | `--databaseId <id>` or `--documentId <id> --changeSetId <id> [--pushModeConfirmation autosave\|draft\|publish]`                                                | Prepare a dry-run Builder execution gate for approved field/body changes with request semantics/idempotency key; never calls Builder                     |
 | `validate-builder-source-execution`         | `--databaseId <id>` or `--documentId <id> --changeSetId <id> [--idempotencyKey <key>]`                                                                         | Validate/replay a prepared Builder execution gate locally as a dry run; never calls Builder                                                              |
 | `execute-builder-source-execution`          | `--databaseId <id>` or `--documentId <id> --changeSetId <id> [--idempotencyKey <key>] [--pushModeConfirmation autosave\|draft\|publish]`                       | Execute a guarded live Builder write only when approved, validated, enabled, idempotent, and targeting `agent-native-blog-article-test`                  |