@stigmer/react 3.12.6 → 3.12.8

package/src/memory/__tests__/memoryHooks.test.tsx

@@ -0,0 +1,283 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { create } from "@bufbuild/protobuf";
+import { MemorySchema, type Memory } from "@stigmer/protos/ai/stigmer/agentic/memory/v1/api_pb";
+import { MemoryLifecycleState } from "@stigmer/protos/ai/stigmer/agentic/memory/v1/enum_pb";
+import { MemoryListSchema } from "@stigmer/protos/ai/stigmer/agentic/memory/v1/io_pb";
+import { StigmerError } from "@stigmer/sdk";
+import { StigmerContext } from "../../context";
+import { FetchCacheContext } from "../../internal/FetchCacheProvider";
+import { useMemories } from "../useMemories";
+import { useMemory } from "../useMemory";
+import { useConfirmMemory } from "../useConfirmMemory";
+import { useRejectMemory } from "../useRejectMemory";
+import { useDeleteMemory } from "../useDeleteMemory";
+import { useUpdateMemoryContent } from "../useUpdateMemoryContent";
+import { groupMemoriesByLifecycle, formatMemoryProvenance } from "../memoryGroups";
+
+function wrapper(client: unknown) {
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <FetchCacheContext.Provider value={null}>
+        <StigmerContext.Provider value={client as never}>
+          {children}
+        </StigmerContext.Provider>
+      </FetchCacheContext.Provider>
+    );
+  };
+}
+
+function makeMemory(
+  id: string,
+  state: MemoryLifecycleState,
+  content = "A fact.",
+): Memory {
+  return create(MemorySchema, {
+    apiVersion: "agentic.stigmer.ai/v1",
+    kind: "Memory",
+    metadata: { id, name: id, slug: id, org: "test-org" },
+    spec: { content },
+    status: { lifecycleState: state },
+  });
+}
+
+const PROPOSED = makeMemory("mem_proposed", MemoryLifecycleState.lifecycle_state_proposed);
+const CONFIRMED = makeMemory("mem_confirmed", MemoryLifecycleState.lifecycle_state_confirmed);
+const REJECTED = makeMemory("mem_rejected", MemoryLifecycleState.lifecycle_state_rejected);
+
+beforeEach(() => vi.clearAllMocks());
+
+// ---------------------------------------------------------------------------
+// Data hook
+// ---------------------------------------------------------------------------
+
+describe("useMemories", () => {
+  it("fetches all memories in one cap-sized page", async () => {
+    const list = vi
+      .fn()
+      .mockResolvedValue(create(MemoryListSchema, { totalCount: 2, items: [PROPOSED, CONFIRMED] }));
+    const client = { memory: { list } };
+
+    const { result } = renderHook(() => useMemories("test-org"), {
+      wrapper: wrapper(client),
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.memories).toHaveLength(2);
+    expect(result.current.error).toBeNull();
+    // One page of exactly the server cap fetches everything by
+    // construction — the list needs no pagination UI.
+    expect(list).toHaveBeenCalledWith(
+      expect.objectContaining({
+        org: "test-org",
+        pageInfo: expect.objectContaining({ num: 1, size: 100 }),
+      }),
+    );
+  });
+
+  it("skips fetching when org is null", () => {
+    const list = vi.fn();
+    const client = { memory: { list } };
+
+    const { result } = renderHook(() => useMemories(null), {
+      wrapper: wrapper(client),
+    });
+
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.memories).toEqual([]);
+    expect(list).not.toHaveBeenCalled();
+  });
+
+  it("surfaces list errors", async () => {
+    const failure = new Error("boom");
+    const client = { memory: { list: vi.fn().mockRejectedValue(failure) } };
+
+    const { result } = renderHook(() => useMemories("test-org"), {
+      wrapper: wrapper(client),
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.error).toBe(failure);
+    expect(result.current.memories).toEqual([]);
+  });
+});
+
+describe("useMemory", () => {
+  it("fetches one record by id", async () => {
+    const get = vi.fn().mockResolvedValue(PROPOSED);
+    const client = { memory: { get } };
+
+    const { result } = renderHook(() => useMemory("mem_proposed"), {
+      wrapper: wrapper(client),
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.memory).toBe(PROPOSED);
+    expect(result.current.notFound).toBe(false);
+    expect(result.current.error).toBeNull();
+    expect(get).toHaveBeenCalledWith("mem_proposed");
+  });
+
+  it("reports a deleted record as the notFound STATE, never an error", async () => {
+    // Deletion is the consent-revocation mechanism — a consumer must
+    // render "no longer stored", not a failure.
+    const get = vi
+      .fn()
+      .mockRejectedValue(new StigmerError("not-found", "memory not found", 5));
+    const client = { memory: { get } };
+
+    const { result } = renderHook(() => useMemory("mem_gone"), {
+      wrapper: wrapper(client),
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.notFound).toBe(true);
+    expect(result.current.memory).toBeNull();
+    expect(result.current.error).toBeNull();
+  });
+
+  it("propagates every other failure as an error", async () => {
+    const failure = new StigmerError("unavailable", "server down", 14);
+    const client = { memory: { get: vi.fn().mockRejectedValue(failure) } };
+
+    const { result } = renderHook(() => useMemory("mem_x"), {
+      wrapper: wrapper(client),
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.error).toBe(failure);
+    expect(result.current.notFound).toBe(false);
+  });
+
+  it("skips fetching when id is null", () => {
+    const get = vi.fn();
+    const client = { memory: { get } };
+
+    const { result } = renderHook(() => useMemory(null), {
+      wrapper: wrapper(client),
+    });
+
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.memory).toBeNull();
+    expect(get).not.toHaveBeenCalled();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Decision hooks
+// ---------------------------------------------------------------------------
+
+describe("decision hooks", () => {
+  it("useConfirmMemory calls memory.confirm and resolves", async () => {
+    const confirm = vi.fn().mockResolvedValue(CONFIRMED);
+    const client = { memory: { confirm } };
+
+    const { result } = renderHook(() => useConfirmMemory(), {
+      wrapper: wrapper(client),
+    });
+
+    const confirmed = await result.current.confirmMemory("mem_proposed");
+    expect(confirmed).toBe(CONFIRMED);
+    expect(confirm).toHaveBeenCalledWith("mem_proposed");
+    await waitFor(() => expect(result.current.isConfirming).toBe(false));
+    expect(result.current.error).toBeNull();
+  });
+
+  it("useRejectMemory surfaces errors and rethrows", async () => {
+    const failure = new Error("memory was confirmed — delete it to stop it from being recalled");
+    const client = { memory: { reject: vi.fn().mockRejectedValue(failure) } };
+
+    const { result } = renderHook(() => useRejectMemory(), {
+      wrapper: wrapper(client),
+    });
+
+    await expect(result.current.rejectMemory("mem_confirmed")).rejects.toBe(failure);
+    await waitFor(() => expect(result.current.error).toBe(failure));
+    result.current.clearError();
+    await waitFor(() => expect(result.current.error).toBeNull());
+  });
+
+  it("useDeleteMemory calls memory.delete", async () => {
+    const del = vi.fn().mockResolvedValue(REJECTED);
+    const client = { memory: { delete: del } };
+
+    const { result } = renderHook(() => useDeleteMemory(), {
+      wrapper: wrapper(client),
+    });
+
+    await result.current.deleteMemory("mem_rejected");
+    expect(del).toHaveBeenCalledWith("mem_rejected");
+  });
+
+  it("useUpdateMemoryContent maps through toMemoryUpdateInput and overrides only content", async () => {
+    const update = vi.fn().mockResolvedValue(CONFIRMED);
+    const client = { memory: { update } };
+
+    const { result } = renderHook(() => useUpdateMemoryContent(), {
+      wrapper: wrapper(client),
+    });
+
+    await result.current.updateContent(CONFIRMED, "Edited fact.");
+    // The wipe-safe rule: the loaded record's identity and immutable
+    // fields ride along; only content changes.
+    expect(update).toHaveBeenCalledWith(
+      expect.objectContaining({
+        id: "mem_confirmed",
+        org: "test-org",
+        content: "Edited fact.",
+      }),
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Grouping helpers
+// ---------------------------------------------------------------------------
+
+describe("groupMemoriesByLifecycle", () => {
+  it("buckets by state and preserves input order within buckets", () => {
+    const secondProposed = makeMemory(
+      "mem_proposed_2",
+      MemoryLifecycleState.lifecycle_state_proposed,
+    );
+    const groups = groupMemoriesByLifecycle([
+      CONFIRMED,
+      PROPOSED,
+      REJECTED,
+      secondProposed,
+    ]);
+
+    expect(groups.proposed.map((m) => m.metadata?.id)).toEqual([
+      "mem_proposed",
+      "mem_proposed_2",
+    ]);
+    expect(groups.confirmed.map((m) => m.metadata?.id)).toEqual(["mem_confirmed"]);
+    expect(groups.rejected.map((m) => m.metadata?.id)).toEqual(["mem_rejected"]);
+  });
+
+  it("buckets the impossible unspecified state with proposals, never hiding it", () => {
+    const zombie = makeMemory("mem_zombie", MemoryLifecycleState.lifecycle_state_unspecified);
+    const groups = groupMemoriesByLifecycle([zombie]);
+    expect(groups.proposed).toHaveLength(1);
+  });
+});
+
+describe("formatMemoryProvenance", () => {
+  it("names the proposing agent and session", () => {
+    const memory = create(MemorySchema, {
+      metadata: { id: "mem_x", org: "test-org" },
+      spec: {
+        content: "A fact.",
+        provenance: { agentId: "agt_1", sessionId: "ses_1" },
+      },
+    });
+    expect(formatMemoryProvenance(memory)).toBe(
+      "Proposed by agent agt_1 in session ses_1",
+    );
+  });
+
+  it("returns null for records without provenance (created directly)", () => {
+    expect(formatMemoryProvenance(PROPOSED)).toBeNull();
+  });
+});

package/src/memory/index.ts

@@ -0,0 +1,24 @@
+// Memory — agent-proposed, user-confirmed facts (stigmer/stigmer#293
+// Phase 2). The record is the trust surface over the recall seam: every
+// fact is individually reviewable, editable, and deletable, and nothing
+// is recalled until its subject confirms it.
+
+export { MemoryListPanel, type MemoryListPanelProps } from "./MemoryListPanel.js";
+export {
+  MemoryProposalCardBody,
+  type MemoryProposalCardBodyProps,
+} from "./MemoryProposalCard.js";
+export {
+  groupMemoriesByLifecycle,
+  formatMemoryProvenance,
+  type MemoryGroups,
+} from "./memoryGroups.js";
+export { useMemories, type UseMemoriesReturn } from "./useMemories.js";
+export { useMemory, type UseMemoryReturn } from "./useMemory.js";
+export { useConfirmMemory, type UseConfirmMemoryReturn } from "./useConfirmMemory.js";
+export { useRejectMemory, type UseRejectMemoryReturn } from "./useRejectMemory.js";
+export { useDeleteMemory, type UseDeleteMemoryReturn } from "./useDeleteMemory.js";
+export {
+  useUpdateMemoryContent,
+  type UseUpdateMemoryContentReturn,
+} from "./useUpdateMemoryContent.js";

package/src/memory/memoryGroups.ts

@@ -0,0 +1,64 @@
+import type { Memory } from "@stigmer/protos/ai/stigmer/agentic/memory/v1/api_pb";
+import { MemoryLifecycleState } from "@stigmer/protos/ai/stigmer/agentic/memory/v1/enum_pb";
+
+/** Memories bucketed by consent lifecycle, pending proposals first. */
+export interface MemoryGroups {
+  /** Awaiting the caller's decision — the catch-up queue. */
+  readonly proposed: readonly Memory[];
+  /** Confirmed facts, recalled into future sessions. */
+  readonly confirmed: readonly Memory[];
+  /** Rejected proposals, kept for audit until deleted. */
+  readonly rejected: readonly Memory[];
+}
+
+/**
+ * Buckets memories by lifecycle state for the pending-proposals-first
+ * page layout (DD-005 D4: the memory page is the catch-up surface for
+ * proposals scrolled past in session). Input order (newest first from
+ * the server) is preserved inside each bucket.
+ *
+ * A record in the zero `unspecified` state should not exist (create
+ * stamps `proposed`); it is bucketed with proposals so a decision
+ * surface is always offered rather than hiding the record.
+ */
+export function groupMemoriesByLifecycle(
+  memories: readonly Memory[],
+): MemoryGroups {
+  const proposed: Memory[] = [];
+  const confirmed: Memory[] = [];
+  const rejected: Memory[] = [];
+
+  for (const memory of memories) {
+    switch (memory.status?.lifecycleState) {
+      case MemoryLifecycleState.lifecycle_state_confirmed:
+        confirmed.push(memory);
+        break;
+      case MemoryLifecycleState.lifecycle_state_rejected:
+        rejected.push(memory);
+        break;
+      default:
+        proposed.push(memory);
+        break;
+    }
+  }
+
+  return { proposed, confirmed, rejected };
+}
+
+/**
+ * One-line provenance attribution for a memory, or `null` when the
+ * record has none (created directly through the API, not by an agent).
+ *
+ * Trust requires "where did this come from" beside every fact (DD-004);
+ * agent/session display names are not resolvable from the record alone,
+ * so ids are shown — they are what links back to the source surfaces.
+ */
+export function formatMemoryProvenance(memory: Memory): string | null {
+  const provenance = memory.spec?.provenance;
+  if (!provenance) return null;
+  const parts: string[] = [];
+  if (provenance.agentId) parts.push(`agent ${provenance.agentId}`);
+  if (provenance.sessionId) parts.push(`session ${provenance.sessionId}`);
+  if (parts.length === 0) return null;
+  return `Proposed by ${parts.join(" in ")}`;
+}

package/src/memory/useConfirmMemory.ts

@@ -0,0 +1,62 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { Memory } from "@stigmer/protos/ai/stigmer/agentic/memory/v1/api_pb";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+
+/** Return value of {@link useConfirmMemory}. */
+export interface UseConfirmMemoryReturn {
+  /** Confirm a proposed memory by its resource ID. Resolves with the confirmed record. */
+  readonly confirmMemory: (id: string) => Promise<Memory>;
+  /** `true` while the confirm request is in flight. */
+  readonly isConfirming: boolean;
+  /** Error from the last failed confirm, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook that wraps `memory.confirm()` — the consent act
+ * (DD-005 D3). A confirmed memory is recalled into the caller's future
+ * sessions as background context.
+ *
+ * Confirming an already-confirmed memory succeeds and changes nothing.
+ * Confirming a rejected memory fails with FAILED_PRECONDITION: the
+ * rejection stands — delete the record and let the agent propose again.
+ *
+ * @example
+ * ```tsx
+ * const { confirmMemory, isConfirming } = useConfirmMemory();
+ *
+ * await confirmMemory(memory.metadata?.id ?? "");
+ * refetch(); // refresh the list after the decision
+ * ```
+ */
+export function useConfirmMemory(): UseConfirmMemoryReturn {
+  const stigmer = useStigmer();
+  const [isConfirming, setIsConfirming] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const confirmMemory = useCallback(
+    async (id: string): Promise<Memory> => {
+      setIsConfirming(true);
+      setError(null);
+
+      try {
+        return await stigmer.memory.confirm(id);
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsConfirming(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { confirmMemory, isConfirming, error, clearError };
+}

package/src/memory/useDeleteMemory.ts

@@ -0,0 +1,61 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { Memory } from "@stigmer/protos/ai/stigmer/agentic/memory/v1/api_pb";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+
+/** Return value of {@link useDeleteMemory}. */
+export interface UseDeleteMemoryReturn {
+  /** Delete a memory by its resource ID, in any lifecycle state. Resolves with the deleted record. */
+  readonly deleteMemory: (id: string) => Promise<Memory>;
+  /** `true` while the delete request is in flight. */
+  readonly isDeleting: boolean;
+  /** Error from the last failed delete, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook that wraps `memory.delete()`.
+ *
+ * Deletion works in any lifecycle state — it is never refused on
+ * lifecycle grounds (DD-004) — and is the revocation mechanism for
+ * confirmed facts: the fact stops reaching future sessions immediately.
+ * Past executions keep their immutable recall snapshots.
+ *
+ * @example
+ * ```tsx
+ * const { deleteMemory, isDeleting, error } = useDeleteMemory();
+ *
+ * await deleteMemory(memory.metadata?.id ?? "");
+ * refetch(); // refresh the list after deletion
+ * ```
+ */
+export function useDeleteMemory(): UseDeleteMemoryReturn {
+  const stigmer = useStigmer();
+  const [isDeleting, setIsDeleting] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const deleteMemory = useCallback(
+    async (id: string): Promise<Memory> => {
+      setIsDeleting(true);
+      setError(null);
+
+      try {
+        return await stigmer.memory.delete(id);
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsDeleting(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { deleteMemory, isDeleting, error, clearError };
+}

package/src/memory/useMemories.ts

@@ -0,0 +1,66 @@
+"use client";
+
+import { create } from "@bufbuild/protobuf";
+import type { Memory } from "@stigmer/protos/ai/stigmer/agentic/memory/v1/api_pb";
+import { ListMemoriesRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/memory/v1/io_pb";
+import { useStigmer } from "../hooks.js";
+import { useFetch } from "../internal/useFetch.js";
+
+/**
+ * The server-enforced per-subject-per-org record ceiling (all lifecycle
+ * states). Requesting one page of exactly this size fetches EVERY record
+ * the caller can see, by construction — the cap is why this list needs
+ * no pagination UI.
+ */
+const MEMORY_CAP = 100;
+
+/** Return value of {@link useMemories}. */
+export interface UseMemoriesReturn {
+  /** Every memory the caller can view in the org, newest first. */
+  readonly memories: readonly Memory[];
+  /** `true` while the initial fetch is in flight. */
+  readonly isLoading: boolean;
+  /** `true` while a background refetch is in flight. */
+  readonly isRefetching: boolean;
+  /** Error from the last failed request, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Discard cached data and re-fetch the list from the server. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that fetches the caller's memories in an organization.
+ *
+ * Memory content is subject-only: the server returns exactly the records
+ * that are about the caller (FGA-filtered in cloud; single-user in local
+ * mode), so this list is always "what the platform remembers about ME
+ * here". Ordering is newest first; group by lifecycle state for display
+ * with {@link groupMemoriesByLifecycle}.
+ *
+ * Pass `null` as `org` to skip fetching (stable no-op).
+ *
+ * @example
+ * ```tsx
+ * const { memories, isLoading, refetch } = useMemories(org);
+ * const groups = groupMemoriesByLifecycle(memories);
+ * ```
+ */
+export function useMemories(org: string | null): UseMemoriesReturn {
+  const stigmer = useStigmer();
+
+  const { data: memories, isLoading, isRefetching, error, refetch } = useFetch(
+    org
+      ? () =>
+          stigmer.memory
+            .list(create(ListMemoriesRequestSchema, {
+              org,
+              pageInfo: { num: 1, size: MEMORY_CAP },
+            }))
+            .then((r) => [...r.items])
+      : null,
+    [stigmer, org],
+    [] as Memory[],
+  );
+
+  return { memories, isLoading, isRefetching, error, refetch };
+}

package/src/memory/useMemory.ts

@@ -0,0 +1,80 @@
+"use client";
+
+import type { Memory } from "@stigmer/protos/ai/stigmer/agentic/memory/v1/api_pb";
+import { isNotFound } from "@stigmer/sdk";
+import { useStigmer } from "../hooks.js";
+import { useFetch } from "../internal/useFetch.js";
+
+/** Return value of {@link useMemory}. */
+export interface UseMemoryReturn {
+  /** The memory record, or `null` while loading / not found / on error. */
+  readonly memory: Memory | null;
+  /** `true` while the initial fetch is in flight. */
+  readonly isLoading: boolean;
+  /**
+   * `true` when the record no longer exists. A first-class STATE, not an
+   * error: deletion is the platform's consent-revocation mechanism, so a
+   * consumer (the proposal chip, a deep link) must render "no longer
+   * stored" honestly rather than a failure.
+   */
+  readonly notFound: boolean;
+  /** Error from the last failed request (never not-found), or `null`. */
+  readonly error: Error | null;
+  /** Discard cached data and re-fetch the record from the server. */
+  readonly refetch: () => void;
+}
+
+/** The fetch result shape that keeps not-found distinct from errors. */
+interface MemoryLookup {
+  readonly memory: Memory | null;
+  readonly notFound: boolean;
+}
+
+const PENDING_LOOKUP: MemoryLookup = { memory: null, notFound: false };
+
+/**
+ * Data hook that fetches one memory record by id.
+ *
+ * Built for surfaces that hold a memory's identity but not its CURRENT
+ * lifecycle state — the in-thread proposal chip is the primary consumer:
+ * the tool result it renders from is frozen at capture time, while the
+ * record may have been confirmed, rejected, or deleted since (from the
+ * chip itself, the memory settings page, or another device). Content
+ * visibility is subject-only, so the fetch answers only for the person
+ * the memory is about.
+ *
+ * Pass `null` as `id` to skip fetching (stable no-op).
+ *
+ * @example
+ * ```tsx
+ * const { memory, isLoading, notFound } = useMemory(memoryId);
+ * ```
+ */
+export function useMemory(id: string | null): UseMemoryReturn {
+  const stigmer = useStigmer();
+
+  const { data, isLoading, error, refetch } = useFetch(
+    id
+      ? () =>
+          stigmer.memory.get(id).then(
+            (memory): MemoryLookup => ({ memory, notFound: false }),
+            (err): MemoryLookup => {
+              // Deletion is a state this hook reports, never an error it
+              // throws — every other failure propagates.
+              if (isNotFound(err)) return { memory: null, notFound: true };
+              throw err;
+            },
+          )
+      : null,
+    [stigmer, id],
+    PENDING_LOOKUP,
+  );
+
+  return {
+    memory: data.memory,
+    isLoading,
+    notFound: data.notFound,
+    error,
+    refetch,
+  };
+}