@stigmer/react 0.0.36 → 0.0.39

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

@@ -0,0 +1,305 @@
+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 { SessionSchema, type Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+import type { Stigmer } from "@stigmer/sdk";
+import { StigmerContext } from "../../context";
+import { useSessionConversation } from "../useSessionConversation";
+
+function makeSession(id: string): Session {
+  const session = create(SessionSchema);
+  const metadata = create(ApiResourceMetadataSchema);
+  metadata.id = id;
+  session.metadata = metadata;
+  return session;
+}
+
+function makeExecution(id: string, phase: ExecutionPhase): AgentExecution {
+  const exec = create(AgentExecutionSchema);
+  const metadata = create(ApiResourceMetadataSchema);
+  metadata.id = id;
+  exec.metadata = metadata;
+  const status = create(AgentExecutionStatusSchema);
+  status.phase = phase;
+  exec.status = status;
+  return exec;
+}
+
+/**
+ * Creates a controllable async generator for streaming.
+ */
+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);
+    },
+  };
+}
+
+interface MockMethods {
+  sessionGet: ReturnType<typeof vi.fn>;
+  listBySession: ReturnType<typeof vi.fn>;
+  executionCreate: ReturnType<typeof vi.fn>;
+  subscribe: ReturnType<typeof vi.fn>;
+  submitApproval: ReturnType<typeof vi.fn>;
+}
+
+function createMockStigmer(methods: MockMethods): Stigmer {
+  return {
+    session: {
+      get: methods.sessionGet,
+    },
+    agentExecution: {
+      listBySession: methods.listBySession,
+      create: methods.executionCreate,
+      subscribe: methods.subscribe,
+      submitApproval: methods.submitApproval,
+    },
+  } as unknown as Stigmer;
+}
+
+function createWrapper(client: Stigmer) {
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <StigmerContext.Provider value={client}>{children}</StigmerContext.Provider>
+    );
+  };
+}
+
+describe("useSessionConversation", () => {
+  let methods: MockMethods;
+  let mockStigmer: Stigmer;
+  let stream: ReturnType<typeof createControllableStream<AgentExecution>>;
+
+  beforeEach(() => {
+    stream = createControllableStream<AgentExecution>();
+    methods = {
+      sessionGet: vi.fn().mockResolvedValue(makeSession("session-1")),
+      listBySession: vi.fn().mockResolvedValue({ entries: [] }),
+      executionCreate: vi.fn(),
+      subscribe: vi.fn().mockReturnValue(stream.generator),
+      submitApproval: vi.fn().mockResolvedValue({}),
+    };
+    mockStigmer = createMockStigmer(methods);
+  });
+
+  it("returns idle state when sessionId is null", () => {
+    const { result } = renderHook(
+      () => useSessionConversation(null, "org"),
+      { wrapper: createWrapper(mockStigmer) },
+    );
+
+    expect(result.current.session).toBeNull();
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.canSendFollowUp).toBe(true);
+    expect(methods.sessionGet).not.toHaveBeenCalled();
+    expect(methods.listBySession).not.toHaveBeenCalled();
+  });
+
+  it("isLoading is true while session and executions are loading", () => {
+    methods.sessionGet.mockReturnValue(new Promise(() => {}));
+    methods.listBySession.mockReturnValue(new Promise(() => {}));
+
+    const { result } = renderHook(
+      () => useSessionConversation("session-1", "org"),
+      { wrapper: createWrapper(mockStigmer) },
+    );
+
+    expect(result.current.isLoading).toBe(true);
+  });
+
+  it("loads session and executions on mount", async () => {
+    const session = makeSession("session-1");
+    methods.sessionGet.mockResolvedValue(session);
+    methods.listBySession.mockResolvedValue({ entries: [] });
+
+    const { result } = renderHook(
+      () => useSessionConversation("session-1", "org"),
+      { wrapper: createWrapper(mockStigmer) },
+    );
+
+    await waitFor(() => {
+      expect(result.current.session).toBe(session);
+      expect(result.current.isLoading).toBe(false);
+    });
+  });
+
+  it("surfaces session fetch errors in loadError", async () => {
+    methods.sessionGet.mockRejectedValue(new Error("session not found"));
+
+    const { result } = renderHook(
+      () => useSessionConversation("session-1", "org"),
+      { wrapper: createWrapper(mockStigmer) },
+    );
+
+    await waitFor(() => {
+      expect(result.current.loadError?.message).toBe("session not found");
+    });
+  });
+
+  it("completedExecutions excludes the active non-terminal execution", async () => {
+    const completed = makeExecution("e1", ExecutionPhase.EXECUTION_COMPLETED);
+    const active = makeExecution("e2", ExecutionPhase.EXECUTION_IN_PROGRESS);
+    methods.listBySession.mockResolvedValue({
+      entries: [completed, active],
+    });
+
+    const { result } = renderHook(
+      () => useSessionConversation("session-1", "org"),
+      { wrapper: createWrapper(mockStigmer) },
+    );
+
+    await waitFor(() => {
+      expect(result.current.completedExecutions).toHaveLength(1);
+      expect(result.current.completedExecutions[0]).toBe(completed);
+    });
+  });
+
+  it("canSendFollowUp is true when no active execution", async () => {
+    const completed = makeExecution("e1", ExecutionPhase.EXECUTION_COMPLETED);
+    methods.listBySession.mockResolvedValue({ entries: [completed] });
+
+    const { result } = renderHook(
+      () => useSessionConversation("session-1", "org"),
+      { wrapper: createWrapper(mockStigmer) },
+    );
+
+    await waitFor(() => {
+      expect(result.current.canSendFollowUp).toBe(true);
+    });
+  });
+
+  it("canSendFollowUp is false while an execution is active", async () => {
+    const active = makeExecution("e1", ExecutionPhase.EXECUTION_IN_PROGRESS);
+    methods.listBySession.mockResolvedValue({ entries: [active] });
+
+    const { result } = renderHook(
+      () => useSessionConversation("session-1", "org"),
+      { wrapper: createWrapper(mockStigmer) },
+    );
+
+    await waitFor(() => {
+      expect(result.current.canSendFollowUp).toBe(false);
+    });
+  });
+
+  it("sendFollowUp sets pendingUserMessage optimistically", async () => {
+    methods.listBySession.mockResolvedValue({ entries: [] });
+    const newExec = makeExecution("new-exec", ExecutionPhase.EXECUTION_PENDING);
+    newExec.metadata!.id = "new-exec";
+    methods.executionCreate.mockResolvedValue(newExec);
+
+    const { result } = renderHook(
+      () => useSessionConversation("session-1", "org"),
+      { wrapper: createWrapper(mockStigmer) },
+    );
+
+    await waitFor(() => {
+      expect(result.current.isLoading).toBe(false);
+    });
+
+    act(() => {
+      result.current.sendFollowUp("Hello agent");
+    });
+
+    expect(result.current.pendingUserMessage).toBe("Hello agent");
+  });
+
+  it("sendFollowUp creates execution via the SDK", async () => {
+    methods.listBySession.mockResolvedValue({ entries: [] });
+    const newExec = makeExecution("new-exec", ExecutionPhase.EXECUTION_PENDING);
+    newExec.metadata!.id = "new-exec";
+    methods.executionCreate.mockResolvedValue(newExec);
+
+    const { result } = renderHook(
+      () => useSessionConversation("session-1", "org"),
+      { wrapper: createWrapper(mockStigmer) },
+    );
+
+    await waitFor(() => {
+      expect(result.current.isLoading).toBe(false);
+    });
+
+    await act(async () => {
+      await result.current.sendFollowUp("Deploy it");
+    });
+
+    expect(methods.executionCreate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        org: "org",
+        sessionId: "session-1",
+        message: "Deploy it",
+      }),
+    );
+  });
+
+  it("pendingUserMessage clears when stream delivers first snapshot", async () => {
+    methods.listBySession.mockResolvedValue({ entries: [] });
+
+    const newExec = makeExecution("new-exec", ExecutionPhase.EXECUTION_PENDING);
+    newExec.metadata!.id = "new-exec";
+    methods.executionCreate.mockResolvedValue(newExec);
+
+    const newStream = createControllableStream<AgentExecution>();
+    methods.subscribe.mockReturnValue(newStream.generator);
+
+    const { result } = renderHook(
+      () => useSessionConversation("session-1", "org"),
+      { wrapper: createWrapper(mockStigmer) },
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    await act(async () => {
+      await result.current.sendFollowUp("Hello");
+    });
+
+    expect(result.current.pendingUserMessage).toBe("Hello");
+
+    act(() => {
+      newStream.push(
+        makeExecution("new-exec", ExecutionPhase.EXECUTION_IN_PROGRESS),
+      );
+    });
+
+    await waitFor(() => {
+      expect(result.current.pendingUserMessage).toBeNull();
+    });
+  });
+});

