@agent-native/core 0.84.67 → 0.85.0

package/corpus/core/docs/content/locales/zh-CN/tracking.mdx

@@ -188,6 +188,61 @@ track("checkout.completed", { total: 49.99, items: 3 });
 
 这与框架的内部浏览器遥测（`trackEvent()` /自动页面浏览量 - 请参阅下面的 [Browser defaults](#browser-defaults)）不同，后者为 Agent Native 自己的产品分析提供支持。将 `track()` 用于您的应用自己的分析事件，这些事件应到达您配置的提供商。
 
+## 会话重放 {#session-replay}
+
+Agent Native 应用无需添加第二个分析 SDK，即可接入第一方浏览器会话重放功能。在浏览器根部调用一次 `configureTracking()`，并传入 Analytics 公钥和采集端点：
+
+```ts
+import { configureTracking } from "@agent-native/core/client";
+
+configureTracking({
+  key: "anpk_...",
+  endpoint: "https://analytics.example.com/api/analytics/track",
+  sessionReplay: {
+    enabled: true,
+    sampleRate: 0.1,
+  },
+  getDefaultProps: (_event, props) => ({
+    ...props,
+    app: "my-app",
+    template: "my-template",
+  }),
+});
+```
+
+当 `sessionReplay.enabled` 为真值时，客户端会在启动后动态导入 `@rrweb/record`，并将重放数据块发送到重放端点。如果 `endpoint` 以 `/api/analytics/track` 或 `/track` 结尾，重放端点会自动推导为 `/api/analytics/replay`。当重放采集器位于其他位置时，可通过 `sessionReplay.endpoint` 显式覆盖。
+
+Agent Native 模板根已经调用了 `configureTracking()`。托管模板部署可以通过 Vite/Netlify 环境变量开启重放，而库使用者则应优先使用上面显式的 `configureTracking({ key, endpoint, sessionReplay })` 形式：
+
+```bash
+VITE_AGENT_NATIVE_ANALYTICS_PUBLIC_KEY=anpk_...
+VITE_AGENT_NATIVE_ANALYTICS_ENDPOINT=https://analytics.example.com/api/analytics/track
+VITE_AGENT_NATIVE_SESSION_REPLAY_ENABLED=true
+VITE_AGENT_NATIVE_SESSION_REPLAY_SAMPLE_RATE=0.1
+```
+
+浏览器端辅助函数还会尽力地、非阻塞地读取当前 Agent Native 认证会话。默认情况下，重放仅限已登录用户：启用 `sessionReplay` 后，除非会话解析出用户邮箱地址，否则不会开始录制。已登录用户的重放会包含基于邮箱的 `userId`/`userEmail` 以及 `orgId`。
+
+仅在有意进行匿名重放部署时，才设置 `sessionReplay.requireSignedInUser: false` 或 `VITE_AGENT_NATIVE_SESSION_REPLAY_REQUIRE_AUTH=false`。禁用认证门控后，匿名录制仍可按匿名访客、会话、应用/模板、主机名和路径进行查询。
+
+会话重放按浏览器会话确定性采样。`sampleRate` 为 `0.1` 时，会记录约 10% 的符合条件的会话；当符合条件的用户群体本就很小时（例如仅限登录用户的内部测试），可使用 `1`。
+
+隐私默认设置刻意保持保守，但仍能满足回放的可用性：
+
+- 默认屏蔽输入内容（`maskAllInputs: true`）。
+- 页面文本默认保持可见，除非元素被标记为 `.an-mask` 或 `data-an-mask`。
+- 敏感区域会通过诸如 `[data-sensitive]`、`.an-block`、`.an-private`、`data-an-block`、`data-an-private` 等选择器以及类似信用卡/密码/社会安全号码的字段进行屏蔽。
+- URL 会使用与浏览器分析相同的 `scrubUrl()` 辅助函数进行清理。
+- 重放采集仅限 Web 端且为选择性加入（opt-in）；不会录制原生桌面屏幕。
+
+录制期间，会话重放还会捕获浏览器控制台输出（`log`、`info`、`warn`、`error`、`debug`，以及 window 的 `error` / `unhandledrejection`）和网络请求元数据（`fetch` 和 XHR），并将其作为带标签的 rrweb 自定义事件记录下来，以便代理和重放查看器调试用户报告的问题。启用重放后，此项捕获默认开启；可通过 `sessionReplay.console` 和 `sessionReplay.network` 选项进行调整或禁用，两者均可接受布尔值或选项对象。请求/响应的正文和请求头永远不会被捕获，URL 会被清理，消息会被截断，录制器自身的上报/跟踪流量会被排除，并且每个会话的配额（1000 条控制台事件 / 2000 条网络事件）在超出时会附加截断提示。
+
+Analytics 模板将重放元数据存储在 SQL（`session_recordings`）中，并通过私有 blob 引用（`session_replay_chunks`）存储数据块。浏览器和代理永远不会收到提供商的 URL。回放通过受限的服务器路由进行，默认的代理工具返回的是摘要或有限范围的重放事件，而非原始数据块表的直接访问权限。
+
+当需要将私有录制内容提供给外部代理时，可使用会话详情页面的**复制给代理**控件。它会生成一个两小时有效期、仅限该录制的 `agent_access` 链接，在 `/sessions/:recordingId` 上以服务器端渲染方式生成一个小型发现载荷，并只暴露代理上下文/事件的 JSON API。该录制本身的可见性不会改变。
+
+仅在本地开发环境下，当私有 blob 存储不可用时，Analytics 可以回退为使用有上限的 SQL 内联数据块。生产部署应配置私有或加密的 blob 存储，而不是依赖 Postgres 来存放重放数据。
+
 ## 高级：自定义提供程序和内部结构 {#advanced}
 
 大多数应用程序只需要 `track()` / `identify()` 和内置提供程序。表面的其余部分 - 注册自定义提供程序、`TrackingProvider` 接口、批处理内部结构以及框架自己的浏览器遥测 - 如下。

package/corpus/core/docs/content/locales/zh-TW/tracking.mdx

@@ -188,6 +188,61 @@ track("checkout.completed", { total: 49.99, items: 3 });
 
 這與框架的內部瀏覽器遙測（`trackEvent()` /自動頁面瀏覽量 - 請參閱下面的 [Browser defaults](#browser-defaults)）不同，後者為 Agent Native 自己的產品分析提供支援。將 `track()` 用於您的應用自己的分析事件，這些事件應到達您設定的提供者。
 
+## 工作階段重播 {#session-replay}
+
+Agent Native 應用程式可以選擇加入第一方瀏覽器工作階段重播，而無需新增第二個分析 SDK。在瀏覽器根目錄中呼叫一次 `configureTracking()`，並傳入 Analytics 公開金鑰以及收集器端點：
+
+```ts
+import { configureTracking } from "@agent-native/core/client";
+
+configureTracking({
+  key: "anpk_...",
+  endpoint: "https://analytics.example.com/api/analytics/track",
+  sessionReplay: {
+    enabled: true,
+    sampleRate: 0.1,
+  },
+  getDefaultProps: (_event, props) => ({
+    ...props,
+    app: "my-app",
+    template: "my-template",
+  }),
+});
+```
+
+當 `sessionReplay.enabled` 為真值時，用戶端會在啟動後動態匯入 `@rrweb/record`，並將重播區塊發佈到重播端點。如果 `endpoint` 以 `/api/analytics/track` 或 `/track` 結尾，重播端點會自動衍生為 `/api/analytics/replay`。當重播收集器位於其他位置時，請使用 `sessionReplay.endpoint` 明確覆寫它。
+
+Agent Native 範本根目錄已經呼叫了 `configureTracking()`。託管範本部署可以透過 Vite/Netlify 環境變數開啟重播，而函式庫使用者則應優先使用上面明確的 `configureTracking({ key, endpoint, sessionReplay })` 形式：
+
+```bash
+VITE_AGENT_NATIVE_ANALYTICS_PUBLIC_KEY=anpk_...
+VITE_AGENT_NATIVE_ANALYTICS_ENDPOINT=https://analytics.example.com/api/analytics/track
+VITE_AGENT_NATIVE_SESSION_REPLAY_ENABLED=true
+VITE_AGENT_NATIVE_SESSION_REPLAY_SAMPLE_RATE=0.1
+```
+
+瀏覽器輔助程式也會盡力執行、非阻塞式讀取目前的 Agent Native 驗證工作階段。重播預設僅限已登入使用者：當 `sessionReplay` 啟用時，除非工作階段解析出使用者電子郵件地址，否則不會開始錄製。已登入使用者的重播包含以電子郵件為基礎的 `userId`/`userEmail` 以及 `orgId`。
+
+僅在刻意進行匿名重播部署時，才設定 `sessionReplay.requireSignedInUser: false` 或 `VITE_AGENT_NATIVE_SESSION_REPLAY_REQUIRE_AUTH=false`。停用驗證閘控後，匿名錄製仍可依匿名訪客、工作階段、應用程式/範本、主機名稱與路徑進行查詢。
+
+工作階段重播是依瀏覽器工作階段進行確定性取樣的。`sampleRate` 為 `0.1` 表示大約記錄 10% 符合條件的工作階段；當符合條件的母體刻意較小時（例如僅限已登入使用者的內部試用），可使用 `1`。
+
+隱私預設值刻意設計得保守，但仍足以支援播放：
+
+- 輸入欄位預設會被遮罩（`maskAllInputs: true`）。
+- 頁面文字保持可見，除非元素被標記為 `.an-mask` 或 `data-an-mask`。
+- 敏感區域會透過選擇器（例如 `[data-sensitive]`、`.an-block`、`.an-private`、`data-an-block`、`data-an-private`，以及類似信用卡/密碼/社會安全號碼的欄位）進行封鎖。
+- URL 會使用瀏覽器分析所用的同一個 `scrubUrl()` 輔助函式進行清理。
+- 重播擷取僅限於網頁，且為選擇加入；它不會錄製原生桌面畫面。
+
+在錄製期間，工作階段重播還會擷取瀏覽器主控台輸出（`log`、`info`、`warn`、`error`、`debug`，以及視窗的 `error`/`unhandledrejection`）與網路請求元資料（`fetch` 與 XHR），並以帶標籤的 rrweb 自訂事件形式儲存，讓代理與重播檢視器能夠偵錯使用者回報的問題。啟用重播後，擷取功能預設為開啟；可透過 `sessionReplay.console` 與 `sessionReplay.network` 選項進行調整或停用，這兩個選項都接受布林值或選項物件。請求/回應主體與標頭永遠不會被擷取，URL 會被清理，訊息會被截斷，記錄器自身的擷取/追蹤流量會被排除，且每個工作階段的預算（1000 個主控台事件／2000 個網路事件）在超過時會加上截斷提示。
+
+Analytics 範本將重播中繼資料儲存在 SQL（`session_recordings`）中，並透過私有 blob 參照（`session_replay_chunks`）儲存區塊。瀏覽器與代理永遠不會收到提供者 URL。播放透過範圍受限的伺服器路由進行，且預設代理工具傳回摘要或範圍受限的重播事件，而非原始區塊資料表存取權。
+
+當您需要將私人錄製內容交給外部代理時，請使用工作階段詳細資料頁面的**複製給代理**控制項。它會產生一個兩小時、僅限該筆錄製的 `agent_access` 連結，在 `/sessions/:recordingId` 上以伺服器端轉譯（SSR）一個小型探索酬載，並僅公開代理內容/事件 JSON API。該筆錄製的可見性不會改變。
+
+僅在本機開發時，Analytics 可以在私有 blob 儲存體無法使用時，回退到有上限的 SQL 內嵌區塊。正式環境部署應設定私有或加密的 blob 儲存體，而不是依賴 Postgres 來儲存重播酬載。
+
 ## 進階：自訂提供者和內部結構 {#advanced}
 
 大多數應用程式只需要 `track()` / `identify()` 和內建提供者。表面的其餘部分 - 註冊自訂提供者、`TrackingProvider` 介面、批處理內部結構以及框架自己的瀏覽器遙測 - 如下。

package/corpus/core/docs/content/tracking.mdx

@@ -235,6 +235,8 @@ Privacy defaults are intentionally conservative but still useful for playback:
 - URLs are scrubbed with the same `scrubUrl()` helper used by browser analytics.
 - Replay capture is web-only and opt-in; it does not record native desktop screens.
 
+While recording, session replay also captures browser console output (`log`, `info`, `warn`, `error`, `debug`, plus window `error` / `unhandledrejection`) and network request metadata (`fetch` and XHR) as tagged rrweb custom events, so agents and the replay viewer can debug user-reported issues. Capture is on by default when replay is enabled; tune or disable it with the `sessionReplay.console` and `sessionReplay.network` options, each accepting a boolean or an options object. Request/response bodies and headers are never captured, URLs are scrubbed, messages are truncated, the recorder's own ingest/tracking traffic is excluded, and per-session budgets (1000 console / 2000 network events) add a truncation notice when exceeded.
+
 The Analytics template stores replay metadata in SQL (`session_recordings`) and stores chunks through private blob refs (`session_replay_chunks`). Browsers and agents never receive provider URLs. Playback goes through scoped server routes and the default agent tools return summaries or bounded replay events, not raw chunk table access.
 
 When you need to hand a private recording to an external agent, use the session detail page's **Copy for agent** control. It mints a two-hour, recording-scoped `agent_access` link, SSRs a small discovery payload on `/sessions/:recordingId`, and exposes only the agent context/events JSON APIs. The recording's visibility does not change.

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.84.67",
+  "version": "0.85.0",
   "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/production-agent.ts

@@ -130,6 +130,7 @@ import {
   claimBackgroundRun,
   readBackgroundRunClaim,
   recordRunDiagnostic,
+  countRunsForTurn,
   RUN_DIAG_STAGE,
   UNCLAIMED_BACKGROUND_RUN_GRACE_MS,
 } from "./run-store.js";
@@ -5527,8 +5528,13 @@ export function createProductionAgentHandler(
         // Insert the run row up front so /runs/active sees it immediately and
         // the slot stays held while the background function cold-starts. Mark
         // it background-dispatched so the stale reaper uses the wider window.
+        // The full request body is persisted ON the row (dispatch_payload) so
+        // the self-POST below can carry only the tiny marker — Netlify caps
+        // background-function request bodies at 256KB, and a large chat
+        // history (inline attachments especially) silently exceeded that.
         await insertRun(runId, effectiveThreadId, effectiveTurnId, {
           dispatchMode: "background",
+          dispatchPayload: JSON.stringify(body),
         });
         backgroundRowInserted = true;
       } catch (err) {
@@ -5560,16 +5566,31 @@ export function createProductionAgentHandler(
           // the Authorization Bearer HMAC is preserved either way.
           path: backgroundDispatchPath,
           taskId: runId,
-          body: {
-            ...body,
-            // Carry the pre-claimed identity so the worker reuses this run.
-            [AGENT_CHAT_BACKGROUND_RUN_FIELD]: {
-              runId,
-              turnId: effectiveTurnId,
-              backgroundFunctionRuntimeExpected:
-                expectsNetlifyBackgroundFunction,
-            },
-          },
+          // When the row (and its persisted payload) landed, send only the
+          // marker — the worker rehydrates the body from dispatch_payload
+          // (`payloadRef`), keeping the self-POST far under Netlify's 256KB
+          // background-function body cap. If the insert failed we fall back to
+          // carrying the full body inline, exactly as before.
+          body: backgroundRowInserted
+            ? {
+                [AGENT_CHAT_BACKGROUND_RUN_FIELD]: {
+                  runId,
+                  turnId: effectiveTurnId,
+                  backgroundFunctionRuntimeExpected:
+                    expectsNetlifyBackgroundFunction,
+                  payloadRef: true,
+                },
+              }
+            : {
+                ...body,
+                // Carry the pre-claimed identity so the worker reuses this run.
+                [AGENT_CHAT_BACKGROUND_RUN_FIELD]: {
+                  runId,
+                  turnId: effectiveTurnId,
+                  backgroundFunctionRuntimeExpected:
+                    expectsNetlifyBackgroundFunction,
+                },
+              },
         });
         dispatched = true;
       } catch (err) {
@@ -5835,6 +5856,38 @@ export function createProductionAgentHandler(
               // 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
@@ -5851,41 +5904,149 @@ export function createProductionAgentHandler(
                   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: Record<string, unknown> = {
+                  ...(body as unknown as Record<string, unknown>),
+                  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(() => {});
-                  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: {
-                      ...body,
-                      internalContinuation: true,
-                      [AGENT_CHAT_BACKGROUND_RUN_FIELD]: {
-                        runId: nextRunId,
-                        turnId: effectiveTurnId,
-                        continuationCount: backgroundContinuationCount + 1,
-                        continuationReason,
-                        ...(actionPreparationTool
-                          ? { actionPreparationTool }
-                          : {}),
-                        backgroundFunctionRuntimeExpected:
-                          continuationExpectsNetlifyBackgroundFunction,
+                  // ── 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),
                       },
-                    },
-                    settleMs: continuationExpectsNetlifyBackgroundFunction
-                      ? BACKGROUND_CLAIM_GRACE_MS
-                      : undefined,
-                  });
+                    );
+                    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: unknown;
+                  for (let attempt = 0; attempt < 3 && !dispatched; attempt++) {
+                    try {
+                      if (attempt > 0) {
+                        await new Promise<void>((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,

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

@@ -105,6 +105,29 @@ export const BACKGROUND_SOFT_TIMEOUT_CEILING_MS = 13 * 60_000; // 780_000
 export const DEFAULT_BACKGROUND_RUN_SOFT_TIMEOUT_MS =
   BACKGROUND_SOFT_TIMEOUT_CEILING_MS;
 
+/**
+ * AUTHORITATIVE no-progress backstop for a run, enforced by the run manager
+ * itself (timer-driven, independent of any layer below).
+ *
+ * The finer-grained watchdogs inside the agent loop (model-stream and
+ * action-preparation no-progress, both 90s) only guard the model event stream
+ * — a stall in any segment OUTSIDE that guarded loop (engine-call
+ * establishment, worker setup between continuation chunks, a wedged transport
+ * that emits keepalives while the loop never runs) previously hung forever
+ * with the client watching keepalives. This backstop covers every segment by
+ * construction: if no REAL progress event (see `shouldBumpProgressForEvent`;
+ * keepalives and zero-byte prep activity don't count) lands for this long —
+ * and no tool call is in flight (tool execution legitimately emits nothing
+ * for minutes and has its own 12-min timeout) — the run manager emits
+ * `auto_continue { reason: "no_progress" }` and aborts the chunk, exactly
+ * like the soft timeout, so the normal continuation machinery recovers it.
+ *
+ * Sits above the 90s in-loop watchdogs (they get first chance to recover with
+ * better context) and far below the 13-min background budget. Only armed when
+ * a soft-timeout regime is active (hosted runs); local dev stays unbounded.
+ */
+export const RUN_NO_PROGRESS_HARD_TIMEOUT_MS = 150_000;
+
 /** Default SQL retention for completed run event logs (24 hours). */
 export const DEFAULT_COMPLETED_RUN_RETENTION_MS = 24 * 60 * 60 * 1000;
 
@@ -220,6 +243,13 @@ export interface StartRunOptions {
    * decision in production-agent.ts.
    */
   backgroundFunction?: boolean;
+  /**
+   * Override the run-manager-level no-progress backstop
+   * (`RUN_NO_PROGRESS_HARD_TIMEOUT_MS`). `0` disables it. Defaults to the
+   * backstop constant whenever a soft-timeout regime is active (hosted runs)
+   * and to disabled otherwise (local dev stays unbounded).
+   */
+  noProgressTimeoutMs?: number;
 }
 
 export interface ResolveRunSoftTimeoutOptions {
@@ -499,6 +529,46 @@ export function startRun(
     return true;
   };
 
+  // ── No-progress backstop (see RUN_NO_PROGRESS_HARD_TIMEOUT_MS) ──────────
+  // Timer-driven and independent of the agent loop, so it fires even when the
+  // stall is in a segment the in-loop watchdogs never see (engine-call
+  // establishment, setup, a wedged transport emitting keepalives). Tool calls
+  // and sub-agent calls in flight suspend it — tool execution legitimately
+  // emits nothing for minutes and carries its own 12-min timeout.
+  let lastRealProgressAt = Date.now();
+  let inFlightWorkCount = 0;
+  const trackInFlightWork = (event: AgentChatEvent) => {
+    if (event.type === "tool_start") {
+      inFlightWorkCount += 1;
+    } else if (event.type === "tool_done") {
+      inFlightWorkCount = Math.max(0, inFlightWorkCount - 1);
+    } else if (event.type === "agent_call") {
+      if (event.status === "start") {
+        inFlightWorkCount += 1;
+      } else {
+        inFlightWorkCount = Math.max(0, inFlightWorkCount - 1);
+      }
+    }
+  };
+  const checkNoProgressBackstop = () => {
+    if (noProgressTimeoutMs <= 0) return;
+    if (run.status !== "running" || abort.signal.aborted) return;
+    if (inFlightWorkCount > 0) return;
+    if (Date.now() - lastRealProgressAt < noProgressTimeoutMs) return;
+    console.error(
+      `[run-manager] no real progress for ${noProgressTimeoutMs}ms with no tool in flight — ` +
+        `checkpointing run for continuation`,
+      runId,
+    );
+    // Mirror the soft-timeout semantics exactly: the chunk completes (not
+    // aborts) at an auto_continue boundary, so the continuation machinery —
+    // server-chained for background workers, client-driven for foreground —
+    // recovers the turn.
+    softTimedOut = true;
+    send({ type: "auto_continue", reason: "no_progress" });
+    abort.abort("no_progress");
+  };
+
   // Periodic SQL abort check interval (for cross-isolate abort on Workers).
   // Also self-aborts when our row is no longer status='running' — catches the
   // false-stale-reap zombie scenario where the reaper flipped the row while
@@ -534,11 +604,18 @@ export function startRun(
   const heartbeatTimer: ReturnType<typeof setInterval> = setInterval(() => {
     updateRunHeartbeat(runId).catch(() => {});
     checkSqlAbort();
+    checkNoProgressBackstop();
   }, 1500);
   const softTimeoutMs = resolveRunSoftTimeoutMs(options?.softTimeoutMs, {
     useHostedDefault: options?.useHostedSoftTimeoutDefault === true,
     backgroundFunction: options?.backgroundFunction === true,
   });
+  // Armed only when a soft-timeout regime is active (hosted): local dev keeps
+  // unbounded runs. For 40s foreground chunks the soft timeout always fires
+  // first, so in practice this guards the long background chunks.
+  const noProgressTimeoutMs =
+    options?.noProgressTimeoutMs ??
+    (softTimeoutMs > 0 ? RUN_NO_PROGRESS_HARD_TIMEOUT_MS : 0);
   const softTimeoutTimer =
     softTimeoutMs > 0
       ? setTimeout(() => {
@@ -610,7 +687,9 @@ export function startRun(
     // a hung run from a healthy one. Keepalive and zero-byte action prep are
     // liveness only; streamed input bytes, text, and tool lifecycle events are
     // real progress.
+    trackInFlightWork(runEvent.event);
     if (shouldBumpProgressForEvent(runEvent.event)) {
+      lastRealProgressAt = Date.now();
       bumpProgressIfDue();
     }