@agent-native/core 0.84.36 → 0.84.38

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @agent-native/core
 
+## 0.84.38
+
+### Patch Changes
+
+- 203c1c3: Keep durable background chat runs attached during long action preparation instead of aborting on keepalive-only or zero-byte preparation activity.
+
+## 0.84.37
+
+### Patch Changes
+
+- 885a0bd: Hide docs formatter guards from rendered content, refine assistant recovery status labels, and keep live background workers from being auto-retried as stuck.
+
 ## 0.84.36
 
 ### Patch Changes

package/corpus/core/docs/content/getting-started.mdx

@@ -59,7 +59,7 @@ An action is one typed operation your agent and UI can both call. Replace the
 starter `hello` action with the first real operation in your domain. This example
 analyzes form responses and returns a validated shape for a custom chat chart:
 
-{/* prettier-ignore */}
+<!-- prettier-ignore -->
 ```ts
 // actions/analyze-responses.ts
 import { defineAction } from "@agent-native/core/action";
@@ -108,7 +108,7 @@ The action above declares `outputSchema` and a product-specific
 into prose. Register a React component for that exact renderer id, for example
 by importing `app/chat-renderers.tsx` once from `app/root.tsx`:
 
-{/* prettier-ignore */}
+<!-- prettier-ignore -->
 ```tsx
 import { registerActionChatRenderer, type ToolRendererProps,} from "@agent-native/core/client/chat";
 
@@ -209,7 +209,7 @@ separate REST route just for the browser if an action is the operation.
 
 Now add a durable page for the data behind the chat result:
 
-{/* prettier-ignore */}
+<!-- prettier-ignore -->
 ```tsx
 // app/routes/response-insights.tsx
 import { useActionMutation, useActionQuery } from "@agent-native/core/client";

package/corpus/core/docs/content/locales/ar-SA/getting-started.mdx

@@ -32,7 +32,7 @@ pnpm dev
 
 Action هي عملية typed operation مشتركة بين agent و UI. في هذا المسار أنشئ `actions/analyze-responses.ts`: تحلل ردود النماذج وتعيد شكلاً موثقًا لرسم مخصص داخل الدردشة.
 
-{/* prettier-ignore */}
+<!-- prettier-ignore -->
 ```ts
 // actions/analyze-responses.ts
 import { defineAction } from "@agent-native/core/action";
@@ -75,7 +75,7 @@ pnpm action analyze-responses --formId demo
 
 لأن action تعلن `outputSchema` و `chatUI.renderer` خاصًا بالمنتج، لا يحول transcript البيانات المنظمة إلى نص عادي. سجّل مكون React لذلك المعرّف نفسه عند بدء التطبيق، مثل استيراد `app/chat-renderers.tsx` مرة واحدة من `app/root.tsx`:
 
-{/* prettier-ignore */}
+<!-- prettier-ignore -->
 ```tsx
 import { registerActionChatRenderer, type ToolRendererProps,} from "@agent-native/core/client/chat";
 

package/corpus/core/docs/content/locales/de-DE/getting-started.mdx

@@ -32,7 +32,7 @@ Das Template enthält durable chat threads, auth, live sync, ein `actions/`-Verz
 
 Eine action ist eine typisierte Operation, die Agent und UI gemeinsam aufrufen. Für diesen Ablauf erstellen Sie `actions/analyze-responses.ts`: Sie analysiert Formularantworten und gibt eine validierte Form für ein eigenes Chat-Diagramm zurück.
 
-{/* prettier-ignore */}
+<!-- prettier-ignore -->
 ```ts
 // actions/analyze-responses.ts
 import { defineAction } from "@agent-native/core/action";
@@ -75,7 +75,7 @@ Oder im Browser den Agent fragen:
 
 Weil die action `outputSchema` und eine produktspezifische `chatUI.renderer` deklariert, muss der Transcript strukturierte Daten nicht in Fließtext verwandeln. Registrieren Sie beim App-Start eine React-Komponente für genau diese Renderer-ID, zum Beispiel indem `app/chat-renderers.tsx` einmal aus `app/root.tsx` importiert wird:
 