package/src/session/group-sessions.ts

@@ -0,0 +1,80 @@
+import type { Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+import { timestampDate } from "@bufbuild/protobuf/wkt";
+
+export interface SessionGroup {
+  /** Display label for this group (e.g. "Today", "Yesterday"). */
+  readonly label: string;
+  /** Sessions belonging to this group, in their original input order. */
+  readonly sessions: readonly Session[];
+}
+
+interface Bucket {
+  label: string;
+  sessions: Session[];
+}
+
+/**
+ * Groups sessions by their creation timestamp into time-based buckets:
+ * "Today", "Yesterday", "Previous 7 Days", "Previous 30 Days", "Older".
+ *
+ * Empty groups are omitted. Sessions with missing timestamps are placed
+ * in the last group. Input order is preserved within each group.
+ *
+ * @param sessions - List of sessions to group (typically from `useSessionList`).
+ * @param now - Reference time for grouping; defaults to the current time.
+ *              Accepts an explicit value for deterministic testing.
+ */
+export function groupSessionsByTime(
+  sessions: readonly Session[],
+  now?: Date,
+): readonly SessionGroup[] {
+  const ref = now ?? new Date();
+  const todayStart = startOfDay(ref);
+  const yesterdayStart = addDays(todayStart, -1);
+  const sevenDaysAgo = addDays(todayStart, -6);
+  const thirtyDaysAgo = addDays(todayStart, -29);
+
+  const buckets: Bucket[] = [
+    { label: "Today", sessions: [] },
+    { label: "Yesterday", sessions: [] },
+    { label: "Previous 7 Days", sessions: [] },
+    { label: "Previous 30 Days", sessions: [] },
+    { label: "Older", sessions: [] },
+  ];
+
+  for (const session of sessions) {
+    const ts = session.status?.audit?.specAudit?.createdAt;
+    const date = ts ? timestampDate(ts) : null;
+
+    if (!date) {
+      buckets[buckets.length - 1].sessions.push(session);
+      continue;
+    }
+
+    if (date >= todayStart) {
+      buckets[0].sessions.push(session);
+    } else if (date >= yesterdayStart) {
+      buckets[1].sessions.push(session);
+    } else if (date >= sevenDaysAgo) {
+      buckets[2].sessions.push(session);
+    } else if (date >= thirtyDaysAgo) {
+      buckets[3].sessions.push(session);
+    } else {
+      buckets[4].sessions.push(session);
+    }
+  }
+
+  return buckets.filter((b) => b.sessions.length > 0);
+}
+
+function startOfDay(date: Date): Date {
+  const d = new Date(date);
+  d.setHours(0, 0, 0, 0);
+  return d;
+}
+
+function addDays(date: Date, days: number): Date {
+  const d = new Date(date);
+  d.setDate(d.getDate() + days);
+  return d;
+}

package/src/session/index.ts

@@ -1,13 +1,33 @@
-// Hooks
-export { useAgentSessionList } from "./hooks/useAgentSessionList";
+export { useCreateSession } from "./useCreateSession";
 export type {
-  UseAgentSessionListOptions,
-  UseAgentSessionListReturn,
-} from "./hooks/useAgentSessionList";
+  CreateSessionInput,
+  CreateSessionResult,
+  UseCreateSessionReturn,
+} from "./useCreateSession";
 
