@stigmer/react 1.0.4 → 2.0.0

package/src/session/__tests__/useNewSessionFlow.test.tsx

@@ -4,6 +4,7 @@ import type { ReactNode } from "react";
 import { DEFAULT_MODEL_ID, DEFAULT_CURSOR_MODEL_ID, parseRegistryJson } from "../../models/registry";
 import { ModelRegistryContext } from "../../models/ModelRegistryContext";
 import type { ModelRegistryState } from "../../models/ModelRegistryContext";
+import { ExecutionTargetContext } from "../../execution-target-context";
 import type { UseCreateSessionReturn } from "../useCreateSession";
 
 const mockCreateSession = vi.fn<UseCreateSessionReturn["create"]>();
@@ -62,17 +63,6 @@ vi.mock("../../execution/useSessionVariables", () => ({
   useSessionVariables: () => mockSessionVariables,
 }));
 
-const mockRunnerList = {
-  runners: [] as { metadata?: { id: string; name?: string } }[],
-  isLoading: false,
-  isRefetching: false,
-  error: null,
-  refetch: vi.fn(),
-};
-vi.mock("../../runner/useRunnerList", () => ({
-  useRunnerList: () => mockRunnerList,
-}));
-
 import { useNewSessionFlow } from "../useNewSessionFlow";
 
 const TEST_MODELS = parseRegistryJson({
@@ -82,13 +72,15 @@ const TEST_MODELS = parseRegistryJson({
   ],
 });
 
-function createWrapper() {
+function createWrapper(executionTarget?: "local" | "cloud") {
   const state: ModelRegistryState = { models: TEST_MODELS, isLoading: false, error: null, refetch: () => {} };
   return function Wrapper({ children }: { children: ReactNode }) {
     return (
-      <ModelRegistryContext.Provider value={state}>
-        {children}
-      </ModelRegistryContext.Provider>
+      <ExecutionTargetContext.Provider value={executionTarget}>
+        <ModelRegistryContext.Provider value={state}>
+          {children}
+        </ModelRegistryContext.Provider>
+      </ExecutionTargetContext.Provider>
     );
   };
 }
@@ -113,8 +105,6 @@ describe("useNewSessionFlow", () => {
     };
     mockDefaultAgent.isLoading = false;
     mockDefaultAgent.error = null;
-    mockRunnerList.runners = [];
-    mockRunnerList.isLoading = false;
     mockCreateSession.mockResolvedValue({ sessionId: "sess-new" });
     mockCreateExecution.mockResolvedValue({});
   });
@@ -249,39 +239,6 @@ describe("useNewSessionFlow", () => {
     });
   });
 