-{/* prettier-ignore */}
+<!-- prettier-ignore -->
 ```tsx
 import { registerActionChatRenderer, type ToolRendererProps,} from "@agent-native/core/client/chat";
 

package/corpus/core/docs/content/locales/es-ES/getting-started.mdx

@@ -32,7 +32,7 @@ El template incluye durable chat threads, auth, live sync, un directorio `action
 
 Una action es una operación tipada que comparten el agent y la UI. Para este flujo, crea `actions/analyze-responses.ts`: analiza respuestas de formularios y devuelve una forma validada para un gráfico de chat propio.
 
-{/* prettier-ignore */}
+<!-- prettier-ignore -->
 ```ts
 // actions/analyze-responses.ts
 import { defineAction } from "@agent-native/core/action";
@@ -75,7 +75,7 @@ O pídeselo al agent en el navegador:
 
 Como la action declara `outputSchema` y una `chatUI.renderer` específica del producto, el transcript no convierte los datos en texto plano. Registra un componente React para ese id exacto desde el arranque de la app, por ejemplo importando `app/chat-renderers.tsx` una vez desde `app/root.tsx`:
 
-{/* prettier-ignore */}
+<!-- prettier-ignore -->
 ```tsx
 import { registerActionChatRenderer, type ToolRendererProps,} from "@agent-native/core/client/chat";
 

package/corpus/core/docs/content/locales/fr-FR/getting-started.mdx

@@ -32,7 +32,7 @@ Le template inclut durable chat threads, auth, live sync, un dossier `actions/`,
 
 Une action est une opération typée appelée par l'agent et par l'UI. Pour ce guide, créez `actions/analyze-responses.ts` : elle analyse des réponses de formulaire et renvoie une forme validée pour un graphique de chat personnalisé.
 
-{/* prettier-ignore */}
+<!-- prettier-ignore -->
 ```ts
 // actions/analyze-responses.ts
 import { defineAction } from "@agent-native/core/action";
@@ -75,7 +75,7 @@ Ou demandez à l'agent dans le navigateur :
 
 Comme l'action déclare `outputSchema` et un `chatUI.renderer` propre au produit, le transcript ne transforme pas les données structurées en simple texte. Enregistrez un composant React pour cet id exact au démarrage de l'app, par exemple en important `app/chat-renderers.tsx` une fois depuis `app/root.tsx` :
 
-{/* prettier-ignore */}
+<!-- prettier-ignore -->
 ```tsx
 import { registerActionChatRenderer, type ToolRendererProps,} from "@agent-native/core/client/chat";
 

package/corpus/core/docs/content/locales/hi-IN/getting-started.mdx

@@ -32,7 +32,7 @@ pnpm dev
 
 Action वह typed operation है जिसे agent और UI दोनों call करते हैं. इस flow के लिए `actions/analyze-responses.ts` बनाएं: यह form responses analyze करता है और custom chat chart के लिए validated shape लौटाता है.
 
-{/* prettier-ignore */}
+<!-- prettier-ignore -->
 ```ts
 // actions/analyze-responses.ts
 import { defineAction } from "@agent-native/core/action";
@@ -75,7 +75,7 @@ pnpm action analyze-responses --formId demo
 
 क्योंकि action `outputSchema` और product-specific `chatUI.renderer` declare करता है, transcript structured data को plain text में नहीं बदलता. फिर app startup से उसी exact renderer id के लिए React component register करें, जैसे `app/root.tsx` से `app/chat-renderers.tsx` को एक बार import करके:
 
-{/* prettier-ignore */}
+<!-- prettier-ignore -->
 ```tsx
 import { registerActionChatRenderer, type ToolRendererProps,} from "@agent-native/core/client/chat";
 

package/corpus/core/docs/content/locales/ja-JP/getting-started.mdx

@@ -32,7 +32,7 @@ pnpm dev
 
 action は agent と UI が共有する typed operation です。この流れでは `actions/analyze-responses.ts` を作成し、フォーム回答を分析してカスタムチャットグラフ用の検証済み形状を返します。
 