-// Components
-export { SessionCard } from "./components/SessionCard";
-export type { SessionCardProps } from "./components/SessionCard";
+export { useUpdateSession } from "./useUpdateSession";
+export type { UseUpdateSessionReturn } from "./useUpdateSession";
 
-export { AgentSessionHistory } from "./components/AgentSessionHistory";
-export type { AgentSessionHistoryProps } from "./components/AgentSessionHistory";
+export { useSession } from "./useSession";
+export type { UseSessionReturn } from "./useSession";
+
+export { useSessionList } from "./useSessionList";
+export type {
+  UseSessionListOptions,
+  UseSessionListReturn,
+} from "./useSessionList";
+
+export { useSessionExecutions } from "./useSessionExecutions";
+export type { UseSessionExecutionsReturn } from "./useSessionExecutions";
+
+export { useSessionConversation } from "./useSessionConversation";
+export type {
+  SendFollowUpOptions,
+  UseSessionConversationReturn,
+} from "./useSessionConversation";
+
+export { useAgentRefFromSession } from "./useAgentRefFromSession";
+export type { UseAgentRefFromSessionReturn } from "./useAgentRefFromSession";
+
+export { groupSessionsByTime } from "./group-sessions";
+export type { SessionGroup } from "./group-sessions";

package/src/session/useAgentRefFromSession.ts

