@steerable/agent-shell-web 0.7.2 → 0.8.0

package/src/components/chat/turn-failure.ts

@@ -0,0 +1,185 @@
+/**
+ * Failed-turn presentation: what to say and what to offer, per failure kind.
+ *
+ * The backend classifies every provider failure (`LLMError.kind`) and records
+ * it with the turn. Matching on that field — never on the message text — keeps
+ * the copy stable while error strings change, and keeps untranslated exception
+ * names out of the headline. The message itself belongs in the details
+ * disclosure, which is for whoever reads it: the user reporting a problem and
+ * the person on support.
+ */
+
+import { t } from '@/i18n';
+
+export type FailureKind =
+  | 'transport'
+  | 'rate_limit'
+  | 'server'
+  | 'auth'
+  | 'invalid_request'
+  | 'context_overflow'
+  | 'unknown';
+
+/** The provider classifications the backend can send. */
+const KINDS: readonly FailureKind[] = [
+  'transport',
+  'rate_limit',
+  'server',
+  'auth',
+  'invalid_request',
+  'context_overflow',
+  'unknown',
+];
+
+/** One action a failed turn can offer. */
+export type FailureAction =
+  | { kind: 'retry' }
+  | { kind: 'network-diagnostics' }
+  | { kind: 'open-model-settings' }
+  | { kind: 'new-chat' };
+
+/** Structured failure detail persisted with the turn (`messageMetadata.failure`). */
+export interface TurnFailureDetail {
+  kind: FailureKind;
+  /** Proxy the failing request used, credentials already stripped. */
+  proxy?: string;
+  /** Provider attempts spent on the request, including the last. */
+  attempts?: number;
+  statusCode?: number;
+}
+
+/** Everything the card renders, derived from one failure. */
+export interface FailurePresentation {
+  title: string;
+  body: string;
+  /** The primary action: the most likely thing to fix this failure. */
+  primary: FailureAction;
+  secondary: FailureAction[];
+  /** True when the details disclosure carries a classified cause. */
+  classified: boolean;
+}
+
+/**
+ * Narrows an unknown metadata value to a failure kind.
+ *
+ * Returns undefined for anything unrecognized — an older sidecar that sent
+ * nothing, a value from a newer one, a corrupted record. The caller then shows
+ * the generic card with the raw message, which is still actionable when the
+ * only remedy is reporting it.
+ */
+export function readFailureKind(value: unknown): FailureKind | undefined {
+  return typeof value === 'string' && (KINDS as readonly string[]).includes(value)
+    ? (value as FailureKind)
+    : undefined;
+}
+
+/**
+ * Copy and actions for one failure.
+ *
+ * The primary action is the one most likely to make the next attempt work:
+ * a rejected key needs settings, an over-long conversation needs a fresh one,
+ * and everything else is worth retrying once the cause clears. Actions whose
+ * handler is unavailable at render time (`available`) are dropped by the card,
+ * so this function can describe the ideal set without knowing the shell.
+ */
+export function failurePresentation(
+  detail: TurnFailureDetail | undefined,
+  options: { completedSteps?: number } = {},
+): FailurePresentation {
+  const steps = options.completedSteps ?? 0;
+  const attempts = detail?.attempts;
+  const retried =
+    typeof attempts === 'number' && attempts > 1
+      ? t('Retried {count} times. ', { count: attempts - 1 })
+      : '';
+  switch (detail?.kind) {
+    case 'transport': {
+      const next =
+        steps > 0
+          ? t(
+              "When your network is back, select Continue. The {count} completed steps won't run again.",
+              { count: steps },
+            )
+          : t('When your network is back, select Continue.');
+      return {
+        title: t("Can't reach the model service right now"),
+        body: t('The connection kept dropping. ') + retried + next,
+        primary: { kind: 'retry' },
+        secondary: [{ kind: 'network-diagnostics' }],
+        classified: true,
+      };
+    }
+    case 'auth':
+      return {
+        title: t('The model service rejected the API key'),
+        body: t('Check the API key in settings, then select Continue.'),
+        primary: { kind: 'open-model-settings' },
+        secondary: [{ kind: 'retry' }],
+        classified: true,
+      };
+    case 'rate_limit':
+      return {
+        title: t('The model service is limiting requests'),
+        body: t('Select Continue in a moment.'),
+        primary: { kind: 'retry' },
+        secondary: [],
+        classified: true,
+      };
+    case 'server':
+      return {
+        title: t('The model service had an error'),
+        body: t('Select Continue in a moment.'),
+        primary: { kind: 'retry' },
+        secondary: [],
+        classified: true,
+      };
+    case 'context_overflow':
+      return {
+        title: t('This conversation is too long for the model'),
+        body: t('Start a new chat, or select Regenerate to try a different approach.'),
+        primary: { kind: 'new-chat' },
+        secondary: [{ kind: 'retry' }],
+        classified: true,
+      };
+    case 'invalid_request':
+      return {
+        title: t('The model service rejected this request'),
+        body: t('Select Continue to try again, or copy the diagnostic info to report it.'),
+        primary: { kind: 'retry' },
+        secondary: [],
+        classified: true,
+      };
+    default:
+      return {
+        title: t('Reply failed'),
+        body: t('Select Continue to try again, or copy the diagnostic info to report it.'),
+        primary: { kind: 'retry' },
+        secondary: [],
+        classified: false,
+      };
+  }
+}
+
+/** Reads the persisted failure block, dropping fields of the wrong type. */
+export function readFailureDetail(value: unknown): TurnFailureDetail | undefined {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+  const record = value as Record<string, unknown>;
+  const kind = readFailureKind(record.errorKind);
+  if (!kind) return undefined;
+  const proxy =
+    typeof record.proxy === 'string' && record.proxy ? record.proxy : undefined;
+  const attempts =
+    typeof record.attempts === 'number' && Number.isFinite(record.attempts)
+      ? record.attempts
+      : undefined;
+  const statusCode =
+    typeof record.statusCode === 'number' && Number.isFinite(record.statusCode)
+      ? record.statusCode
+      : undefined;
+  return {
+    kind,
+    ...(proxy ? { proxy } : {}),
+    ...(attempts !== undefined ? { attempts } : {}),
+    ...(statusCode !== undefined ? { statusCode } : {}),
+  };
+}