-  describe("runner validation gate", () => {
-    it("restores runner when it exists in the live runner list", () => {
-      localStorage.setItem("stigmer:session:runner", "runner-abc");
-      mockRunnerList.runners = [{ metadata: { id: "runner-abc", name: "My Runner" } }];
-      mockRunnerList.isLoading = false;
-
-      const { result } = renderHook(() => useNewSessionFlow(defaultOptions()), { wrapper: createWrapper() });
-
-      expect(result.current.runnerId).toBe("runner-abc");
-    });
-
-    it("discards stale runner that no longer exists in the runner list", () => {
-      localStorage.setItem("stigmer:session:runner", "deleted-runner");
-      mockRunnerList.runners = [{ metadata: { id: "runner-abc", name: "My Runner" } }];
-      mockRunnerList.isLoading = false;
-
-      const { result } = renderHook(() => useNewSessionFlow(defaultOptions()), { wrapper: createWrapper() });
-
-      expect(result.current.runnerId).toBeNull();
-      expect(localStorage.getItem("stigmer:session:runner")).toBeNull();
-    });
-
-    it("does not restore runner while runner list is loading", () => {
-      localStorage.setItem("stigmer:session:runner", "runner-abc");
-      mockRunnerList.runners = [];
-      mockRunnerList.isLoading = true;
-
-      const { result } = renderHook(() => useNewSessionFlow(defaultOptions()), { wrapper: createWrapper() });
-
-      expect(result.current.runnerId).toBeNull();
-    });
-  });
-
   describe("model validation timing", () => {
     it("does not restore model while registry is loading", () => {
       localStorage.setItem(STORAGE_KEY_MODEL_NATIVE, DEFAULT_MODEL_ID);
@@ -381,6 +338,60 @@ describe("useNewSessionFlow", () => {
     });
   });
 
+  describe("submit with executionTarget", () => {
+    it("passes executionTarget to createSession when provided", async () => {
+      const opts = { ...defaultOptions(), executionTarget: "local" as const };
+      const { result } = renderHook(() => useNewSessionFlow(opts), { wrapper: createWrapper() });
+
+      await act(async () => {
+        await result.current.submit("Hello");
+      });
+
+      expect(mockCreateSession).toHaveBeenCalledOnce();
+      const sessionInput = mockCreateSession.mock.calls[0][0];
+      expect(sessionInput.executionTarget).toBe("local");
+    });
+
+    it("does not include executionTarget when not provided", async () => {
+      const opts = defaultOptions();
+      const { result } = renderHook(() => useNewSessionFlow(opts), { wrapper: createWrapper() });
+
+      await act(async () => {
+        await result.current.submit("Hello");
+      });
+
+      expect(mockCreateSession).toHaveBeenCalledOnce();
+      const sessionInput = mockCreateSession.mock.calls[0][0];
+      expect(sessionInput.executionTarget).toBeUndefined();
+    });
+
+    it("uses context executionTarget when per-hook option is omitted", async () => {
+      const opts = defaultOptions();
+      const { result } = renderHook(() => useNewSessionFlow(opts), { wrapper: createWrapper("local") });
+
+      await act(async () => {
+        await result.current.submit("Hello");
+      });
+
+      expect(mockCreateSession).toHaveBeenCalledOnce();
+      const sessionInput = mockCreateSession.mock.calls[0][0];
+      expect(sessionInput.executionTarget).toBe("local");
+    });
+
+    it("per-hook executionTarget option overrides context", async () => {
+      const opts = { ...defaultOptions(), executionTarget: "local" as const };
+      const { result } = renderHook(() => useNewSessionFlow(opts), { wrapper: createWrapper("cloud") });
+
+      await act(async () => {
+        await result.current.submit("Hello");
+      });
+
+      expect(mockCreateSession).toHaveBeenCalledOnce();
+      const sessionInput = mockCreateSession.mock.calls[0][0];
+      expect(sessionInput.executionTarget).toBe("local");
+    });
+  });
+
   describe("submit while default agent is loading", () => {
     it("awaits default agent and creates session when fetch resolves", async () => {
       const resolvedAgent = { status: { defaultInstanceId: "awaited-inst" } };

package/src/session/__tests__/useSessionUsage.test.ts

@@ -0,0 +1,180 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { GetSessionUsageReportOutput } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+
+vi.mock("../../hooks", () => ({
+  useStigmer: vi.fn(),
+}));
+
+import { useStigmer } from "../../hooks";
+import { useSessionUsage } from "../useSessionUsage";
+
+// ── Test data builders ───────────────────────────────────────────────────
+
+const SESSION_ID = "sess-1";
+
+function makeExecution(
+  phase: ExecutionPhase,
+  streamingUsage?: Record<string, unknown>,
+): AgentExecution {
+  return {
+    spec: { sessionId: SESSION_ID },
+    status: { phase, streamingUsage },
+  } as unknown as AgentExecution;
+}
+
+function streamingUsage(costUsd: number): Record<string, unknown> {
+  return {
+    inputTokens: 100n,
+    outputTokens: 20n,
+    cacheReadTokens: 0n,
+    cacheWriteTokens: 0n,
+    totalTokens: 120n,
+    turnCount: 1,
+    estimatedCostUsd: costUsd,
+    model: "claude-sonnet-4-6",
+    observedAt: "",
+  };
+}
+
+function authoritativeReport(billableMicros: bigint): GetSessionUsageReportOutput {
+  return {
+    totalUsage: {
+      llmCallCount: 2,
+      totalTokens: 120n,
+      billableCostMicros: billableMicros,
+      inputTokens: 60n,
+      outputTokens: 40n,
+      cacheReadInputTokens: 0n,
+      cacheCreationInputTokens: 0n,
+      primaryModel: "claude-sonnet-4-6",
+      primaryProvider: "cursor",
+    },
+    modelBreakdown: [],
+    isEstimated: false,
+  } as unknown as GetSessionUsageReportOutput;
+}
+
+function emptyReport(): GetSessionUsageReportOutput {
+  return {
+    totalUsage: {
+      llmCallCount: 0,
+      totalTokens: 0n,
+      billableCostMicros: 0n,
+      inputTokens: 0n,
+      outputTokens: 0n,
+      cacheReadInputTokens: 0n,
+      cacheCreationInputTokens: 0n,
+      primaryModel: "",
+      primaryProvider: "",
+    },
+    modelBreakdown: [],
+    isEstimated: true,
+  } as unknown as GetSessionUsageReportOutput;
+}
+
+function mockStigmer(getSessionUsageReport: ReturnType<typeof vi.fn>) {
+  const stigmer = { agentExecution: { getSessionUsageReport } };
+  (useStigmer as ReturnType<typeof vi.fn>).mockReturnValue(stigmer);
+}
+
+async function flush(): Promise<void> {
+  await act(async () => {
+    await Promise.resolve();
+  });
+}
+
+describe("useSessionUsage", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("falls back to the streaming estimate when no billing record exists yet", async () => {
+    const getReport = vi.fn(async () => emptyReport());
+    mockStigmer(getReport);
+
+    const executions = [makeExecution(ExecutionPhase.EXECUTION_IN_PROGRESS, streamingUsage(0.05))];
+    const { result } = renderHook(() => useSessionUsage(executions));
+
+    await flush();
+
+    expect(result.current.isEstimated).toBe(true);
+    expect(result.current.totalCostUsd).toBeCloseTo(0.05);
+    expect(result.current.primaryProvider).toBe("cursor");
+  });
+
+  it("prefers the authoritative billing report once records exist", async () => {
+    const getReport = vi.fn(async () => authoritativeReport(60_000n));
+    mockStigmer(getReport);
+
+    const executions = [makeExecution(ExecutionPhase.EXECUTION_IN_PROGRESS, streamingUsage(0.05))];
+    const { result } = renderHook(() => useSessionUsage(executions));
+
+    await flush();
+
+    expect(result.current.isEstimated).toBe(false);
+    // 60_000 micros = $0.06 billable, replacing the $0.05 estimate.
+    expect(result.current.totalCostUsd).toBeCloseTo(0.06);
+    expect(result.current.llmCallCount).toBe(2);
+  });
+
+  it("polls the usage report while an execution is in progress", async () => {
+    vi.useFakeTimers();
+    const getReport = vi.fn(async () => authoritativeReport(60_000n));
+    mockStigmer(getReport);
+
+    const executions = [makeExecution(ExecutionPhase.EXECUTION_IN_PROGRESS, streamingUsage(0.05))];
+    renderHook(() => useSessionUsage(executions));
+
+    await act(async () => {
+      await Promise.resolve();
+    });
+    expect(getReport).toHaveBeenCalledTimes(1);
+
+    // Each poll interval triggers a fresh fetch so the settled cost climbs live.
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(2500);
+    });
+    expect(getReport).toHaveBeenCalledTimes(2);
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(2500);
+    });
+    expect(getReport).toHaveBeenCalledTimes(3);
+  });
+
+  it("stops polling once all executions are terminal, after one final refetch", async () => {
+    vi.useFakeTimers();
+    const getReport = vi.fn(async () => authoritativeReport(60_000n));
+    mockStigmer(getReport);
+
+    let executions = [makeExecution(ExecutionPhase.EXECUTION_IN_PROGRESS, streamingUsage(0.05))];
+    const { rerender } = renderHook(() => useSessionUsage(executions));
+
+    await act(async () => {
+      await Promise.resolve();
+    });
+    expect(getReport).toHaveBeenCalledTimes(1);
+
+    // Execution settles — polling stops, and a single final refetch fires to
+    // capture the last turn's authoritative record promptly.
+    executions = [makeExecution(ExecutionPhase.EXECUTION_COMPLETED, streamingUsage(0.05))];
+    rerender();
+    await act(async () => {
+      await Promise.resolve();
+    });
+    expect(getReport).toHaveBeenCalledTimes(2);
+
+    // No further polling once terminal.
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(10_000);
+    });
+    expect(getReport).toHaveBeenCalledTimes(2);
+  });
+});

