@steerable/agent-shell-web 0.6.15

package/src/components/chat/orchestration-children-model.ts

@@ -0,0 +1,104 @@
+import type { OrchestrationTaskStatus } from '@steerable/agent-ui/cards';
+import type { OrchestrationPlanPayload } from '@steerable/agent-protocol';
+
+/**
+ * Pure model half of OrchestrationChildrenCard — no React and no runtime
+ * framework imports (type-only, erased at build), so the desktop's node
+ * vitest suite can exercise the mapping without the agent-ui dist build.
+ *
+ * The sidecar emits `agent.child` lifecycle notifications for orchestration
+ * children AND for `delegate_subagent` delegations (delegate-on-pool); the
+ * router forwards them as `orchestration_child` SSE events and AgentPage
+ * accumulates them into the `ChildInfo` list below.
+ */
+
+export interface ChildInfo {
+  childId: string;
+  /** Spawn task text (only `child_spawned` carries it). */
+  task?: string;
+  depth?: number;
+  /** Resolved subagent profile (delegate children; `general-purpose` when
+   * the delegation named no subagent_type). Rendered as the task's agent. */
+  profile?: string;
+  /** running | completed | failed | cancelled | interrupted */
+  status: string;
+}
+
+const STATUS_MAP: Record<string, OrchestrationTaskStatus> = {
+  running: 'running',
+  completed: 'ok',
+  failed: 'failed',
+  cancelled: 'skipped',
+  // Interrupted = paused-but-resumable; renders as pending (not terminal).
+  interrupted: 'pending',
+};
+
+/**
+ * Pure projection of the live child list onto the card model — the card
+ * itself is click-tested in `@steerable/agent-ui`.
+ */
+export function childrenToCardModel(children: ChildInfo[]): {
+  payload: OrchestrationPlanPayload;
+  taskStatuses: Record<string, OrchestrationTaskStatus>;
+} {
+  return {
+    payload: {
+      mode: 'parallel',
+      tasks: children.map((c) => ({
+        id: c.childId,
+        // 委派子代理显示其 profile 名(如 researcher / general-purpose);
+        // 编排六件套的子代理没有 profile,退回 lineage childId。
+        agentId: c.profile ?? c.childId,
+        prompt: c.task ?? '',
+      })),
+    },
+    taskStatuses: Object.fromEntries(
+      children.map((c) => [c.childId, STATUS_MAP[c.status] ?? 'pending']),
+    ),
+  };
+}
+
+/**
+ * Fold the accumulated raw sidecar `agent.child` lifecycle events (as
+ * forwarded by the backend's `orchestration_child` SSE payload) back into a
+ * `ChildInfo[]`. Used to rebuild the in-flight child list when re-attaching
+ * to a running turn (where the original event stream was consumed by a now
+ * unmounted view).
+ */
+export function foldOrchestrationChildEvents(
+  events: ReadonlyArray<Record<string, unknown>>,
+): ChildInfo[] {
+  const list: ChildInfo[] = [];
+  for (const ev of events) {
+    if (!ev || typeof ev !== 'object') continue;
+    const kind = typeof ev.kind === 'string' ? ev.kind : '';
+    const childId = typeof ev.childId === 'string' ? ev.childId : '';
+    if (!kind || !childId) continue;
+    const idx = list.findIndex((c) => c.childId === childId);
+    if (kind === 'child_spawned') {
+      if (idx >= 0) continue;
+      list.push({
+        childId,
+        task: typeof ev.task === 'string' ? ev.task : undefined,
+        depth: typeof ev.depth === 'number' ? ev.depth : undefined,
+        status: 'running',
+      });
+      continue;
+    }
+    if (idx < 0) continue;
+    const status =
+      kind === 'child_completed'
+        ? 'completed'
+        : kind === 'child_failed'
+          ? 'failed'
+          : kind === 'child_cancelled'
+            ? 'cancelled'
+            : kind === 'child_interrupted'
+              ? 'interrupted'
+              : kind === 'child_resumed'
+                ? 'running'
+                : list[idx].status;
+    list[idx] = { ...list[idx], status };
+  }
+  return list;
+}