-{/* prettier-ignore */}
+<!-- prettier-ignore -->
 ```ts
 // actions/analyze-responses.ts
 import { defineAction } from "@agent-native/core/action";
@@ -75,7 +75,7 @@ pnpm action analyze-responses --formId demo
 
 action が `outputSchema` とプロダクト固有の `chatUI.renderer` を宣言しているため、チャットは構造化データを長い文章に潰しません。次に、app の起動時にその正確な renderer id に対応する React コンポーネントを登録します。たとえば `app/root.tsx` から `app/chat-renderers.tsx` を一度 import します。
 
-{/* prettier-ignore */}
+<!-- prettier-ignore -->
 ```tsx
 import { registerActionChatRenderer, type ToolRendererProps,} from "@agent-native/core/client/chat";
 

package/corpus/core/docs/content/locales/ko-KR/getting-started.mdx

@@ -32,7 +32,7 @@ pnpm dev
 
 action은 agent와 UI가 함께 호출하는 typed operation입니다. 이 흐름에서는 `actions/analyze-responses.ts`를 만들고, 폼 응답을 분석해 custom chat chart를 위한 검증된 형태를 반환합니다.
 
-{/* prettier-ignore */}
+<!-- prettier-ignore -->
 ```ts
 // actions/analyze-responses.ts
 import { defineAction } from "@agent-native/core/action";
@@ -75,7 +75,7 @@ pnpm action analyze-responses --formId demo
 
 action이 `outputSchema`와 제품별 `chatUI.renderer`를 선언하므로 transcript가 구조화된 데이터를 긴 텍스트로 바꾸지 않습니다. 그런 다음 app startup에서 정확히 같은 renderer id에 대한 React component를 등록합니다. 예를 들어 `app/root.tsx`에서 `app/chat-renderers.tsx`를 한 번 import합니다.
 
-{/* prettier-ignore */}
+<!-- prettier-ignore -->
 ```tsx
 import { registerActionChatRenderer, type ToolRendererProps,} from "@agent-native/core/client/chat";
 

package/corpus/core/docs/content/locales/pt-BR/getting-started.mdx

@@ -32,7 +32,7 @@ O template inclui durable chat threads, auth, live sync, diretório `actions/`,
 
 Uma action é uma operação tipada que o agent e a UI chamam juntos. Para este fluxo, crie `actions/analyze-responses.ts`: ela analisa respostas de formulários e retorna um formato validado para um gráfico de chat customizado.
 
-{/* prettier-ignore */}
+<!-- prettier-ignore -->
 ```ts
 // actions/analyze-responses.ts
 import { defineAction } from "@agent-native/core/action";
@@ -75,7 +75,7 @@ Ou peça ao agent no navegador:
 
 Como a action declara `outputSchema` e uma `chatUI.renderer` específica do produto, o transcript não transforma dados estruturados em texto corrido. Registre um componente React para esse id exato no startup da app, por exemplo importando `app/chat-renderers.tsx` uma vez a partir de `app/root.tsx`:
 
-{/* prettier-ignore */}
+<!-- prettier-ignore -->
 ```tsx
 import { registerActionChatRenderer, type ToolRendererProps,} from "@agent-native/core/client/chat";
 

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

@@ -42,7 +42,7 @@ npx @agent-native/core@latest create my-app
 Action 是 agent 和 UI 共同调用的一次 typed operation。可以把入门示例换成
 `actions/analyze-responses.ts`：它分析表单反馈，并返回自定义聊天图表的已验证数据形状。
 
-{/* prettier-ignore */}
+<!-- prettier-ignore -->
 ```ts
 // actions/analyze-responses.ts
 import { defineAction } from "@agent-native/core/action";
@@ -85,7 +85,7 @@ pnpm action analyze-responses --formId demo
 
 因为 action 声明了 `outputSchema` 和产品专属的 `chatUI.renderer`，聊天记录不需要把结构化数据压成一段文字。然后在 app 启动时为这个完全相同的 renderer id 注册 React 组件，例如从 `app/root.tsx` 导入一次 `app/chat-renderers.tsx`：
 
-{/* prettier-ignore */}
+<!-- prettier-ignore -->
 ```tsx
 import { registerActionChatRenderer, type ToolRendererProps,} from "@agent-native/core/client/chat";
 

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

@@ -40,7 +40,7 @@ npx @agent-native/core@latest create my-app
 
 Action 是 agent 與 UI 共同呼叫的一個 typed operation。可將入門範例換成 `actions/analyze-responses.ts`：它分析表單回覆並返回自訂聊天圖表的已驗證資料形狀。
 