@@ -0,0 +1,94 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import type { ResourceRef } from "@stigmer/sdk";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+export interface UseAgentRefFromSessionReturn {
+  /** Resolved agent reference, or `null` while loading / on error. */
+  readonly agentRef: ResourceRef | null;
+  readonly isLoading: boolean;
+  readonly error: Error | null;
+}
+
+/**
+ * Derives an {@link ResourceRef} for the agent used by a session,
+ * given the session's `agentInstanceId`.
+ *
+ * Chains two lookups:
+ * 1. `agentInstance.get(instanceId)` → `spec.agentId`
+ * 2. `agent.get(agentId)` → `metadata.org` + `metadata.slug`
+ *
+ * Pass `null` or empty string to skip (stable no-op). The hook
+ * re-derives when `instanceId` changes and discards stale in-flight
+ * requests via cancellation.
+ *
+ * @example
+ * ```tsx
+ * const { agentRef, isLoading } = useAgentRefFromSession(
+ *   session?.spec?.agentInstanceId ?? null,
+ * );
+ * ```
+ */
+export function useAgentRefFromSession(
+  instanceId: string | null | undefined,
+): UseAgentRefFromSessionReturn {
+  const stigmer = useStigmer();
+  const [agentRef, setAgentRef] = useState<ResourceRef | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    if (!instanceId) {
+      setAgentRef(null);
+      setIsLoading(false);
+      setError(null);
+      return;
+    }
+
+    const cancelled = { current: false };
+    setIsLoading(true);
+    setError(null);
+
+    (async () => {
+      const instance = await stigmer.agentInstance.get(instanceId);
+      if (cancelled.current) return;
+
+      const agentId = instance.spec?.agentId;
+      if (!agentId) {
+        throw new Error(
+          `AgentInstance "${instanceId}" has no spec.agentId. ` +
+            "Cannot derive an agent reference.",
+        );
+      }
+
+      const agent = await stigmer.agent.get(agentId);
+      if (cancelled.current) return;
+
+      const org = agent.metadata?.org;
+      const slug = agent.metadata?.slug;
+      if (!org || !slug) {
+        throw new Error(
+          `Agent "${agentId}" is missing metadata.org or metadata.slug. ` +
+            "Cannot construct a ResourceRef.",
+        );
+      }
+
+      setAgentRef({ org, slug, kind: ApiResourceKind.agent });
+      setIsLoading(false);
+    })().catch((err) => {
+      if (cancelled.current) return;
+      setError(toError(err));
+      setAgentRef(null);
+      setIsLoading(false);
+    });
+
+    return () => {
+      cancelled.current = true;
+    };
+  }, [instanceId, stigmer]);
+
+  return { agentRef, isLoading, error };
+}

package/src/session/useCreateSession.ts