package/src/components/chat/timestamp.ts

@@ -0,0 +1,24 @@
+/**
+ * Friendly timestamp formatter shared by `UserMessage` / `AssistantMessage`.
+ * Today → `HH:MM`, other days → `MM-DD HH:MM`.
+ *
+ * Direct port of the helper from
+ * `deeppath/apps/web/src/app/goals/desktop/components/ChatPanel/MessageList/UserMessage.tsx`.
+ */
+export function getFriendlyDate(date: Date): string {
+  const now = new Date();
+  const isToday = now.toDateString() === date.toDateString();
+  if (isToday) {
+    return date.toLocaleTimeString([], {
+      hour: '2-digit',
+      minute: '2-digit',
+    });
+  }
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  const time = date.toLocaleTimeString([], {
+    hour: '2-digit',
+    minute: '2-digit',
+  });
+  return `${month}-${day} ${time}`;
+}

package/src/components/chat/turn-timeline.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from 'vitest';
+import type { ExecutedAction } from './ExecutedActionsCard';
+import {
+  appendDelta,
+  countProcessTools,
+  fallbackTimeline,
+  parseTurnBlocks,
+  processHasReasoning,
+  splitTurnProcess,
+  syncTools,
+} from './turn-timeline';
+
+const tool = (name: string, result?: unknown): ExecutedAction => ({
+  tool: name,
+  arguments: { path: `/${name}` },
+  ...(result === undefined ? {} : { result }),
+});
+
+describe('turn-timeline', () => {
+  it('merges consecutive deltas of the same kind and splits on kind change', () => {
+    let blocks = appendDelta([], 'reasoning', '想');
+    blocks = appendDelta(blocks, 'reasoning', '一下');
+    blocks = appendDelta(blocks, 'text', '先读文件');
+    blocks = appendDelta(blocks, 'text', '。');
+    expect(blocks).toEqual([
+      { type: 'reasoning', content: '想一下' },
+      { type: 'text', content: '先读文件。' },
+    ]);
+  });
+
+  it('places tools after the text that preceded them, then more text', () => {
+    let blocks = appendDelta([], 'text', '开始');
+    blocks = syncTools(blocks, [tool('read')]);
+    blocks = appendDelta(blocks, 'text', '接着写');
+    blocks = syncTools(blocks, [tool('read'), tool('write')]);
+    expect(blocks.map((b) => b.type)).toEqual(['text', 'tools', 'text', 'tools']);
+    expect(blocks[1]).toEqual({ type: 'tools', actions: [tool('read')] });
+    expect(blocks[3]).toEqual({ type: 'tools', actions: [tool('write')] });
+  });
+
+  it('groups consecutive tools and updates in-place results', () => {
+    const running = tool('read');
+    const done = tool('read', { success: true });
+    let blocks = syncTools([], [running]);
+    blocks = syncTools(blocks, [done]);
+    blocks = syncTools(blocks, [done, tool('write')]);
+    expect(blocks).toHaveLength(1);
+    expect(blocks[0]).toEqual({ type: 'tools', actions: [done, tool('write')] });
+  });
+
+  it('ignores empty deltas', () => {
+    expect(appendDelta([], 'text', '')).toEqual([]);
+  });
+
+  it('falls back to tools-then-text for history without a timeline', () => {
+    expect(fallbackTimeline('答', [tool('read', { success: true })])).toEqual([
+      { type: 'tools', actions: [tool('read', { success: true })] },
+      { type: 'text', content: '答' },
+    ]);
+    expect(fallbackTimeline('', undefined)).toEqual([]);
+  });
+
+  it('splits trailing summary text from the think→act process', () => {
+    const blocks = [
+      { type: 'reasoning' as const, content: '想' },
+      { type: 'tools' as const, actions: [tool('read')] },
+      { type: 'text' as const, content: '中间说明' },
+      { type: 'tools' as const, actions: [tool('write')] },
+      { type: 'text' as const, content: '总结' },
+    ];
+    expect(splitTurnProcess(blocks)).toEqual({
+      process: blocks.slice(0, 4),
+      answer: [blocks[4]],
+    });
+    expect(splitTurnProcess([{ type: 'text', content: '只回答' }])).toEqual({
+      process: [],
+      answer: [{ type: 'text', content: '只回答' }],
+    });
+    expect(splitTurnProcess([{ type: 'tools', actions: [tool('read')] }])).toEqual({
+      process: [{ type: 'tools', actions: [tool('read')] }],
+      answer: [],
+    });
+    expect(countProcessTools(blocks.slice(0, 4))).toBe(2);
+    expect(processHasReasoning(blocks.slice(0, 4))).toBe(true);
+  });
+
+  it('parses persisted timeline JSON and rejects unknown kinds', () => {
+    const parsed = parseTurnBlocks([
+      { type: 'reasoning', content: 'hmm' },
+      { type: 'tools', actions: [tool('read')] },
+      { type: 'text', content: 'ok' },
+    ]);
+    expect(parsed).toHaveLength(3);
+    expect(parseTurnBlocks([{ type: 'image' }])).toBeNull();
+    expect(parseTurnBlocks([])).toBeNull();
+  });
+});

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

