@stigmer/react 0.3.3 → 0.4.0

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

@@ -0,0 +1,320 @@
+import { describe, it, expect } from "vitest";
+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,
+  type ToolCall,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { SubAgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/subagent_pb";
+import {
+  ExecutionPhase,
+  MessageType,
+  ToolCallStatus,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { toolCallGroupPropsEqual, type ToolCallGroupProps } from "../ToolCallGroup";
+import { buildThreadItems } from "../MessageThread";
+import { structuralShare } from "../../internal/store";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeMessage(
+  type: MessageType,
+  content: string,
+  opts?: { toolCalls?: ToolCall[]; isStreaming?: boolean },
+) {
+  const msg = create(AgentMessageSchema);
+  msg.type = type;
+  msg.content = content;
+  if (opts?.toolCalls) msg.toolCalls = opts.toolCalls;
+  if (opts?.isStreaming) msg.isStreaming = true;
+  return msg;
+}
+
+function makeToolCall(name: string, id: string) {
+  const tc = create(ToolCallSchema);
+  tc.id = id;
+  tc.name = name;
+  tc.status = ToolCallStatus.TOOL_CALL_COMPLETED;
+  return tc;
+}
+
+function makeSubAgent(id: string) {
+  const sa = create(SubAgentExecutionSchema);
+  sa.id = id;
+  sa.name = "test-agent";
+  return sa;
+}
+
+function makeExecution(opts: {
+  id: string;
+  specMessage?: string;
+  phase?: ExecutionPhase;
+  messages?: ReturnType<typeof makeMessage>[];
+  subAgents?: ReturnType<typeof makeSubAgent>[];
+}): AgentExecution {
+  const exec = create(AgentExecutionSchema);
+  const meta = create(ApiResourceMetadataSchema);
+  meta.id = opts.id;
+  exec.metadata = meta;
+  if (opts.specMessage) {
+    const spec = create(AgentExecutionSpecSchema);
+    spec.message = opts.specMessage;
+    exec.spec = spec;
+  }
+  const status = create(AgentExecutionStatusSchema);
+  status.phase = opts.phase ?? ExecutionPhase.EXECUTION_COMPLETED;
+  if (opts.messages) status.messages = opts.messages;
+  if (opts.subAgents) status.subAgentExecutions = opts.subAgents;
+  exec.status = status;
+  return exec;
+}
+
+// ---------------------------------------------------------------------------
+// toolCallGroupPropsEqual
+// ---------------------------------------------------------------------------
+
+describe("toolCallGroupPropsEqual", () => {
+  it("returns true when both arrays share the same ToolCall references", () => {
+    const tc1 = makeToolCall("shell", "tc-1");
+    const tc2 = makeToolCall("read_file", "tc-2");
+    const prev: ToolCallGroupProps = { toolCalls: [tc1, tc2] };
+    const next: ToolCallGroupProps = { toolCalls: [tc1, tc2] };
+    expect(toolCallGroupPropsEqual(prev, next)).toBe(true);
+  });
+
+  it("returns false when array lengths differ", () => {
+    const tc1 = makeToolCall("shell", "tc-1");
+    const prev: ToolCallGroupProps = { toolCalls: [tc1] };
+    const next: ToolCallGroupProps = { toolCalls: [tc1, makeToolCall("read_file", "tc-2")] };
+    expect(toolCallGroupPropsEqual(prev, next)).toBe(false);
+  });
+
+  it("returns false when a ToolCall reference changes", () => {
+    const tc1 = makeToolCall("shell", "tc-1");
+    const tc1Copy = makeToolCall("shell", "tc-1");
+    const prev: ToolCallGroupProps = { toolCalls: [tc1] };
+    const next: ToolCallGroupProps = { toolCalls: [tc1Copy] };
+    expect(toolCallGroupPropsEqual(prev, next)).toBe(false);
+  });
+
+  it("returns false when className changes", () => {
+    const tc1 = makeToolCall("shell", "tc-1");
+    const prev: ToolCallGroupProps = { toolCalls: [tc1], className: "mx-4" };
+    const next: ToolCallGroupProps = { toolCalls: [tc1], className: "mx-6" };
+    expect(toolCallGroupPropsEqual(prev, next)).toBe(false);
+  });
+
+  it("returns false when subAgentExecutions reference changes", () => {
+    const tc1 = makeToolCall("shell", "tc-1");
+    const subs1 = [makeSubAgent("sa-1")];
+    const subs2 = [makeSubAgent("sa-1")];
+    const prev: ToolCallGroupProps = { toolCalls: [tc1], subAgentExecutions: subs1 };
+    const next: ToolCallGroupProps = { toolCalls: [tc1], subAgentExecutions: subs2 };
+    expect(toolCallGroupPropsEqual(prev, next)).toBe(false);
+  });
+
+  it("returns true when subAgentExecutions is the same reference", () => {
+    const tc1 = makeToolCall("shell", "tc-1");
+    const subs = [makeSubAgent("sa-1")];
+    const prev: ToolCallGroupProps = { toolCalls: [tc1], subAgentExecutions: subs };
+    const next: ToolCallGroupProps = { toolCalls: [tc1], subAgentExecutions: subs };
+    expect(toolCallGroupPropsEqual(prev, next)).toBe(true);
+  });
+
+  it("returns false when formatSummary reference changes", () => {
+    const tc1 = makeToolCall("shell", "tc-1");
+    const fn1 = () => "summary";
+    const fn2 = () => "summary";
+    const prev: ToolCallGroupProps = { toolCalls: [tc1], formatSummary: fn1 };
+    const next: ToolCallGroupProps = { toolCalls: [tc1], formatSummary: fn2 };
+    expect(toolCallGroupPropsEqual(prev, next)).toBe(false);
+  });
+
+  it("handles empty arrays", () => {
+    const prev: ToolCallGroupProps = { toolCalls: [] };
+    const next: ToolCallGroupProps = { toolCalls: [] };
+    expect(toolCallGroupPropsEqual(prev, next)).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildThreadItems — toolCalls array reuse
+// ---------------------------------------------------------------------------
+
+describe("buildThreadItems toolCalls array reuse", () => {
+  it("reuses msg.toolCalls reference when no task tools are present", () => {
+    const tc1 = makeToolCall("shell", "tc-1");
+    const tc2 = makeToolCall("read_file", "tc-2");
+    const aiMsg = makeMessage(MessageType.MESSAGE_AI, "using tools", {
+      toolCalls: [tc1, tc2],
+    });
+
+    const exec = makeExecution({ id: "exec-1", messages: [aiMsg] });
+    const items = buildThreadItems([exec], null, null, false, undefined);
+
+    const toolGroup = items.find((i) => i.kind === "tool-group");
+    expect(toolGroup).toBeDefined();
+    if (toolGroup?.kind === "tool-group") {
+      expect(toolGroup.toolCalls).toBe(aiMsg.toolCalls);
+    }
+  });
+
+  it("creates a new array when task tools are present", () => {
+    const tc1 = makeToolCall("shell", "tc-1");
+    const tc2 = makeToolCall("task", "sa-1");
+    const sa = makeSubAgent("sa-1");
+    const aiMsg = makeMessage(MessageType.MESSAGE_AI, "delegating", {
+      toolCalls: [tc1, tc2],
+    });
+
+    const exec = makeExecution({
+      id: "exec-1",
+      messages: [aiMsg],
+      subAgents: [sa],
+    });
+    const items = buildThreadItems([exec], null, null, false, undefined);
+
+    const toolGroup = items.find((i) => i.kind === "tool-group");
+    expect(toolGroup).toBeDefined();
+    if (toolGroup?.kind === "tool-group") {
+      expect(toolGroup.toolCalls).not.toBe(aiMsg.toolCalls);
+      expect(toolGroup.toolCalls).toHaveLength(1);
+      expect(toolGroup.toolCalls[0]).toBe(tc1);
+    }
+
+    const subAgentItem = items.find((i) => i.kind === "sub-agent");
+    expect(subAgentItem).toBeDefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Structural sharing + memoization integration
+// ---------------------------------------------------------------------------
+
+describe("structural sharing preserves references for memo boundaries", () => {
+  it("completed messages keep the same reference across stream updates", () => {
+    const humanMsg = makeMessage(MessageType.MESSAGE_HUMAN, "Hello");
+    const completedAi = makeMessage(MessageType.MESSAGE_AI, "Full response");
+
+    const prev = makeExecution({
+      id: "exec-1",
+      phase: ExecutionPhase.EXECUTION_IN_PROGRESS,
+      messages: [
+        humanMsg,
+        completedAi,
+        makeMessage(MessageType.MESSAGE_AI, "streaming par", { isStreaming: true }),
+      ],
+    });
+
+    const next = makeExecution({
+      id: "exec-1",
+      phase: ExecutionPhase.EXECUTION_IN_PROGRESS,
+      messages: [
+        makeMessage(MessageType.MESSAGE_HUMAN, "Hello"),
+        makeMessage(MessageType.MESSAGE_AI, "Full response"),
+        makeMessage(MessageType.MESSAGE_AI, "streaming partial text grow", {
+          isStreaming: true,
+        }),
+      ],
+    });
+
+    const shared = structuralShare(prev, next);
+
+    expect(shared.status!.messages[0]).toBe(humanMsg);
+    expect(shared.status!.messages[1]).toBe(completedAi);
+    expect(shared.status!.messages[2]).not.toBe(prev.status!.messages[2]);
+  });
+
+  it("toolCalls within completed messages keep their references", () => {
+    const tc1 = makeToolCall("shell", "tc-1");
+    const tc2 = makeToolCall("read_file", "tc-2");
+    const aiMsg = makeMessage(MessageType.MESSAGE_AI, "tools done", {
+      toolCalls: [tc1, tc2],
+    });
+
+    const prev = makeExecution({
+      id: "exec-1",
+      phase: ExecutionPhase.EXECUTION_IN_PROGRESS,
+      messages: [
+        aiMsg,
+        makeMessage(MessageType.MESSAGE_AI, "now streaming", { isStreaming: true }),
+      ],
+    });
+
+    const next = makeExecution({
+      id: "exec-1",
+      phase: ExecutionPhase.EXECUTION_IN_PROGRESS,
+      messages: [
+        makeMessage(MessageType.MESSAGE_AI, "tools done", {
+          toolCalls: [
+            makeToolCall("shell", "tc-1"),
+            makeToolCall("read_file", "tc-2"),
+          ],
+        }),
+        makeMessage(MessageType.MESSAGE_AI, "now streaming more", {
+          isStreaming: true,
+        }),
+      ],
+    });
+
+    const shared = structuralShare(prev, next);
+
+    expect(shared.status!.messages[0]).toBe(aiMsg);
+    expect(shared.status!.messages[0].toolCalls[0]).toBe(tc1);
+    expect(shared.status!.messages[0].toolCalls[1]).toBe(tc2);
+  });
+
+  it("buildThreadItems with shared execution preserves tool group stability", () => {
+    const tc1 = makeToolCall("shell", "tc-1");
+    const completedMsg = makeMessage(MessageType.MESSAGE_AI, "used tools", {
+      toolCalls: [tc1],
+    });
+
+    const prev = makeExecution({
+      id: "exec-1",
+      phase: ExecutionPhase.EXECUTION_IN_PROGRESS,
+      messages: [
+        completedMsg,
+        makeMessage(MessageType.MESSAGE_AI, "stream", { isStreaming: true }),
+      ],
+    });
+
+    const next = makeExecution({
+      id: "exec-1",
+      phase: ExecutionPhase.EXECUTION_IN_PROGRESS,
+      messages: [
+        makeMessage(MessageType.MESSAGE_AI, "used tools", {
+          toolCalls: [makeToolCall("shell", "tc-1")],
+        }),
+        makeMessage(MessageType.MESSAGE_AI, "stream grows", {
+          isStreaming: true,
+        }),
+      ],
+    });
+
+    const shared = structuralShare(prev, next);
+
+    const itemsPrev = buildThreadItems([], prev, null, false, undefined);
+    const itemsNext = buildThreadItems([], shared, null, false, undefined);
+
+    const prevToolGroup = itemsPrev.find((i) => i.kind === "tool-group");
+    const nextToolGroup = itemsNext.find((i) => i.kind === "tool-group");
+
+    expect(prevToolGroup).toBeDefined();
+    expect(nextToolGroup).toBeDefined();
+
+    if (prevToolGroup?.kind === "tool-group" && nextToolGroup?.kind === "tool-group") {
+      expect(nextToolGroup.toolCalls).toBe(shared.status!.messages[0].toolCalls);
+      expect(nextToolGroup.toolCalls[0]).toBe(tc1);
+    }
+  });
+});

package/src/execution/__tests__/thread-skeleton.test.tsx

@@ -0,0 +1,44 @@
+import { describe, it, expect } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { ThreadSkeleton } from "../ThreadSkeleton";
+
+describe("ThreadSkeleton", () => {
+  it("renders with aria-busy and loading label", () => {
+    const { container } = render(<ThreadSkeleton />);
+
+    const root = container.firstElementChild as HTMLElement;
+    expect(root.getAttribute("aria-busy")).toBe("true");
+    expect(root.getAttribute("aria-label")).toBe("Loading conversation");
+  });
+
+  it("renders human message bubble silhouettes", () => {
+    const { container } = render(<ThreadSkeleton />);
+
+    const humanBubbles = container.querySelectorAll("[class*='ms-']");
+    expect(humanBubbles.length).toBe(2);
+  });
+
+  it("renders AI response line silhouettes", () => {
+    const { container } = render(<ThreadSkeleton />);
+
+    const pulseContainer = container.querySelector(".animate-pulse");
+    expect(pulseContainer).toBeTruthy();
+
+    const lines = pulseContainer!.querySelectorAll("[style]");
+    expect(lines.length).toBe(7);
+  });
+
+  it("applies custom className", () => {
+    const { container } = render(<ThreadSkeleton className="my-custom-class" />);
+
+    const root = container.firstElementChild as HTMLElement;
+    expect(root.className).toContain("my-custom-class");
+  });
+
+  it("uses muted color tokens for skeleton bars", () => {
+    const { container } = render(<ThreadSkeleton />);
+
+    const bars = container.querySelectorAll("[class*='bg-muted']");
+    expect(bars.length).toBeGreaterThan(0);
+  });
+});

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

@@ -12,6 +12,10 @@ import type { Stigmer } from "@stigmer/sdk";
 import { StigmerContext } from "../../context";
 import { useExecutionStream } from "../useExecutionStream";
 
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
 /**
  * Creates a controllable async generator. Call `push(value)` to yield
  * the next value, `finish()` to end the stream, or `fail(err)` to
@@ -61,7 +65,9 @@ function makeSnapshot(phase: ExecutionPhase): AgentExecution {
   return exec;
 }
 
-function createMockStigmer(subscribeFn: Stigmer["agentExecution"]["subscribe"]) {
+function createMockStigmer(
+  subscribeFn: Stigmer["agentExecution"]["subscribe"],
+) {
   return {
     agentExecution: { subscribe: subscribeFn },
   } as unknown as Stigmer;
@@ -70,11 +76,17 @@ function createMockStigmer(subscribeFn: Stigmer["agentExecution"]["subscribe"])
 function createWrapper(client: Stigmer) {
   return function Wrapper({ children }: { children: ReactNode }) {
     return (
-      <StigmerContext.Provider value={client}>{children}</StigmerContext.Provider>
+      <StigmerContext.Provider value={client}>
+        {children}
+      </StigmerContext.Provider>
     );
   };
 }
 
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
 describe("useExecutionStream", () => {
   let stream: ReturnType<typeof createControllableStream<AgentExecution>>;
   let subscribeFn: ReturnType<typeof vi.fn>;
@@ -98,12 +110,14 @@ describe("useExecutionStream", () => {
     expect(subscribeFn).not.toHaveBeenCalled();
   });
 
-  it("starts in isConnecting state when given an ID", () => {
+  it("starts in isConnecting state when given an ID", async () => {
     const { result } = renderHook(() => useExecutionStream("exec-1"), {
       wrapper: createWrapper(mockStigmer),
     });
 
-    expect(result.current.isConnecting).toBe(true);
+    await waitFor(() => {
+      expect(result.current.isConnecting).toBe(true);
+    });
     expect(result.current.isStreaming).toBe(false);
     expect(result.current.execution).toBeNull();
   });
@@ -129,18 +143,25 @@ describe("useExecutionStream", () => {
       wrapper: createWrapper(mockStigmer),
     });
 
-    const snap1 = makeSnapshot(ExecutionPhase.EXECUTION_PENDING);
-    act(() => stream.push(snap1));
+    act(() => {
+      stream.push(makeSnapshot(ExecutionPhase.EXECUTION_PENDING));
+    });
 
     await waitFor(() => {
-      expect(result.current.execution).toBe(snap1);
+      expect(result.current.execution).not.toBeNull();
+      expect(result.current.execution?.status?.phase).toBe(
+        ExecutionPhase.EXECUTION_PENDING,
+      );
     });
 
-    const snap2 = makeSnapshot(ExecutionPhase.EXECUTION_IN_PROGRESS);
-    act(() => stream.push(snap2));
+    act(() => {
+      stream.push(makeSnapshot(ExecutionPhase.EXECUTION_IN_PROGRESS));
+    });
 
     await waitFor(() => {
-      expect(result.current.execution).toBe(snap2);
+      expect(result.current.execution?.status?.phase).toBe(
+        ExecutionPhase.EXECUTION_IN_PROGRESS,
+      );
     });
   });
 
@@ -222,8 +243,10 @@ describe("useExecutionStream", () => {
 
     rerender({ id: "exec-2" });
 
-    expect(result.current.isConnecting).toBe(true);
-    expect(result.current.execution).toBeNull();
+    await waitFor(() => {
+      expect(result.current.isConnecting).toBe(true);
+      expect(result.current.execution).toBeNull();
+    });
     expect(subscribeFn).toHaveBeenCalledTimes(2);
   });
 
@@ -239,4 +262,78 @@ describe("useExecutionStream", () => {
 
     expect(signal.aborted).toBe(true);
   });
+
+  it("resets state when executionId becomes null", async () => {
+    const { result, rerender } = renderHook(
+      ({ id }: { id: string | null }) => useExecutionStream(id),
+      {
+        wrapper: createWrapper(mockStigmer),
+        initialProps: { id: "exec-1" as string | null },
+      },
+    );
+
+    act(() => {
+      stream.push(makeSnapshot(ExecutionPhase.EXECUTION_IN_PROGRESS));
+    });
+
+    await waitFor(() => {
+      expect(result.current.execution).not.toBeNull();
+    });
+
+    rerender({ id: null });
+
+    await waitFor(() => {
+      expect(result.current.execution).toBeNull();
+      expect(result.current.isConnecting).toBe(false);
+      expect(result.current.isStreaming).toBe(false);
+    });
+  });
+
+  it("derives phase from execution snapshot", async () => {
+    const { result } = renderHook(() => useExecutionStream("exec-1"), {
+      wrapper: createWrapper(mockStigmer),
+    });
+
+    expect(result.current.phase).toBe(
+      ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED,
+    );
+
+    act(() => {
+      stream.push(makeSnapshot(ExecutionPhase.EXECUTION_IN_PROGRESS));
+    });
+
+    await waitFor(() => {
+      expect(result.current.phase).toBe(
+        ExecutionPhase.EXECUTION_IN_PROGRESS,
+      );
+    });
+  });
+
+  it("handles all terminal phases correctly", async () => {
+    for (const terminalPhase of [
+      ExecutionPhase.EXECUTION_COMPLETED,
+      ExecutionPhase.EXECUTION_FAILED,
+      ExecutionPhase.EXECUTION_CANCELLED,
+      ExecutionPhase.EXECUTION_TERMINATED,
+    ]) {
+      const localStream = createControllableStream<AgentExecution>();
+      subscribeFn.mockReturnValue(localStream.generator);
+
+      const { result, unmount } = renderHook(
+        () => useExecutionStream("exec-terminal"),
+        { wrapper: createWrapper(mockStigmer) },
+      );
+
+      act(() => {
+        localStream.push(makeSnapshot(terminalPhase));
+      });
+
+      await waitFor(() => {
+        expect(result.current.isStreaming).toBe(false);
+        expect(result.current.phase).toBe(terminalPhase);
+      });
+
+      unmount();
+    }
+  });
 });

package/src/execution/__tests__/useSessionVariables-stability.test.ts

@@ -0,0 +1,95 @@
+import { describe, it, expect } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import { useSessionVariables } from "../useSessionVariables";
+
+describe("useSessionVariables — return reference stability", () => {
+  it("returns the same object reference across re-renders when state is unchanged", () => {
+    const { result, rerender } = renderHook(() => useSessionVariables());
+
+    const first = result.current;
+    rerender();
+    const second = result.current;
+
+    expect(second).toBe(first);
+  });
+
+  it("returns a new reference after adding an entry", () => {
+    const { result } = renderHook(() => useSessionVariables());
+
+    const before = result.current;
+
+    act(() => {
+      result.current.addEntry();
+    });
+
+    expect(result.current).not.toBe(before);
+    expect(result.current.entries).toHaveLength(1);
+    expect(result.current.isEmpty).toBe(false);
+  });
+
+  it("stabilizes after mutation — re-renders without state change preserve reference", () => {
+    const { result, rerender } = renderHook(() => useSessionVariables());
+
+    act(() => {
+      result.current.addEntry();
+    });
+
+    const afterAdd = result.current;
+    rerender();
+
+    expect(result.current).toBe(afterAdd);
+  });
+
+  it("callback references are stable across re-renders", () => {
+    const { result, rerender } = renderHook(() => useSessionVariables());
+
+    const { addEntry, removeEntry, updateEntry, clear, toRuntimeEnv, toSaveForFutureEnv } =
+      result.current;
+
+    rerender();
+
+    expect(result.current.addEntry).toBe(addEntry);
+    expect(result.current.removeEntry).toBe(removeEntry);
+    expect(result.current.updateEntry).toBe(updateEntry);
+    expect(result.current.clear).toBe(clear);
+    expect(result.current.toRuntimeEnv).toBe(toRuntimeEnv);
+    expect(result.current.toSaveForFutureEnv).toBe(toSaveForFutureEnv);
+  });
+
+  it("returns a new reference after clearing", () => {
+    const { result } = renderHook(() => useSessionVariables());
+
+    act(() => {
+      result.current.addEntry();
+    });
+
+    const withEntry = result.current;
+
+    act(() => {
+      result.current.clear();
+    });
+
+    expect(result.current).not.toBe(withEntry);
+    expect(result.current.isEmpty).toBe(true);
+  });
+
+  it("derived booleans update correctly on state change", () => {
+    const { result } = renderHook(() => useSessionVariables());
+
+    expect(result.current.isEmpty).toBe(true);
+    expect(result.current.hasValidEntries).toBe(false);
+
+    act(() => {
+      result.current.addEntry();
+    });
+
+    const entryId = result.current.entries[0].id;
+
+    act(() => {
+      result.current.updateEntry(entryId, { key: "API_KEY", value: "secret123" });
+    });
+
+    expect(result.current.isEmpty).toBe(false);
+    expect(result.current.hasValidEntries).toBe(true);
+  });
+});