package/src/components/settings/DiagnoseSettingsPanel.tsx

@@ -1,6 +1,11 @@
-import { useState } from 'react';
+import { useEffect, useState } from 'react';
 import { LuCircleCheck, LuCircleX, LuLoader, LuPlay } from 'react-icons/lu';
-import { diagnoseLlmConnection, type DiagnoseResult } from '@/lib/local-api';
+import {
+  diagnoseLlmConnection,
+  getReliabilitySummary,
+  type DiagnoseResult,
+  type ReliabilitySummary,
+} from '@/lib/local-api';
 import { t } from '@/i18n';
 
 /**
@@ -8,6 +13,110 @@ import { t } from '@/i18n';
  * （DNS → TCP → TLS → HTTP /models → chat completion），并报告
  * 宿主机的 ambient 代理配置。
  */
+/**
+ * 「最近 7 天」：失败与重试的统计。
+ *
+ * 与下面的连接检查分开：检查回答「现在能不能连上」，统计回答「这一周
+ * 到底发生了什么」。没有回复时显示空状态，而不是一排 0——0 会被读成
+ * 「一切正常」，实际是「还没数据」。
+ */
+function ReliabilityPanel() {
+  const [summary, setSummary] = useState<ReliabilitySummary | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    void getReliabilitySummary(7)
+      .then((value) => {
+        if (!cancelled) setSummary(value);
+      })
+      .catch((err: unknown) => {
+        if (!cancelled) setError(err instanceof Error ? err.message : String(err));
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  if (error) {
+    return (
+      <p className="mt-2 text-xs text-agent-muted-foreground" data-testid="reliability-error">
+        {t('Could not load the statistics: {error}', { error })}
+      </p>
+    );
+  }
+  if (!summary) {
+    return (
+      <p className="mt-2 text-xs text-agent-muted-foreground" data-testid="reliability-loading">
+        {t('Loading…')}
+      </p>
+    );
+  }
+  if (summary.total === 0) {
+    return (
+      <p className="mt-2 text-xs text-agent-muted-foreground" data-testid="reliability-empty">
+        {t('No replies in the last 7 days')}
+      </p>
+    );
+  }
+
+  return (
+    <div className="mt-2 space-y-2" data-testid="reliability-summary">
+      <div className="grid grid-cols-3 gap-2">
+        <Stat value={summary.total} label={t('Replies')} />
+        <Stat value={summary.failed} label={t('Failed')} />
+        <Stat value={summary.recoveredByRetry} label={t('Recovered by retry')} />
+      </div>
+      {summary.failuresByKind.length > 0 ? (
+        <ul className="space-y-1 rounded-agent-sm bg-agent-muted/40 px-2.5 py-1.5 text-xs">
+          {summary.failuresByKind.map((row) => (
+            <li key={row.kind} className="flex items-center justify-between gap-2">
+              <span className="text-agent-muted-foreground">{kindLabel(row.kind)}</span>
+              <span className="font-mono text-agent-foreground">{row.count}</span>
+            </li>
+          ))}
+        </ul>
+      ) : null}
+      {summary.usedDirect > 0 ? (
+        <p className="text-xs text-agent-muted-foreground">
+          {t('{count} replies went direct instead of through the system proxy.', {
+            count: summary.usedDirect,
+          })}
+        </p>
+      ) : null}
+    </div>
+  );
+}
+
+function Stat({ value, label }: { value: number; label: string }) {
+  return (
+    <div className="rounded-agent-sm bg-agent-muted/40 px-2.5 py-1.5">
+      <div className="font-mono text-sm text-agent-foreground">{value}</div>
+      <div className="text-[11px] text-agent-muted-foreground">{label}</div>
+    </div>
+  );
+}
+
+/** Provider failure kinds, in the words a user reads. */
+function kindLabel(kind: string): string {
+  switch (kind) {
+    case 'transport':
+      return t('Network');
+    case 'auth':
+      return t('Credentials');
+    case 'rate_limit':
+      return t('Rate limit');
+    case 'server':
+      return t('Service error');
+    case 'context_overflow':
+      return t('Conversation too long');
+    case 'invalid_request':
+      return t('Rejected request');
+    default:
+      return t('Other');
+  }
+}
+
 export function DiagnoseSettingsPanel() {
   const [running, setRunning] = useState(false);
   const [result, setResult] = useState<DiagnoseResult | null>(null);
@@ -36,6 +145,8 @@ export function DiagnoseSettingsPanel() {
         {t('The diagnosis runs in the host process and also reports system and environment proxy settings.')}
       </p>
 
+      <ReliabilityPanel />
+
       <button
         type="button"
         onClick={() => void run()}

package/src/components/settings/LlmSettingsPanel.tsx

@@ -52,6 +52,11 @@ import {
 
 export interface LlmSettingsPanelHandle {
   save: () => Promise<void>;
+  /**
+   * 把光标放到 API Key 输入框。返回 false 表示字段当前不存在（面板还在
+   * 加载，或该服务商没有这个字段），调用方据此决定是否稍后再试。
+   */
+  focusApiKey: () => boolean;
 }
 
 export interface LlmSaveUi {
@@ -389,8 +394,16 @@ export const LlmSettingsPanel = forwardRef<LlmSettingsPanelHandle, LlmSettingsPa
 
   const handleSaveRef = useRef(handleSave);
   handleSaveRef.current = handleSave;
+  const apiKeyRef = useRef<HTMLInputElement | null>(null);
+
   useImperativeHandle(ref, () => ({
     save: () => handleSaveRef.current(),
+    focusApiKey: () => {
+      const field = apiKeyRef.current;
+      if (!field) return false;
+      field.focus();
+      return document.activeElement === field;
+    },
   }), []);
 
   useEffect(() => {
@@ -482,7 +495,12 @@ export const LlmSettingsPanel = forwardRef<LlmSettingsPanelHandle, LlmSettingsPa
                     </label>
                     <div className="flex items-center gap-2">
                       <input
+                        ref={apiKeyRef}
                         type="password"
+                        // The failure card's 「打开模型设置」 targets this field:
+                        // an authentication failure is fixed here, so the panel
+                        // focuses it instead of leaving the reader to hunt.
+                        data-settings-field="llm-api-key"
                         value={settings.apiKey || ''}
                         onChange={(e) =>
                           setSettings((prev) => ({ ...prev, apiKey: e.target.value }))

package/src/layouts/AgentLayout.tsx

@@ -365,7 +365,7 @@ function AgentLayoutContent() {
     return {
       kind,
       contentId,
-      title: request.title || contentTitle(contentId, slot.title),
+      title: request.title || contentTitle(contentId, t(slot.title)),
     };
   }, [packChatSlots]);
 

package/src/layouts/RightPanelTabBar.tsx

@@ -192,7 +192,7 @@ function unopenedPanels(
     const Icon = slot.Icon;
     entries.push({
       id: slot.slotId,
-      title: slot.title,
+      title: t(slot.title),
       testId: `header-slot-${slot.slotId}`,
       icon: <Icon className="h-3.5 w-3.5 shrink-0" />,
     });

package/src/layouts/right-panel-tabs.ts

@@ -143,7 +143,7 @@ export function normalizeRightPanelEntry(
  *
  * 兼容这些历史格式：
  *   - v2：{"version":2,"sessions":{"<chatId>":{"tabs":[...],"activeTabId":"..."}}}；
- *   - 旧多标签：{"<chatId>": { "tabs": ["ppt", "terminal"], "active": "ppt" }}；
+ *   - 旧多标签：{"<chatId>": { "tabs": ["<slotId>", "terminal"], "active": "<slotId>" }}；
  *   - 单值映射：{"<chatId>": "terminal" | "<slotId>"} → 一个标签；
  *   - 整个值就是单个字符串 → 迁到当前会话；
  *   - 更老：只记录终端是否打开过的布尔 key。

package/src/lib/local-api.ts

@@ -915,6 +915,24 @@ export async function installCommandLineTool(name: string) {
   });
 }
 
+/** Reliability numbers for the settings page's network section (R4). */
+export interface ReliabilitySummary {
+  sinceDays: number;
+  total: number;
+  failed: number;
+  cancelled: number;
+  recoveredByRetry: number;
+  usedDirect: number;
+  failuresByKind: Array<{ kind: string; count: number }>;
+}
+
+export async function getReliabilitySummary(days = 7) {
+  return bridge().localBackend.request<ReliabilitySummary>({
+    method: 'GET',
+    path: `/api/v2/usage/reliability?days=${encodeURIComponent(days)}`,
+  });
+}
+
 export async function diagnoseLlmConnection(input: {
   baseUrl?: string;
   apiKey?: string;

package/src/pages/AgentPage.tsx

@@ -10,6 +10,8 @@ import {
 } from "@/lib/chat-transport";
 import { ChatHeader } from "@/components/ChatHeader";
 import { EmptyChatHero } from "@/components/chat/EmptyChatHero";
+import type { RetryState } from "@/components/chat/RetryStatus";
+import type { FailureAction } from "@/components/chat/turn-failure";
 import { LocalChatPanel } from "@/components/chat/LocalChatPanel";
 import { ModelPicker } from "@/components/chat/ModelPicker";
 import {
@@ -540,6 +542,11 @@ function AgentChatView({
   // before this signal, the UI looked frozen whenever the model paused to
   // wait for tool results.
   const [currentRound, setCurrentRound] = useState(1);
+  // Live "reconnecting" state for the in-flight turn. Set by the backend's
+  // `turn_retry` notice, cleared when the round ends or the stream settles —
+  // a retry that succeeded leaves no trace in the UI or in history.
+  const [retryState, setRetryState] = useState<RetryState | null>(null);
+  const navigate = useNavigate();
   // Holds the latest in-flight actions for the `message_id` reconciliation
   // — `useState`'s setter sees the latest value via the functional update
   // form, but we keep this ref so the reconciliation event handler can read
@@ -624,6 +631,21 @@ function AgentChatView({
       // 这不是新一轮，跳过计数。
       if (ev.payload?.status === "cancelled") return;
       setCurrentRound((r) => r + 1);
+      // A new round means the previous request finished (or was replaced), so
+      // any "reconnecting" line belongs to the round that is now over.
+      setRetryState(null);
+      return;
+    }
+    if (ev.event === "turn_retry") {
+      // The backend announces each retry; the first one starts the clock the
+      // status line counts from. Later ones keep it so the count is the whole
+      // wait, not just the latest attempt.
+      const delayMs =
+        typeof ev.payload?.delayMs === "number" ? ev.payload.delayMs : undefined;
+      setRetryState((prev) => ({
+        startedAt: prev?.startedAt ?? Date.now(),
+        ...(delayMs !== undefined ? { delayMs } : {}),
+      }));
       return;
     }
     if (ev.event === "orchestration_child") {
@@ -942,6 +964,7 @@ function AgentChatView({
       pendingTurnFilesRef.current = [];
       setCurrentTurnFiles([]);
       setCurrentRound(1);
+      setRetryState(null);
       const started = Date.now();
       turnStartedAtRef.current = started;
       setCurrentTurnStartedAtMs(started);
@@ -1059,6 +1082,7 @@ function AgentChatView({
     pendingTurnFilesRef.current = [];
     setCurrentTurnFiles([]);
     setCurrentRound(1);
+    setRetryState(null);
     const started = Date.now();
     turnStartedAtRef.current = started;
     setCurrentTurnStartedAtMs(started);
@@ -1081,6 +1105,63 @@ function AgentChatView({
     setInterrupted(false);
   }, []);
 
+  // 「新建对话」失败时的就地提示；点一次清一次。
+  const [newChatError, setNewChatError] = useState<string | null>(null);
+
+  /**
+   * 失败卡片的按钮。和「继续上次回复」走同一条 resume 通道：sidecar 回放
+   * durable record，已完成的工具调用不会再执行一遍——这正是失败后点
+   * 「继续」想要的语义。本轮正在跑时按钮禁用（同一会话不能同时两轮）。
+   */
+  const failureAction = useCallback(
+    (action: FailureAction) => {
+      switch (action.kind) {
+        case "retry":
+          return {
+            onClick: () => void handleContinueInterrupted(),
+            disabled: isStreaming,
+            hint: isStreaming ? t("This chat is running. Continue when it finishes.") : undefined,
+          };
+        case "network-diagnostics":
+          // 诊断区挂在设置页「通用」下（settingsChrome('diagnose') 控制显隐）。
+          return settingsChrome("diagnose")
+            ? { onClick: () => navigate("/settings") }
+            : null;
+        case "open-model-settings":
+          return settingsChrome("llm") && hasHostBridge()
+            ? { onClick: () => setLlmSettingsOpen(true) }
+            : null;
+        case "new-chat":
+          // 同项目的空会话：对话过长时的新出路，而不是把用户丢回落地页再
+          // 重选项目、重填输入。失败时提示并留在原地，不吞掉这次点击。
+          return {
+            onClick: () => {
+              void ctx
+                .createChat({
+                  ...(chat?.projectId ? { projectId: chat.projectId } : {}),
+                  ...(chat?.agentId ? { agentId: chat.agentId } : {}),
+                })
+                .then((id) => {
+                  if (id) navigate(`/agent/${id}`);
+                  else setNewChatError(t("Failed to create the chat. Please try again."));
+                })
+                .catch((err: unknown) =>
+                  setNewChatError(err instanceof Error ? err.message : String(err)),
+                );
+            },
+          };
+      }
+    },
+    [
+      chat?.agentId,
+      chat?.projectId,
+      ctx,
+      handleContinueInterrupted,
+      isStreaming,
+      navigate,
+    ],
+  );
+
   // 轮中插队 + 失败兜底（W6-2）：streaming 期间 ⌘/Ctrl+Enter 优先注入运行中的
   // CoreLoop 回合；注入不了时 hook 按回合实况降级——仍在跑则排入待发队列
   // （'queued'，ChatInput 提示"已改为排队"），恰好已结束则作为新回合直发
@@ -1322,6 +1403,8 @@ function AgentChatView({
         currentTurnChildren={effectiveCurrentTurnChildren}
         orchestrationChildrenByMessageId={orchestrationChildrenByMessageId}
         currentRound={currentRound}
+        retryState={retryState}
+        failureAction={failureAction}
         interrupted={interrupted}
         onContinueInterrupted={handleContinueInterrupted}
         onDismissInterrupted={handleDismissInterrupted}
@@ -1369,6 +1452,23 @@ function AgentChatView({
         }
         inputBanner={
           <>
+            {newChatError ? (
+              <div
+                role="status"
+                data-testid="new-chat-error"
+                className="mb-1 flex items-center justify-between gap-2 rounded-agent-md border border-agent-destructive/20 bg-agent-destructive/10 px-2.5 py-1.5 text-xs text-agent-destructive"
+              >
+                <span>{newChatError}</span>
+                <button
+                  type="button"
+                  onClick={() => setNewChatError(null)}
+                  className="rounded px-1 hover:bg-agent-destructive/10"
+                  aria-label={t("Dismiss")}
+                >
+                  ✕
+                </button>
+              </div>
+            ) : null}
             <GoalLoopStatusBar
               chatId={chatId}
               goal={goal}

package/src/pages/SettingsPage.tsx

@@ -220,7 +220,7 @@ export function SettingsPage() {
     for (const panel of packPanels) {
       list.push({
         id: panel.panelId,
-        label: panel.title,
+        label: t(panel.title),
         Icon: panel.Icon ?? LuSettings,
       });
     }
@@ -503,7 +503,7 @@ export function SettingsPage() {
                     {panel.Icon ? (
                       <panel.Icon className="h-3.5 w-3.5 text-agent-muted-foreground" />
                     ) : null}
-                    {panel.title}
+                    {t(panel.title)}
                   </h2>
                   <panel.Component />
                 </section>