@@ -0,0 +1,132 @@
+/**
+ * Assistant-turn display timeline: reasoning, tool cards, and reply text
+ * in call order (think → act → observe → reply), not as two stacked
+ * groups.
+ *
+ * Live streams reconstruct this from SSE order. Persisted assistant
+ * metadata may carry the same `timeline` array so history reloads keep
+ * the interleaving. Messages without it fall back to tools-then-text.
+ */
+
+import type { ExecutedAction } from './ExecutedActionsCard';
+
+export type TurnBlock =
+  | { type: 'reasoning'; content: string }
+  | { type: 'text'; content: string }
+  | { type: 'tools'; actions: ExecutedAction[] };
+
+export function appendDelta(
+  blocks: TurnBlock[],
+  type: 'text' | 'reasoning',
+  delta: string,
+): TurnBlock[] {
+  if (!delta) return blocks;
+  const last = blocks[blocks.length - 1];
+  if (last && last.type === type) {
+    const next = blocks.slice();
+    next[next.length - 1] = { type, content: last.content + delta };
+    return next;
+  }
+  return [...blocks, { type, content: delta }];
+}
+
+export function syncTools(
+  blocks: TurnBlock[],
+  actions: ExecutedAction[],
+): TurnBlock[] {
+  let placed = 0;
+  for (const block of blocks) {
+    if (block.type === 'tools') placed += block.actions.length;
+  }
+
+  const next: TurnBlock[] = blocks.map((block) =>
+    block.type === 'tools' ? { type: 'tools', actions: [...block.actions] } : block,
+  );
+
+  let idx = 0;
+  for (const block of next) {
+    if (block.type !== 'tools') continue;
+    for (let i = 0; i < block.actions.length; i += 1) {
+      if (idx < actions.length) {
+        block.actions[i] = actions[idx];
+        idx += 1;
+      }
+    }
+  }
+
+  const added = actions.slice(placed);
+  if (added.length === 0) return next;
+
+  const last = next[next.length - 1];
+  if (last && last.type === 'tools') {
+    next[next.length - 1] = { type: 'tools', actions: [...last.actions, ...added] };
+  } else {
+    next.push({ type: 'tools', actions: added });
+  }
+  return next;
+}
+
+/** Legacy history: all tools, then the concatenated reply. */
+export function fallbackTimeline(
+  content: string,
+  actions: ExecutedAction[] | undefined,
+): TurnBlock[] {
+  const blocks: TurnBlock[] = [];
+  if (actions && actions.length > 0) {
+    blocks.push({ type: 'tools', actions });
+  }
+  if (content) {
+    blocks.push({ type: 'text', content });
+  }
+  return blocks;
+}
+
+export function parseTurnBlocks(raw: unknown): TurnBlock[] | null {
+  if (!Array.isArray(raw) || raw.length === 0) return null;
+  const blocks: TurnBlock[] = [];
+  for (const item of raw) {
+    if (!item || typeof item !== 'object') return null;
+    const rec = item as Record<string, unknown>;
+    if (rec.type === 'text' || rec.type === 'reasoning') {
+      if (typeof rec.content !== 'string') return null;
+      blocks.push({ type: rec.type, content: rec.content });
+      continue;
+    }
+    if (rec.type === 'tools') {
+      if (!Array.isArray(rec.actions)) return null;
+      blocks.push({ type: 'tools', actions: rec.actions as ExecutedAction[] });
+      continue;
+    }
+    return null;
+  }
+  return blocks;
+}
+
+/**
+ * Trailing text is the final summary. Reasoning, tools, and any narration
+ * that happened before that last answer stay in the foldable process group
+ * (Codex / DeepSeek turn-process).
+ */
+export function splitTurnProcess(blocks: TurnBlock[]): {
+  process: TurnBlock[];
+  answer: Extract<TurnBlock, { type: 'text' }>[];
+} {
+  let split = blocks.length;
+  while (split > 0 && blocks[split - 1].type === 'text') split -= 1;
+  return {
+    process: blocks.slice(0, split),
+    answer: blocks.slice(split) as Extract<TurnBlock, { type: 'text' }>[],
+  };
+}
+
+export function countProcessTools(process: TurnBlock[]): number {
+  let n = 0;
+  for (const block of process) {
+    if (block.type === 'tools') n += block.actions.length;
+  }
+  return n;
+}
+
+export function processHasReasoning(process: TurnBlock[]): boolean {
+  return process.some((block) => block.type === 'reasoning' && block.content.trim().length > 0);
+}

