@steerable/agent-shell-web 0.7.4 → 0.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steerable/agent-shell-web",
-  "version": "0.7.4",
+  "version": "0.8.1",
   "type": "module",
   "description": "Steerable framework — product-neutral renderer SPA source for @steerable/agent-shell (React + Vite). Consumed by product web entry points via the `@/` alias (anchored at this package's src/) and the createProductViteConfig factory. Published as a source package (src/), plus the compiled vite.base config factory (vite.base.js + .d.ts) for Node-side config loading.",
   "license": "Apache-2.0",
@@ -45,8 +45,8 @@
     "react-router-dom": "^6.30.0",
     "rehype-raw": "^7.0.0",
     "remark-gfm": "^4.0.1",
-    "@steerable/agent-protocol": "0.7.4",
-    "@steerable/agent-ui": "0.7.4"
+    "@steerable/agent-protocol": "0.8.1",
+    "@steerable/agent-ui": "0.8.1"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.0",
@@ -59,7 +59,7 @@
     "typescript": "^5.8.3",
     "vite": "^5.4.21",
     "vitest": "^3.2.4",
-    "@steerable/pack-sdk": "0.7.4"
+    "@steerable/pack-sdk": "0.8.1"
   },
   "scripts": {
     "gen": "echo agent-shell-web",

package/src/components/LocalLlmSettingsModal.tsx

@@ -1,8 +1,11 @@
-import { useEffect } from 'react';
+import { useEffect, useRef } from 'react';
 import { createPortal } from 'react-dom';
 import { LuX } from 'react-icons/lu';
 import type { LlmSettings } from '@/lib/local-api';
-import { LlmSettingsPanel } from '@/components/settings/LlmSettingsPanel';
+import {
+  LlmSettingsPanel,
+  type LlmSettingsPanelHandle,
+} from '@/components/settings/LlmSettingsPanel';
 import { t } from '@/i18n';
 
 interface LocalLlmSettingsModalProps {
@@ -16,6 +19,7 @@ interface LocalLlmSettingsModalProps {
  * 侧栏「设置」走 `/settings` 页（模型 + 洞察 / 遥测 / 用量 / 搜索 / 安全）。
  */
 export function LocalLlmSettingsModal({ open, onClose, onSaved }: LocalLlmSettingsModalProps) {
+  const panelRef = useRef<LlmSettingsPanelHandle | null>(null);
   useEffect(() => {
     if (!open) return;
     const onKey = (e: KeyboardEvent) => {
@@ -25,6 +29,39 @@ export function LocalLlmSettingsModal({ open, onClose, onSaved }: LocalLlmSettin
     return () => window.removeEventListener('keydown', onKey);
   }, [open, onClose]);
 
+  // An authentication failure opens this modal specifically to fix the key,
+  // so put the cursor there instead of at the top of a form the reader then
+  // has to scan.
+  //
+  // It goes through the panel's handle rather than a document query: the panel
+  // owns the field, mounts it asynchronously once settings load, and knows when
+  // it is actually focusable. Polling the DOM found an element that had already
+  // been replaced by a re-render, so the focus call landed on a detached node.
+  useEffect(() => {
+    if (!open) return;
+    let cancelled = false;
+    let timer: number | undefined;
+    const focusKey = () => {
+      if (cancelled) return;
+      // 用户已经开始在别处输入时不要抢焦点。
+      const active = document.activeElement;
+      const userTyping =
+        active instanceof HTMLElement &&
+        active !== document.body &&
+        (active.tagName === 'INPUT' ||
+          active.tagName === 'TEXTAREA' ||
+          active.isContentEditable);
+      if (userTyping) return;
+      if (panelRef.current?.focusApiKey()) return;
+      timer = window.setTimeout(focusKey, 50);
+    };
+    focusKey();
+    return () => {
+      cancelled = true;
+      if (timer !== undefined) window.clearTimeout(timer);
+    };
+  }, [open]);
+
   if (!open) return null;
   if (typeof document === 'undefined') return null;
 
@@ -55,7 +92,7 @@ export function LocalLlmSettingsModal({ open, onClose, onSaved }: LocalLlmSettin
           </button>
         </div>
         <div className="flex-1 overflow-y-auto p-3">
-          <LlmSettingsPanel onSaved={onSaved} />
+          <LlmSettingsPanel ref={panelRef} onSaved={onSaved} />
         </div>
         <div className="flex h-9 flex-shrink-0 items-center justify-end border-t border-agent-border px-3 bg-agent-muted/10">
           <button

package/src/components/chat/AssistantMessage.tsx

@@ -1,6 +1,16 @@
 import { useEffect, useRef, useState } from 'react';
 import { motion } from 'framer-motion';
-import { LuCheck, LuCopy, LuListChecks, LuLoaderCircle, LuRefreshCw, LuShare2 } from 'react-icons/lu';
+import {
+  LuCheck,
+  LuChevronDown,
+  LuChevronUp,
+  LuCopy,
+  LuListChecks,
+  LuLoaderCircle,
+  LuRefreshCw,
+  LuShare2,
+  LuTriangleAlert,
+} from 'react-icons/lu';
 import type { ChatMessage } from '@steerable/agent-protocol';
 import type { LocalChat, LocalChatAgent } from '@/lib/local-api';
 import { t } from '@/i18n';
@@ -10,6 +20,9 @@ import type { ChildInfo } from './OrchestrationChildrenCard';
 import { collectTurnParticipants, extractMentionedAgentIds } from './executed-actions-model';
 import type { InspectTaskInput } from './executed-actions-model';
 import { StreamingStatus } from './StreamingStatus';
+import { TurnFailureCard, type TurnFailureCardProps } from './TurnFailureCard';
+import { readFailureDetail, type TurnFailureDetail } from './turn-failure';
+import type { RetryState } from './RetryStatus';
 import { getFriendlyDate } from './timestamp';
 import { useCopy } from './useCopy';
 import type { TurnBlock } from './turn-timeline';
@@ -101,6 +114,12 @@ interface AssistantMessageProps {
    * `StreamingStatus` to render "Round 2 · 继续推理..." between LLM bursts.
    */
   currentRound?: number;
+  /**
+   * Live retry state of the in-flight request. While set, the status line
+   * says "reconnecting" instead of "thinking": a seconds-scale backoff and a
+   * stalled request look the same without it.
+   */
+  retryState?: RetryState | null;
   /** True iff the message was generated in Plan mode. */
   isPlanMode?: boolean;
   /**
@@ -110,6 +129,12 @@ interface AssistantMessageProps {
    * has fully streamed; the caller then re-hydrates the message list.
    */
   onRegenerate?: (messageId: string) => Promise<void>;
+  /**
+   * Resolves a failed turn's action into a handler. The message list decides
+   * what this build can do (Continue needs a backend route, opening settings
+   * needs the modal); the card only draws what it is given.
+   */
+  failureAction?: TurnFailureCardProps['action'];
   /** Epoch ms when this turn started — live ticker while streaming. */
   startedAtMs?: number;
   /** Frozen wall-clock of a finished turn. */
@@ -188,11 +213,71 @@ function bubbleClass(isPlanMode: boolean): string {
 // 两处汇合到同一个错误气泡，失败回合不再只显示"（空消息）"。
 const STREAM_ERROR_PREFIX = '[stream error] ';
 
-function readTurnFailure(
-  message: ChatMessage,
-  content: string,
-): { reason: string; contentIsError: boolean } | null {
+interface TurnFailure {
+  reason: string;
+  contentIsError: boolean;
+  /** Classified detail; undefined for live stream errors and old records. */
+  detail?: TurnFailureDetail;
+  traceId?: string;
+}
+
+/**
+ * Terminal state of a persisted turn, for the card it should show.
+ *
+ * `failed` and `cancelled` are different for the reader even though both can
+ * be continued: one is the network's fault and comes back as a failure card,
+ * the other is the user's own Stop and reads as a neutral notice. Absent
+ * metadata means the turn finished normally (older records carry no status).
+ */
+/**
+ * Whether this failed/stopped turn was continued afterwards.
+ *
+ * The host stamps `continuedAt` when a resume starts from this turn. The card
+ * then collapses into one line: the failure is history the user already acted
+ * on, and re-showing the full card after a reload would read as "it failed
+ * again". Expanding it still yields the original diagnostics.
+ */
+function readContinued(message: ChatMessage): boolean {
+  const raw = (message as { messageMetadata?: unknown }).messageMetadata;
+  if (typeof raw !== 'string' || !raw) return false;
+  try {
+    const at = (JSON.parse(raw) as { continuedAt?: unknown }).continuedAt;
+    return typeof at === 'string' && at.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+/** True when the user's Stop landed while a retry was pending. */
+function readStoppedDuringRetry(message: ChatMessage): boolean {
+  const raw = (message as { messageMetadata?: unknown }).messageMetadata;
+  if (typeof raw !== 'string' || !raw) return false;
+  try {
+    const reason = (JSON.parse(raw) as { completionReason?: unknown }).completionReason;
+    return reason === 'aborted_during_retry';
+  } catch {
+    return false;
+  }
+}
+
+function readTurnStatus(message: ChatMessage): 'failed' | 'cancelled' | 'completed' {
+  const raw = (message as { messageMetadata?: unknown }).messageMetadata;
+  if (typeof raw !== 'string' || !raw) return 'completed';
+  try {
+    const status = (JSON.parse(raw) as { completionStatus?: unknown }).completionStatus;
+    if (status === 'failed') return 'failed';
+    if (status === 'cancelled') return 'cancelled';
+    return 'completed';
+  } catch {
+    // 元数据损坏按正常完成处理——落回原有的空消息展示。
+    return 'completed';
+  }
+}
+
+function readTurnFailure(message: ChatMessage, content: string): TurnFailure | null {
   if (content.startsWith(STREAM_ERROR_PREFIX)) {
+    // Live path: the framework stamped the reason into the content before the
+    // turn was persisted, so nothing structured is available yet.
     return { reason: content.slice(STREAM_ERROR_PREFIX.length), contentIsError: true };
   }
   const raw = (message as { messageMetadata?: unknown }).messageMetadata;
@@ -201,13 +286,20 @@ function readTurnFailure(
     const meta = JSON.parse(raw) as {
       completionStatus?: unknown;
       completionReason?: unknown;
+      failure?: unknown;
+      traceId?: unknown;
     };
     if (
       meta?.completionStatus === 'failed' &&
       typeof meta.completionReason === 'string' &&
       meta.completionReason
     ) {
-      return { reason: meta.completionReason, contentIsError: false };
+      return {
+        reason: meta.completionReason,
+        contentIsError: false,
+        detail: readFailureDetail(meta.failure),
+        traceId: typeof meta.traceId === 'string' && meta.traceId ? meta.traceId : undefined,
+      };
     }
   } catch {
     // 元数据损坏按无失败处理——落回原有的空消息展示。
@@ -226,10 +318,102 @@ function readPersistedAgentId(message: ChatMessage): string | undefined {
   }
 }
 
-function TurnErrorBubble({ reason }: { reason: string }) {
+function TurnErrorBubble({
+  failure,
+  completedSteps,
+  happenedAt,
+  onAction,
+}: {
+  failure: TurnFailure;
+  completedSteps: number;
+  happenedAt?: string;
+  onAction?: TurnFailureCardProps['action'];
+}) {
+  return (
+    <TurnFailureCard
+      detail={failure.detail}
+      reason={failure.reason}
+      completedSteps={completedSteps}
+      happenedAt={happenedAt}
+      traceId={failure.traceId}
+      action={onAction}
+    />
+  );
+}
+
+/**
+ * One collapsed line standing in for a failure the user already continued.
+ *
+ * It stays expandable rather than disappearing: the diagnostics are the only
+ * record of what went wrong, and someone filing a report a day later still
+ * needs them. The default is collapsed so a resumed conversation reads as
+ * continuous work rather than a stack of past failures.
+ */
+function ContinuedHereLine({ children }: { children: React.ReactNode }) {
+  const [open, setOpen] = useState(false);
   return (
-    <div className="rounded-agent-lg border border-agent-destructive/40 bg-agent-destructive/5 px-2.5 py-2 text-xs leading-relaxed text-agent-destructive shadow-sm">
-      {t('Request failed: {reason}', { reason })}
+    <div data-testid="continued-here">
+      <button
+        type="button"
+        onClick={() => setOpen((value) => !value)}
+        aria-expanded={open}
+        className="inline-flex items-center gap-1 text-[11px] text-agent-muted-foreground hover:text-agent-foreground"
+        data-action="continued-here"
+      >
+        <LuTriangleAlert className="h-3 w-3" />
+        {t('Connection failed here. Continued.')}
+        {open ? <LuChevronUp className="h-3 w-3" /> : <LuChevronDown className="h-3 w-3" />}
+      </button>
+      {open ? <div className="mt-1.5">{children}</div> : null}
+    </div>
+  );
+}
+
+/**
+ * Neutral notice for a turn the user stopped.
+ *
+ * Deliberately not the failure card: nothing went wrong, the user chose to
+ * stop. It still offers Continue, because the usual reason to stop a turn is
+ * impatience with a retry, and the work done so far is worth keeping. The copy
+ * distinguishes a stop during reconnection — the case where "continue" is
+ * almost certainly wanted — from a stop while the model was writing.
+ */
+function TurnStoppedCard({
+  duringRetry,
+  action,
+}: {
+  duringRetry: boolean;
+  action?: TurnFailureCardProps['action'];
+}) {
+  const handler = action?.({ kind: 'retry' }) ?? null;
+  return (
+    <div
+      className="rounded-agent-lg border border-agent-border bg-agent-muted/40 px-2.5 py-2 text-xs leading-relaxed"
+      data-testid="turn-stopped"
+    >
+      <div className="flex items-start gap-2 font-medium text-agent-foreground">
+        <span className="mt-[3px] h-2 w-2 flex-shrink-0 rounded-[2px] bg-agent-muted-foreground" />
+        <span>{t('Stopped')}</span>
+      </div>
+      <p className="mt-1 ml-5 text-agent-muted-foreground">
+        {duringRetry
+          ? t('You stopped this task while it was reconnecting.')
+          : t('You stopped this task.')}
+      </p>
+      {handler ? (
+        <div className="mt-2 ml-5">
+          <button
+            type="button"
+            disabled={handler.disabled}
+            title={handler.hint}
+            onClick={handler.onClick}
+            className="rounded-agent-md border border-agent-border bg-agent-card px-3 py-1 text-xs text-agent-foreground transition hover:bg-agent-muted disabled:opacity-50"
+            data-action="continue"
+          >
+            {t('Continue')}
+          </button>
+        </div>
+      ) : null}
     </div>
   );
 }
@@ -263,8 +447,10 @@ export function AssistantMessage({
   orchestrationChildren,
   previousUser,
   currentRound = 1,
+  retryState,
   isPlanMode = false,
   onRegenerate,
+  failureAction,
   startedAtMs,
   durationMs,
   llmSpeed,
@@ -274,6 +460,9 @@ export function AssistantMessage({
 }: AssistantMessageProps) {
   const content = message.content || '';
   const failure = readTurnFailure(message, content);
+  const stopped = !failure && readTurnStatus(message) === 'cancelled';
+  const stoppedDuringRetry = stopped && readStoppedDuringRetry(message);
+  const continued = readContinued(message);
   // live 错误文本（"[stream error] ..."）不当正文渲染；落库的失败回合可能
   // 留有部分正文，此时正文与错误气泡都展示。
   const displayContent = failure?.contentIsError ? '' : content;
@@ -308,6 +497,10 @@ export function AssistantMessage({
     llmRequestElapsedMs(llmSpeed, now),
   );
 
+  // A continued failure renders as one line; expanding it yields the card.
+  const wrapContinued = (card: React.ReactNode) =>
+    continued ? <ContinuedHereLine>{card}</ContinuedHereLine> : card;
+
   return (
     <motion.div
       className="group/message"
@@ -359,15 +552,25 @@ export function AssistantMessage({
             orchestrationChildren={orchestrationChildren}
             emptyFallback={
               failure ? (
-                <TurnErrorBubble reason={failure.reason} />
+                wrapContinued(
+                  <TurnErrorBubble
+                    failure={failure}
+                    completedSteps={toolActions.length}
+                    happenedAt={message.createdAt}
+                    onAction={failureAction}
+                  />,
+                )
               ) : isStreaming ? (
                 <div className={bubbleClass(isPlanMode)}>
                   <StreamingStatus
                     round={currentRound}
                     actionCount={executedActions?.length ?? 0}
                     hasContent={false}
+                    retry={retryState ?? undefined}
                   />
                 </div>
+              ) : stopped ? (
+                <TurnStoppedCard duringRetry={stoppedDuringRetry} action={failureAction} />
               ) : (
                 <div className={`${bubbleClass(isPlanMode)} text-xs italic text-agent-muted-foreground`}>
                   {t('(empty message)')}
@@ -379,6 +582,7 @@ export function AssistantMessage({
                 round={currentRound}
                 actionCount={executedActions?.length ?? 0}
                 hasContent={false}
+                retry={retryState ?? undefined}
               />
             }
             renderAnswer={(block, isLast) => (
@@ -394,7 +598,19 @@ export function AssistantMessage({
               （无块时走上面的 emptyFallback，不会重复）。 */}
           {failure && blocks.length > 0 ? (
             <div className="mt-1.5">
-              <TurnErrorBubble reason={failure.reason} />
+              {wrapContinued(
+                <TurnErrorBubble
+                  failure={failure}
+                  completedSteps={toolActions.length}
+                  happenedAt={message.createdAt}
+                  onAction={failureAction}
+                />,
+              )}
+            </div>
+          ) : null}
+          {stopped && blocks.length > 0 ? (
+            <div className="mt-1.5">
+              <TurnStoppedCard duringRetry={stoppedDuringRetry} action={failureAction} />
             </div>
           ) : null}
           </>
@@ -417,15 +633,25 @@ export function AssistantMessage({
                 {isStreaming && <StreamingCursor />}
               </div>
             ) : failure ? (
-              <TurnErrorBubble reason={failure.reason} />
+              wrapContinued(
+                <TurnErrorBubble
+                  failure={failure}
+                  completedSteps={toolActions.length}
+                  happenedAt={message.createdAt}
+                  onAction={failureAction}
+                />,
+              )
             ) : isStreaming ? (
               <div className={bubbleClass(isPlanMode)}>
                 <StreamingStatus
                   round={currentRound}
                   actionCount={executedActions?.length ?? 0}
                   hasContent={false}
+                  retry={retryState ?? undefined}
                 />
               </div>
+            ) : stopped ? (
+              <TurnStoppedCard duringRetry={stoppedDuringRetry} action={failureAction} />
             ) : (
               <div className={`${bubbleClass(isPlanMode)} text-xs italic text-agent-muted-foreground`}>
                 {t('(empty message)')}
@@ -433,7 +659,14 @@ export function AssistantMessage({
             )}
             {displayContent && failure ? (
               <div className="mt-1.5">
-                <TurnErrorBubble reason={failure.reason} />
+                {wrapContinued(
+                  <TurnErrorBubble
+                    failure={failure}
+                    completedSteps={toolActions.length}
+                    happenedAt={message.createdAt}
+                    onAction={failureAction}
+                  />,
+                )}
               </div>
             ) : null}
           </>
@@ -474,7 +707,11 @@ export function AssistantMessage({
               )}
             </button>
           )}
-          {content && !isStreaming && onRegenerate && (
+          {/* Regenerate is offered for a failed or stopped turn even when it
+              produced no text: the reply the user wanted is missing, and
+              regenerating from the turn's start is the alternative to
+              Continue when Continue is not the right answer. */}
+          {(content || failure || stopped) && !isStreaming && onRegenerate && (
             <button
               type="button"
               disabled={regenerating}
@@ -497,7 +734,7 @@ export function AssistantMessage({
               title={
                 regenerating
                   ? t('Regenerating...')
-                  : t('Regenerate (the old reply is kept as a branch)')
+                  : t('Regenerate (start this turn over; the old reply is kept as a branch)')
               }
               aria-label={regenerating ? t('Regenerating') : t('Regenerate')}
               data-action="regenerate"

package/src/components/chat/LocalChatPanel.tsx

@@ -18,6 +18,8 @@ import type { InspectTaskInput } from './executed-actions-model';
 import type { ChildInfo } from './OrchestrationChildrenCard';
 import type { TurnBlock } from './turn-timeline';
 import type { TurnFile } from './turn-files';
+import type { RetryState } from './RetryStatus';
+import type { TurnFailureCardProps } from './TurnFailureCard';
 import type { LlmSpeedSnapshot } from './process-status';
 import { ComposerStatusStack } from './composer-status-stack';
 import { t } from '@/i18n';
@@ -120,6 +122,10 @@ export interface LocalChatPanelProps {
   orchestrationChildrenByMessageId?: Record<string, ChildInfo[]>;
   /** Current round number for the in-flight turn (1-based). */
   currentRound?: number;
+  /** Live "reconnecting" state of the in-flight turn (see RetryStatus). */
+  retryState?: RetryState | null;
+  /** Resolves a failed turn's action buttons (see TurnFailureCard). */
+  failureAction?: TurnFailureCardProps['action'];
   /**
    * Settings gear callback for the input toolbar. Receiving this enables
    * the gear button on `ChatInput`; AgentPage wires it to opening
@@ -196,6 +202,8 @@ export function LocalChatPanel({
   currentTurnChildren,
   orchestrationChildrenByMessageId,
   currentRound,
+  retryState,
+  failureAction,
   onOpenSettings,
   inputToolbarExtras,
   inputLeadingChrome,
@@ -509,6 +517,8 @@ export function LocalChatPanel({
                 currentTurnChildren={currentTurnChildren}
                 orchestrationChildrenByMessageId={orchestrationChildrenByMessageId}
                 currentRound={currentRound}
+                retryState={retryState}
+                failureAction={failureAction}
                 emptyState={emptyState ?? <EmptyChat onSelectPrompt={handleSelectPrompt} />}
                 mode={mode}
                 onRegenerate={onRegenerate}

package/src/components/chat/MessageList.tsx

@@ -25,6 +25,8 @@ import { followedPreviewPath, type TurnFile } from './turn-files';
 import { publishConversationPreview } from '@/layouts/conversation-preview';
 import { inferDurationMs, readPersistedDurationMs } from './elapsed';
 import type { LlmSpeedSnapshot } from './process-status';
+import type { RetryState } from './RetryStatus';
+import type { TurnFailureCardProps } from './TurnFailureCard';
 
 /**
  * MessageList — scrolling viewport that renders user/assistant message
@@ -154,6 +156,13 @@ interface MessageListProps {
    * AssistantMessage so its `StreamingStatus` can show "Round 2 · 继续推理...".
    */
   currentRound?: number;
+  /**
+   * Live "reconnecting" state of the in-flight turn (backend `turn_retry`).
+   * Forwarded to the tail message so the status line replaces "thinking".
+   */
+  retryState?: RetryState | null;
+  /** Resolves a failed turn's action buttons (see TurnFailureCard). */
+  failureAction?: TurnFailureCardProps['action'];
   /** Current chat mode (Agent / Plan). */
   mode?: ChatMode;
   /** W1.2.1: regenerate an assistant turn (fork-preserving). */
@@ -207,6 +216,8 @@ export function MessageList({
   currentTurnChildren,
   orchestrationChildrenByMessageId,
   currentRound,
+  retryState,
+  failureAction,
   mode,
   onRegenerate,
   interrupted = false,
@@ -530,6 +541,16 @@ export function MessageList({
                         orchestrationChildren={childList}
                         previousUser={previousUser}
                         currentRound={isStreamingTail ? currentRound : undefined}
+                        retryState={isStreamingTail ? retryState : null}
+                        // 「继续」只属于当前最后一个回合：用户已经发了新消息
+                        // 时，继续旧回合会把旧任务的输出接在新消息之后，前后
+                        // 顺序就乱了。判据是「这条是不是会话里最后一条消息」，
+                        // 不是「最后一条助手消息」——后者在用户已追问后仍成立。
+                        failureAction={
+                          message.id === lastAssistantId && isLast
+                            ? failureAction
+                            : undefined
+                        }
                         isPlanMode={isPlanMode}
                         onRegenerate={onRegenerate}
                         startedAtMs={isStreamingTail ? currentTurnStartedAtMs : undefined}

package/src/components/chat/RetryStatus.tsx

@@ -0,0 +1,77 @@
+import { useEffect, useState } from 'react';
+import { motion } from 'framer-motion';
+import { t } from '@/i18n';
+
+/**
+ * RetryStatus — "reconnecting" line for a model request that is being retried.
+ *
+ * The backend retries connection failures on a seconds-scale backoff, so a
+ * turn that is working looks identical to one that is stuck. This renders the
+ * three facts a waiting user needs: it is retrying, since when, and that Stop
+ * still works. The elapsed label appears only after
+ * `RETRY_ELAPSED_VISIBLE_MS`, because a sub-10s wait reads as progress while a
+ * ticking timer on a short wait reads as a problem.
+ */
+
+/** Elapsed seconds are shown from here on: 10s is where a wait needs progress. */
+export const RETRY_ELAPSED_VISIBLE_MS = 10_000;
+
+export interface RetryState {
+  /** Epoch ms when the first retry of this request started. */
+  startedAt: number;
+  /** Delay the loop announced for this attempt, for the next tick. */
+  delayMs?: number;
+}
+
+interface RetryStatusProps {
+  /** Live retry state, or undefined once the request is no longer retrying. */
+  retry: RetryState;
+  /** Injectable clock for tests; real time by default. */
+  now?: () => number;
+}
+
+/** Seconds waited so far; exported for the label's unit tests. */
+export function waitedSeconds(startedAt: number, now: number): number {
+  return Math.max(0, Math.floor((now - startedAt) / 1000));
+}
+
+/** The line's text: bare "reconnecting", then the elapsed count. */
+export function retryLabel(startedAt: number, now: number): string {
+  const waited = waitedSeconds(startedAt, now);
+  if (now - startedAt < RETRY_ELAPSED_VISIBLE_MS) {
+    return t('Network unstable, reconnecting…');
+  }
+  return t('Network unstable, reconnecting… ({seconds}s)', { seconds: waited });
+}
+
+export function RetryStatus({ retry, now = Date.now }: RetryStatusProps) {
+  const [tick, setTick] = useState(() => now());
+  useEffect(() => {
+    const id = window.setInterval(() => setTick(now()), 1000);
+    return () => window.clearInterval(id);
+  }, [now, retry.startedAt]);
+
+  const current = Math.max(tick, retry.startedAt);
+
+  return (
+    <motion.div
+      key="retry"
+      initial={{ opacity: 0, y: 2 }}
+      animate={{ opacity: 1, y: 0 }}
+      transition={{ duration: 0.2 }}
+      // `polite` announces the line once when it appears. The elapsed counter
+      // updates every second but is not announced again: it is informational,
+      // and a per-second announcement would interrupt screen-reader reading.
+      role="status"
+      aria-live="polite"
+      aria-atomic="true"
+      className="my-2 inline-flex items-center gap-2 text-xs text-agent-warning"
+      data-testid="retry-status"
+    >
+      <span className="h-3 w-3 animate-spin rounded-full border-2 border-current border-r-transparent" />
+      <span>{retryLabel(retry.startedAt, current)}</span>
+    </motion.div>
+  );
+}
+
+export default RetryStatus;