canopy-ui 0.3.0 → 0.6.0

package/src/chat/SendBox.tsx

@@ -0,0 +1,306 @@
+import {
+  useEffect,
+  useRef,
+  useState,
+  type KeyboardEvent,
+  type ReactNode,
+} from "react";
+import type React from "react";
+
+import type { Draft } from "./protocol";
+import { isDraftIdle, msUntilDraftIdle } from "./drafts";
+import { Button } from "../ui/button";
+
+/** An attachment the composer is holding, uploaded but not yet sent. */
+export interface PendingAttachment {
+  id: string;
+  filename: string;
+  /** Set while the upload is still in flight — the chip renders as busy and
+   *  cannot be removed yet, because there is no id on the server to remove. */
+  uploading?: boolean;
+  /** Upload failed; the chip explains why and is dismissible. */
+  error?: string;
+}
+
+interface Props {
+  draft: Draft | null;
+  /** Live socket. Typing never depends on this; SENDING does — see canSend. */
+  connected: boolean;
+  currentUserId: number;
+  holderIsPresent: boolean;
+  isStreaming: boolean;
+  streamingMessageId: string | null;
+  onUpdate: (body: string) => void;
+  onSend: () => void;
+  /** messageId is null when the turn is still QUEUED — no reply exists yet.
+   *  The server cancels every non-terminal turn regardless, so a null id is
+   *  a valid cancel, not a no-op. */
+  onStop: (messageId: string | null) => void;
+  onTakeOver: () => void;
+  /** Optional app-supplied banner rendered above the composer (e.g. an
+   *  imported-session note). The kit itself has no CLI-auth banners. */
+  banner?: ReactNode;
+  /** When set, sending is disabled and this reason is shown as a hint. */
+  disabledReason?: string;
+  /** Files staged for the next send. Omit to hide attaching entirely — the kit
+   *  stays usable by hosts that have no upload endpoint. */
+  attachments?: PendingAttachment[];
+  /** Hand off chosen files. The host owns the upload (the kit knows no REST
+   *  paths); it re-renders `attachments` as they progress. */
+  onAttach?: (files: File[]) => void;
+  onRemoveAttachment?: (id: string) => void;
+}
+
+export function SendBox({
+  draft,
+  connected,
+  currentUserId,
+  holderIsPresent,
+  isStreaming,
+  streamingMessageId,
+  onUpdate,
+  onSend,
+  onStop,
+  onTakeOver,
+  banner,
+  disabledReason,
+  attachments,
+  onAttach,
+  onRemoveAttachment,
+}: Props) {
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
+  // Force a re-render when the lock transitions from live to idle.
+  // Without this, nothing would trigger a re-render exactly at T+2s
+  // after the last edit, and another user's UI would stay locked
+  // indefinitely until some unrelated event happens to arrive.
+  const [, forceTick] = useState(0);
+
+  useEffect(() => {
+    if (!draft) return;
+    const remaining = msUntilDraftIdle(draft);
+    if (remaining === 0) return;
+    const t = window.setTimeout(() => forceTick((n) => n + 1), remaining + 10);
+    return () => window.clearTimeout(t);
+  }, [draft?.last_edit_at, draft]);
+
+  const holderId = draft?.last_editor ?? null;
+  const isHolder = holderId != null && holderId === currentUserId;
+  const holderIsIdle = isDraftIdle(draft);
+
+  // LOCAL-FIRST: the textarea's value is local state, never server state.
+  // Rendering `draft.body` directly made every inbound frame a chance to
+  // overwrite the user mid-keystroke — a stale echo of your own debounced
+  // update, or a `session.state` snapshot on reconnect (which replaces state
+  // wholesale), would rewind the composer to a body from 150ms ago. In
+  // single-player that reconciliation protects against nothing at all, since
+  // there is no co-editor whose edits could be lost.
+  const [localBody, setLocalBody] = useState(draft?.body ?? "");
+
+  // The ONE case where the server genuinely knows better than this client:
+  // somebody ELSE edited the shared draft. Our own echo is ignored, which is
+  // also what stops two clients on one account (phone + desktop) from
+  // fighting — each keeps its own text instead of clobbering the other.
+  const theirEdit =
+    draft != null && draft.last_editor !== currentUserId ? draft.body : null;
+  useEffect(() => {
+    if (theirEdit != null) setLocalBody(theirEdit);
+  }, [theirEdit]);
+
+  // Typing is ALWAYS allowed unless a teammate is actively holding the draft.
+  // It used to require `draft != null`, so the composer was disabled until
+  // session.state landed — locking you out of your own input on first paint
+  // and again on every reconnect. Keystrokes typed early are held locally and
+  // flushed when the draft exists (see useSessionSocket.sendChat).
+  const canEdit = isHolder || holderIsIdle || !holderIsPresent;
+
+  useEffect(() => {
+    if (canEdit && !isHolder && textareaRef.current) {
+      textareaRef.current.focus();
+    }
+  }, [canEdit, isHolder]);
+
+  const body = localBody;
+  const blocked = Boolean(disabledReason);
+  // Sending needs a draft (`chat.send` commits the SERVER's copy, so there must
+  // be one) AND a live socket. The socket check is load-bearing now that the
+  // composer clears optimistically: `send()` drops every frame but chat.stop
+  // when the socket is closed, so an allowed-but-undeliverable send would clear
+  // the box and lose the message outright.
+  const canSend =
+    canEdit &&
+    connected &&
+    draft != null &&
+    body.trim().length > 0 &&
+    !isStreaming &&
+    !blocked;
+
+  const handleChange = (value: string) => {
+    setLocalBody(value);
+    onUpdate(value);
+  };
+
+  const canAttach = typeof onAttach === "function" && canEdit && !blocked;
+  const fileInputRef = useRef<HTMLInputElement>(null);
+  const [dragging, setDragging] = useState(false);
+
+  const take = (files: FileList | null | undefined) => {
+    if (!canAttach || !files || files.length === 0) return;
+    onAttach!(Array.from(files));
+  };
+
+  // Paste is the point on desktop: a screenshot goes to the clipboard, and
+  // making people save it to disk first is most of the friction.
+  const handlePaste = (e: React.ClipboardEvent<HTMLTextAreaElement>) => {
+    if (!canAttach) return;
+    const files = Array.from(e.clipboardData?.files ?? []);
+    if (files.length === 0) return;
+    e.preventDefault();  // else the filename lands in the textarea as text
+    onAttach!(files);
+  };
+
+  const handleSend = () => {
+    // Clear locally rather than waiting for the server's cleared draft to
+    // echo back: that echo carries last_editor === us, which the adopt rule
+    // above (correctly) ignores, so nothing else would empty the box.
+    setLocalBody("");
+    onSend();
+  };
+
+  const handleKey = (e: KeyboardEvent<HTMLTextAreaElement>) => {
+    // `isComposing` is true during IME input (CJK, etc.). Pressing
+    // Enter to commit a composition must not send the message.
+    const isComposing = (e.nativeEvent as unknown as { isComposing?: boolean })
+      .isComposing;
+    if (e.key === "Enter" && !e.shiftKey && !isComposing) {
+      e.preventDefault();
+      if (canSend) handleSend();
+    }
+  };
+
+  const handleStopClick = () => {
+    // Fires even with no streamingMessageId: while a turn sits QUEUED there is
+    // no assistant message to name, and that is exactly when you want out.
+    onStop(streamingMessageId);
+  };
+
+  const placeholder = blocked
+    ? disabledReason
+    : !canEdit
+      ? "Another teammate is editing…"
+      : !draft
+        ? "Type a message… (connecting…)"
+        : "Type a message… (Enter to send, Shift+Enter for newline)";
+
+  const staged = attachments ?? [];
+
+  return (
+    <div
+      className="border-t border-border bg-background"
+      onDragOver={(e) => {
+        if (!canAttach) return;
+        e.preventDefault();
+        setDragging(true);
+      }}
+      onDragLeave={() => setDragging(false)}
+      onDrop={(e) => {
+        if (!canAttach) return;
+        e.preventDefault();
+        setDragging(false);
+        take(e.dataTransfer?.files);
+      }}
+    >
+      {banner}
+      <div className={`p-2 ${dragging ? "bg-primary/5 ring-1 ring-inset ring-primary/40" : ""}`}>
+        {staged.length > 0 && (
+          <ul className="mb-1.5 flex flex-wrap gap-1.5" data-testid="attachment-chips">
+            {staged.map((a) => (
+              <li
+                key={a.id}
+                className={`flex items-center gap-1.5 rounded-md border px-2 py-1 text-xs ${
+                  a.error
+                    ? "border-destructive/40 bg-destructive/10 text-destructive"
+                    : "border-border bg-muted text-foreground-secondary"
+                }`}
+              >
+                <span className="max-w-[14rem] truncate">{a.filename}</span>
+                {a.uploading && <span className="text-muted-foreground">uploading…</span>}
+                {a.error && <span title={a.error}>· {a.error}</span>}
+                {!a.uploading && onRemoveAttachment && (
+                  <button
+                    type="button"
+                    aria-label={`Remove ${a.filename}`}
+                    onClick={() => onRemoveAttachment(a.id)}
+                    className="text-muted-foreground hover:text-foreground"
+                  >
+                    ×
+                  </button>
+                )}
+              </li>
+            ))}
+          </ul>
+        )}
+        <textarea
+          ref={textareaRef}
+          value={body}
+          disabled={!canEdit || blocked}
+          onChange={(e) => handleChange(e.target.value)}
+          onKeyDown={handleKey}
+          onPaste={handlePaste}
+          placeholder={placeholder}
+          rows={3}
+          className="w-full resize-none rounded-md border border-input bg-transparent p-2 text-sm text-foreground shadow-sm placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:bg-muted disabled:text-muted-foreground"
+        />
+        <div className="mt-1 flex items-center justify-end gap-2">
+          {canAttach && (
+            <>
+              <input
+                ref={fileInputRef}
+                type="file"
+                multiple
+                accept="image/*"
+                className="hidden"
+                data-testid="attachment-input"
+                onChange={(e) => {
+                  take(e.target.files);
+                  e.target.value = "";  // same file twice in a row must re-fire
+                }}
+              />
+              <Button
+                type="button"
+                variant="outline"
+                size="sm"
+                className="mr-auto"
+                onClick={() => fileInputRef.current?.click()}
+              >
+                attach
+              </Button>
+            </>
+          )}
+          {blocked && (
+            <span className="mr-auto text-xs text-muted-foreground">
+              {disabledReason}
+            </span>
+          )}
+          {isStreaming ? (
+            <Button
+              type="button"
+              variant="destructive"
+              size="sm"
+              onClick={handleStopClick}
+            >
+              stop
+            </Button>
+          ) : null}
+          {!canEdit && holderIsPresent && !holderIsIdle ? (
+            <Button type="button" variant="outline" size="sm" onClick={onTakeOver}>
+              take over
+            </Button>
+          ) : null}
+          <Button type="button" size="sm" disabled={!canSend} onClick={handleSend}>
+            send
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/chat/ToolCallPair.tsx

@@ -0,0 +1,86 @@
+import { Check, ChevronRight, Loader2, X } from "lucide-react";
+
+import type { Message } from "./protocol";
+import { deriveToolStatus, toolDisplayName, toolPreview } from "./pairToolMessages";
+
+interface Props {
+  use: Message;
+  result: Message | null;
+  /** Controlled-open state: true to force open, false to force closed,
+   *  undefined to let the user control via the native <details> toggle. */
+  forceOpen?: boolean;
+}
+
+/**
+ * Renders a tool_use + tool_result as a single collapsible row.
+ *
+ * Header line: ``{status icon} {tool name} · {preview}`` — readable when
+ * collapsed so the user can scan a long stream of tool calls without
+ * expanding any. Expanded view stacks the input JSON on top of the
+ * result body, both monospace.
+ */
+export function ToolCallPair({ use, result, forceOpen }: Props) {
+  const status = deriveToolStatus(use, result);
+  const name = toolDisplayName(use);
+  const preview = toolPreview(use, result);
+
+  const StatusIcon =
+    status.kind === "success" ? Check : status.kind === "error" ? X : Loader2;
+  const iconColor =
+    status.kind === "success"
+      ? "text-success"
+      : status.kind === "error"
+        ? "text-destructive"
+        : "text-muted-foreground animate-spin";
+
+  const input = (use.content as { input?: unknown } | undefined)?.input;
+
+  return (
+    <details
+      // ``open`` controls the row when forceOpen is set; otherwise
+      // ``open={undefined}`` lets the native toggle take over so single
+      // rows still expand/collapse on click.
+      open={forceOpen}
+      className="group my-1 rounded border border-border bg-muted/40 text-sm"
+    >
+      <summary className="flex cursor-pointer items-center gap-2 px-2 py-1.5 text-muted-foreground hover:bg-muted/60 select-none [&::-webkit-details-marker]:hidden">
+        <ChevronRight className="h-3 w-3 shrink-0 transition-transform group-open:rotate-90" />
+        <StatusIcon className={`h-3.5 w-3.5 shrink-0 ${iconColor}`} />
+        <span className="font-mono text-xs font-medium text-foreground">
+          {name}
+        </span>
+        {preview && (
+          <span className="truncate text-xs italic text-muted-foreground">
+            · {preview}
+          </span>
+        )}
+      </summary>
+      <div className="space-y-2 border-t border-border/60 p-2">
+        {input !== undefined && (
+          <div>
+            <div className="mb-1 text-[10px] uppercase tracking-wider text-muted-foreground">
+              input
+            </div>
+            <pre className="overflow-x-auto whitespace-pre-wrap break-all rounded bg-background p-2 text-xs">
+              {JSON.stringify(input, null, 2)}
+            </pre>
+          </div>
+        )}
+        <div>
+          <div className="mb-1 text-[10px] uppercase tracking-wider text-muted-foreground">
+            result
+          </div>
+          {result === null ? (
+            <div className="text-xs italic text-muted-foreground">
+              (running…)
+            </div>
+          ) : (
+            <pre className="overflow-x-auto whitespace-pre-wrap break-all rounded bg-background p-2 text-xs">
+              {result.plaintext}
+            </pre>
+          )}
+        </div>
+      </div>
+    </details>
+  );
+}

package/src/chat/drafts.test.ts

@@ -0,0 +1,90 @@
+import { afterEach, describe, expect, it, vi } from "vitest"
+
+import type { Draft } from "./protocol"
+import {
+  IDLE_THRESHOLD_MS,
+  isDraftIdle,
+  msUntilDraftIdle,
+  shouldSyncDraftLive,
+} from "./drafts"
+
+const NOW = 1_700_000_000_000
+
+function draftEditedAt(msAgo: number): Draft {
+  return {
+    id: "d1",
+    slot: "next",
+    status: "open",
+    body: "",
+    version: 0,
+    last_editor: 1,
+    last_edit_at: new Date(NOW - msAgo).toISOString(),
+  }
+}
+
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+describe("isDraftIdle", () => {
+  it("treats a null/undefined draft as idle", () => {
+    expect(isDraftIdle(null)).toBe(true)
+    expect(isDraftIdle(undefined)).toBe(true)
+  })
+
+  it("treats a draft with no last_edit_at as idle", () => {
+    const d = { ...draftEditedAt(0), last_edit_at: "" }
+    expect(isDraftIdle(d)).toBe(true)
+  })
+
+  it("is NOT idle immediately after an edit", () => {
+    vi.useFakeTimers()
+    vi.setSystemTime(NOW)
+    // edited 500ms ago — well within the 2s threshold
+    expect(isDraftIdle(draftEditedAt(500))).toBe(false)
+  })
+
+  it("IS idle once more than the threshold has elapsed", () => {
+    vi.useFakeTimers()
+    vi.setSystemTime(NOW)
+    expect(isDraftIdle(draftEditedAt(IDLE_THRESHOLD_MS + 1))).toBe(true)
+  })
+})
+
+describe("msUntilDraftIdle", () => {
+  it("returns 0 for a null draft", () => {
+    expect(msUntilDraftIdle(null)).toBe(0)
+  })
+
+  it("returns the remaining time before the idle transition", () => {
+    vi.useFakeTimers()
+    vi.setSystemTime(NOW)
+    // edited 500ms ago → 1500ms remain
+    expect(msUntilDraftIdle(draftEditedAt(500))).toBe(1500)
+  })
+
+  it("clamps to 0 once past the threshold", () => {
+    vi.useFakeTimers()
+    vi.setSystemTime(NOW)
+    expect(msUntilDraftIdle(draftEditedAt(IDLE_THRESHOLD_MS + 5000))).toBe(0)
+  })
+})
+
+describe("shouldSyncDraftLive", () => {
+  it("does not mirror keystrokes when you are alone", () => {
+    // The single-player case: a per-keystroke draft.update costs a round trip,
+    // an echo that can rewind the textarea, and a version to disagree about —
+    // and protects no co-editor, because there isn't one.
+    expect(shouldSyncDraftLive([1])).toBe(false)
+  })
+
+  it("treats an empty presence set as alone", () => {
+    // Pre-connect: presence has not landed yet, which is precisely when there
+    // is nobody to sync with.
+    expect(shouldSyncDraftLive([])).toBe(false)
+  })
+
+  it("mirrors keystrokes once somebody else is present", () => {
+    expect(shouldSyncDraftLive([1, 2])).toBe(true)
+  })
+})

package/src/chat/drafts.ts

@@ -0,0 +1,37 @@
+import type { Draft } from "./protocol";
+
+export const IDLE_THRESHOLD_MS = 2_000;
+
+export function isDraftIdle(draft: Draft | null | undefined): boolean {
+  if (!draft?.last_edit_at) return true;
+  return Date.now() - new Date(draft.last_edit_at).getTime() > IDLE_THRESHOLD_MS;
+}
+
+/**
+ * Whether keystrokes need to be mirrored to the server AS YOU TYPE.
+ *
+ * The co-edited draft only earns its cost when somebody else is looking at it.
+ * Alone in a session — the overwhelmingly common case — a per-keystroke
+ * `draft.update` buys nothing and costs a round trip, a re-render on the echo,
+ * and a version to disagree about. The body still reaches the server once,
+ * right before `chat.send` (which commits the SERVER's copy), so sending is
+ * unaffected; see useSessionSocket.sendChat.
+ *
+ * Presence includes yourself, so "alone" is a set of 0 or 1. An empty set means
+ * presence has not arrived yet — treated as alone, since the pre-connect window
+ * is exactly when there is no one to sync with.
+ */
+export function shouldSyncDraftLive(presenceUserIds: readonly number[]): boolean {
+  return presenceUserIds.length > 1;
+}
+
+/**
+ * Milliseconds until the draft lock becomes idle. Returns 0 if already
+ * idle. Use this to schedule a timer that forces a re-render at the
+ * idle transition point.
+ */
+export function msUntilDraftIdle(draft: Draft | null | undefined): number {
+  if (!draft?.last_edit_at) return 0;
+  const elapsed = Date.now() - new Date(draft.last_edit_at).getTime();
+  return Math.max(0, IDLE_THRESHOLD_MS - elapsed);
+}

package/src/chat/groupToolRuns.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from "vitest"
+
+import { MIN_RUN_TO_GROUP, groupToolRuns, runHasError, runIsActive, summariseRun } from "./groupToolRuns"
+import type { ChatRow } from "./pairToolMessages"
+import type { Message } from "./protocol"
+
+function msg(over: Partial<Message> = {}): Message {
+  return {
+    id: "m", turn_index: 0, role: "tool_use", content: {}, plaintext: "",
+    status: "complete", error_detail: null, started_at: null, completed_at: null,
+    created_at: "", ...over,
+  }
+}
+
+const pair = (i: number, name = "Bash", result?: Partial<Message>): ChatRow => ({
+  kind: "tool_pair",
+  use: msg({ id: `u${i}`, content: { id: `t${i}`, name } }),
+  result: result ? msg({ id: `r${i}`, role: "tool_result", ...result }) : msg({ id: `r${i}`, role: "tool_result" }),
+  key: `pair-${i}`,
+})
+
+const prose = (i: number): ChatRow => ({
+  kind: "message",
+  message: msg({ id: `p${i}`, role: "assistant", plaintext: "words" }),
+  key: `msg-${i}`,
+})
+
+describe("groupToolRuns", () => {
+  it("collapses a run of consecutive tool calls into one row", () => {
+    const out = groupToolRuns([pair(1), pair(2), pair(3), pair(4)])
+    expect(out).toHaveLength(1)
+    expect(out[0].kind).toBe("tool_run")
+  })
+
+  it("prose breaks a run, so the conversation stays legible", () => {
+    // The whole point: an agent's own words must never be buried inside a
+    // collapsed group of the calls that surrounded them.
+    const out = groupToolRuns([pair(1), pair(2), pair(3), prose(1), pair(4), pair(5), pair(6)])
+    expect(out.map((r) => r.kind)).toEqual(["tool_run", "message", "tool_run"])
+  })
+
+  it("leaves short runs alone", () => {
+    // Wrapping one or two calls costs a click and hides nothing.
+    const out = groupToolRuns([pair(1), pair(2)])
+    expect(out.map((r) => r.kind)).toEqual(["tool_pair", "tool_pair"])
+    expect(MIN_RUN_TO_GROUP).toBe(3)
+  })
+
+  it("keeps every call, in order, inside the group", () => {
+    const out = groupToolRuns([pair(1), pair(2), pair(3)])
+    const run = out[0] as { rows: ChatRow[] }
+    expect(run.rows.map((r) => r.key)).toEqual(["pair-1", "pair-2", "pair-3"])
+  })
+
+  it("summarises a run by count and the tools it used", () => {
+    expect(summariseRun([pair(1, "Bash"), pair(2, "Read"), pair(3, "Bash")]))
+      .toBe("3 tool calls · Bash, Read")
+  })
+
+  it("flags a run containing a failure", () => {
+    // A collapsed group must not hide the one thing worth stopping for.
+    expect(runHasError([pair(1), pair(2)])).toBe(false)
+    expect(runHasError([pair(1), pair(2, "Bash", { status: "error" })])).toBe(true)
+    expect(runHasError([pair(1, "Bash", { content: { is_error: true } })])).toBe(true)
+  })
+
+  it("a session of only prose is untouched", () => {
+    const out = groupToolRuns([prose(1), prose(2)])
+    expect(out.map((r) => r.kind)).toEqual(["message", "message"])
+  })
+})
+
+describe("runIsActive", () => {
+  it("a run with a call still in flight reports active", () => {
+    // Collapsed, an agent mid-task would otherwise look idle — which is the
+    // exact question "is this session working?" asks.
+    const pending: ChatRow = { kind: "tool_pair", use: msg({ id: "u9" }), result: null, key: "pair-9" }
+    expect(runIsActive([pair(1), pending])).toBe(true)
+    expect(runIsActive([pair(1), pair(2)])).toBe(false)
+  })
+})

package/src/chat/groupToolRuns.ts

@@ -0,0 +1,82 @@
+import type { ChatRow } from "./pairToolMessages";
+
+/**
+ * Collapse a run of consecutive tool calls into ONE row.
+ *
+ * An agent working on something emits long stretches of back-to-back tool
+ * calls. Rendered one per row they push everything you actually read — the
+ * agent's prose, your own messages — off the screen, and a session you glance
+ * at becomes a wall of `Bash` you have to scroll past. Claude Code's own answer
+ * is a single "Running 5 shell commands…" line you can open if you care, and
+ * this is that.
+ *
+ * A run is broken by any non-tool row, so prose always separates groups and the
+ * conversation stays legible. Runs of one are left alone: wrapping a single
+ * call in a group adds a click without hiding anything.
+ */
+export type GroupedRow =
+  | ChatRow
+  | { kind: "tool_run"; rows: ChatRow[]; key: string };
+
+/** Below this, a run renders as individual rows — grouping one or two calls
+ *  costs a click and saves no space. */
+export const MIN_RUN_TO_GROUP = 3;
+
+export function groupToolRuns(
+  rows: ChatRow[],
+  minRun: number = MIN_RUN_TO_GROUP,
+): GroupedRow[] {
+  const out: GroupedRow[] = [];
+  let run: ChatRow[] = [];
+
+  const flush = () => {
+    if (run.length === 0) return;
+    if (run.length >= minRun) {
+      out.push({ kind: "tool_run", rows: run, key: `run-${run[0].key}` });
+    } else {
+      out.push(...run);
+    }
+    run = [];
+  };
+
+  for (const row of rows) {
+    if (row.kind === "tool_pair") {
+      run.push(row);
+      continue;
+    }
+    flush();
+    out.push(row);
+  }
+  flush();
+  return out;
+}
+
+/** True when any call in the run is still running — a collapsed group should say
+ *  so, or an agent mid-task looks idle. */
+export function runIsActive(rows: ChatRow[]): boolean {
+  return rows.some((row) => row.kind === "tool_pair" && row.result === null);
+}
+
+/** A short label for a collapsed run: "5 tool calls · Bash, Read". */
+export function summariseRun(rows: ChatRow[]): string {
+  const names = new Set<string>();
+  for (const row of rows) {
+    if (row.kind !== "tool_pair") continue;
+    const name = (row.use.content as { name?: unknown } | undefined)?.name;
+    if (typeof name === "string" && name) names.add(name);
+  }
+  const kinds = [...names].slice(0, 3).join(", ");
+  const plural = rows.length === 1 ? "call" : "calls";
+  return kinds ? `${rows.length} tool ${plural} · ${kinds}` : `${rows.length} tool ${plural}`;
+}
+
+/** True when any call in the run failed — a collapsed run must not hide an
+ *  error, or you'd scroll past the one thing worth stopping for. */
+export function runHasError(rows: ChatRow[]): boolean {
+  return rows.some(
+    (row) =>
+      row.kind === "tool_pair" &&
+      (row.result?.status === "error" ||
+        (row.result?.content as { is_error?: unknown } | undefined)?.is_error === true),
+  );
+}