package/src/components/chat/useChatTasks.test.ts

@@ -0,0 +1,136 @@
+/**
+ * useChatTasks 契约：
+ *   - 拉 GET /chats/:id/tasks，`task-updated` 推送后重拉；
+ *   - `finished` 只收本次挂载期间跑到终态的任务——首屏已经终态的历史任务
+ *     不算「刚跑完」，否则每次打开对话都会重弹一遍；
+ *   - 两次刷新之间从建到完的任务算刚跑完（用户同样没看见它运行过）；
+ *   - `dismissFinished` 只隐藏通知，不影响 `tasks` 与 `summary`。
+ */
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { LocalTask } from '@/lib/local-api';
+import { useChatTasks } from './useChatTasks';
+
+afterEach(() => {
+  delete (window as { electron?: unknown }).electron;
+});
+
+function makeTask(overrides: Partial<LocalTask> = {}): LocalTask {
+  return {
+    id: 'task-1',
+    chatId: 'chat_1',
+    task: '跑测试',
+    status: 'running',
+    answer: null,
+    error: null,
+    worktreePath: null,
+    worktreeBranch: null,
+    worktreeState: null,
+    createdAt: '2026-09-13T01:00:00.000Z',
+    updatedAt: '2026-09-13T01:01:00.000Z',
+    ...overrides,
+  };
+}
+
+function installBridge(initial: LocalTask[]) {
+  let current = initial;
+  const listeners: Array<(p: { chatId: string; taskId: string; status: string }) => void> = [];
+  (window as { electron?: unknown }).electron = {
+    localBackend: {
+      request: vi.fn((input: { method: string; path: string }) => {
+        if (input.method === 'GET' && input.path.endsWith('/tasks')) {
+          return Promise.resolve({ tasks: current });
+        }
+        return Promise.reject(new Error(`unexpected request: ${input.path}`));
+      }),
+    },
+    onTaskUpdated: (cb: (p: { chatId: string; taskId: string; status: string }) => void) => {
+      listeners.push(cb);
+      return () => listeners.splice(listeners.indexOf(cb), 1);
+    },
+  };
+  return {
+    async push(next: LocalTask[]) {
+      current = next;
+      await act(async () => {
+        for (const cb of listeners) cb({ chatId: 'chat_1', taskId: 'task-1', status: 'x' });
+      });
+    },
+  };
+}
+
+describe('useChatTasks', () => {
+  it('首屏已终态的历史任务不算刚跑完', async () => {
+    installBridge([makeTask({ id: 'a', status: 'completed' })]);
+    const { result } = renderHook(() => useChatTasks('chat_1'));
+
+    await waitFor(() => expect(result.current.tasks).toHaveLength(1));
+    expect(result.current.finished).toEqual([]);
+    expect(result.current.summary.total).toBe(1);
+  });
+
+  it('运行中的任务跑到终态时进 finished', async () => {
+    const bridge = installBridge([makeTask({ id: 'a', status: 'running' })]);
+    const { result } = renderHook(() => useChatTasks('chat_1'));
+
+    await waitFor(() => expect(result.current.tasks).toHaveLength(1));
+    expect(result.current.finished).toEqual([]);
+
+    const done = makeTask({ id: 'a', status: 'completed', answer: '42 行' });
+    await bridge.push([done]);
+
+    await waitFor(() => expect(result.current.finished).toEqual([done]));
+  });
+
+  it('两次刷新之间从建到完的任务也算刚跑完', async () => {
+    const bridge = installBridge([]);
+    const { result } = renderHook(() => useChatTasks('chat_1'));
+
+    await waitFor(() => expect(result.current.tasks).toEqual([]));
+
+    const flash = makeTask({ id: 'a', status: 'failed', error: '炸了' });
+    await bridge.push([flash]);
+
+    await waitFor(() => expect(result.current.finished).toEqual([flash]));
+  });
+
+  it('同一个终态不会重复进 finished', async () => {
+    const bridge = installBridge([makeTask({ id: 'a', status: 'running' })]);
+    const { result } = renderHook(() => useChatTasks('chat_1'));
+
+    await waitFor(() => expect(result.current.tasks).toHaveLength(1));
+
+    const done = makeTask({ id: 'a', status: 'completed' });
+    await bridge.push([done]);
+    await waitFor(() => expect(result.current.finished).toHaveLength(1));
+
+    await bridge.push([done]);
+    expect(result.current.finished).toHaveLength(1);
+  });
+
+  it('dismissFinished 只隐藏通知，任务本身还在', async () => {
+    const bridge = installBridge([makeTask({ id: 'a', status: 'running' })]);
+    const { result } = renderHook(() => useChatTasks('chat_1'));
+
+    await waitFor(() => expect(result.current.tasks).toHaveLength(1));
+    await bridge.push([makeTask({ id: 'a', status: 'failed', error: '炸了' })]);
+    await waitFor(() => expect(result.current.finished).toHaveLength(1));
+
+    act(() => result.current.dismissFinished('a'));
+
+    expect(result.current.finished).toEqual([]);
+    expect(result.current.tasks).toHaveLength(1);
+    expect(result.current.summary.failed).toBe(1);
+  });
+
+  it('任务表读不到时按「没有任务」处理', async () => {
+    (window as { electron?: unknown }).electron = {
+      localBackend: { request: vi.fn(() => Promise.reject(new Error('sidecar 离线'))) },
+      onTaskUpdated: () => () => {},
+    };
+    const { result } = renderHook(() => useChatTasks('chat_1'));
+
+    await waitFor(() => expect(result.current.summary.total).toBe(0));
+    expect(result.current.finished).toEqual([]);
+  });
+});

