@stigmer/react 1.0.4 → 2.0.1

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

@@ -0,0 +1,271 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, screen, cleanup, fireEvent } 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,
+  ExecutionConfigSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+import { AgentMessageSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { PendingApprovalSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
+import {
+  ExecutionPhase,
+  InteractionMode,
+  MessageType,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { MessageThread } from "../MessageThread";
+
+// ---------------------------------------------------------------------------
+// DOM stubs — useAutoScroll depends on browser APIs not available in happy-dom
+// ---------------------------------------------------------------------------
+
+beforeEach(() => {
+  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(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeExecution(opts: {
+  id: string;
+  specMessage?: string;
+  phase?: ExecutionPhase;
+  interactionMode?: InteractionMode;
+  aiContent?: string;
+}): AgentExecution {
+  const exec = create(AgentExecutionSchema);
+
+  const meta = create(ApiResourceMetadataSchema);
+  meta.id = opts.id;
+  exec.metadata = meta;
+
+  const spec = create(AgentExecutionSpecSchema);
+  spec.message = opts.specMessage ?? "Hello";
+  if (opts.interactionMode !== undefined) {
+    const config = create(ExecutionConfigSchema);
+    config.interactionMode = opts.interactionMode;
+    spec.executionConfig = config;
+  }
+  exec.spec = spec;
+
+  const status = create(AgentExecutionStatusSchema);
+  status.phase = opts.phase ?? ExecutionPhase.EXECUTION_COMPLETED;
+
+  const humanMsg = create(AgentMessageSchema);
+  humanMsg.type = MessageType.MESSAGE_HUMAN;
+  humanMsg.content = opts.specMessage ?? "Hello";
+
+  const aiMsg = create(AgentMessageSchema);
+  aiMsg.type = MessageType.MESSAGE_AI;
+  aiMsg.content = opts.aiContent ?? "Hi there!";
+
+  status.messages = [humanMsg, aiMsg];
+  exec.status = status;
+
+  return exec;
+}
+
+function makeExecutionWithApproval(
+  id: string,
+  toolCallId: string,
+  toolName: string,
+): AgentExecution {
+  const exec = create(AgentExecutionSchema);
+
+  const meta = create(ApiResourceMetadataSchema);
+  meta.id = id;
+  exec.metadata = meta;
+
+  const spec = create(AgentExecutionSpecSchema);
+  spec.message = "Do something";
+  exec.spec = spec;
+
+  const status = create(AgentExecutionStatusSchema);
+  status.phase = ExecutionPhase.EXECUTION_IN_PROGRESS;
+
+  const aiMsg = create(AgentMessageSchema);
+  aiMsg.type = MessageType.MESSAGE_AI;
+  aiMsg.content = "I need to run a tool.";
+  status.messages = [aiMsg];
+
+  status.pendingApprovals = [
+    create(PendingApprovalSchema, { toolCallId, toolName }),
+  ];
+  exec.status = status;
+
+  return exec;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("MessageThread", () => {
+  it("renders role=log container when executions array is empty", () => {
+    render(<MessageThread executions={[]} />);
+
+    const log = screen.getByRole("log");
+    expect(log).toBeTruthy();
+    expect(log.getAttribute("aria-live")).toBe("polite");
+  });
+
+  it("renders human and AI messages from completed execution", () => {
+    const exec = makeExecution({
+      id: "exec-1",
+      specMessage: "What is Stigmer?",
+      aiContent: "Stigmer is a platform for platforms.",
+    });
+
+    render(<MessageThread executions={[exec]} />);
+
+    // spec.message renders as a synthetic human bubble, plus it may
+    // also appear in status.messages — assert at least one is present.
+    const humanMessages = screen.getAllByText("What is Stigmer?");
+    expect(humanMessages.length).toBeGreaterThanOrEqual(1);
+    expect(
+      screen.getByText("Stigmer is a platform for platforms."),
+    ).toBeTruthy();
+  });
+
+  it("renders pending user message with opacity indicator", () => {
+    render(
+      <MessageThread
+        executions={[]}
+        pendingUserMessage="I am thinking..."
+      />,
+    );
+
+    const pendingText = screen.getByText("I am thinking...");
+    expect(pendingText).toBeTruthy();
+
+    const article = pendingText.closest("[role='article']");
+    expect(article?.className).toContain("opacity-70");
+  });
+
+  it("renders approval card when onApprovalSubmit is provided and execution has pending approvals", () => {
+    const exec = makeExecutionWithApproval("exec-a", "tc-1", "write_file");
+    const onApproval = vi.fn();
+
+    render(
+      <MessageThread
+        executions={[]}
+        activeStreamExecution={exec}
+        onApprovalSubmit={onApproval}
+      />,
+    );
+
+    const alert = screen.getByRole("alert");
+    expect(alert).toBeTruthy();
+    expect(alert.getAttribute("aria-label")).toContain("write_file");
+  });
+
+  it("does NOT render approval cards when onApprovalSubmit is omitted", () => {
+    const exec = makeExecutionWithApproval("exec-b", "tc-2", "shell");
+
+    render(
+      <MessageThread executions={[]} activeStreamExecution={exec} />,
+    );
+
+    expect(screen.queryByRole("alert")).toBeNull();
+  });
+
+  it("onApprovalSubmit fires with correct toolCallId and action", () => {
+    const exec = makeExecutionWithApproval("exec-c", "tc-approve", "read_file");
+    const onApproval = vi.fn();
+
+    render(
+      <MessageThread
+        executions={[]}
+        activeStreamExecution={exec}
+        onApprovalSubmit={onApproval}
+      />,
+    );
+
+    const approveBtn = screen.getByRole("button", { name: "Approve" });
+    fireEvent.click(approveBtn);
+
+    expect(onApproval).toHaveBeenCalledOnce();
+    expect(onApproval).toHaveBeenCalledWith(
+      "tc-approve",
+      expect.any(Number),
+      undefined,
+    );
+    // First arg is toolCallId, second is ApprovalAction.APPROVE (enum value)
+    expect(onApproval.mock.calls[0][0]).toBe("tc-approve");
+  });
+
+  it("renders ExecutionPhaseBadge for non-completed terminal phase", () => {
+    const exec = makeExecution({
+      id: "exec-fail",
+      phase: ExecutionPhase.EXECUTION_FAILED,
+    });
+
+    render(<MessageThread executions={[exec]} />);
+
+    expect(screen.getByText(/failed/i)).toBeTruthy();
+  });
+
+  it("renders plan-completion card when last execution is completed Plan mode", () => {
+    const exec = makeExecution({
+      id: "exec-plan",
+      phase: ExecutionPhase.EXECUTION_COMPLETED,
+      interactionMode: InteractionMode.PLAN,
+    });
+
+    const onBuildFromPlan = vi.fn();
+
+    render(
+      <MessageThread
+        executions={[exec]}
+        onBuildFromPlan={onBuildFromPlan}
+      />,
+    );
+
+    const implementBtn = screen.getByRole("button", { name: /implement/i });
+    expect(implementBtn).toBeTruthy();
+
+    fireEvent.click(implementBtn);
+    expect(onBuildFromPlan).toHaveBeenCalledOnce();
+  });
+});

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

@@ -507,4 +507,108 @@ describe("buildThreadItems key generation", () => {
       expect(pendingSetup!.key).toBe(inProgressSetup!.key);
     });
   });
+
+  describe("internal tool filtering", () => {
+    it("filters updateTodos tool calls from tool groups", () => {
+      const tc = makeToolCall("updateTodos", "tc-todo");
+      const exec = makeExecution({
+        id: "exec-todo",
+        messages: [
+          makeMessage(MessageType.MESSAGE_AI, "Planning...", { toolCalls: [tc] }),
+        ],
+      });
+
+      const items = buildThreadItems([exec], null, null, false, undefined);
+      const toolGroups = items.filter((i) => i.kind === "tool-group");
+      expect(toolGroups).toHaveLength(0);
+    });
+
+    it("filters TodoWrite tool calls from tool groups", () => {
+      const tc = makeToolCall("TodoWrite", "tc-tw");
+      const exec = makeExecution({
+        id: "exec-tw",
+        messages: [
+          makeMessage(MessageType.MESSAGE_AI, "Planning...", { toolCalls: [tc] }),
+        ],
+      });
+
+      const items = buildThreadItems([exec], null, null, false, undefined);
+      const toolGroups = items.filter((i) => i.kind === "tool-group");
+      expect(toolGroups).toHaveLength(0);
+    });
+
+    it("filters write_todos tool calls from tool groups", () => {
+      const tc = makeToolCall("write_todos", "tc-wt");
+      const exec = makeExecution({
+        id: "exec-wt",
+        messages: [
+          makeMessage(MessageType.MESSAGE_AI, "Planning...", { toolCalls: [tc] }),
+        ],
+      });
+
+      const items = buildThreadItems([exec], null, null, false, undefined);
+      const toolGroups = items.filter((i) => i.kind === "tool-group");
+      expect(toolGroups).toHaveLength(0);
+    });
+
+    it("preserves non-internal tools alongside filtered internal tools", () => {
+      const shellTc = makeToolCall("Shell", "tc-shell");
+      const todoTc = makeToolCall("updateTodos", "tc-todo");
+      const exec = makeExecution({
+        id: "exec-mixed",
+        messages: [
+          makeMessage(MessageType.MESSAGE_AI, "Working...", {
+            toolCalls: [shellTc, todoTc],
+          }),
+        ],
+      });
+
+      const items = buildThreadItems([exec], null, null, false, undefined);
+      const toolGroups = items.filter((i) => i.kind === "tool-group");
+      expect(toolGroups).toHaveLength(1);
+      expect(toolGroups[0].kind === "tool-group" && toolGroups[0].toolCalls).toHaveLength(1);
+      expect(toolGroups[0].kind === "tool-group" && toolGroups[0].toolCalls[0].name).toBe("Shell");
+    });
+
+    it("empty AI message with only internal tools produces no items", () => {
+      const todoTc = makeToolCall("updateTodos", "tc-todo");
+      const exec = makeExecution({
+        id: "exec-empty",
+        messages: [
+          makeMessage(MessageType.MESSAGE_AI, "  ", { toolCalls: [todoTc] }),
+        ],
+      });
+
+      const items = buildThreadItems([exec], null, null, false, undefined);
+      const messageItems = items.filter((i) => i.kind === "message");
+      const toolGroups = items.filter((i) => i.kind === "tool-group");
+      expect(messageItems).toHaveLength(0);
+      expect(toolGroups).toHaveLength(0);
+    });
+
+    it("filters internal tools alongside task tool splitting", () => {
+      const taskTc = makeToolCall("task", "tc-task");
+      const todoTc = makeToolCall("updateTodos", "tc-todo");
+      const shellTc = makeToolCall("Shell", "tc-shell");
+      const sa = makeSubAgent("tc-task");
+      const exec = makeExecution({
+        id: "exec-mixed-task",
+        messages: [
+          makeMessage(MessageType.MESSAGE_AI, "Delegating...", {
+            toolCalls: [taskTc, todoTc, shellTc],
+          }),
+        ],
+        subAgents: [sa],
+      });
+
+      const items = buildThreadItems([exec], null, null, false, undefined);
+      const toolGroups = items.filter((i) => i.kind === "tool-group");
+      const subAgentItems = items.filter((i) => i.kind === "sub-agent");
+
+      expect(subAgentItems).toHaveLength(1);
+      expect(toolGroups).toHaveLength(1);
+      expect(toolGroups[0].kind === "tool-group" && toolGroups[0].toolCalls).toHaveLength(1);
+      expect(toolGroups[0].kind === "tool-group" && toolGroups[0].toolCalls[0].name).toBe("Shell");
+    });
+  });
 });

package/src/execution/tool-categories.ts

@@ -21,6 +21,7 @@ export type ToolCategory =
   | "list"
   | "think"
   | "sub-agent"
+  | "internal"
   | "mcp"
   | "unknown";
 
@@ -74,6 +75,10 @@ const TOOL_DISPLAY_MAP: ReadonlyMap<string, ToolDisplayEntry> = new Map([
   ["think",           { category: "think",     label: "Thinking",  primaryField: "thought" }],
 
   ["task",            { category: "sub-agent", label: "Sub-agent", primaryField: "description", fallbackFields: ["prompt"] }],
+
+  ["updateTodos",     { category: "internal",  label: "Todos",     primaryField: "todos" }],
+  ["TodoWrite",       { category: "internal",  label: "Todos",     primaryField: "todos" }],
+  ["write_todos",     { category: "internal",  label: "Todos",     primaryField: "todos" }],
 ]);
 
 /**
@@ -87,6 +92,17 @@ const TOOL_DISPLAY_MAP: ReadonlyMap<string, ToolDisplayEntry> = new Map([
  * Falls back to `"unknown"` only when the tool is neither
  * built-in nor MCP-originated.
  */
+/**
+ * Returns true if the tool is an internal state management tool that
+ * should not be displayed in the message thread. Internal tools are
+ * rendered through dedicated UX surfaces (e.g. TodoList sidebar)
+ * rather than as expandable tool call items.
+ */
+export function isInternalTool(toolName: string): boolean {
+  const entry = TOOL_DISPLAY_MAP.get(toolName);
+  return entry?.category === "internal";
+}
+
 export function resolveToolCategory(
   toolName: string,
   mcpServerSlug?: string,

package/src/execution/useCreateAgentExecution.ts

@@ -1,6 +1,7 @@
 "use client";
 
 import { useCallback, useState } from "react";
+import type { JsonObject } from "@bufbuild/protobuf";
 import type { AttachmentInput, EnvVarInput } from "@stigmer/sdk";
 import { InteractionMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { useStigmer } from "../hooks";
@@ -58,6 +59,24 @@ export interface CreateAgentExecutionInput {
    * Maps to `ExecutionConfig.interaction_mode` in the proto.
    */
   readonly interactionMode?: "agent" | "plan";
+  /**
+   * JSON Schema that the agent's final output must conform to.
+   *
+   * When set, the runner enforces structured output:
+   * - Native harness: ToolStrategy adds an extract tool; agent must call it
+   * - Cursor harness: prompt injection + 3-tier extraction fallback
+   *
+   * The validated data is returned in `execution.status.structuredOutput`.
+   */
+  readonly structuredOutputSchema?: JsonObject;
+  /**
+   * Workspace-relative file paths the user wants the agent to focus on.
+   *
+   * These are lightweight "attention" signals — the agent reads the files
+   * directly from the workspace filesystem. No upload, no injection.
+   * Populated by the drag-to-reference feature in SessionComposer.
+   */
+  readonly workspaceFileRefs?: string[];
 }
 
 /** Resolved output of {@link UseCreateAgentExecutionReturn.create}. */
@@ -135,13 +154,16 @@ export function useCreateAgentExecution(): UseCreateAgentExecutionReturn {
       setError(null);
 
       try {
-        const hasConfig = input.modelName || input.interactionMode;
+        const hasConfig = input.modelName || input.interactionMode || input.structuredOutputSchema;
         const executionConfig = hasConfig
           ? {
               ...(input.modelName ? { modelName: input.modelName } : {}),
               ...(input.interactionMode
                 ? { interactionMode: INTERACTION_MODE_MAP[input.interactionMode] ?? InteractionMode.UNSPECIFIED }
                 : {}),
+              ...(input.structuredOutputSchema
+                ? { structuredOutputSchema: input.structuredOutputSchema }
+                : {}),
             }
           : undefined;
 
@@ -154,6 +176,7 @@ export function useCreateAgentExecution(): UseCreateAgentExecutionReturn {
           executionConfig,
           runtimeEnv: input.runtimeEnv,
           attachments: input.attachments,
+          workspaceFileRefs: input.workspaceFileRefs,
         });
 
         return {

package/src/execution/useThreadSelection.ts

@@ -0,0 +1,95 @@
+"use client";
+
+import { useCallback, useContext, useSyncExternalStore } from "react";
+import type { SelectedThreadItem } from "../internal/store/selection-store";
+import { ThreadSelectionContext } from "./ThreadSelectionContext";
+
+/**
+ * Return value of {@link useThreadSelection} when a provider is present.
+ *
+ * - `isSelected`: whether *this* item is currently selected.
+ * - `select`: callback to select/toggle this item.
+ *
+ * Both are referentially stable (safe as `useEffect`/`useMemo` deps).
+ */
+export interface ThreadSelectionHandle {
+  readonly isSelected: boolean;
+  readonly select: () => void;
+}
+
+const NOOP_SUBSCRIBE = (_cb: () => void) => () => {};
+const NOOP_SNAPSHOT = () => false;
+
+/**
+ * Per-item selection hook for thread leaves.
+ *
+ * Uses `useSyncExternalStore` so only the previously- and
+ * newly-selected rows re-render on a selection change (≤2 rows).
+ *
+ * Returns `null` when `ThreadSelectionContext` is absent (DD-011:
+ * opt-in, backward compatible). Callers should guard:
+ *
+ * ```tsx
+ * const selection = useThreadSelection("tool-call", tc.id);
+ * // selection is null when no provider → no selection affordance
+ * ```
+ */
+export function useThreadSelection(
+  kind: SelectedThreadItem["kind"],
+  id: string,
+): ThreadSelectionHandle | null {
+  const store = useContext(ThreadSelectionContext);
+
+  const subscribe = store?.subscribe ?? NOOP_SUBSCRIBE;
+  const getSnapshot = store
+    ? () => store.isSelected(kind, id)
+    : NOOP_SNAPSHOT;
+
+  const isSelected = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+
+  const select = useCallback(() => {
+    if (!store) return;
+    const item = buildItem(kind, id);
+    store.toggle(item);
+  }, [store, kind, id]);
+
+  if (!store) return null;
+
+  return { isSelected, select };
+}
+
+/**
+ * Hook to read the full selection from the store (for the InspectTab).
+ *
+ * Returns `null` when no provider is present or nothing is selected.
+ */
+export function useSelectedThreadItem(): SelectedThreadItem | null {
+  const store = useContext(ThreadSelectionContext);
+
+  const subscribe = store?.subscribe ?? NOOP_SUBSCRIBE;
+  const getSnapshot = store
+    ? store.getSelection
+    : () => null;
+
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function buildItem(
+  kind: SelectedThreadItem["kind"],
+  id: string,
+): SelectedThreadItem {
+  switch (kind) {
+    case "tool-call":
+      return { kind: "tool-call", toolCallId: id };
+    case "sub-agent":
+      return { kind: "sub-agent", subAgentId: id };
+    case "artifact":
+      return { kind: "artifact", artifactKey: id };
+    case "write-back":
+      return { kind: "write-back", workspaceEntryName: id };
+  }
+}

package/src/execution-target-context.ts

@@ -0,0 +1,32 @@
+"use client";
+
+import { createContext, useContext } from "react";
+import type { ExecutionTargetOption } from "./session/execution-target";
+
+/**
+ * React context for the app-level execution target.
+ *
+ * Separated from the provider to mirror the `DeploymentModeContext`
+ * pattern and avoid circular imports.
+ *
+ * `undefined` means no explicit target was configured at the provider
+ * level -- the server decides based on deployment context.
+ */
+export const ExecutionTargetContext = createContext<
+  ExecutionTargetOption | undefined
+>(undefined);
+
+/**
+ * Read the app-level execution target from the nearest
+ * `StigmerProvider`.
+ *
+ * Returns `"local"`, `"cloud"`, or `undefined` when the provider
+ * does not specify one (server decides).
+ *
+ * Hooks like `useNewSessionFlow` and `useCreateSession` read this
+ * to apply a consistent execution target across all sessions without
+ * requiring per-call configuration.
+ */
+export function useExecutionTarget(): ExecutionTargetOption | undefined {
+  return useContext(ExecutionTargetContext);
+}