@steerable/agent-shell-web 0.7.4 → 0.8.0

package/src/components/chat/StreamingStatus.tsx

@@ -1,5 +1,6 @@
 import { motion } from 'framer-motion';
 import { t } from '@/i18n';
+import { RetryStatus, type RetryState } from './RetryStatus';
 
 /**
  * StreamingStatus — informative placeholder for an assistant bubble that has
@@ -30,13 +31,21 @@ interface StreamingStatusProps {
    * nothing (the content + cursor blink is enough).
    */
   hasContent: boolean;
+  /**
+   * Set while the request is being retried. Outranks `hasContent`: a turn
+   * that already streamed text and then lost its connection is waiting, not
+   * writing, and the cursor alone would read as a stall.
+   */
+  retry?: RetryState;
 }
 
 export function StreamingStatus({
   round,
   actionCount,
   hasContent,
+  retry,
 }: StreamingStatusProps) {
+  if (retry) return <RetryStatus retry={retry} />;
   // Once tokens are flowing the parent already has plenty of visual feedback
   // (the streaming cursor); a separate status line would be noise.
   if (hasContent) return null;

package/src/components/chat/TurnFailureCard.tsx

@@ -0,0 +1,272 @@
+import { useState } from 'react';
+import { LuChevronDown, LuChevronUp, LuCopy, LuTriangleAlert } from 'react-icons/lu';
+import { t } from '@/i18n';
+import {
+  failurePresentation,
+  type FailureAction,
+  type TurnFailureDetail,
+} from './turn-failure';
+
+/**
+ * TurnFailureCard — what a failed turn shows in place of an answer.
+ *
+ * Two layers, chosen by who reads them. The headline and one sentence say
+ * what happened and what to do next; nobody needs `SSLEOFError` to press
+ * Continue. The details disclosure holds the raw cause, the hop the request
+ * took, and the trace id — the material a support reply or a bug report
+ * needs, which is exactly why it must not be in the way.
+ *
+ * The card never decides whether an action is available; it renders the ones
+ * its caller passed and shows the rest as disabled. That keeps the choice of
+ * "what can this build actually do" in one place (the message list) instead of
+ * duplicating capability checks per failure kind.
+ */
+
+export interface TurnFailureCardProps {
+  /** Classified detail, when the backend recorded one. */
+  detail?: TurnFailureDetail;
+  /** Raw failure text, always present; the details layer's main content. */
+  reason: string;
+  /** Tool calls that already completed in this turn. */
+  completedSteps?: number;
+  /** ISO timestamp of the failed turn, for the details layer. */
+  happenedAt?: string;
+  /** Trace id, for the details layer and the copied report. */
+  traceId?: string;
+  /** Renders the action buttons this build can perform. */
+  action?: (action: FailureAction) => { onClick: () => void; disabled?: boolean; hint?: string } | null;
+}
+
+/** Details-layer field label/value pair. */
+function DetailRow({ label, children }: { label: string; children: React.ReactNode }) {
+  return (
+    <>
+      <dt className="text-agent-muted-foreground">{label}</dt>
+      <dd className="min-w-0 break-words">{children}</dd>
+    </>
+  );
+}
+
+export function TurnFailureCard({
+  detail,
+  reason,
+  completedSteps = 0,
+  happenedAt,
+  traceId,
+  action,
+}: TurnFailureCardProps) {
+  const [open, setOpen] = useState(false);
+  const presentation = failurePresentation(detail, { completedSteps });
+  const actions = [presentation.primary, ...presentation.secondary]
+    .map((entry) => ({ entry, handler: action?.(entry) ?? null }))
+    .filter((row): row is { entry: FailureAction; handler: NonNullable<typeof row.handler> } =>
+      row.handler !== null,
+    );
+
+  return (
+    <div
+      className="rounded-agent-lg border border-agent-destructive/40 bg-agent-destructive/5 px-2.5 py-2 text-xs leading-relaxed shadow-sm"
+      data-testid="turn-failure"
+      data-failure-kind={detail?.kind ?? 'unknown'}
+    >
+      <div className="flex items-start gap-2 font-medium text-agent-destructive">
+        <LuTriangleAlert className="mt-0.5 h-3.5 w-3.5 flex-shrink-0" />
+        <span>{presentation.title}</span>
+      </div>
+      <p className="mt-1 ml-5 text-agent-foreground/90">{presentation.body}</p>
+      <div className="mt-2 ml-5 flex flex-wrap items-center gap-2">
+        {actions.map(({ entry, handler }, index) => (
+          <button
+            key={entry.kind}
+            type="button"
+            disabled={handler.disabled}
+            title={handler.hint}
+            onClick={handler.onClick}
+            className={
+              index === 0
+                ? 'rounded-agent-md bg-agent-primary px-3 py-1 text-xs font-medium text-agent-primary-foreground transition hover:bg-agent-primary/90 disabled:opacity-50'
+                : '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={entry.kind}
+          >
+            {actionLabel(entry)}
+          </button>
+        ))}
+        <button
+          type="button"
+          onClick={() => setOpen((value) => !value)}
+          className="inline-flex items-center gap-0.5 rounded px-1 text-agent-muted-foreground hover:text-agent-foreground"
+          aria-expanded={open}
+          data-action="details"
+        >
+          {open ? t('Hide details') : t('Details')}
+          {open ? <LuChevronUp className="h-3 w-3" /> : <LuChevronDown className="h-3 w-3" />}
+        </button>
+      </div>
+      {open && (
+        <div className="mt-2 ml-5 border-t border-agent-destructive/20 pt-2" data-testid="turn-failure-details">
+          <dl className="grid grid-cols-[5.5rem_1fr] gap-x-3 gap-y-1">
+            <DetailRow label={t('Category')}>
+              {presentation.classified ? categoryLabel(detail?.kind) : t('Not classified')}
+            </DetailRow>
+            <DetailRow label={t('Cause')}>
+              <span className="block">{causeSummary(detail, reason)}</span>
+              {presentation.classified && reason !== causeSummary(detail, reason) ? (
+                <code className="mt-0.5 block break-all font-mono text-[11px] text-agent-muted-foreground">
+                  {reason}
+                </code>
+              ) : null}
+            </DetailRow>
+            {detail?.proxy || detail?.kind === 'transport' ? (
+              <DetailRow label={t('Connection')}>
+                {detail?.proxy
+                  ? t('Through system proxy {proxy}', { proxy: detail.proxy })
+                  : t('Direct')}
+              </DetailRow>
+            ) : null}
+            {detail?.attempts ? (
+              <DetailRow label={t('Retries')}>
+                {t('{count} attempts', { count: detail.attempts })}
+              </DetailRow>
+            ) : null}
+            {happenedAt ? (
+              <DetailRow label={t('Time')}>
+                <span className="font-mono text-[11px]">{happenedAt}</span>
+              </DetailRow>
+            ) : null}
+            {traceId ? (
+              <DetailRow label={t('Trace ID')}>
+                <span className="font-mono text-[11px]">{traceId}</span>
+              </DetailRow>
+            ) : null}
+          </dl>
+          {traceId ? <CopyDiagnostics detail={detail} reason={reason} traceId={traceId} /> : null}
+        </div>
+      )}
+    </div>
+  );
+}
+
+/** Button text per action, so the card does not repeat the copy three times. */
+function actionLabel(action: FailureAction): string {
+  switch (action.kind) {
+    case 'retry':
+      return t('Continue');
+    case 'network-diagnostics':
+      return t('Network diagnostics');
+    case 'open-model-settings':
+      return t('Open model settings');
+    case 'new-chat':
+      return t('New chat');
+  }
+}
+
+/** The details layer's one-line Chinese cause, or the raw text when unknown. */
+function causeSummary(detail: TurnFailureDetail | undefined, reason: string): string {
+  switch (detail?.kind) {
+    case 'transport':
+      return t('The connection to the model service dropped.');
+    case 'auth':
+      return t('The service rejected the credentials.');
+    case 'rate_limit':
+      return t('The service asked us to slow down.');
+    case 'server':
+      return t('The service reported its own failure.');
+    case 'context_overflow':
+      return t('The request exceeds the model window.');
+    case 'invalid_request':
+      return t('The service rejected the request.');
+    default:
+      return reason;
+  }
+}
+
+function categoryLabel(kind: string | undefined): 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('Not classified');
+  }
+}
+
+/**
+ * One-click report text. Everything a reader needs to reproduce the failure,
+ * and nothing that identifies the user: the proxy address is already stripped
+ * of credentials by the backend, and the API key never enters a failure.
+ */
+export function buildDiagnostics(input: {
+  detail?: TurnFailureDetail;
+  reason: string;
+  traceId: string;
+  version?: string;
+}): string {
+  const lines = [
+    input.version ? t('Version: {version}', { version: input.version }) : null,
+    t('Category: {category}', {
+      category: input.detail ? categoryLabel(input.detail.kind) : t('Not classified'),
+    }),
+    t('Cause: {cause}', { cause: input.reason }),
+    input.detail?.proxy
+      ? t('Connection: through system proxy {proxy}', { proxy: input.detail.proxy })
+      : t('Connection: direct'),
+    input.detail?.attempts
+      ? t('Retries: {count}', { count: input.detail.attempts })
+      : null,
+    t('Trace ID: {traceId}', { traceId: input.traceId }),
+  ].filter((line): line is string => line !== null);
+  return lines.join('\n');
+}
+
+function CopyDiagnostics({
+  detail,
+  reason,
+  traceId,
+}: {
+  detail?: TurnFailureDetail;
+  reason: string;
+  traceId: string;
+}) {
+  const [copied, setCopied] = useState(false);
+  const copy = async () => {
+    const text = buildDiagnostics({ detail, reason, traceId });
+    try {
+      await navigator.clipboard.writeText(text);
+      setCopied(true);
+      window.setTimeout(() => setCopied(false), 2000);
+    } catch {
+      // Clipboard permission can be refused (browser, kiosk). The text is
+      // already on screen in the details layer, so reporting the failure is
+      // only a manual selection away; do not block on it.
+      setCopied(false);
+    }
+  };
+  return (
+    <div className="mt-2 flex items-center gap-2">
+      <button
+        type="button"
+        onClick={() => void copy()}
+        className="inline-flex items-center gap-1 rounded-agent-md border border-agent-border bg-agent-card px-2 py-0.5 text-[11px] hover:bg-agent-muted"
+        data-action="copy-diagnostics"
+      >
+        <LuCopy className="h-3 w-3" />
+        {copied ? t('Copied') : t('Copy diagnostic info')}
+      </button>
+      <span className="text-[11px] text-agent-muted-foreground">
+        {t("Doesn't include your API key")}
+      </span>
+    </div>
+  );
+}
+
+export default TurnFailureCard;

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/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;