@@ -0,0 +1,141 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type {
+  McpServerUsageInput,
+  ResourceRef,
+  WorkspaceEntryInput,
+} from "@stigmer/sdk";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+interface SharedSessionFields {
+  readonly org: string;
+  readonly workspaceEntries?: WorkspaceEntryInput[];
+  readonly subject?: string;
+  readonly mcpServerUsages?: McpServerUsageInput[];
+  readonly skillRefs?: ResourceRef[];
+}
+
+/**
+ * Input for creating a session. Exactly one agent resolution strategy
+ * must be provided:
+ *
+ * - **`agentInstanceId`** — Use a pre-provisioned AgentInstance directly.
+ * - **`agentRef`** — Resolve the agent's default instance via
+ *   `agent.getByReference()`.
+ *
+ * Providing both is a type error. Platform builders who need the
+ * backend's implicit agent resolution can use `@stigmer/sdk`'s
+ * `session.create()` directly.
+ */
+export type CreateSessionInput = SharedSessionFields &
+  (
+    | { readonly agentInstanceId: string; readonly agentRef?: never }
+    | { readonly agentRef: ResourceRef; readonly agentInstanceId?: never }
+  );
+
+export interface CreateSessionResult {
+  readonly sessionId: string;
+}
+
+export interface UseCreateSessionReturn {
+  readonly create: (input: CreateSessionInput) => Promise<CreateSessionResult>;
+  readonly isCreating: boolean;
+  readonly error: Error | null;
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook that wraps `session.create()` with loading/error state.
+ *
+ * Creates a Session — the conversation context that holds workspace
+ * entries, thread state, and sandbox references.
+ *
+ * Exactly one agent resolution strategy must be provided:
+ *
+ * 1. **`agentInstanceId`** — Use a pre-provisioned instance directly.
+ *    Typical for platform builders who manage instances programmatically.
+ * 2. **`agentRef`** — Resolve the agent's default instance via
+ *    `agent.getByReference()`. Useful when you know the agent slug
+ *    but not the instance ID.
+ *
+ * This hook maps 1:1 to the Session aggregate. To start the first
+ * execution within the session, compose with {@link useCreateAgentExecution}.
+ *
+ * @example
+ * ```tsx
+ * // Platform builder: pre-provisioned instance
+ * const { create } = useCreateSession();
+ * await create({ org: "acme", agentInstanceId: "inst-abc123" });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Agent reference: resolves to the agent's default instance
+ * const { create } = useCreateSession();
+ * await create({
+ *   org: "acme",
+ *   agentRef: { org: "acme", slug: "code-reviewer" },
+ * });
+ * ```
+ */
+export function useCreateSession(): UseCreateSessionReturn {
+  const stigmer = useStigmer();
+  const [isCreating, setIsCreating] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const create = useCallback(
+    async (input: CreateSessionInput): Promise<CreateSessionResult> => {
+      setIsCreating(true);
+      setError(null);
+
+      try {
+        let resolvedInstanceId: string;
+
+        if (input.agentInstanceId) {
+          resolvedInstanceId = input.agentInstanceId;
+        } else if (input.agentRef) {
+          const agent = await stigmer.agent.getByReference(input.agentRef);
+          const defaultId = agent.status?.defaultInstanceId;
+
+          if (!defaultId) {
+            throw new Error(
+              `Agent "${input.agentRef.org}/${input.agentRef.slug}" does not have a default instance. ` +
+                `Pass an explicit agentInstanceId instead.`,
+            );
+          }
+
+          resolvedInstanceId = defaultId;
+        } else {
+          throw new Error(
+            "useCreateSession requires either agentInstanceId or agentRef. " +
+              "Provide one to specify which agent this session should use.",
+          );
+        }
+
+        const session = await stigmer.session.create({
+          name: `session-${Date.now()}`,
+          org: input.org,
+          subject: input.subject,
+          workspaceEntries: input.workspaceEntries,
+          mcpServerUsages: input.mcpServerUsages,
+          skillRefs: input.skillRefs,
+          agentInstanceId: resolvedInstanceId,
+        });
+
+        return { sessionId: session.metadata!.id };
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsCreating(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { create, isCreating, error, clearError };
+}