@steerable/agent-shell-web 0.6.15

package/src/components/chat/SessionTreeModal.test.tsx

@@ -0,0 +1,161 @@
+/**
+ * SessionTreeModal 的接线契约：
+ *   - 打开时经 localBackend 拉 GET /branches/tree，DFS 渲染缩进树，
+ *     activeRecordId 行高亮带 ✓；
+ *   - 点击（或 Enter）非 active 节点 → POST /branches/activate →
+ *     onBranchSwitched + onClose；
+ *   - 树只有当前记录一个节点时显示空态文案；
+ *   - Escape 关闭。
+ */
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { ChatBranchTreeResponse } from '@/lib/local-api';
+import { SessionTreeModal } from './SessionTreeModal';
+
+afterEach(() => {
+  cleanup();
+  delete (window as { electron?: unknown }).electron;
+});
+
+const TREE_RESPONSE: ChatBranchTreeResponse = {
+  activeRecordId: 'chat_1:r2',
+  nodeCount: 4,
+  truncated: false,
+  tree: {
+    recordId: 'chat_1',
+    sourceRecordId: null,
+    sourceUntilSeq: null,
+    label: 'root',
+    depth: 0,
+    children: [
+      {
+        recordId: 'chat_1:r2',
+        sourceRecordId: 'chat_1',
+        sourceUntilSeq: 5,
+        label: 'question 1',
+        depth: 1,
+        children: [
+          {
+            recordId: 'chat_1:r2:x',
+            sourceRecordId: 'chat_1:r2',
+            sourceUntilSeq: 2,
+            label: 'variant question',
+            depth: 2,
+            children: [],
+          },
+        ],
+      },
+      {
+        recordId: 'chat_1:r3',
+        sourceRecordId: 'chat_1',
+        sourceUntilSeq: 3,
+        label: 'question 0',
+        depth: 1,
+        children: [],
+      },
+    ],
+  },
+};
+
+function installBridge(treeResponse: ChatBranchTreeResponse | null = TREE_RESPONSE) {
+  const request = vi.fn((input: { method: string; path: string; body?: unknown }) => {
+    if (input.method === 'GET' && input.path.endsWith('/branches/tree')) {
+      return Promise.resolve(treeResponse);
+    }
+    if (input.method === 'POST' && input.path.endsWith('/branches/activate')) {
+      return Promise.resolve({ activeRecordId: 'x', messageCount: 3 });
+    }
+    return Promise.reject(new Error(`unexpected request: ${input.method} ${input.path}`));
+  });
+  (window as { electron?: unknown }).electron = { localBackend: { request } };
+  return { request };
+}
+
+describe('SessionTreeModal', () => {
+  it('渲染全树：缩进行 + active 节点高亮', async () => {
+    installBridge();
+    render(<SessionTreeModal chatId="chat_1" onClose={() => {}} />);
+
+    await waitFor(() => expect(screen.queryByText('正在加载分支…')).toBeNull());
+
+    const rows = screen.getAllByRole('button').filter((b) => b.hasAttribute('data-tree-row'));
+    expect(rows).toHaveLength(4);
+    // DFS 顺序：root → r2 → r2:x → r3；label 按行展示（label 在 truncate span 里）。
+    const labels = rows.map(
+      (r) => (r.querySelector('span.truncate') as HTMLElement | null)?.textContent,
+    );
+    expect(labels).toEqual(['root', 'question 1', 'variant question', 'question 0']);
+    // 连接线前缀：根无前缀，孙节点带 │ 缩进。
+    const prefixes = rows.map(
+      (r) => (r.querySelector('span.font-mono') as HTMLElement | null)?.textContent ?? '',
+    );
+    expect(prefixes).toEqual(['', '├─ ', '│  └─ ', '└─ ']);
+    // active 标记在 r2 行。
+    expect(rows[1].getAttribute('data-active')).toBe('true');
+    expect(rows[0].getAttribute('data-active')).toBeNull();
+  });
+
+  it('点击堂兄弟节点：activate + onBranchSwitched + 关闭', async () => {
+    const { request } = installBridge();
+    const onClose = vi.fn();
+    const onBranchSwitched = vi.fn();
+    render(
+      <SessionTreeModal chatId="chat_1" onClose={onClose} onBranchSwitched={onBranchSwitched} />,
+    );
+    await waitFor(() => screen.getByText('question 0'));
+
+    fireEvent.click(screen.getByText('question 0'));
+
+    await waitFor(() => expect(onClose).toHaveBeenCalledTimes(1));
+    expect(request).toHaveBeenCalledWith({
+      method: 'POST',
+      path: '/api/v2/chats/chat_1/branches/activate',
+      body: { recordId: 'chat_1:r3' },
+    });
+    expect(onBranchSwitched).toHaveBeenCalledTimes(1);
+  });
+
+  it('点击 active 节点不触发切换', async () => {
+    const { request } = installBridge();
+    render(<SessionTreeModal chatId="chat_1" onClose={() => {}} />);
+    await waitFor(() => screen.getByText('question 1'));
+
+    fireEvent.click(screen.getByText('question 1'));
+
+    expect(
+      request.mock.calls.filter(([input]) => (input as { method: string }).method === 'POST'),
+    ).toHaveLength(0);
+  });
+
+  it('单节点树显示空态', async () => {
+    installBridge({
+      activeRecordId: 'chat_1',
+      nodeCount: 1,
+      truncated: false,
+      tree: {
+        recordId: 'chat_1',
+        sourceRecordId: null,
+        sourceUntilSeq: null,
+        label: 'root',
+        depth: 0,
+        children: [],
+      },
+    });
+    render(<SessionTreeModal chatId="chat_1" onClose={() => {}} />);
+
+    await waitFor(() => screen.getByText(/重新生成回复后，旧版本会保留在这里/));
+    expect(screen.queryAllByRole('button').filter((b) => b.hasAttribute('data-tree-row')))
+      .toHaveLength(0);
+  });
+
+  it('Escape 关闭模态', async () => {
+    const onClose = vi.fn();
+    installBridge();
+    render(<SessionTreeModal chatId="chat_1" onClose={onClose} />);
+    await waitFor(() => screen.getByText('question 0'));
+
+    fireEvent.keyDown(document, { key: 'Escape' });
+
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+});

package/src/components/chat/SessionTreeModal.tsx

@@ -0,0 +1,221 @@
+import { useEffect, useMemo, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { LuCheck, LuGitBranch, LuLoaderCircle, LuX } from 'react-icons/lu';
+import {
+  activateChatBranch,
+  getChatBranchTree,
+  type ChatBranchTreeNode,
+  type ChatBranchTreeResponse,
+} from '@/lib/local-api';
+
+/**
+ * SessionTreeModal — pi 式全树分支视图（session tree）。
+ *
+ * 数据来自 getChatBranchTree（sidecar `agent.session.tree`）：从家族根
+ * 展开的完整 fork 树，含堂兄弟分支——Header 下拉只有 lineage + 直接
+ * 子节点，这里能看到并一键切换到任意家族成员。
+ *
+ * 渲染参考 pi 的 TreeSelector：DFS 铺平成缩进行，│/├─/└─ 连接线，
+ * 当前 activeRecordId 高亮。交互：点击（或 ↑↓ + Enter）切换分支 →
+ * activateChatBranch → onBranchSwitched 触发消息区重投影 → 关闭；
+ * Escape / 点击遮罩关闭。
+ */
+
+interface SessionTreeModalProps {
+  chatId: string;
+  onClose: () => void;
+  /** 切换成功后调用——页面据此重新水合消息列表（branchTick 机制）。 */
+  onBranchSwitched?: () => void;
+}
+
+interface FlatNode {
+  node: ChatBranchTreeNode;
+  /** 已拼好的缩进前缀，如 "│   ├─ "（根节点为空）。 */
+  prefix: string;
+}
+
+/** DFS 铺平树为渲染行，前缀沿用 pi 的 │/├─/└─ 连接线风格。 */
+function flattenTree(root: ChatBranchTreeNode): FlatNode[] {
+  const out: FlatNode[] = [];
+  const walk = (node: ChatBranchTreeNode, ancestorPrefix: string, isLast: boolean, isRoot: boolean) => {
+    out.push({
+      node,
+      prefix: isRoot ? '' : `${ancestorPrefix}${isLast ? '└─ ' : '├─ '}`,
+    });
+    const childPrefix = isRoot ? '' : `${ancestorPrefix}${isLast ? '   ' : '│  '}`;
+    node.children.forEach((child, index) =>
+      walk(child, childPrefix, index === node.children.length - 1, false),
+    );
+  };
+  walk(root, '', true, true);
+  return out;
+}
+
+export function SessionTreeModal({ chatId, onClose, onBranchSwitched }: SessionTreeModalProps) {
+  const [data, setData] = useState<ChatBranchTreeResponse | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [switching, setSwitching] = useState(false);
+  const [selectedIndex, setSelectedIndex] = useState(0);
+
+  useEffect(() => {
+    let cancelled = false;
+    setLoading(true);
+    getChatBranchTree(chatId)
+      .then((res) => {
+        if (!cancelled) setData(res);
+      })
+      .catch(() => {
+        if (!cancelled) setData(null);
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [chatId]);
+
+  const rows = useMemo(() => (data?.tree ? flattenTree(data.tree) : []), [data]);
+  // 无分支 = 树只有当前记录一个节点（还没有任何 regenerate fork）。
+  const isEmpty = !loading && (!data?.tree || rows.length <= 1);
+
+  useEffect(() => {
+    if (!data) return;
+    const activeIndex = rows.findIndex((r) => r.node.recordId === data.activeRecordId);
+    setSelectedIndex(activeIndex >= 0 ? activeIndex : 0);
+  }, [data, rows]);
+
+  const switchTo = async (recordId: string) => {
+    if (!data || switching || recordId === data.activeRecordId) return;
+    setSwitching(true);
+    try {
+      await activateChatBranch(chatId, recordId);
+      onBranchSwitched?.();
+      onClose();
+    } catch {
+      // 切换失败（分支族外记录 / sidecar 离线）——模态保持打开，用户可重试。
+    } finally {
+      setSwitching(false);
+    }
+  };
+
+  useEffect(() => {
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        e.stopPropagation();
+        onClose();
+        return;
+      }
+      if (rows.length === 0) return;
+      if (e.key === 'ArrowDown') {
+        e.preventDefault();
+        setSelectedIndex((i) => Math.min(i + 1, rows.length - 1));
+      } else if (e.key === 'ArrowUp') {
+        e.preventDefault();
+        setSelectedIndex((i) => Math.max(i - 1, 0));
+      } else if (e.key === 'Enter') {
+        e.preventDefault();
+        const row = rows[selectedIndex];
+        if (row) void switchTo(row.node.recordId);
+      }
+    };
+    document.addEventListener('keydown', onKeyDown, true);
+    return () => document.removeEventListener('keydown', onKeyDown, true);
+    // switchTo 依赖 data/switching，每次渲染重建监听即可（模态生命周期短）。
+  });
+
+  return createPortal(
+    <div
+      className="fixed inset-0 z-50 flex items-center justify-center bg-black/40 p-4"
+      role="dialog"
+      aria-modal="true"
+      aria-label="会话分支树"
+      onMouseDown={(e) => {
+        if (e.target === e.currentTarget) onClose();
+      }}
+      data-session-tree-modal
+    >
+      <div className="flex max-h-[85vh] w-full max-w-lg flex-col overflow-hidden rounded-agent-lg border border-agent-border bg-agent-canvas shadow-xl">
+        <div className="flex items-center gap-2 border-b border-agent-border px-4 py-2.5">
+          <LuGitBranch className="h-4 w-4 shrink-0 text-agent-muted-foreground" />
+          <span className="min-w-0 flex-1 truncate text-sm font-medium text-agent-foreground">
+            会话分支树
+            {data && data.nodeCount > 1 && (
+              <span className="ml-1.5 text-xs font-normal text-agent-muted-foreground">
+                {data.nodeCount} 个分支
+              </span>
+            )}
+          </span>
+          <button
+            type="button"
+            onClick={onClose}
+            className="flex h-6 w-6 shrink-0 items-center justify-center rounded-full text-agent-muted-foreground transition-colors hover:bg-agent-foreground/5 hover:text-agent-foreground"
+            aria-label="关闭"
+          >
+            <LuX className="h-3.5 w-3.5" />
+          </button>
+        </div>
+
+        <div className="min-h-0 flex-1 overflow-auto p-2">
+          {loading ? (
+            <div className="flex items-center justify-center gap-2 px-3 py-6 text-xs text-agent-muted-foreground">
+              <LuLoaderCircle className="h-3.5 w-3.5 animate-spin" />
+              正在加载分支…
+            </div>
+          ) : isEmpty ? (
+            <div className="px-3 py-6 text-center text-xs text-agent-muted-foreground">
+              暂无分支 — 重新生成回复后，旧版本会保留在这里。
+            </div>
+          ) : (
+            rows.map((row, index) => {
+              const active = row.node.recordId === data?.activeRecordId;
+              const selected = index === selectedIndex;
+              return (
+                <button
+                  key={row.node.recordId}
+                  type="button"
+                  onClick={() => void switchTo(row.node.recordId)}
+                  onMouseEnter={() => setSelectedIndex(index)}
+                  aria-current={active ? 'true' : undefined}
+                  aria-disabled={switching || active || undefined}
+                  className={`flex w-full items-center gap-1 rounded px-2 py-1.5 text-left text-xs transition-colors ${
+                    active
+                      ? 'cursor-default font-medium text-agent-foreground'
+                      : 'text-agent-muted-foreground hover:text-agent-foreground'
+                  } ${selected ? 'bg-agent-foreground/5' : ''} ${
+                    switching ? 'pointer-events-none opacity-60' : ''
+                  }`}
+                  data-tree-row
+                  data-active={active || undefined}
+                >
+                  {row.prefix && (
+                    <span className="shrink-0 whitespace-pre font-mono text-agent-muted-foreground/60">
+                      {row.prefix}
+                    </span>
+                  )}
+                  <span className="min-w-0 flex-1 truncate">
+                    {row.node.label || '(空分支)'}
+                  </span>
+                  {active && (
+                    <LuCheck className="h-3 w-3 shrink-0 text-emerald-600 dark:text-emerald-400" />
+                  )}
+                </button>
+              );
+            })
+          )}
+        </div>
+
+        {!loading && !isEmpty && (
+          <div className="border-t border-agent-border px-4 py-2 text-[10px] text-agent-muted-foreground/80">
+            {data?.truncated
+              ? '分支过多，树已被截断（仅显示部分节点）。'
+              : '点击切换分支；↑↓ 移动，Enter 切换，Esc 关闭。'}
+          </div>
+        )}
+      </div>
+    </div>,
+    document.body,
+  );
+}
+
+export default SessionTreeModal;

package/src/components/chat/StreamingStatus.tsx

@@ -0,0 +1,95 @@
+import { motion } from 'framer-motion';
+
+/**
+ * StreamingStatus — informative placeholder for an assistant bubble that has
+ * been created but doesn't have content tokens yet (or is between rounds).
+ *
+ * Local-backend's SSE stream gives us these signals while a turn is running:
+ *   • token chunks   (`{content: "..."}`)   — handled by useChatStream
+ *   • round_end      (`completion: executing`) — bumps `round` counter
+ *   • executed_actions — fires after each round's tool calls
+ *   • completion (completed/failed) — stream end
+ *
+ * So the meaningful "thinking" states we can actually display are:
+ *   1. Round 1, no actions yet         → "正在思考..."
+ *   2. Round 1+, just executed tools   → "已调用 N 个工具，正在分析..."
+ *   3. Round ≥ 2, no actions this round → "Round N · 继续推理..."
+ *
+ * If the backend ever starts emitting real reasoning chunks, we can extend
+ * `label` with a streaming text channel and progress dots.
+ */
+interface StreamingStatusProps {
+  /** Current round number (1-based). `executions_actions` per round, framework appends content tokens between rounds. */
+  round: number;
+  /** Number of tool calls executed in this turn so far (across all rounds). */
+  actionCount: number;
+  /**
+   * True when the assistant bubble has at least one content token already.
+   * Pass through from the parent — when content is non-empty we render
+   * nothing (the content + cursor blink is enough).
+   */
+  hasContent: boolean;
+}
+
+export function StreamingStatus({
+  round,
+  actionCount,
+  hasContent,
+}: StreamingStatusProps) {
+  // 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;
+
+  const label = selectLabel(round, actionCount);
+
+  return (
+    <motion.div
+      key={label}
+      initial={{ opacity: 0, y: 2 }}
+      animate={{ opacity: 1, y: 0 }}
+      transition={{ duration: 0.2 }}
+      // aria-live=polite + aria-atomic=true so AT clients (VoiceOver,
+      // NVDA, JAWS) announce the new status text on each transition. We
+      // chose `polite` over `assertive` because the change is informational,
+      // not actionable — `assertive` would barge in on whatever the user is
+      // currently reading.
+      role="status"
+      aria-live="polite"
+      aria-atomic="true"
+      className="my-2 inline-flex items-center gap-2 text-xs text-agent-muted-foreground"
+    >
+      <Dots />
+      <span>{label}</span>
+      {round > 1 && (
+        <span className="rounded-full border border-agent-border bg-agent-muted/40 px-1.5 py-[1px] font-mono text-[10px] text-agent-muted-foreground">
+          round {round}
+        </span>
+      )}
+    </motion.div>
+  );
+}
+
+function selectLabel(round: number, actionCount: number): string {
+  if (round >= 2 && actionCount === 0) {
+    return `Round ${round} · 继续推理...`;
+  }
+  if (actionCount > 0) {
+    return `已调用 ${actionCount} 个工具，正在分析...`;
+  }
+  return '正在思考...';
+}
+
+function Dots() {
+  // Three pulsing dots — matches the inline indicator used inside
+  // AssistantMessage when content === '', so the visual hands off cleanly
+  // once tokens start streaming.
+  return (
+    <span className="inline-flex items-center gap-1">
+      <span className="h-1 w-1 animate-pulse rounded-full bg-agent-foreground/40 [animation-delay:0ms]" />
+      <span className="h-1 w-1 animate-pulse rounded-full bg-agent-foreground/40 [animation-delay:150ms]" />
+      <span className="h-1 w-1 animate-pulse rounded-full bg-agent-foreground/40 [animation-delay:300ms]" />
+    </span>
+  );
+}
+
+export default StreamingStatus;

package/src/components/chat/TaskOutcomeCards.test.tsx

@@ -0,0 +1,97 @@
+/**
+ * TaskOutcomeCards 契约：后台任务的终态要出现在用户正在看的对话里。
+ *   - 完成显示 answer、失败显示 error，任务名都在；
+ *   - 「查看过程」把任务交给右侧推理面板，「忽略」只发出 taskId；
+ *   - worktree 待合并的任务提示去任务按钮处理（卡片不重复那套操作）；
+ *   - 一次结束太多任务时只留前几张，其余折成一行汇总。
+ */
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { LocalTask } from '@/lib/local-api';
+import { TaskOutcomeCards } from './TaskOutcomeCards';
+
+afterEach(cleanup);
+
+function makeTask(overrides: Partial<LocalTask> = {}): LocalTask {
+  return {
+    id: 'task-1',
+    chatId: 'chat_1',
+    task: '统计仓库行数',
+    status: 'completed',
+    answer: '共 42 行。',
+    error: null,
+    worktreePath: null,
+    worktreeBranch: null,
+    worktreeState: null,
+    createdAt: '2026-09-13T01:00:00.000Z',
+    updatedAt: '2026-09-13T01:01:00.000Z',
+    ...overrides,
+  };
+}
+
+function renderCards(tasks: LocalTask[]) {
+  const onInspect = vi.fn();
+  const onDismiss = vi.fn();
+  render(<TaskOutcomeCards tasks={tasks} onInspect={onInspect} onDismiss={onDismiss} />);
+  return { onInspect, onDismiss };
+}
+
+describe('TaskOutcomeCards', () => {
+  it('没有终态任务时什么都不渲染', () => {
+    renderCards([]);
+    expect(screen.queryByTestId('task-outcome-cards')).toBeNull();
+  });
+
+  it('完成的任务显示任务名与结果', () => {
+    renderCards([makeTask()]);
+
+    expect(screen.getByText('统计仓库行数')).toBeTruthy();
+    expect(screen.getByText('共 42 行。')).toBeTruthy();
+    expect(
+      document.querySelector('[data-task-outcome="task-1"]')?.getAttribute('data-status'),
+    ).toBe('completed');
+  });
+
+  it('失败的任务显示错误原因', () => {
+    renderCards([makeTask({ status: 'failed', answer: null, error: '依赖任务失败：abc' })]);
+
+    expect(screen.getByText('依赖任务失败：abc')).toBeTruthy();
+    expect(
+      document.querySelector('[data-task-outcome="task-1"]')?.getAttribute('data-status'),
+    ).toBe('failed');
+  });
+
+  it('「查看过程」交出整个任务，「忽略」交出 taskId', () => {
+    const task = makeTask();
+    const { onInspect, onDismiss } = renderCards([task]);
+
+    fireEvent.click(screen.getByRole('button', { name: '查看过程' }));
+    expect(onInspect).toHaveBeenCalledWith(task);
+
+    fireEvent.click(screen.getByRole('button', { name: '忽略' }));
+    expect(onDismiss).toHaveBeenCalledWith('task-1');
+  });
+
+  it('worktree 待合并时指回任务按钮，卡片自己不放合并操作', () => {
+    renderCards([
+      makeTask({
+        worktreeState: 'pending',
+        worktreePath: '/tmp/wt',
+        worktreeBranch: 'steerable/fix',
+      }),
+    ]);
+
+    expect(screen.getByText('steerable/fix')).toBeTruthy();
+    expect(screen.getByText(/待合并 — 在标题栏的任务按钮里处理/)).toBeTruthy();
+    expect(screen.queryByRole('button', { name: /合并/ })).toBeNull();
+  });
+
+  it('超过三个时只留前三张，其余折成一行汇总', () => {
+    renderCards(
+      Array.from({ length: 5 }, (_, i) => makeTask({ id: `t${i}`, task: `任务 ${i}` })),
+    );
+
+    expect(document.querySelectorAll('[data-task-outcome]')).toHaveLength(3);
+    expect(screen.getByText(/另有 2 个后台任务已结束/)).toBeTruthy();
+  });
+});