package/src/session/execution-target.ts

@@ -0,0 +1,39 @@
+import { ExecutionTarget } from "@stigmer/protos/ai/stigmer/agentic/session/v1/enum_pb";
+
+/**
+ * String literal alias for the proto {@link ExecutionTarget} enum.
+ *
+ * Used on hook options so platform builders do not need to import
+ * proto enums to configure where session activities execute.
+ *
+ * - `"local"` — Client's embedded runner (desktop app or CLI) polls
+ *   the session's task queue.
+ * - `"cloud"` — Server provisions a cloud sandbox with a runner.
+ */
+export type ExecutionTargetOption = "local" | "cloud";
+
+/** Convert an {@link ExecutionTargetOption} string to the proto {@link ExecutionTarget} enum. */
+export function toProtoExecutionTarget(t: ExecutionTargetOption): ExecutionTarget {
+  switch (t) {
+    case "local":
+      return ExecutionTarget.LOCAL;
+    case "cloud":
+      return ExecutionTarget.CLOUD;
+  }
+}
+
+/**
+ * Convert a proto {@link ExecutionTarget} enum to an {@link ExecutionTargetOption} string,
+ * or `undefined` when the value is `UNSPECIFIED` (server decides).
+ */
+export function fromProtoExecutionTarget(t: ExecutionTarget): ExecutionTargetOption | undefined {
+  switch (t) {
+    case ExecutionTarget.LOCAL:
+      return "local";
+    case ExecutionTarget.CLOUD:
+      return "cloud";
+    case ExecutionTarget.UNSPECIFIED:
+    default:
+      return undefined;
+  }
+}