-{/* prettier-ignore */}
+<!-- prettier-ignore -->
 ```ts
 // actions/analyze-responses.ts
 import { defineAction } from "@agent-native/core/action";
@@ -83,7 +83,7 @@ pnpm action analyze-responses --formId demo
 
 因為 action 宣告了 `outputSchema` 與產品專屬的 `chatUI.renderer`，聊天紀錄不必把結構化資料壓成文字。然後在 app 啟動時為這個完全相同的 renderer id 註冊 React 元件，例如從 `app/root.tsx` 匯入一次 `app/chat-renderers.tsx`：
 
-{/* prettier-ignore */}
+<!-- prettier-ignore -->
 ```tsx
 import { registerActionChatRenderer, type ToolRendererProps,} from "@agent-native/core/client/chat";
 

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.84.36",
+  "version": "0.84.38",
   "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

@@ -5106,6 +5106,7 @@ 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", "background");
           return stream;
         }
         // A background worker owns this run but we cannot subscribe — surface an
@@ -5912,6 +5913,7 @@ 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");
 
     return stream;
   });

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

@@ -662,6 +662,23 @@ export function resolveAssistantChatRunningState({
   };
 }
 
+export function resolveAssistantChatRunningStatusLabel({
+  runningActivityLabel,
+  isAutoResuming,
+  isReconnecting,
+  hasReconnectContent,
+}: {
+  runningActivityLabel: string | null | undefined;
+  isAutoResuming: boolean;
+  isReconnecting: boolean;
+  hasReconnectContent: boolean;
+}): string {
+  if (runningActivityLabel) return runningActivityLabel;
+  if (isAutoResuming) return "Resuming";
+  if (isReconnecting && hasReconnectContent) return "Continuing";
+  return "Thinking";
+}
+
 type QueuedMessage = {
   id: string;
   text: string;
@@ -1497,18 +1514,15 @@ const AssistantChatInner = forwardRef<
     hasActiveServerRun,
   });
   const textStreaming = showRunningInUI || externalStreaming;
