@stigmer/react 0.2.2 → 0.3.0

package/src/runner/phase.ts

@@ -9,15 +9,17 @@ import { RunnerPhase } from "@stigmer/protos/ai/stigmer/agentic/runner/v1/enum_p
 export const PHASE_SORT_ORDER: Record<RunnerPhase, number> = {
   [RunnerPhase.READY]: 0,
   [RunnerPhase.BUSY]: 1,
-  [RunnerPhase.PENDING]: 2,
-  [RunnerPhase.STOPPED]: 3,
-  [RunnerPhase.FAILED]: 4,
-  [RunnerPhase.UNSPECIFIED]: 5,
+  [RunnerPhase.STARTING]: 2,
+  [RunnerPhase.PENDING]: 3,
+  [RunnerPhase.STOPPED]: 4,
+  [RunnerPhase.FAILED]: 5,
+  [RunnerPhase.UNSPECIFIED]: 6,
 };
 
 const LABELS: Record<RunnerPhase, string> = {
   [RunnerPhase.READY]: "Ready",
   [RunnerPhase.BUSY]: "Busy",
+  [RunnerPhase.STARTING]: "Starting",
   [RunnerPhase.PENDING]: "Pending",
   [RunnerPhase.STOPPED]: "Stopped",
   [RunnerPhase.FAILED]: "Failed",
@@ -37,9 +39,10 @@ export function phaseLabel(phase: RunnerPhase): string {
 /**
  * Tailwind `bg-*` class for the small colored dot indicator.
  *
- * - Ready  → `bg-success`  (green)
- * - Busy   → `bg-warning`  (amber)
- * - Others → `bg-muted-foreground` (neutral)
+ * - Ready    → `bg-success`  (green)
+ * - Busy     → `bg-warning`  (amber)
+ * - Starting → `bg-primary`  (blue)
+ * - Others   → `bg-muted-foreground` (neutral)
  */
 export function phaseDotColor(phase: RunnerPhase): string {
   switch (phase) {
@@ -47,6 +50,8 @@ export function phaseDotColor(phase: RunnerPhase): string {
       return "bg-success";
     case RunnerPhase.BUSY:
       return "bg-warning";
+    case RunnerPhase.STARTING:
+      return "bg-primary";
     default:
       return "bg-muted-foreground";
   }
@@ -65,14 +70,15 @@ export function isActivePhase(phase: RunnerPhase): boolean {
  * Whether the runner is in a transitional phase whose status is
  * expected to change soon without user action.
  *
- * Currently only `PENDING` — the runner has registered but hasn't
- * completed its startup handshake yet. This is distinct from
- * {@link isActivePhase} (READY | BUSY) where the runner is stable
- * and accepting work.
+ * `PENDING` — resource created, no process launched yet.
+ * `STARTING` — process launched, runtime bootstrapping in progress.
+ *
+ * This is distinct from {@link isActivePhase} (READY | BUSY) where
+ * the runner is stable and accepting work.
  *
  * Useful for driving conditional polling: poll while transitional
  * runners exist, stop when all runners reach a stable state.
  */
 export function isTransitionalPhase(phase: RunnerPhase): boolean {
-  return phase === RunnerPhase.PENDING;
+  return phase === RunnerPhase.PENDING || phase === RunnerPhase.STARTING;
 }

package/src/runner/useRunnerFileBrowser.ts

@@ -58,6 +58,12 @@ export interface UseRunnerFileBrowserReturn {
 // Reducer
 // ---------------------------------------------------------------------------
 
+/** Cached result of a single directory listing. */
+interface CachedListing {
+  readonly entries: readonly DirectoryEntry[];
+  readonly fetchedAt: number;
+}
+
 interface State {
   currentPath: string;
   entries: readonly DirectoryEntry[];
@@ -68,13 +74,18 @@ interface State {
   error: Error | null;
   /** The path we last requested — used for retry. */
   requestedPath: string;
+  /** Directory listing cache keyed by resolved absolute path. */
+  cache: Map<string, CachedListing>;
 }
 
 type Action =
   | { type: "NAVIGATE"; path: string }
   | { type: "SUCCESS"; resolvedPath: string; entries: DirectoryEntry[]; homeDirectory: string; currentDirectory: string }
   | { type: "FAILURE"; error: Error }
-  | { type: "TOGGLE_HIDDEN" };
+  | { type: "TOGGLE_HIDDEN" }
+  | { type: "CACHE_HIT"; resolvedPath: string; entries: readonly DirectoryEntry[] };
+
+const CACHE_MAX_AGE_MS = 30_000;
 
 function reducer(state: State, action: Action): State {
   switch (action.type) {
@@ -85,7 +96,12 @@ function reducer(state: State, action: Action): State {
         isLoading: true,
         error: null,
       };
-    case "SUCCESS":
+    case "SUCCESS": {
+      const nextCache = new Map(state.cache);
+      nextCache.set(action.resolvedPath, {
+        entries: action.entries,
+        fetchedAt: Date.now(),
+      });
       return {
         ...state,
         currentPath: action.resolvedPath,
@@ -94,6 +110,17 @@ function reducer(state: State, action: Action): State {
         currentDirectory: action.currentDirectory || state.currentDirectory,
         isLoading: false,
         error: null,
+        cache: nextCache,
+      };
+    }
+    case "CACHE_HIT":
+      return {
+        ...state,
+        currentPath: action.resolvedPath,
+        entries: action.entries,
+        isLoading: false,
+        error: null,
+        requestedPath: action.resolvedPath,
       };
     case "FAILURE":
       return { ...state, isLoading: false, error: action.error };
@@ -111,6 +138,7 @@ const INITIAL_STATE: State = {
   isLoading: false,
   error: null,
   requestedPath: "",
+  cache: new Map(),
 };
 
 // ---------------------------------------------------------------------------
@@ -182,10 +210,19 @@ export function useRunnerFileBrowser(
   const [state, dispatch] = useReducer(reducer, INITIAL_STATE);
   const requestIdRef = useRef(0);
 
+  const cacheRef = useRef(state.cache);
+  cacheRef.current = state.cache;
+
   const fetchDirectory = useCallback(
     async (path: string) => {
       if (!runnerId) return;
 
+      const cached = cacheRef.current.get(path);
+      if (cached && Date.now() - cached.fetchedAt < CACHE_MAX_AGE_MS) {
+        dispatch({ type: "CACHE_HIT", resolvedPath: path, entries: cached.entries });
+        return;
+      }
+
       const id = ++requestIdRef.current;
       dispatch({ type: "NAVIGATE", path });
 
@@ -200,7 +237,6 @@ export function useRunnerFileBrowser(
           }),
         );
 
-        // Stale response guard — a newer navigation has started.
         if (id !== requestIdRef.current) return;
 
         if (response.result.case === "error") {

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

@@ -0,0 +1,296 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { Harness } from "@stigmer/protos/ai/stigmer/agentic/session/v1/enum_pb";
+import type { Stigmer } from "@stigmer/sdk";
+import { StigmerContext } from "../../context";
+import { useCreateSession } from "../useCreateSession";
+
+function buildMockClient(overrides: {
+  sessionCreate?: ReturnType<typeof vi.fn>;
+  agentGetByReference?: ReturnType<typeof vi.fn>;
+} = {}) {
+  return {
+    session: {
+      create: overrides.sessionCreate ?? vi.fn(),
+    },
+    agent: {
+      getByReference: overrides.agentGetByReference ?? vi.fn(),
+    },
+  } as unknown as Stigmer;
+}
+
+function makeWrapper(client: Stigmer) {
+  return ({ children }: { children: ReactNode }) => (
+    <StigmerContext.Provider value={client}>{children}</StigmerContext.Provider>
+  );
+}
+
+function fakeSessionResponse(sessionId: string) {
+  return { metadata: { id: sessionId } };
+}
+
+describe("useCreateSession", () => {
+  let sessionCreateMock: ReturnType<typeof vi.fn>;
+  let agentGetByRefMock: ReturnType<typeof vi.fn>;
+  let client: Stigmer;
+
+  beforeEach(() => {
+    sessionCreateMock = vi.fn();
+    agentGetByRefMock = vi.fn();
+    client = buildMockClient({
+      sessionCreate: sessionCreateMock,
+      agentGetByReference: agentGetByRefMock,
+    });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("starts in idle state", () => {
+    const { result } = renderHook(() => useCreateSession(), {
+      wrapper: makeWrapper(client),
+    });
+    expect(result.current.isCreating).toBe(false);
+    expect(result.current.error).toBeNull();
+  });
+
+  describe("agentInstanceId path", () => {
+    it("creates a session with the given instance ID", async () => {
+      sessionCreateMock.mockResolvedValueOnce(fakeSessionResponse("sess-1"));
+
+      const { result } = renderHook(() => useCreateSession(), {
+        wrapper: makeWrapper(client),
+      });
+
+      let outcome: { sessionId: string } | undefined;
+      await act(async () => {
+        outcome = await result.current.create({
+          org: "acme",
+          agentInstanceId: "inst-abc",
+        });
+      });
+
+      expect(outcome!.sessionId).toBe("sess-1");
+      expect(sessionCreateMock).toHaveBeenCalledOnce();
+      expect(sessionCreateMock.mock.calls[0][0]).toMatchObject({
+        org: "acme",
+        agentInstanceId: "inst-abc",
+      });
+    });
+  });
+
+  describe("agentRef path", () => {
+    it("resolves the agent reference to its default instance", async () => {
+      agentGetByRefMock.mockResolvedValueOnce({
+        status: { defaultInstanceId: "inst-resolved" },
+      });
+      sessionCreateMock.mockResolvedValueOnce(fakeSessionResponse("sess-2"));
+
+      const { result } = renderHook(() => useCreateSession(), {
+        wrapper: makeWrapper(client),
+      });
+
+      await act(async () => {
+        await result.current.create({
+          org: "acme",
+          agentRef: { org: "acme", slug: "my-agent" },
+        });
+      });
+
+      expect(agentGetByRefMock).toHaveBeenCalledWith({
+        org: "acme",
+        slug: "my-agent",
+      });
+      expect(sessionCreateMock.mock.calls[0][0]).toMatchObject({
+        agentInstanceId: "inst-resolved",
+      });
+    });
+
+    it("throws when agent has no default instance", async () => {
+      agentGetByRefMock.mockResolvedValueOnce({ status: {} });
+
+      const { result } = renderHook(() => useCreateSession(), {
+        wrapper: makeWrapper(client),
+      });
+
+      await act(async () => {
+        await expect(
+          result.current.create({
+            org: "acme",
+            agentRef: { org: "acme", slug: "no-instance" },
+          }),
+        ).rejects.toThrow("does not have a default instance");
+      });
+
+      expect(result.current.error).not.toBeNull();
+      expect(result.current.error!.message).toContain(
+        "does not have a default instance",
+      );
+    });
+  });
+
+  describe("harness proto conversion", () => {
+    it("passes Harness.CURSOR when harness is cursor", async () => {
+      sessionCreateMock.mockResolvedValueOnce(fakeSessionResponse("sess-h1"));
+
+      const { result } = renderHook(() => useCreateSession(), {
+        wrapper: makeWrapper(client),
+      });
+
+      await act(async () => {
+        await result.current.create({
+          org: "acme",
+          agentInstanceId: "inst-1",
+          harness: "cursor",
+        });
+      });
+
+      expect(sessionCreateMock.mock.calls[0][0].harness).toBe(Harness.CURSOR);
+    });
+
+    it("passes Harness.NATIVE when harness is native", async () => {
+      sessionCreateMock.mockResolvedValueOnce(fakeSessionResponse("sess-h2"));
+
+      const { result } = renderHook(() => useCreateSession(), {
+        wrapper: makeWrapper(client),
+      });
+
+      await act(async () => {
+        await result.current.create({
+          org: "acme",
+          agentInstanceId: "inst-1",
+          harness: "native",
+        });
+      });
+
+      expect(sessionCreateMock.mock.calls[0][0].harness).toBe(Harness.NATIVE);
+    });
+
+    it("passes undefined when harness is omitted", async () => {
+      sessionCreateMock.mockResolvedValueOnce(fakeSessionResponse("sess-h3"));
+
+      const { result } = renderHook(() => useCreateSession(), {
+        wrapper: makeWrapper(client),
+      });
+
+      await act(async () => {
+        await result.current.create({
+          org: "acme",
+          agentInstanceId: "inst-1",
+        });
+      });
+
+      expect(sessionCreateMock.mock.calls[0][0].harness).toBeUndefined();
+    });
+  });
+
+  describe("loading state lifecycle", () => {
+    it("isCreating is true during the RPC and false after", async () => {
+      let resolveCreate!: (v: unknown) => void;
+      sessionCreateMock.mockReturnValueOnce(
+        new Promise((r) => { resolveCreate = r; }),
+      );
+
+      const { result } = renderHook(() => useCreateSession(), {
+        wrapper: makeWrapper(client),
+      });
+
+      let createPromise: Promise<unknown>;
+      act(() => {
+        createPromise = result.current.create({
+          org: "acme",
+          agentInstanceId: "inst-1",
+        });
+      });
+
+      expect(result.current.isCreating).toBe(true);
+
+      await act(async () => {
+        resolveCreate(fakeSessionResponse("sess-lc"));
+        await createPromise;
+      });
+
+      expect(result.current.isCreating).toBe(false);
+    });
+  });
+
+  describe("error handling", () => {
+    it("sets error on RPC failure and resets isCreating", async () => {
+      sessionCreateMock.mockRejectedValueOnce(new Error("network timeout"));
+
+      const { result } = renderHook(() => useCreateSession(), {
+        wrapper: makeWrapper(client),
+      });
+
+      await act(async () => {
+        await expect(
+          result.current.create({
+            org: "acme",
+            agentInstanceId: "inst-1",
+          }),
+        ).rejects.toThrow("network timeout");
+      });
+
+      expect(result.current.isCreating).toBe(false);
+      expect(result.current.error).toBeInstanceOf(Error);
+      expect(result.current.error!.message).toBe("network timeout");
+    });
+
+    it("clearError resets error to null", async () => {
+      sessionCreateMock.mockRejectedValueOnce(new Error("fail"));
+
+      const { result } = renderHook(() => useCreateSession(), {
+        wrapper: makeWrapper(client),
+      });
+
+      await act(async () => {
+        try {
+          await result.current.create({
+            org: "acme",
+            agentInstanceId: "inst-1",
+          });
+        } catch { /* expected */ }
+      });
+
+      expect(result.current.error).not.toBeNull();
+
+      act(() => {
+        result.current.clearError();
+      });
+
+      expect(result.current.error).toBeNull();
+    });
+
+    it("clears previous error on new create attempt", async () => {
+      sessionCreateMock
+        .mockRejectedValueOnce(new Error("first fail"))
+        .mockResolvedValueOnce(fakeSessionResponse("sess-retry"));
+
+      const { result } = renderHook(() => useCreateSession(), {
+        wrapper: makeWrapper(client),
+      });
+
+      await act(async () => {
+        try {
+          await result.current.create({
+            org: "acme",
+            agentInstanceId: "inst-1",
+          });
+        } catch { /* expected */ }
+      });
+
+      expect(result.current.error).not.toBeNull();
+
+      await act(async () => {
+        await result.current.create({
+          org: "acme",
+          agentInstanceId: "inst-1",
+        });
+      });
+
+      expect(result.current.error).toBeNull();
+    });
+  });
+});