package/src/session/index.ts

@@ -1,3 +1,6 @@
+export { toProtoExecutionTarget, fromProtoExecutionTarget } from "./execution-target";
+export type { ExecutionTargetOption } from "./execution-target";
+
 export { useCreateSession } from "./useCreateSession";
 export type {
   SharedSessionFields,
@@ -85,5 +88,32 @@ export type {
   UseSessionSearchReturn,
 } from "./useSessionSearch";
 
+// SessionViewer — full-featured session viewer organism
+export { SessionViewer } from "./SessionViewer";
+export type { SessionViewerProps } from "./SessionViewer";
+
+// NewSessionViewer — launcher organism with progressive Setup panel
+export { NewSessionViewer } from "./NewSessionViewer";
+export type { NewSessionViewerProps } from "./NewSessionViewer";
+
+// Selection types (for platform builders using SessionInspector directly)
+export type { SelectedThreadItem } from "../internal/store/selection-store";
+
+// SessionInspector — tabbed right-side inspector panel
+export {
+  SessionInspector,
+  useSessionInspector,
+  buildVisibleTabs,
+  SetupTab,
+} from "./inspector";
+export type {
+  SessionInspectorProps,
+  SessionInspectorTabId,
+  UseSessionInspectorOptions,
+  UseSessionInspectorReturn,
+  SetupTabProps,
+  SetupTabMutationCallbacks,
+} from "./inspector";
+
 // Session utilities (re-exported from @stigmer/sdk)
 export { PENDING_SUBJECT, resolvedSubject } from "@stigmer/sdk";

package/src/session/inspector/ArtifactsTab.tsx

@@ -0,0 +1,77 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import {
+  useSessionArtifacts,
+  type SessionArtifactEntry,
+} from "../useSessionArtifacts";
+import { ArtifactCard } from "../../execution/ArtifactCard";
+import { ArtifactPreviewModal } from "../../execution/ArtifactPreviewModal";
+import type { ApplyResourceResult } from "../../library/useApplyResource";
+
+export interface ArtifactsTabProps {
+  readonly executions: readonly AgentExecution[];
+  readonly org: string;
+  readonly onApplied?: (result: ApplyResourceResult) => void;
+}
+
+/**
+ * Artifacts facet for the SessionInspector.
+ *
+ * Wraps `useSessionArtifacts` → `ArtifactCard` list with
+ * `ArtifactPreviewModal` — the same content as `ArtifactsWidget`
+ * without the section heading.
+ */
+export function ArtifactsTab({ executions, org, onApplied }: ArtifactsTabProps) {
+  const { artifacts, hasArtifacts } = useSessionArtifacts(executions);
+  const [previewEntry, setPreviewEntry] = useState<SessionArtifactEntry | null>(null);
+
+  const handlePreview = useCallback((entry: SessionArtifactEntry) => {
+    setPreviewEntry(entry);
+  }, []);
+
+  const handleClosePreview = useCallback(() => {
+    setPreviewEntry(null);
+  }, []);
+
+  if (!hasArtifacts) {
+    return (
+      <div className="flex flex-col items-center justify-center px-4 py-8 text-center">
+        <p className="text-xs text-muted-foreground">
+          No artifacts yet. Files generated by the agent will appear here.
+        </p>
+      </div>
+    );
+  }
+
+  return (
+    <>
+      <div role="list" className="space-y-2">
+        {artifacts.map((entry) => (
+          <div key={entry.artifact.sandboxPath || entry.artifact.name} role="listitem">
+            <ArtifactCard
+              artifact={entry.artifact}
+              executionId={entry.executionId}
+              org={org}
+              hasNameCollision={entry.hasNameCollision}
+              onPreview={() => handlePreview(entry)}
+            />
+          </div>
+        ))}
+      </div>
+
+      {previewEntry && (
+        <ArtifactPreviewModal
+          artifact={previewEntry.artifact}
+          executionId={previewEntry.executionId}
+          isTerminal={previewEntry.isTerminal}
+          org={org}
+          open
+          onClose={handleClosePreview}
+          onApplied={onApplied}
+        />
+      )}
+    </>
+  );
+}

package/src/session/inspector/ChangesTab.tsx

@@ -0,0 +1,42 @@
+"use client";
+
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { useSessionWriteBacks } from "../useSessionWriteBacks";
+import { WriteBackCard } from "../../execution/WriteBackCard";
+
+export interface ChangesTabProps {
+  readonly executions: readonly AgentExecution[];
+}
+
+/**
+ * Changes facet for the SessionInspector.
+ *
+ * Wraps the existing `useSessionWriteBacks` hook and renders
+ * `WriteBackCard` per write-back entry — the same content as
+ * `WriteBacksWidget` but without its section heading (the tab
+ * label provides that context).
+ */
+export function ChangesTab({ executions }: ChangesTabProps) {
+  const { writeBacks, hasWriteBacks } = useSessionWriteBacks(executions);
+
+  if (!hasWriteBacks) {
+    return (
+      <div className="flex flex-col items-center justify-center px-4 py-8 text-center">
+        <p className="text-xs text-muted-foreground">
+          No pull requests yet. Changes will appear here when the agent
+          writes back to a workspace.
+        </p>
+      </div>
+    );
+  }
+
+  return (
+    <div role="list" className="space-y-2">
+      {writeBacks.map((entry) => (
+        <div key={entry.writeBack.workspaceEntryName} role="listitem">
+          <WriteBackCard writeBack={entry.writeBack} />
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/session/inspector/InspectTab.tsx

@@ -0,0 +1,57 @@
+"use client";
+
+import type { SelectedThreadItem } from "../../internal/store/selection-store";
+
+export interface InspectTabProps {
+  readonly selectedItem: SelectedThreadItem | null;
+}
+
+/**
+ * Selection-driven inspector facet (Phase 2).
+ *
+ * In Phase 1 this renders an empty hint state. Phase 2 will populate
+ * it with tool-call detail, sub-agent mini-thread, and artifact
+ * preview based on the selected thread item.
+ */
+export function InspectTab({ selectedItem }: InspectTabProps) {
+  if (!selectedItem) {
+    return (
+      <div className="flex flex-col items-center justify-center px-4 py-8 text-center">
+        <SelectItemIcon />
+        <p className="mt-2 text-xs text-muted-foreground">
+          Click a tool call or sub-agent in the thread to inspect it
+        </p>
+      </div>
+    );
+  }
+
+  return (
+    <div className="px-1 py-2 text-xs text-muted-foreground">
+      <p>
+        Inspecting: <span className="font-medium text-foreground">{selectedItem.kind}</span>
+      </p>
+      <p className="mt-1 text-[11px]">
+        Detailed view coming in Phase 2.
+      </p>
+    </div>
+  );
+}
+
+function SelectItemIcon() {
+  return (
+    <svg
+      width="20"
+      height="20"
+      viewBox="0 0 20 20"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      className="text-muted-foreground"
+      aria-hidden="true"
+    >
+      <rect x="2" y="2" width="16" height="16" rx="3" />
+      <path d="M7 10h6M10 7v6" />
+    </svg>
+  );
+}

package/src/session/inspector/PlanTab.tsx

@@ -0,0 +1,31 @@
+"use client";
+
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionProgress } from "../../execution/ExecutionProgress";
+
+export interface PlanTabProps {
+  readonly execution: AgentExecution | null;
+}
+
+/**
+ * Plan facet for the SessionInspector.
+ *
+ * Wraps the existing chrome-less {@link ExecutionProgress} component
+ * (phase badge + todo list). The `role="region" aria-label="Execution
+ * progress"` contract is preserved for E2E and screen readers.
+ *
+ * Renders nothing when no execution is available (pre-first-run state).
+ */
+export function PlanTab({ execution }: PlanTabProps) {
+  if (!execution) {
+    return (
+      <div className="flex flex-col items-center justify-center px-4 py-8 text-center">
+        <p className="text-xs text-muted-foreground">
+          No execution yet. Send a message to start.
+        </p>
+      </div>
+    );
+  }
+
+  return <ExecutionProgress execution={execution} />;
+}