@stigmer/react 3.0.9-dev.20260616060535 → 3.1.1

package/src/execution/__tests__/subagent-file-review-badge.test.tsx

@@ -0,0 +1,273 @@
+/**
+ * Sub-agent file-review badges (DD-24/T05_0 follow-up).
+ *
+ * A sub-agent's flowed file-edit row is stamped by the runner with the PARENT
+ * turn's change set id (sub-agent writes fold into the parent set). These tests
+ * lock the React side: a stamped row rendered inside a `SubAgentSection`
+ * resolves its review-state badge against the session-wide `FileReviewContext`
+ * map, and — end to end through `MessageThread` — that map is built from the
+ * parent execution's `status.fileChangeSets` and reaches the nested row.
+ *
+ * The per-row badge resolution itself (pending/kept/discarded/none) is covered
+ * exhaustively in `ToolCallItem.test.tsx`; here the emphasis is the SUB-AGENT
+ * wiring — the novel path this change enables.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, screen, cleanup } from "@testing-library/react";
+import { create } from "@bufbuild/protobuf";
+import {
+  AgentExecutionSchema,
+  AgentExecutionStatusSchema,
+  type AgentExecution,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { AgentExecutionSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+import {
+  AgentMessageSchema,
+  ToolCallSchema,
+  FileContentSchema,
+  type AgentMessage,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import {
+  SubAgentExecutionSchema,
+  type SubAgentExecution,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/subagent_pb";
+import {
+  CapturedFileChangeSchema,
+  FileChangeSetSchema,
+  FileDecisionSchema,
+  type FileChangeSet,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+import {
+  DiffCompleteness,
+  ExecutionPhase,
+  FileChangeKind,
+  FileChangeSetStatus,
+  FileDecisionAction,
+  FileDecisionScope,
+  MessageType,
+  SubAgentStatus,
+  ToolCallStatus,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { SubAgentSection } from "../SubAgentSection";
+import { ApprovalContext, type ApprovalContextValue } from "../ApprovalContext";
+import { FileReviewContext } from "../FileReviewContext";
+import { MessageThread } from "../MessageThread";
+
+const SET_ID = "exec-1:0";
+const ROW_PATH = "src/a.ts";
+
+const emptyApprovalCtx: ApprovalContextValue = {
+  approvalsByToolCallId: new Map(),
+  submittingIds: new Set(),
+  errorsByToolCallId: new Map(),
+};
+
+afterEach(cleanup);
+
+/** A sub-agent whose message carries one stamped, flowed file-edit row. */
+function subAgentWithStampedEdit(
+  status: SubAgentStatus,
+  fileChangeSetId: string,
+  rowPath = ROW_PATH,
+): SubAgentExecution {
+  return create(SubAgentExecutionSchema, {
+    id: "sa-1",
+    name: "code_editor",
+    status,
+    messages: [
+      create(AgentMessageSchema, {
+        type: MessageType.MESSAGE_AI,
+        toolCalls: [
+          create(ToolCallSchema, {
+            id: "sa-tc-edit",
+            name: "edit",
+            status: ToolCallStatus.TOOL_CALL_COMPLETED,
+            args: { path: rowPath, old_string: "a", new_string: "b" },
+            fileChangeSetId,
+          }),
+        ],
+      }),
+    ],
+  });
+}
+
+/** A change set carrying one change for {@link ROW_PATH}, with optional verdict. */
+function reviewSet(
+  status: FileChangeSetStatus,
+  decisions: FileDecisionAction[] = [],
+): FileChangeSet {
+  return create(FileChangeSetSchema, {
+    id: SET_ID,
+    status,
+    aggregateDigest: "agg-1",
+    diffCompleteness: DiffCompleteness.COMPLETE,
+    changes: [
+      create(CapturedFileChangeSchema, {
+        id: `${SET_ID}:${ROW_PATH}`,
+        pathBefore: ROW_PATH,
+        pathAfter: ROW_PATH,
+        kind: FileChangeKind.MODIFY,
+        before: create(FileContentSchema, { body: { case: "inline", value: "old\n" } }),
+        after: create(FileContentSchema, { body: { case: "inline", value: "new\n" } }),
+        fileDigest: "d-a",
+        diffComplete: true,
+      }),
+    ],
+    decisions: decisions.map((action) =>
+      create(FileDecisionSchema, {
+        changeSetId: SET_ID,
+        scope: FileDecisionScope.CHANGE_SET,
+        action,
+      }),
+    ),
+  });
+}
+
+function renderSubAgentRow(sub: SubAgentExecution, set: FileChangeSet | null) {
+  const map = set ? new Map([[set.id, set]]) : new Map<string, FileChangeSet>();
+  return render(
+    <ApprovalContext.Provider value={emptyApprovalCtx}>
+      <FileReviewContext.Provider value={{ changeSetsById: map }}>
+        {/* collapsible=false renders the nested rows flat — deterministic, no
+            dependence on the card's auto-disclosure state. */}
+        <SubAgentSection subAgentExecution={sub} collapsible={false} />
+      </FileReviewContext.Provider>
+    </ApprovalContext.Provider>,
+  );
+}
+
+function badge(container: HTMLElement): Element | null {
+  return container.querySelector('[data-cursor-target="file-review-row-badge"]');
+}
+
+describe("sub-agent row badges (SubAgentSection)", () => {
+  it("badges a stamped sub-agent edit row 'Pending review' while its set awaits review", () => {
+    const { container } = renderSubAgentRow(
+      subAgentWithStampedEdit(SubAgentStatus.SUB_AGENT_COMPLETED, SET_ID),
+      reviewSet(FileChangeSetStatus.AWAITING_REVIEW),
+    );
+    expect(badge(container)?.textContent).toBe("Pending review");
+  });
+
+  it("flips a sub-agent row to the file's verdict once the set is decided", () => {
+    const kept = renderSubAgentRow(
+      subAgentWithStampedEdit(SubAgentStatus.SUB_AGENT_COMPLETED, SET_ID),
+      reviewSet(FileChangeSetStatus.RECONCILED, [FileDecisionAction.APPROVE]),
+    );
+    expect(badge(kept.container)?.textContent).toBe("Kept");
+    cleanup();
+
+    const discarded = renderSubAgentRow(
+      subAgentWithStampedEdit(SubAgentStatus.SUB_AGENT_COMPLETED, SET_ID),
+      reviewSet(FileChangeSetStatus.RECONCILED, [FileDecisionAction.REJECT]),
+    );
+    expect(badge(discarded.container)?.textContent).toBe("Discarded");
+  });
+
+  it("shows no badge when the stamped set cannot be resolved (graceful degrade, DD-24 D3)", () => {
+    // Row stamped with a set id absent from the session map.
+    const orphan = renderSubAgentRow(
+      subAgentWithStampedEdit(SubAgentStatus.SUB_AGENT_COMPLETED, "exec-1:missing"),
+      reviewSet(FileChangeSetStatus.AWAITING_REVIEW),
+    );
+    expect(badge(orphan.container)).toBeNull();
+    cleanup();
+
+    // Row stamped with the right (settled) set, but its path is not in the set's
+    // changes: the per-file verdict cannot be resolved, so no badge. (An
+    // AWAITING_REVIEW set badges every stamped row 'pending' regardless of path —
+    // path resolution only decides the verdict of a SETTLED set.)
+    const pathMiss = renderSubAgentRow(
+      subAgentWithStampedEdit(SubAgentStatus.SUB_AGENT_COMPLETED, SET_ID, "src/other.ts"),
+      reviewSet(FileChangeSetStatus.RECONCILED, [FileDecisionAction.APPROVE]),
+    );
+    expect(badge(pathMiss.container)).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// End-to-end through MessageThread: proves the session-wide FileReviewContext
+// map is built from the PARENT execution's status.fileChangeSets and reaches a
+// stamped row nested inside a sub-agent (the map + provider + nested-render path).
+// ---------------------------------------------------------------------------
+
+describe("sub-agent row badges (MessageThread integration)", () => {
+  beforeEach(() => {
+    // useAutoScroll depends on browser APIs absent in happy-dom.
+    vi.stubGlobal(
+      "IntersectionObserver",
+      vi.fn(() => ({
+        observe: vi.fn(),
+        unobserve: vi.fn(),
+        disconnect: vi.fn(),
+        takeRecords: vi.fn(() => []),
+        root: null,
+        rootMargin: "",
+        thresholds: [0],
+      })),
+    );
+    vi.stubGlobal(
+      "ResizeObserver",
+      vi.fn(() => ({ observe: vi.fn(), unobserve: vi.fn(), disconnect: vi.fn() })),
+    );
+    vi.stubGlobal(
+      "requestAnimationFrame",
+      vi.fn((cb: FrameRequestCallback) => {
+        cb(performance.now());
+        return 1;
+      }),
+    );
+    vi.stubGlobal("cancelAnimationFrame", vi.fn());
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  /**
+   * A live execution that delegated to a sub-agent which edited a file this
+   * turn. The parent carries the `task` tool call (matched to the sub-agent by
+   * id) and the change set on `status.fileChangeSets`; the sub-agent (running,
+   * so its card auto-opens) carries the stamped edit row.
+   */
+  function makeExecWithSubAgentEdit(): AgentExecution {
+    const exec = create(AgentExecutionSchema);
+    exec.metadata = create(ApiResourceMetadataSchema, { id: "exec-1" });
+    exec.spec = create(AgentExecutionSpecSchema, { message: "Delegate an edit" });
+
+    const status = create(AgentExecutionStatusSchema);
+    status.phase = ExecutionPhase.EXECUTION_IN_PROGRESS;
+    const aiMsg: AgentMessage = create(AgentMessageSchema, {
+      type: MessageType.MESSAGE_AI,
+      content: "Delegating.",
+      toolCalls: [
+        create(ToolCallSchema, {
+          id: "sa-1", // matches the SubAgentExecution id
+          name: "task",
+          status: ToolCallStatus.TOOL_CALL_COMPLETED,
+        }),
+      ],
+    });
+    status.messages = [aiMsg];
+    status.subAgentExecutions = [
+      subAgentWithStampedEdit(SubAgentStatus.SUB_AGENT_IN_PROGRESS, SET_ID),
+    ];
+    status.fileChangeSets = [reviewSet(FileChangeSetStatus.AWAITING_REVIEW)];
+    exec.status = status;
+    return exec;
+  }
+
+  it("badges a stamped sub-agent row from a set on the parent execution's fileChangeSets", () => {
+    render(
+      <MessageThread
+        executions={[]}
+        activeStreamExecution={makeExecWithSubAgentEdit()}
+        showFileReviewRecords
+      />,
+    );
+    const el = document.querySelector('[data-cursor-target="file-review-row-badge"]');
+    expect(el?.textContent).toBe("Pending review");
+  });
+});

package/src/execution/__tests__/thread-keys.test.ts

@@ -12,9 +12,14 @@ import {
   ToolCallSchema,
 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
 import { SubAgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/subagent_pb";
+import {
+  TodoItemSchema,
+  type TodoItem,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/todo_pb";
 import {
   ExecutionPhase,
   MessageType,
+  TodoStatus,
   ToolCallStatus,
 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { buildThreadItems } from "../MessageThread";
@@ -55,12 +60,24 @@ function makeSubAgent(id: string) {
   return sa;
 }
 
+function makeTodo(id: string, content: string, status: TodoStatus): TodoItem {
+  return create(TodoItemSchema, { id, content, status });
+}
+
+/** Build the `status.todos` proto map from a list of items, keyed by id. */
+function todoMap(items: TodoItem[]): { [id: string]: TodoItem } {
+  const map: { [id: string]: TodoItem } = {};
+  for (const t of items) map[t.id] = t;
+  return map;
+}
+
 function makeExecution(opts: {
   id: string;
   specMessage?: string;
   phase?: ExecutionPhase;
   messages?: ReturnType<typeof makeMessage>[];
   subAgents?: ReturnType<typeof makeSubAgent>[];
+  todos?: { [id: string]: TodoItem };
 }): AgentExecution {
   const exec = create(AgentExecutionSchema);
 
@@ -82,6 +99,9 @@ function makeExecution(opts: {
   if (opts.subAgents) {
     status.subAgentExecutions = opts.subAgents;
   }
+  if (opts.todos) {
+    status.todos = opts.todos;
+  }
   exec.status = status;
 
   return exec;
@@ -612,3 +632,178 @@ describe("buildThreadItems key generation", () => {
     });
   });
 });
+
+// ---------------------------------------------------------------------------
+// Inline todos card
+// ---------------------------------------------------------------------------
+
+describe("buildThreadItems todos card", () => {
+  it("emits no todos card when status.todos is empty", () => {
+    const exec = makeExecution({
+      id: "exec-no-todos",
+      messages: [makeMessage(MessageType.MESSAGE_AI, "Done")],
+    });
+
+    const items = buildThreadItems([exec], null, null, false, undefined);
+    expect(items.filter((i) => i.kind === "todos")).toHaveLength(0);
+  });
+
+  it("anchors the card immediately after the opening AI message (anchor 1)", () => {
+    const exec = makeExecution({
+      id: "exec-a1",
+      messages: [
+        makeMessage(MessageType.MESSAGE_AI, "Here is my plan"),
+        makeMessage(MessageType.MESSAGE_AI, "Working on it"),
+      ],
+      todos: todoMap([makeTodo("t1", "Step 1", TodoStatus.TODO_IN_PROGRESS)]),
+    });
+
+    const items = buildThreadItems([exec], null, null, false, undefined);
+    const keys = extractKeys(items);
+    // ...-m0 (opening AI) -> todos -> ...-m1
+    expect(keys).toEqual(["exec-a1-m0", "exec-a1-todos", "exec-a1-m1"]);
+  });
+
+  it("anchors the card after the opening thinking message", () => {
+    const exec = makeExecution({
+      id: "exec-think",
+      messages: [
+        makeMessage(MessageType.MESSAGE_THINKING, "Let me think"),
+        makeMessage(MessageType.MESSAGE_AI, "Answer"),
+      ],
+      todos: todoMap([makeTodo("t1", "Step 1", TodoStatus.TODO_PENDING)]),
+    });
+
+    const items = buildThreadItems([exec], null, null, false, undefined);
+    const keys = extractKeys(items);
+    expect(keys).toEqual(["exec-think-m0", "exec-think-todos", "exec-think-m1"]);
+  });
+
+  it("anchors before the first tool-group when work precedes any narration (anchor 2)", () => {
+    // An empty-content AI message that only carries a Shell tool call: no
+    // rendered narration, so the plan must lead the work.
+    const shellTc = makeToolCall("Shell", "tc-shell");
+    const exec = makeExecution({
+      id: "exec-a2",
+      messages: [
+        makeMessage(MessageType.MESSAGE_AI, "  ", { toolCalls: [shellTc] }),
+      ],
+      todos: todoMap([makeTodo("t1", "Step 1", TodoStatus.TODO_IN_PROGRESS)]),
+    });
+
+    const items = buildThreadItems([exec], null, null, false, undefined);
+    const keys = extractKeys(items);
+    expect(keys).toEqual(["exec-a2-todos", "exec-a2-m0-tc"]);
+  });
+
+  it("falls back to the turn tail when there is no narration or work (anchor 3)", () => {
+    // Only a suppressed/internal todo tool call, empty content: nothing renders
+    // except the plan itself, which must still surface.
+    const todoTc = makeToolCall("updateTodos", "tc-todo");
+    const exec = makeExecution({
+      id: "exec-a3",
+      messages: [
+        makeMessage(MessageType.MESSAGE_AI, "  ", { toolCalls: [todoTc] }),
+      ],
+      todos: todoMap([makeTodo("t1", "Step 1", TodoStatus.TODO_COMPLETED)]),
+    });
+
+    const items = buildThreadItems([exec], null, null, false, undefined);
+    const todoItems = items.filter((i) => i.kind === "todos");
+    expect(todoItems).toHaveLength(1);
+    expect(todoItems[0].key).toBe("exec-a3-todos");
+  });
+
+  it("emits exactly one card per execution even with multiple AI messages", () => {
+    const exec = makeExecution({
+      id: "exec-one",
+      messages: [
+        makeMessage(MessageType.MESSAGE_AI, "First"),
+        makeMessage(MessageType.MESSAGE_AI, "Second"),
+        makeMessage(MessageType.MESSAGE_AI, "Third"),
+      ],
+      todos: todoMap([makeTodo("t1", "Step 1", TodoStatus.TODO_PENDING)]),
+    });
+
+    const items = buildThreadItems([exec], null, null, false, undefined);
+    expect(items.filter((i) => i.kind === "todos")).toHaveLength(1);
+  });
+
+  it("emits one card per turn across a multi-turn session", () => {
+    const turn1 = makeExecution({
+      id: "exec-1",
+      messages: [makeMessage(MessageType.MESSAGE_AI, "Plan A")],
+      todos: todoMap([makeTodo("t1", "A", TodoStatus.TODO_COMPLETED)]),
+    });
+    // A follow-up turn that did not write todos shows no card.
+    const turn2 = makeExecution({
+      id: "exec-2",
+      messages: [makeMessage(MessageType.MESSAGE_AI, "No plan here")],
+    });
+    const turn3 = makeExecution({
+      id: "exec-3",
+      messages: [makeMessage(MessageType.MESSAGE_AI, "Plan C")],
+      todos: todoMap([makeTodo("t1", "C", TodoStatus.TODO_IN_PROGRESS)]),
+    });
+
+    const items = buildThreadItems([turn1, turn2, turn3], null, null, false, undefined);
+    const todoKeys = items.filter((i) => i.kind === "todos").map((i) => i.key);
+    expect(todoKeys).toEqual(["exec-1-todos", "exec-3-todos"]);
+  });
+
+  it("carries the live status.todos reference (no clone) for memoization", () => {
+    const todos = todoMap([makeTodo("t1", "Step 1", TodoStatus.TODO_PENDING)]);
+    const exec = makeExecution({
+      id: "exec-ref",
+      messages: [makeMessage(MessageType.MESSAGE_AI, "Plan")],
+      todos,
+    });
+
+    const items = buildThreadItems([exec], null, null, false, undefined);
+    const todoItem = items.find((i) => i.kind === "todos");
+    expect(todoItem?.kind === "todos" && todoItem.todos).toBe(exec.status!.todos);
+  });
+
+  it("native-harness shape: filters the write_todos tool call but still shows the card", () => {
+    // Native keeps write_todos as a (filtered) tool call AND populates status.todos.
+    const writeTodosTc = makeToolCall("write_todos", "tc-wt");
+    const exec = makeExecution({
+      id: "exec-native",
+      messages: [
+        makeMessage(MessageType.MESSAGE_AI, "Planning", {
+          toolCalls: [writeTodosTc],
+        }),
+      ],
+      todos: todoMap([makeTodo("t1", "Step 1", TodoStatus.TODO_IN_PROGRESS)]),
+    });
+
+    const items = buildThreadItems([exec], null, null, false, undefined);
+    expect(items.filter((i) => i.kind === "tool-group")).toHaveLength(0);
+    expect(items.filter((i) => i.kind === "todos")).toHaveLength(1);
+  });
+
+  it("keeps a stable key as todos update (no remount)", () => {
+    const before = makeExecution({
+      id: "exec-stable",
+      messages: [makeMessage(MessageType.MESSAGE_AI, "Plan")],
+      todos: todoMap([makeTodo("t1", "Step 1", TodoStatus.TODO_PENDING)]),
+    });
+    const after = makeExecution({
+      id: "exec-stable",
+      messages: [makeMessage(MessageType.MESSAGE_AI, "Plan")],
+      todos: todoMap([
+        makeTodo("t1", "Step 1", TodoStatus.TODO_COMPLETED),
+        makeTodo("t2", "Step 2", TodoStatus.TODO_IN_PROGRESS),
+      ]),
+    });
+
+    const k1 = buildThreadItems([before], null, null, false, undefined).find(
+      (i) => i.kind === "todos",
+    )?.key;
+    const k2 = buildThreadItems([after], null, null, false, undefined).find(
+      (i) => i.kind === "todos",
+    )?.key;
+    expect(k1).toBe("exec-stable-todos");
+    expect(k2).toBe("exec-stable-todos");
+  });
+});

package/src/execution/__tests__/tool-presenter.test.tsx

@@ -75,4 +75,99 @@ describe("useToolPresentation", () => {
     const { result } = renderHook(() => useToolPresentation(tc));
     expect(result.current.label).toBe("Shell");
   });
+
+  describe("disclosure", () => {
+    it("keeps known compact tools as summary", () => {
+      // Shell/edit/write are intentionally excluded — they are `preview`
+      // categories (output / diff is the information), asserted separately below.
+      for (const name of ["Read", "Grep", "Glob"]) {
+        const tc = makeToolCall({ name, args: { path: "/x", command: "ls", pattern: "p" } });
+        const { result } = renderHook(() => useToolPresentation(tc));
+        expect(result.current.disclosure).toBe("summary");
+      }
+    });
+
+    it("previews file edits and writes (the diff is the information)", () => {
+      for (const name of ["StrReplace", "Write"]) {
+        const tc = makeToolCall({
+          name,
+          args: { path: "/x.ts", contents: "x", old_string: "a", new_string: "b" },
+        });
+        const { result } = renderHook(() => useToolPresentation(tc));
+        expect(result.current.disclosure).toBe("preview");
+      }
+    });
+
+    it("keeps a shell tool's output as a persistent preview", () => {
+      const tc = makeToolCall({ name: "Shell", args: { command: "ls" }, result: "files" });
+      const { result } = renderHook(() => useToolPresentation(tc));
+      expect(result.current.category).toBe("shell");
+      expect(result.current.disclosure).toBe("preview");
+    });
+
+    it("foregrounds MCP tools as preview", () => {
+      const tc = makeToolCall({
+        name: "send_message",
+        mcpServerSlug: "acme/slack",
+        args: { channel: "general" },
+      });
+      const { result } = renderHook(() => useToolPresentation(tc));
+      expect(result.current.category).toBe("mcp");
+      expect(result.current.disclosure).toBe("preview");
+    });
+
+    it("foregrounds an unrecognized tool as preview", () => {
+      const tc = makeToolCall({ name: "frobnicate_widget", args: { x: "1" } });
+      const { result } = renderHook(() => useToolPresentation(tc));
+      expect(result.current.category).toBe("unknown");
+      expect(result.current.disclosure).toBe("preview");
+    });
+
+    it("lets a registered presenter override the disclosure", () => {
+      const dispose = registerToolPresenter(ToolKind.MCP, {
+        disclosure: () => "summary",
+      });
+      try {
+        const tc = makeToolCall({
+          name: "noisy_tool",
+          mcpServerSlug: "acme/noisy",
+        });
+        const { result } = renderHook(() => useToolPresentation(tc));
+        expect(result.current.disclosure).toBe("summary");
+      } finally {
+        dispose();
+      }
+    });
+  });
+
+  describe("runGroupable", () => {
+    it("folds read-only repetitive categories", () => {
+      for (const name of ["Read", "Grep", "Glob"]) {
+        const tc = makeToolCall({ name, args: { path: "/x", pattern: "p" } });
+        const { result } = renderHook(() => useToolPresentation(tc));
+        expect(result.current.runGroupable).toBe(true);
+      }
+    });
+
+    it("never folds high-signal categories", () => {
+      for (const name of ["Shell", "StrReplace"]) {
+        const tc = makeToolCall({ name, args: { command: "ls", path: "/x" } });
+        const { result } = renderHook(() => useToolPresentation(tc));
+        expect(result.current.runGroupable).toBe(false);
+      }
+    });
+
+    it("lets a registered presenter override run-grouping", () => {
+      const dispose = registerToolPresenter(ToolKind.SHELL, {
+        runGroupable: () => true,
+      });
+      try {
+        const tc = makeToolCall({ name: "Shell", args: { command: "ls" } });
+        const { result } = renderHook(() => useToolPresentation(tc));
+        expect(result.current.runGroupable).toBe(true);
+      } finally {
+        dispose();
+      }
+    });
+  });
 });

package/src/execution/__tests__/useArtifactDownload.test.tsx

@@ -0,0 +1,67 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import type { ReactNode } from "react";
+import type { Stigmer } from "@stigmer/sdk";
+import { StigmerContext } from "../../context";
+import { useArtifactDownload } from "../useArtifactDownload";
+
+function wrapperFor(stigmer: Stigmer) {
+  return ({ children }: { children: ReactNode }) => (
+    <StigmerContext.Provider value={stigmer}>{children}</StigmerContext.Provider>
+  );
+}
+
+function makeStigmer(getArtifactDownloadUrl = vi.fn()) {
+  return { agentExecution: { getArtifactDownloadUrl } } as unknown as Stigmer;
+}
+
+// Browser download is triggered via a transient anchor; stub the click so the
+// jsdom navigation no-op doesn't add noise and we can keep the test focused on
+// the URL-minting behavior.
+beforeEach(() => {
+  vi.spyOn(HTMLAnchorElement.prototype, "click").mockImplementation(() => {});
+});
+
+describe("useArtifactDownload", () => {
+  it("mints a fresh URL at click time and toggles isDownloading", async () => {
+    const fn = vi.fn().mockResolvedValue({ downloadUrl: "https://fresh/dl" });
+    const { result } = renderHook(() => useArtifactDownload("aex_1"), {
+      wrapper: wrapperFor(makeStigmer(fn)),
+    });
+
+    expect(result.current.isDownloading).toBe(false);
+    await act(async () => {
+      await result.current.download("artifacts/aex_1/file.bin", "file.bin");
+    });
+
+    expect(fn).toHaveBeenCalledTimes(1);
+    const req = fn.mock.calls[0][0];
+    expect(req.executionId).toBe("aex_1");
+    expect(req.storageKey).toBe("artifacts/aex_1/file.bin");
+    expect(result.current.isDownloading).toBe(false);
+    expect(result.current.error).toBeNull();
+  });
+
+  it("is a no-op when the execution id is unknown", async () => {
+    const fn = vi.fn();
+    const { result } = renderHook(() => useArtifactDownload(null), {
+      wrapper: wrapperFor(makeStigmer(fn)),
+    });
+    await act(async () => {
+      await result.current.download("artifacts/x/file.bin");
+    });
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it("surfaces an error when the refresh RPC fails", async () => {
+    const fn = vi.fn().mockRejectedValue(new Error("boom"));
+    const { result } = renderHook(() => useArtifactDownload("aex_1"), {
+      wrapper: wrapperFor(makeStigmer(fn)),
+    });
+    await act(async () => {
+      await result.current.download("artifacts/aex_1/file.bin");
+    });
+    expect(result.current.error?.message).toBe("boom");
+    expect(result.current.isDownloading).toBe(false);
+  });
+});