package/src/components/chat/useChatTasks.ts

@@ -0,0 +1,134 @@
+/**
+ * `useChatTasks` — 本对话后台任务的单一订阅源（host SQLite 任务表 + 主进程
+ * `task-updated` 广播）。header 角标、任务弹层的直达入口和消息列尾部的终态
+ * 卡都读它，三者因此永远看到同一份列表、同一个瞬间。
+ *
+ * `finished` 只收本次挂载期间跑到终态的任务：终态卡是「刚刚发生了什么」的
+ * 通知，重开会话后由角标承担持久状态——否则几天前跑完的任务会在每次打开
+ * 对话时重新弹一遍。首次加载只播种 `seenRef`，不产出通知。
+ */
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { listChatTasks, type LocalTask } from '@/lib/local-api';
+import { getElectronBridge, isElectron } from '@/lib/electron-bridge';
+
+export interface ChatTaskSummary {
+  total: number;
+  running: number;
+  /** 等依赖任务完成后自动点火。 */
+  blocked: number;
+  /** 跑完的 worktree 任务，等用户合并或丢弃——唯一需要用户动手的状态。 */
+  needsReview: number;
+  failed: number;
+}
+
+export interface ChatTasksState {
+  tasks: LocalTask[];
+  summary: ChatTaskSummary;
+  /** 本次挂载期间跑完、用户还没忽略的任务（新→旧）。 */
+  finished: LocalTask[];
+  /** 忽略一条终态通知。仅本次挂载生效，不写库。 */
+  dismissFinished: (taskId: string) => void;
+}
+
+/** 空数组用同一个引用，重置时 setState 才能在值没变时跳过重渲染。 */
+const NO_TASKS: LocalTask[] = [];
+const NO_IDS: string[] = [];
+
+function isTerminal(status: LocalTask['status']): boolean {
+  return status === 'completed' || status === 'failed';
+}
+
+export function summarizeTasks(tasks: LocalTask[]): ChatTaskSummary {
+  return {
+    total: tasks.length,
+    running: tasks.filter((t) => t.status === 'running').length,
+    blocked: tasks.filter((t) => t.status === 'blocked').length,
+    needsReview: tasks.filter(
+      (t) => t.status === 'completed' && t.worktreeState === 'pending',
+    ).length,
+    failed: tasks.filter((t) => t.status === 'failed').length,
+  };
+}
+
+/** 等用户处理的任务：worktree 待合并（要动手）或失败（要知道原因）。 */
+export function actionableTasks(tasks: LocalTask[]): LocalTask[] {
+  return tasks.filter(
+    (t) =>
+      (t.status === 'completed' && t.worktreeState === 'pending') ||
+      t.status === 'failed',
+  );
+}
+
+export function useChatTasks(chatId: string | null): ChatTasksState {
+  const [tasks, setTasks] = useState<LocalTask[]>(NO_TASKS);
+  const [finishedIds, setFinishedIds] = useState<string[]>(NO_IDS);
+  const [dismissedIds, setDismissedIds] = useState<string[]>(NO_IDS);
+  /** 上一次见到的每个任务的状态；null = 还没播种。 */
+  const seenRef = useRef<Map<string, LocalTask['status']> | null>(null);
+
+  const refresh = useCallback(async () => {
+    if (!chatId || !isElectron()) {
+      setTasks(NO_TASKS);
+      return;
+    }
+    let next: LocalTask[];
+    try {
+      next = (await listChatTasks(chatId)).tasks;
+    } catch {
+      // 任务表读不到（sidecar 离线 / 对话刚删）——按「没有任务」处理。
+      setTasks(NO_TASKS);
+      return;
+    }
+    const seen = seenRef.current;
+    seenRef.current = new Map(next.map((t) => [t.id, t.status]));
+    setTasks(next);
+    if (!seen) return;
+    // 首次见到就已是终态的任务也算刚跑完：它在两次刷新之间从建到完，
+    // 用户同样没看见过它运行。
+    const justFinished = next
+      .filter((t) => isTerminal(t.status) && seen.get(t.id) !== t.status)
+      .map((t) => t.id);
+    if (justFinished.length === 0) return;
+    setFinishedIds((prev) => [
+      ...justFinished.filter((id) => !prev.includes(id)),
+      ...prev,
+    ]);
+  }, [chatId]);
+
+  useEffect(() => {
+    seenRef.current = null;
+    setFinishedIds(NO_IDS);
+    setDismissedIds(NO_IDS);
+    void refresh();
+  }, [refresh]);
+
+  useEffect(() => {
+    if (!chatId) return;
+    const bridge = getElectronBridge();
+    if (!bridge?.onTaskUpdated) return;
+    return bridge.onTaskUpdated((payload) => {
+      if (payload.chatId === chatId) void refresh();
+    });
+  }, [chatId, refresh]);
+
+  const dismissFinished = useCallback((taskId: string) => {
+    setDismissedIds((prev) =>
+      prev.includes(taskId) ? prev : [...prev, taskId],
+    );
+  }, []);
+
+  const summary = useMemo(() => summarizeTasks(tasks), [tasks]);
+  const finished = useMemo(
+    () =>
+      finishedIds
+        .filter((id) => !dismissedIds.includes(id))
+        .map((id) => tasks.find((t) => t.id === id))
+        .filter((t): t is LocalTask => t !== undefined),
+    [finishedIds, dismissedIds, tasks],
+  );
+
+  return { tasks, summary, finished, dismissFinished };
+}
+
+export default useChatTasks;