-  // A revealed activity label wins; otherwise stay a steady "Thinking" by
-  // default. We only surface "Reconnecting" while we are actively replaying
-  // recovered content (reconnectContent populated). A bare reconnect with no
-  // replayed content is normal ongoing work, so it must read as "Thinking",
-  // never a perpetual "Working".
-  const runningStatusLabel = runningActivityLabel
-    ? runningActivityLabel
-    : isAutoResuming
-      ? "Resuming"
-      : isReconnecting && reconnectContent.length > 0
-        ? "Reconnecting"
-        : "Thinking";
+  // A revealed activity label wins; otherwise keep recovery states calm and
+  // product-facing. Reconnect is transport machinery, so normal replay reads as
+  // "Continuing" instead of exposing "Reconnecting" mid-chat.
+  const runningStatusLabel = resolveAssistantChatRunningStatusLabel({
+    runningActivityLabel,
+    isAutoResuming,
+    isReconnecting,
+    hasReconnectContent: reconnectContent.length > 0,
+  });
   const reconnectActivityContent = useMemo(
     () =>
       (isReconnecting || reconnectFrozen) && reconnectContent.length === 0
@@ -1952,7 +1966,7 @@ const AssistantChatInner = forwardRef<
           }
           setRunErrorInfo({
             message:
-              "The previous agent run stopped producing visible progress while reconnecting, so it was stopped before it could keep looping.",
+              "The previous agent run stopped producing visible progress during recovery, so it was stopped before it could keep looping.",
             errorCode: "reconnect_no_progress",
             recoverable: true,
             runId,

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

@@ -55,6 +55,7 @@ export interface RunStuckBannerProps {
 }
 
 const AUTO_RETRY_CLAIM_TTL_MS = 5 * 60 * 1000;
+const BACKGROUND_WORKER_FRESH_HEARTBEAT_MS = 30_000;
 
 type BusyState = { type: "none" } | { type: "cancel" | "retry"; runId: string };
 
@@ -78,6 +79,16 @@ function autoRetryClaimKey(threadId: string, runId: string) {
   return `agent-native:stuck-auto-retry:${threadId}:${runId}`;
 }
 
+function isFreshBackgroundWorker(state: RunStuckState): boolean {
+  return Boolean(
+    state.status === "running" &&
+    state.dispatchMode === "background-processing" &&
+    state.heartbeatSinceMs != null &&
+    state.heartbeatSinceMs >= 0 &&
+    state.heartbeatSinceMs < BACKGROUND_WORKER_FRESH_HEARTBEAT_MS,
+  );
+}
+
 function markAutoRetryClaim(key: string, ownerId: string) {
   if (typeof window === "undefined") return true;
   const now = Date.now();
@@ -151,6 +162,7 @@ export function RunStuckBanner({
     generatedOwnerIdRef.current = createAutoRetryOwnerId();
   }
   const ownerId = autoRetryOwnerId ?? generatedOwnerIdRef.current;
+  const backgroundWorkerStillAlive = isFreshBackgroundWorker(state);
 
   const lastReportedRef = useRef<{
     isStuck: boolean;
@@ -190,6 +202,7 @@ export function RunStuckBanner({
   useEffect(() => {
     if (
       !autoRetry ||
+      backgroundWorkerStillAlive ||
       !state.isStuck ||
       !state.runId ||
       busy.type !== "none" ||
@@ -223,6 +236,7 @@ export function RunStuckBanner({
   }, [
     abortRun,
     autoRetry,
+    backgroundWorkerStillAlive,
     busy,
     onRetry,
     ownerId,
@@ -280,11 +294,17 @@ export function RunStuckBanner({
       />
       <div className="flex min-w-0 flex-1 flex-col gap-1.5">
         <div className="leading-snug">
-          <span className="font-medium">This chat looks stuck.</span>{" "}
+          <span className="font-medium">
+            {backgroundWorkerStillAlive
+              ? "The agent is still working."
+              : "This chat looks stuck."}
+          </span>{" "}
           <span className="text-muted-foreground">
             No progress
-            {stuckSeconds != null ? ` for ${stuckSeconds}s` : ""}. The agent may
-            have hit a server timeout or lost its connection.
+            {stuckSeconds != null ? ` for ${stuckSeconds}s` : ""}.{" "}
+            {backgroundWorkerStillAlive
+              ? "The background worker is still alive; large updates can take a few minutes."
+              : "The agent may have hit a server timeout or lost its connection."}
             {autoRetry && busyType === "retry"
               ? " Retrying automatically now."
               : ""}

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

@@ -1418,6 +1418,7 @@ export function createAgentChatAdapter(
       const turnId = generateTurnId();
       let runId: string | null = null;
       let lastSeq = -1;
+      let currentRunDispatchMode: string | null = null;
       let currentMessageText = normalizeMentions(
         recoveryMessageText.trim() || userMessageText,
       );
@@ -1579,6 +1580,17 @@ export function createAgentChatAdapter(
         }
       };
 
+      const updateCurrentRunDispatchMode = (value: unknown) => {
+        if (typeof value !== "string") return;
+        const mode = value.trim();
+        if (mode) currentRunDispatchMode = mode;
+      };
+
+      const currentSSEOptions = () => ({
+        durableBackgroundRun:
+          currentRunDispatchMode?.startsWith("background") === true,
+      });
+
       const captureChatClientError = (
         error: unknown,
         phase: string,
@@ -1687,6 +1699,9 @@ export function createAgentChatAdapter(
                 reconnectErrorCaptured = true;
                 break;
               }
+              updateCurrentRunDispatchMode(
+                reconnectRes.headers.get("X-Dispatch-Mode"),
+              );
 
               for await (const result of readSSEStream(
                 reconnectRes.body,
@@ -1698,6 +1713,7 @@ export function createAgentChatAdapter(
                   if (threadId) updateActiveRunSeq(seq);
                 },
                 runId,
+                currentSSEOptions(),
               )) {
                 yield withRequestModeMetadata(result);
               }
@@ -1778,6 +1794,7 @@ export function createAgentChatAdapter(
               }
               const active = await activeRes.json();
               if (active?.active && active.runId) {
+                updateCurrentRunDispatchMode(active.dispatchMode);
                 const activeStatus =
                   typeof active.status === "string" ? active.status : "";
                 const activeTurnId =
@@ -1851,6 +1868,7 @@ export function createAgentChatAdapter(
                   typeof active.dispatchMode === "string"
                     ? active.dispatchMode
                     : "";
+                updateCurrentRunDispatchMode(dispatchMode);
                 if (activeRunId === interruptedRunId) {
                   if (dispatchMode.startsWith("background")) continue;
                   return false;
@@ -2429,6 +2447,7 @@ export function createAgentChatAdapter(
 
             // Track the run ID for reconnection
             runId = res.headers.get("X-Run-Id");
+            updateCurrentRunDispatchMode(res.headers.get("X-Dispatch-Mode"));
             if (runId && !attemptedRunIds.includes(runId)) {
               attemptedRunIds.push(runId);
             }
@@ -2448,6 +2467,7 @@ export function createAgentChatAdapter(
                 }
               },
               runId,
+              currentSSEOptions(),
             )) {
               yield withRequestModeMetadata(result);
             }

package/corpus/core/src/client/sse-event-processor.ts

@@ -148,6 +148,16 @@ export class AgentAutoContinueSignal extends Error {
 export const SSE_NO_PROGRESS_TIMEOUT_MS = 75_000;
 export const SSE_ACTION_PREPARATION_STALL_TIMEOUT_MS = 90_000;
 
+export interface SSEStreamOptions {
+  /**
+   * Durable background runs have their own server-side liveness budget and
+   * heartbeat. While one is active, keepalive-only periods and zero-byte
+   * action-preparation activity should keep the client attached instead of
+   * aborting and starting duplicate continuations.
+   */
+  durableBackgroundRun?: boolean;
+}
+
 type ActivityTrailEntry = AgentActivityTrailEntry;
 
 type PreparingActionEntry = {
@@ -193,9 +203,13 @@ function isPreparingActionActivity(ev: SSEEvent): boolean {
 function isMeaningfulProgressEvent(
   ev: SSEEvent,
   actionPreparationProgress?: boolean,
+  options?: SSEStreamOptions,
 ): boolean {
-  if (ev.type === "stream_keepalive") return false;
+  if (ev.type === "stream_keepalive") {
+    return options?.durableBackgroundRun === true;
+  }
   if (ev.type === "activity" && isPreparingActionActivity(ev)) {
+    if (options?.durableBackgroundRun === true) return true;
     return actionPreparationProgress === true;
   }
   return true;
@@ -345,7 +359,12 @@ function updatePreparingActionState(
   return undefined;
 }
 
-function hasStalledPreparingAction(state: PreparingActionState, now: number) {
+function hasStalledPreparingAction(
+  state: PreparingActionState,
+  now: number,
+  options?: SSEStreamOptions,
+) {
+  if (options?.durableBackgroundRun === true) return false;
   // Fire only when a tool input has gone SILENT — no further streaming deltas
   // for the whole window — never merely because a large input has been
   // streaming for a long time. `lastProgressAt` advances on every delta
@@ -1193,6 +1212,7 @@ export async function* readSSEStream(
   tabId: string | undefined,
   onSeq?: (seq: number) => void,
   runId?: string | null,
+  options?: SSEStreamOptions,
 ): AsyncGenerator<ChatModelRunResult> {
   const reader = body.getReader();
   const decoder = new TextDecoder();
@@ -1278,7 +1298,7 @@ export async function* readSSEStream(
           ev,
           now,
         );
-        if (isMeaningfulProgressEvent(ev, actionPreparationProgress)) {
+        if (isMeaningfulProgressEvent(ev, actionPreparationProgress, options)) {
           sawProgressEvent = true;
           lastMeaningfulEventAt = now;
         }
@@ -1320,7 +1340,9 @@ export async function* readSSEStream(
         );
 
         if (result) yield withStreamMetadata(result);
-        if (hasStalledPreparingAction(preparingActionState, Date.now())) {
+        if (
+          hasStalledPreparingAction(preparingActionState, Date.now(), options)
+        ) {
           throw new AgentAutoContinueSignal({
             reason: "no_progress",
             activityTrail: [...activityTrail],
@@ -1384,6 +1406,7 @@ export async function readSSEStreamRaw(
   tabId: string | undefined,
   onUpdate: (content: ContentPart[]) => void,
   onSeq?: (seq: number) => void,
+  options?: SSEStreamOptions,
 ): Promise<void> {
   const reader = body.getReader();
   const decoder = new TextDecoder();
@@ -1444,7 +1467,7 @@ export async function readSSEStreamRaw(
           ev,
           now,
         );
-        if (isMeaningfulProgressEvent(ev, actionPreparationProgress)) {
+        if (isMeaningfulProgressEvent(ev, actionPreparationProgress, options)) {
           sawProgressEvent = true;
           lastMeaningfulEventAt = now;
         }
@@ -1502,7 +1525,9 @@ export async function readSSEStreamRaw(
               : { reason: "stream_ended", activityTrail: [...activityTrail] },
           );
         }
-        if (hasStalledPreparingAction(preparingActionState, Date.now())) {
+        if (
+          hasStalledPreparingAction(preparingActionState, Date.now(), options)
+        ) {
           onUpdate(contentSnapshot(content));
           throw new AgentAutoContinueSignal({
             reason: "no_progress",

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

@@ -24,6 +24,10 @@ export interface RunStuckState {
   stuckSinceMs: number | null;
   /** Server timestamp (ms) of the last process-alive heartbeat. */
   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. */
+  dispatchMode: string | null;
 }
 
 export interface UseRunStuckDetectionOptions {
@@ -51,6 +55,7 @@ interface ActiveRunResponse {
   status?: string;
   heartbeatAt: number | null;
   lastProgressAt?: number | null;
+  dispatchMode?: string | null;
   /** Server clock at response time, used to compute elapsed server-relative. */
   serverNow?: number;
 }
@@ -62,6 +67,8 @@ const EMPTY_STATE: RunStuckState = {
   lastProgressAt: null,
   stuckSinceMs: null,
   heartbeatAt: null,
+  heartbeatSinceMs: null,
+  dispatchMode: null,
 };
 
 export function useRunStuckDetection({
@@ -102,6 +109,9 @@ export function useRunStuckDetection({
           const nowMs = data.serverNow ?? Date.now();
           const stuckSinceMs =
             lastProgressAt != null ? nowMs - lastProgressAt : null;
+          const heartbeatAt = data.heartbeatAt ?? null;
+          const heartbeatSinceMs =
+            heartbeatAt != null ? nowMs - heartbeatAt : null;
           const isStuck = Boolean(
             data.active &&
             data.status === "running" &&
@@ -114,7 +124,10 @@ export function useRunStuckDetection({
             status: data.status ?? null,
             lastProgressAt,
             stuckSinceMs,
-            heartbeatAt: data.heartbeatAt ?? null,
+            heartbeatAt,
+            heartbeatSinceMs,
+            dispatchMode:
+              typeof data.dispatchMode === "string" ? data.dispatchMode : null,
           });
           // Back off polling when nothing is in flight — there's no point
           // hammering the endpoint while the chat is idle. We still poll

package/corpus/core/src/server/agent-chat-plugin.ts

@@ -7278,8 +7278,11 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
             let reason = "user";
             try {
               const body = await readBody(event);
-              if (body?.reason === "no_progress") {
-                reason = "no_progress";
+              if (
+                typeof body?.reason === "string" &&
+                /^[a-z0-9_-]{1,64}$/i.test(body.reason)
+              ) {
+                reason = body.reason;
               }
             } catch {
               // Empty/invalid body — keep the default user abort reason.
@@ -7343,6 +7346,9 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
               setResponseStatus(event, 404);
               return { error: "Run not found" };
             }
+            const runClaim = await readBackgroundRunClaim(runId).catch(
+              () => null,
+            );
             const query = getQuery(event);
             const after = parseInt(String(query.after ?? "0"), 10) || 0;
 
@@ -7355,6 +7361,11 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
             setResponseHeader(event, "Content-Type", "text/event-stream");
             setResponseHeader(event, "Cache-Control", "no-cache");
             setResponseHeader(event, "Connection", "keep-alive");
+            setResponseHeader(
+              event,
+              "X-Dispatch-Mode",
+              runClaim?.dispatchMode ?? "foreground",
+            );
             return stream;
           }