@stigmer/react 0.0.36 → 0.0.40

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

@@ -0,0 +1,416 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { render, screen, cleanup } from "@testing-library/react";
+import { create } from "@bufbuild/protobuf";
+
+afterEach(cleanup);
+import {
+  AgentExecutionSchema,
+  AgentExecutionStatusSchema,
+  type AgentExecution,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { SubAgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/subagent_pb";
+import {
+  UsageMetricsSchema,
+  ModelUsageSchema,
+  type ModelUsage,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/usage_pb";
+import {
+  ExecutionCostSummary,
+  formatCost,
+  formatTokenCount,
+} from "../ExecutionCostSummary";
+
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+
+function makeUsage(
+  overrides: Partial<{
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    llmCallCount: number;
+    estimatedCostUsd: number;
+    primaryModel: string;
+    primaryProvider: string;
+    cacheCreationTokens: number;
+    cacheReadTokens: number;
+  }> = {},
+) {
+  return create(UsageMetricsSchema, overrides);
+}
+
+function makeUsageWithModels(
+  overrides: {
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+    llmCallCount?: number;
+    estimatedCostUsd?: number;
+    primaryModel?: string;
+    primaryProvider?: string;
+    cacheCreationTokens?: number;
+    cacheReadTokens?: number;
+    modelBreakdown?: ModelUsage[];
+  } = {},
+) {
+  return create(UsageMetricsSchema, overrides);
+}
+
+function makeModelUsage(
+  model: string,
+  provider: string,
+  overrides: Partial<{
+    inputTokens: number;
+    outputTokens: number;
+    callCount: number;
+    estimatedCostUsd: number;
+  }> = {},
+) {
+  return create(ModelUsageSchema, { model, provider, ...overrides });
+}
+
+function makeExecution(
+  mainUsage?: ReturnType<typeof makeUsage>,
+  subAgents: Array<{
+    name: string;
+    usage?: ReturnType<typeof makeUsage>;
+  }> = [],
+): AgentExecution {
+  const status = create(AgentExecutionStatusSchema, {
+    usage: mainUsage,
+    subAgentExecutions: subAgents.map((s) =>
+      create(SubAgentExecutionSchema, { name: s.name, usage: s.usage }),
+    ),
+  });
+  return create(AgentExecutionSchema, { status });
+}
+
+// ---------------------------------------------------------------------------
+// formatCost
+// ---------------------------------------------------------------------------
+
+describe("formatCost", () => {
+  it("formats zero as $0.00", () => {
+    expect(formatCost(0)).toBe("$0.00");
+  });
+
+  it("formats sub-dollar with 4 decimal places", () => {
+    expect(formatCost(0.0042)).toBe("$0.0042");
+  });
+
+  it("formats sub-dollar with trailing zeros", () => {
+    expect(formatCost(0.15)).toBe("$0.1500");
+  });
+
+  it("formats $1+ with 2 decimal places", () => {
+    expect(formatCost(1.5)).toBe("$1.50");
+  });
+
+  it("rounds $1+ to 2 decimal places", () => {
+    expect(formatCost(123.456)).toBe("$123.46");
+  });
+
+  it("formats exactly $1 with 2 decimal places", () => {
+    expect(formatCost(1)).toBe("$1.00");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// formatTokenCount
+// ---------------------------------------------------------------------------
+
+describe("formatTokenCount", () => {
+  it("formats zero", () => {
+    expect(formatTokenCount(0)).toBe("0");
+  });
+
+  it("formats small numbers without commas", () => {
+    expect(formatTokenCount(999)).toBe("999");
+  });
+
+  it("formats thousands with commas", () => {
+    expect(formatTokenCount(1234)).toBe("1,234");
+  });
+
+  it("formats millions with commas", () => {
+    expect(formatTokenCount(1234567)).toBe("1,234,567");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// ExecutionCostSummary — component rendering
+// ---------------------------------------------------------------------------
+
+describe("ExecutionCostSummary", () => {
+  it("returns null when execution is null", () => {
+    const { container } = render(
+      <ExecutionCostSummary execution={null} />,
+    );
+    expect(container.innerHTML).toBe("");
+  });
+
+  it("returns null when usage is not yet available", () => {
+    const execution = create(AgentExecutionSchema, {
+      status: create(AgentExecutionStatusSchema),
+    });
+    const { container } = render(
+      <ExecutionCostSummary execution={execution} />,
+    );
+    expect(container.innerHTML).toBe("");
+  });
+
+  it("renders cost, tokens, calls, and model for a basic execution", () => {
+    const execution = makeExecution(
+      makeUsage({
+        estimatedCostUsd: 0.0042,
+        totalTokens: 1234,
+        promptTokens: 1000,
+        completionTokens: 234,
+        llmCallCount: 3,
+        primaryModel: "claude-sonnet-4",
+        primaryProvider: "anthropic",
+      }),
+    );
+
+    render(<ExecutionCostSummary execution={execution} />);
+
+    expect(screen.getByText("$0.0042")).toBeTruthy();
+    expect(screen.getByText("claude-sonnet-4 · anthropic")).toBeTruthy();
+    expect(screen.getByText(/1,234 tokens/)).toBeTruthy();
+    expect(screen.getByText(/3 calls/)).toBeTruthy();
+  });
+
+  it("renders token breakdown with prompt and completion", () => {
+    const execution = makeExecution(
+      makeUsage({
+        totalTokens: 1234,
+        promptTokens: 1000,
+        completionTokens: 234,
+        llmCallCount: 1,
+      }),
+    );
+
+    render(<ExecutionCostSummary execution={execution} />);
+
+    expect(screen.getByText(/prompt 1,000/)).toBeTruthy();
+    expect(screen.getByText(/completion 234/)).toBeTruthy();
+  });
+
+  it("uses singular 'call' for a single LLM call", () => {
+    const execution = makeExecution(
+      makeUsage({
+        llmCallCount: 1,
+        totalTokens: 100,
+        promptTokens: 80,
+        completionTokens: 20,
+      }),
+    );
+
+    render(<ExecutionCostSummary execution={execution} />);
+
+    const metricsLine = screen.getByText(/100 tokens/);
+    expect(metricsLine.textContent).toContain("1 call");
+    expect(metricsLine.textContent).not.toContain("1 calls");
+  });
+
+  it("does not show cache line when cache tokens are zero", () => {
+    const execution = makeExecution(
+      makeUsage({
+        totalTokens: 100,
+        promptTokens: 80,
+        completionTokens: 20,
+      }),
+    );
+
+    const { container } = render(
+      <ExecutionCostSummary execution={execution} />,
+    );
+    expect(container.textContent).not.toContain("cache");
+  });
+
+  it("shows cache read tokens when present", () => {
+    const execution = makeExecution(
+      makeUsage({
+        totalTokens: 100,
+        promptTokens: 80,
+        completionTokens: 20,
+        cacheReadTokens: 500,
+      }),
+    );
+
+    const { container } = render(
+      <ExecutionCostSummary execution={execution} />,
+    );
+    expect(container.textContent).toContain("cache");
+    expect(container.textContent).toContain("500 read");
+    expect(container.textContent).not.toContain("write");
+  });
+
+  it("shows cache write tokens when present", () => {
+    const execution = makeExecution(
+      makeUsage({
+        totalTokens: 100,
+        promptTokens: 80,
+        completionTokens: 20,
+        cacheCreationTokens: 200,
+      }),
+    );
+
+    const { container } = render(
+      <ExecutionCostSummary execution={execution} />,
+    );
+    expect(container.textContent).toContain("cache");
+    expect(container.textContent).toContain("200 write");
+    expect(container.textContent).not.toContain("read");
+  });
+
+  it("shows both cache read and write when both present", () => {
+    const execution = makeExecution(
+      makeUsage({
+        totalTokens: 100,
+        promptTokens: 80,
+        completionTokens: 20,
+        cacheReadTokens: 500,
+        cacheCreationTokens: 100,
+      }),
+    );
+
+    const { container } = render(
+      <ExecutionCostSummary execution={execution} />,
+    );
+    expect(container.textContent).toContain("500 read");
+    expect(container.textContent).toContain("100 write");
+  });
+
+  it("shows sub-agent annotation when sub-agents have usage", () => {
+    const execution = makeExecution(
+      makeUsage({
+        totalTokens: 1000,
+        promptTokens: 800,
+        completionTokens: 200,
+      }),
+      [
+        { name: "researcher", usage: makeUsage({ totalTokens: 500 }) },
+        { name: "writer", usage: makeUsage({ totalTokens: 300 }) },
+      ],
+    );
+
+    render(<ExecutionCostSummary execution={execution} />);
+    expect(screen.getByText("Includes 2 sub-agents")).toBeTruthy();
+  });
+
+  it("uses singular 'sub-agent' for one sub-agent", () => {
+    const execution = makeExecution(
+      makeUsage({
+        totalTokens: 1000,
+        promptTokens: 800,
+        completionTokens: 200,
+      }),
+      [{ name: "researcher", usage: makeUsage({ totalTokens: 500 }) }],
+    );
+
+    render(<ExecutionCostSummary execution={execution} />);
+    expect(screen.getByText("Includes 1 sub-agent")).toBeTruthy();
+  });
+
+  it("does not show sub-agent annotation when no sub-agents have usage", () => {
+    const execution = makeExecution(
+      makeUsage({
+        totalTokens: 1000,
+        promptTokens: 800,
+        completionTokens: 200,
+      }),
+      [{ name: "idle-agent" }],
+    );
+
+    const { container } = render(
+      <ExecutionCostSummary execution={execution} />,
+    );
+    expect(container.textContent).not.toContain("sub-agent");
+  });
+
+  it("shows per-model breakdown when multiple models exist", () => {
+    const execution = makeExecution(
+      makeUsageWithModels({
+        totalTokens: 2000,
+        promptTokens: 1500,
+        completionTokens: 500,
+        estimatedCostUsd: 0.0142,
+        primaryModel: "claude-sonnet-4",
+        primaryProvider: "anthropic",
+        modelBreakdown: [
+          makeModelUsage("claude-sonnet-4", "anthropic", {
+            estimatedCostUsd: 0.012,
+          }),
+          makeModelUsage("gpt-4o", "openai", {
+            estimatedCostUsd: 0.0022,
+          }),
+        ],
+      }),
+    );
+
+    render(<ExecutionCostSummary execution={execution} />);
+
+    expect(screen.getByText("claude-sonnet-4")).toBeTruthy();
+    expect(screen.getByText("$0.0120")).toBeTruthy();
+    expect(screen.getByText("gpt-4o")).toBeTruthy();
+    expect(screen.getByText("$0.0022")).toBeTruthy();
+    expect(
+      screen.queryByText("claude-sonnet-4 · anthropic"),
+    ).toBeNull();
+  });
+
+  it("shows model breakdown list with proper accessibility", () => {
+    const execution = makeExecution(
+      makeUsageWithModels({
+        totalTokens: 2000,
+        promptTokens: 1500,
+        completionTokens: 500,
+        modelBreakdown: [
+          makeModelUsage("model-a", "provider-a"),
+          makeModelUsage("model-b", "provider-b"),
+        ],
+      }),
+    );
+
+    render(<ExecutionCostSummary execution={execution} />);
+
+    expect(
+      screen.getByRole("list", { name: "Model cost breakdown" }),
+    ).toBeTruthy();
+  });
+
+  it("has proper region role and aria-label", () => {
+    const execution = makeExecution(
+      makeUsage({
+        totalTokens: 100,
+        promptTokens: 80,
+        completionTokens: 20,
+      }),
+    );
+
+    render(<ExecutionCostSummary execution={execution} />);
+
+    expect(
+      screen.getByRole("region", { name: "Execution cost summary" }),
+    ).toBeTruthy();
+  });
+
+  it("accepts and applies className", () => {
+    const execution = makeExecution(
+      makeUsage({
+        totalTokens: 100,
+        promptTokens: 80,
+        completionTokens: 20,
+      }),
+    );
+
+    render(
+      <ExecutionCostSummary execution={execution} className="my-custom" />,
+    );
+
+    const region = screen.getByRole("region");
+    expect(region.className).toContain("my-custom");
+  });
+});

package/src/execution/__tests__/execution-phases.test.ts

@@ -0,0 +1,31 @@
+import { describe, it, expect } from "vitest";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { isTerminalPhase } from "../execution-phases";
+
+describe("isTerminalPhase", () => {
+  const terminalPhases = [
+    ExecutionPhase.EXECUTION_COMPLETED,
+    ExecutionPhase.EXECUTION_FAILED,
+    ExecutionPhase.EXECUTION_CANCELLED,
+    ExecutionPhase.EXECUTION_TERMINATED,
+  ];
+
+  it.each(terminalPhases)("returns true for terminal phase %i", (phase) => {
+    expect(isTerminalPhase(phase)).toBe(true);
+  });
+
+  const nonTerminalPhases = [
+    ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED,
+    ExecutionPhase.EXECUTION_PENDING,
+    ExecutionPhase.EXECUTION_IN_PROGRESS,
+    ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL,
+    ExecutionPhase.EXECUTION_PAUSED,
+  ];
+
+  it.each(nonTerminalPhases)(
+    "returns false for non-terminal phase %i",
+    (phase) => {
+      expect(isTerminalPhase(phase)).toBe(false);
+    },
+  );
+});

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

@@ -0,0 +1,242 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook, act, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { create } from "@bufbuild/protobuf";
+import {
+  AgentExecutionSchema,
+  AgentExecutionStatusSchema,
+  type AgentExecution,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { Stigmer } from "@stigmer/sdk";
+import { StigmerContext } from "../../context";
+import { useExecutionStream } from "../useExecutionStream";
+
+/**
+ * Creates a controllable async generator. Call `push(value)` to yield
+ * the next value, `finish()` to end the stream, or `fail(err)` to
+ * throw an error from the stream.
+ */
+function createControllableStream<T>() {
+  let resolve: ((v: IteratorResult<T>) => void) | null = null;
+  let reject: ((err: unknown) => void) | null = null;
+
+  const generator: AsyncGenerator<T> = {
+    next() {
+      return new Promise<IteratorResult<T>>((res, rej) => {
+        resolve = res;
+        reject = rej;
+      });
+    },
+    return(value?: unknown) {
+      return Promise.resolve({ done: true as const, value: value as T });
+    },
+    throw(err?: unknown) {
+      return Promise.reject(err);
+    },
+    [Symbol.asyncIterator]() {
+      return generator;
+    },
+  };
+
+  return {
+    generator,
+    push(value: T) {
+      resolve?.({ done: false, value });
+    },
+    finish() {
+      resolve?.({ done: true, value: undefined as unknown as T });
+    },
+    fail(err: Error) {
+      reject?.(err);
+    },
+  };
+}
+
+function makeSnapshot(phase: ExecutionPhase): AgentExecution {
+  const exec = create(AgentExecutionSchema);
+  const status = create(AgentExecutionStatusSchema);
+  status.phase = phase;
+  exec.status = status;
+  return exec;
+}
+
+function createMockStigmer(subscribeFn: Stigmer["agentExecution"]["subscribe"]) {
+  return {
+    agentExecution: { subscribe: subscribeFn },
+  } as unknown as Stigmer;
+}
+
+function createWrapper(client: Stigmer) {
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <StigmerContext.Provider value={client}>{children}</StigmerContext.Provider>
+    );
+  };
+}
+
+describe("useExecutionStream", () => {
+  let stream: ReturnType<typeof createControllableStream<AgentExecution>>;
+  let subscribeFn: ReturnType<typeof vi.fn>;
+  let mockStigmer: Stigmer;
+
+  beforeEach(() => {
+    stream = createControllableStream<AgentExecution>();
+    subscribeFn = vi.fn().mockReturnValue(stream.generator);
+    mockStigmer = createMockStigmer(subscribeFn);
+  });
+
+  it("returns idle state when executionId is null", () => {
+    const { result } = renderHook(() => useExecutionStream(null), {
+      wrapper: createWrapper(mockStigmer),
+    });
+
+    expect(result.current.execution).toBeNull();
+    expect(result.current.isConnecting).toBe(false);
+    expect(result.current.isStreaming).toBe(false);
+    expect(result.current.error).toBeNull();
+    expect(subscribeFn).not.toHaveBeenCalled();
+  });
+
+  it("starts in isConnecting state when given an ID", () => {
+    const { result } = renderHook(() => useExecutionStream("exec-1"), {
+      wrapper: createWrapper(mockStigmer),
+    });
+
+    expect(result.current.isConnecting).toBe(true);
+    expect(result.current.isStreaming).toBe(false);
+    expect(result.current.execution).toBeNull();
+  });
+
+  it("transitions to isStreaming after first non-terminal snapshot", async () => {
+    const { result } = renderHook(() => useExecutionStream("exec-1"), {
+      wrapper: createWrapper(mockStigmer),
+    });
+
+    act(() => {
+      stream.push(makeSnapshot(ExecutionPhase.EXECUTION_IN_PROGRESS));
+    });
+
+    await waitFor(() => {
+      expect(result.current.isStreaming).toBe(true);
+      expect(result.current.isConnecting).toBe(false);
+      expect(result.current.execution).not.toBeNull();
+    });
+  });
+
+  it("updates execution with each streamed snapshot", async () => {
+    const { result } = renderHook(() => useExecutionStream("exec-1"), {
+      wrapper: createWrapper(mockStigmer),
+    });
+
+    const snap1 = makeSnapshot(ExecutionPhase.EXECUTION_PENDING);
+    act(() => stream.push(snap1));
+
+    await waitFor(() => {
+      expect(result.current.execution).toBe(snap1);
+    });
+
+    const snap2 = makeSnapshot(ExecutionPhase.EXECUTION_IN_PROGRESS);
+    act(() => stream.push(snap2));
+
+    await waitFor(() => {
+      expect(result.current.execution).toBe(snap2);
+    });
+  });
+
+  it("sets isStreaming to false when a terminal phase is received", async () => {
+    const { result } = renderHook(() => useExecutionStream("exec-1"), {
+      wrapper: createWrapper(mockStigmer),
+    });
+
+    act(() => {
+      stream.push(makeSnapshot(ExecutionPhase.EXECUTION_COMPLETED));
+    });
+
+    await waitFor(() => {
+      expect(result.current.isStreaming).toBe(false);
+      expect(result.current.execution).not.toBeNull();
+      expect(result.current.phase).toBe(ExecutionPhase.EXECUTION_COMPLETED);
+    });
+  });
+
+  it("sets error when the stream throws", async () => {
+    const { result } = renderHook(() => useExecutionStream("exec-1"), {
+      wrapper: createWrapper(mockStigmer),
+    });
+
+    act(() => {
+      stream.fail(new Error("connection lost"));
+    });
+
+    await waitFor(() => {
+      expect(result.current.error?.message).toBe("connection lost");
+      expect(result.current.isConnecting).toBe(false);
+      expect(result.current.isStreaming).toBe(false);
+    });
+  });
+
+  it("reconnect clears error and re-subscribes", async () => {
+    const { result } = renderHook(() => useExecutionStream("exec-1"), {
+      wrapper: createWrapper(mockStigmer),
+    });
+
+    act(() => stream.fail(new Error("timeout")));
+
+    await waitFor(() => {
+      expect(result.current.error?.message).toBe("timeout");
+    });
+
+    const newStream = createControllableStream<AgentExecution>();
+    subscribeFn.mockReturnValue(newStream.generator);
+
+    act(() => result.current.reconnect());
+
+    await waitFor(() => {
+      expect(result.current.error).toBeNull();
+      expect(result.current.isConnecting).toBe(true);
+    });
+
+    expect(subscribeFn).toHaveBeenCalledTimes(2);
+  });
+
+  it("aborts previous subscription when executionId changes", async () => {
+    const { result, rerender } = renderHook(
+      ({ id }: { id: string | null }) => useExecutionStream(id),
+      {
+        wrapper: createWrapper(mockStigmer),
+        initialProps: { id: "exec-1" },
+      },
+    );
+
+    act(() => {
+      stream.push(makeSnapshot(ExecutionPhase.EXECUTION_IN_PROGRESS));
+    });
+
+    await waitFor(() => {
+      expect(result.current.isStreaming).toBe(true);
+    });
+
+    const newStream = createControllableStream<AgentExecution>();
+    subscribeFn.mockReturnValue(newStream.generator);
+
+    rerender({ id: "exec-2" });
+
+    expect(result.current.isConnecting).toBe(true);
+    expect(result.current.execution).toBeNull();
+    expect(subscribeFn).toHaveBeenCalledTimes(2);
+  });
+
+  it("cleans up subscription on unmount", () => {
+    const { unmount } = renderHook(() => useExecutionStream("exec-1"), {
+      wrapper: createWrapper(mockStigmer),
+    });
+
+    const signal = subscribeFn.mock.calls[0][1] as AbortSignal;
+    expect(signal.aborted).toBe(false);
+
+    unmount();
+
+    expect(signal.aborted).toBe(true);
+  });
+});