package/src/components/chat/useCopy.ts

@@ -0,0 +1,62 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+/**
+ * `useCopy(text)` — copy-button helper for message bubbles.
+ *
+ * Returns `{ copied, copy }`. `copy()` writes `text` to clipboard and flips
+ * `copied` to true for `resetMs` milliseconds, then back to false so the
+ * button can revert to its idle icon.
+ *
+ * Why not just inline this in each component:
+ *   - UserMessage + AssistantMessage + (eventually) tool-result cards all
+ *     need the same "copied / not copied" state machine + clipboard
+ *     fallback. Factoring keeps the timer-clearing logic in one place.
+ *   - `navigator.clipboard.writeText` rejects on insecure origins or
+ *     unsupported browsers (older Electron); we fall back to a hidden
+ *     textarea + `document.execCommand('copy')` so the chat stays
+ *     interactive even when permissions are odd.
+ */
+export interface UseCopyResult {
+  /** True for `resetMs` after a successful copy. */
+  copied: boolean;
+  /** Trigger a clipboard write. Idempotent if `copied` is already true. */
+  copy: () => Promise<void>;
+}
+
+export function useCopy(text: string, resetMs = 1500): UseCopyResult {
+  const [copied, setCopied] = useState(false);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const copy = useCallback(async () => {
+    if (!text) return;
+    try {
+      if (navigator.clipboard?.writeText) {
+        await navigator.clipboard.writeText(text);
+      } else {
+        // Fallback for older Electron / non-secure contexts.
+        const ta = document.createElement('textarea');
+        ta.value = text;
+        ta.style.position = 'fixed';
+        ta.style.opacity = '0';
+        document.body.appendChild(ta);
+        ta.select();
+        document.execCommand('copy');
+        document.body.removeChild(ta);
+      }
+      setCopied(true);
+      if (timerRef.current) clearTimeout(timerRef.current);
+      timerRef.current = setTimeout(() => setCopied(false), resetMs);
+    } catch {
+      // Swallow; user can still highlight + ⌘C the bubble manually.
+    }
+  }, [text, resetMs]);
+
+  useEffect(
+    () => () => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+    },
+    [],
+  );
+
+  return { copied, copy };
+}