@stigmer/react 3.12.7 → 3.12.9

package/src/execution/RecalledMemoriesCard.tsx

@@ -0,0 +1,164 @@
+"use client";
+
+import { memo, useId, useMemo, useState } from "react";
+import type { RecalledMemoriesReport } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { RecalledMemoryFact } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
+import { cn } from "@stigmer/theme";
+
+/**
+ * Resolve the report's injected memory ids against the execution's
+ * snapshot facts, preserving snapshot order (the stable prompt order —
+ * the selector re-sorts its subset the same way, so this join renders
+ * the facts exactly as the agent saw them).
+ *
+ * The contract guarantees injected ids are a subset of the snapshot
+ * (the merge path's never-invent pin), so an unknown id can only mean a
+ * bug upstream — it is skipped, never invented. The summary count stays
+ * the wire truth (`injectedMemoryIds.length`) regardless.
+ */
+export function resolveInjectedFacts(
+  report: RecalledMemoriesReport,
+  facts: readonly RecalledMemoryFact[],
+): RecalledMemoryFact[] {
+  const injected = new Set(report.injectedMemoryIds);
+  return facts.filter((fact) => injected.has(fact.memoryId));
+}
+
+/** Props for {@link RecalledMemoriesCard}. */
+export interface RecalledMemoriesCardProps {
+  /** The runner's injection report from the execution's status. */
+  readonly report: RecalledMemoriesReport;
+  /** The full candidate set from `spec.recalled_memories.facts`. */
+  readonly facts: readonly RecalledMemoryFact[];
+  /** Additional CSS classes for the root element. */
+  readonly className?: string;
+}
+
+/**
+ * Inline timeline card disclosing the semantic retriever's selection for
+ * one execution: "Recalled N of M memories", expandable to the injected
+ * facts (stigmer/stigmer#293 Phase 3a, DD-008 D5's transparency promise).
+ *
+ * Renders at the top of the execution's {@link MessageThread} segment,
+ * right after the user's turn — `spec.message` is the query the
+ * retriever embedded, so the card reads as "for this message, these
+ * memories were most relevant".
+ *
+ * Renders NOTHING unless the report says selection was active: an
+ * absent report and `selection_active=false` both mean wholesale (every
+ * snapshot fact injected — the shipped Phase 2 behavior), and unchanged
+ * behavior earns no UI noise. The same rule is applied by the thread
+ * builder; it is repeated here so directly-embedding platform builders
+ * get the correct contract by construction.
+ *
+ * All visual properties flow through `--stgm-*` tokens.
+ *
+ * @see resolveInjectedFacts - the report→snapshot join this card renders
+ * @see SummarizationCard - the sibling system-event card this follows
+ */
+export const RecalledMemoriesCard = memo(function RecalledMemoriesCard({
+  report,
+  facts,
+  className,
+}: RecalledMemoriesCardProps) {
+  const [expanded, setExpanded] = useState(false);
+  const listId = useId();
+
+  const injectedFacts = useMemo(
+    () => resolveInjectedFacts(report, facts),
+    [report, facts],
+  );
+
+  if (!report.selectionActive) return null;
+
+  const injectedCount = report.injectedMemoryIds.length;
+  const summary = `Recalled ${injectedCount} of ${facts.length} memories`;
+
+  return (
+    <div
+      role="status"
+      aria-label={summary}
+      className={cn(
+        "stg:mx-4 stg:rounded-md stg:border stg:border-border/50 stg:bg-muted/30",
+        className,
+      )}
+    >
+      <button
+        type="button"
+        aria-expanded={expanded}
+        aria-controls={listId}
+        onClick={() => setExpanded((prev) => !prev)}
+        className={cn(
+          "stg:flex stg:w-full stg:items-center stg:gap-3 stg:px-3 stg:py-2 stg:text-left",
+          "stg:text-xs stg:text-muted-foreground hover:stg:text-foreground",
+        )}
+      >
+        <MemoryIcon />
+        <span className="stg:flex stg:min-w-0 stg:flex-1 stg:flex-wrap stg:items-baseline stg:gap-x-2">
+          <span className="stg:font-medium">{summary}</span>
+          {report.embeddingModel && (
+            <>
+              <span aria-hidden="true" className="stg:text-muted-foreground/50">&middot;</span>
+              <span className="stg:text-muted-foreground/80">{report.embeddingModel}</span>
+            </>
+          )}
+        </span>
+        <ChevronIcon expanded={expanded} />
+      </button>
+      {expanded && (
+        <ul
+          id={listId}
+          className="stg:m-0 stg:flex stg:list-none stg:flex-col stg:gap-1.5 stg:border-t stg:border-border/50 stg:px-3 stg:py-2"
+        >
+          {injectedFacts.map((fact) => (
+            <li
+              key={fact.memoryId}
+              className="stg:text-xs stg:leading-relaxed stg:text-muted-foreground"
+            >
+              {fact.content}
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+});
+
+function MemoryIcon() {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className="stg:shrink-0 stg:text-muted-foreground/70"
+      aria-hidden="true"
+    >
+      <path d="M8 2a3 3 0 0 0-3 3c-1.2.4-2 1.5-2 2.8 0 1 .5 1.9 1.3 2.4A2.8 2.8 0 0 0 7 13.8c.4.1.7.2 1 .2s.6-.1 1-.2a2.8 2.8 0 0 0 2.7-3.6c.8-.5 1.3-1.4 1.3-2.4 0-1.3-.8-2.4-2-2.8a3 3 0 0 0-3-3z" />
+      <path d="M8 2v12" />
+    </svg>
+  );
+}
+
+function ChevronIcon({ expanded }: { expanded: boolean }) {
+  return (
+    <svg
+      width="14"
+      height="14"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className="stg:shrink-0 stg:text-muted-foreground/70"
+      aria-hidden="true"
+    >
+      {expanded ? <path d="M4 10l4-4 4 4" /> : <path d="M4 6l4 4 4-4" />}
+    </svg>
+  );
+}

package/src/execution/ResultView.tsx

@@ -80,6 +80,12 @@ export function ResultView({ view, showFileName = true, showStats = true, classN
       return view.text ? <CollapsiblePre content={view.text} className={cn("stg:text-foreground", className)} /> : null;
     case "json":
       return <CollapsibleCode label="Result" content={formatJson(view.value)} className={className} />;
+    case "memoryProposal":
+      // Fallback for consumers composing ResultView directly: the verbatim
+      // proposed fact (DD-005 D6 — never paraphrased). The consent chip
+      // (Confirm/Reject, live lifecycle state) is the thread's primary
+      // surface for this view and renders it in place of this.
+      return <CollapsiblePre content={view.fact} className={cn("stg:text-foreground", className)} />;
     case "error":
       return <ErrorResultView message={view.message} className={className} />;
     case "empty":

package/src/execution/ToolCallItem.tsx

@@ -26,6 +26,7 @@ import { TerminalTail } from "./TerminalSession.js";
 import { ToolCallDetail, formatHeaderDuration } from "./ToolCallDetail.js";
 import { SubAgentSection } from "./SubAgentSection.js";
 import { ApprovalCardBody } from "./ApprovalCard.js";
+import { MemoryProposalCardBody } from "../memory/MemoryProposalCard.js";
 import { useApproval } from "./ApprovalContext.js";
 import { useFileReviewRowState } from "./FileReviewContext.js";
 import type { FileReviewRowState } from "./file-review-status.js";
@@ -351,7 +352,8 @@ export const ToolCallItem = memo(function ToolCallItem({
     (disclosure === "preview" || (isTailCategory && tailSession == null));
 
   // The disclosed body, shared by both layouts: a pending gate decides inline,
-  // a sub-agent shows its delegation, otherwise the category detail.
+  // a sub-agent shows its delegation, a settled remember call renders the
+  // memory-proposal consent surface, otherwise the category detail.
   const body = isSubAgent ? (
     <SubAgentSection subAgentExecution={subAgentExecution} collapsible={false} />
   ) : approval ? (
@@ -364,6 +366,12 @@ export const ToolCallItem = memo(function ToolCallItem({
       isSubmitting={approval.isSubmitting}
       error={approval.error}
     />
+  ) : result.type === "memoryProposal" ? (
+    // The remember tool's consent chip (DD-005 D4): verbatim fact +
+    // Confirm/Reject, with the record's CURRENT lifecycle fetched so a
+    // reloaded thread never shows stale action buttons. Borderless — this
+    // row's card owns the chrome (the ApprovalCardBody posture).
+    <MemoryProposalCardBody memoryId={result.memoryId} fact={result.fact} />
   ) : (
     <ToolCallDetail
       toolCall={toolCall}
@@ -608,9 +616,18 @@ export const CATEGORY_ICON: Record<ToolCategory, () => React.JSX.Element> = {
   "sub-agent": BotIcon,
   internal: WrenchIcon,
   mcp: McpPlugIcon,
+  memory: BookmarkIcon,
   unknown: WrenchIcon,
 };
 
+function BookmarkIcon() {
+  return (
+    <svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" strokeWidth="1.2" strokeLinecap="round" strokeLinejoin="round">
+      <path d="M9 11L6 8.5L3 11V2.5C3 1.95 3.45 1.5 4 1.5H8C8.55 1.5 9 1.95 9 2.5V11Z" />
+    </svg>
+  );
+}
+
 function GlobeIcon() {
   return (
     <svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" strokeWidth="1.2" strokeLinecap="round" strokeLinejoin="round">

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

@@ -0,0 +1,123 @@
+// The retriever transparency card (stigmer/stigmer#293 Phase 3a, DD-008
+// D5): an honest "Recalled N of M memories" join of the status report
+// against the spec snapshot — and NOTHING for wholesale, the majority
+// case that must stay noise-free.
+
+import { describe, it, expect, afterEach } from "vitest";
+import { cleanup, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { create } from "@bufbuild/protobuf";
+import {
+  RecalledMemoriesReportSchema,
+  type RecalledMemoriesReport,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import {
+  RecalledMemoryFactSchema,
+  type RecalledMemoryFact,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
+import {
+  RecalledMemoriesCard,
+  resolveInjectedFacts,
+} from "../RecalledMemoriesCard";
+
+function makeFact(id: string, content: string): RecalledMemoryFact {
+  return create(RecalledMemoryFactSchema, { memoryId: id, content });
+}
+
+function makeReport(
+  overrides: Partial<Pick<RecalledMemoriesReport, "selectionActive" | "injectedMemoryIds" | "embeddingModel">>,
+): RecalledMemoriesReport {
+  return create(RecalledMemoriesReportSchema, {
+    selectionActive: true,
+    embeddingModel: "text-embedding-3-small",
+    ...overrides,
+  });
+}
+
+const SNAPSHOT: RecalledMemoryFact[] = [
+  makeFact("mem_a", "Prefers concise answers."),
+  makeFact("mem_b", "Works in the Europe/Berlin timezone."),
+  makeFact("mem_c", "Deploys with Bazel."),
+  makeFact("mem_d", "Reviews PRs on Fridays."),
+];
+
+afterEach(cleanup);
+
+describe("resolveInjectedFacts", () => {
+  it("preserves snapshot order regardless of the report's id order", () => {
+    const report = makeReport({ injectedMemoryIds: ["mem_d", "mem_a"] });
+    expect(resolveInjectedFacts(report, SNAPSHOT).map((f) => f.memoryId)).toEqual([
+      "mem_a",
+      "mem_d",
+    ]);
+  });
+
+  it("skips an unknown id — never invents a fact", () => {
+    const report = makeReport({ injectedMemoryIds: ["mem_b", "mem_ghost"] });
+    expect(resolveInjectedFacts(report, SNAPSHOT).map((f) => f.memoryId)).toEqual([
+      "mem_b",
+    ]);
+  });
+
+  it("returns nothing against an empty snapshot", () => {
+    const report = makeReport({ injectedMemoryIds: ["mem_a"] });
+    expect(resolveInjectedFacts(report, [])).toEqual([]);
+  });
+});
+
+describe("RecalledMemoriesCard", () => {
+  it("renders nothing for a wholesale report (selection_active=false)", () => {
+    const report = makeReport({
+      selectionActive: false,
+      injectedMemoryIds: [],
+      embeddingModel: "",
+    });
+    const { container } = render(
+      <RecalledMemoriesCard report={report} facts={SNAPSHOT} />,
+    );
+    expect(container.innerHTML).toBe("");
+  });
+
+  it("summarizes the selection with the wire count and the embedding model", () => {
+    const report = makeReport({ injectedMemoryIds: ["mem_a", "mem_c"] });
+    render(<RecalledMemoriesCard report={report} facts={SNAPSHOT} />);
+
+    expect(screen.getByRole("status", { name: "Recalled 2 of 4 memories" })).toBeTruthy();
+    expect(screen.getByText("text-embedding-3-small")).toBeTruthy();
+    // Collapsed by default: the facts are behind the disclosure.
+    expect(screen.queryByText("Prefers concise answers.")).toBeNull();
+  });
+
+  it("expands to exactly the injected facts, in snapshot order", async () => {
+    const report = makeReport({ injectedMemoryIds: ["mem_c", "mem_a"] });
+    render(<RecalledMemoriesCard report={report} facts={SNAPSHOT} />);
+    const user = userEvent.setup();
+
+    const toggle = screen.getByRole("button", { expanded: false });
+    expect(toggle.getAttribute("aria-controls")).toBeTruthy();
+
+    await user.click(toggle);
+
+    expect(toggle.getAttribute("aria-expanded")).toBe("true");
+    const items = screen.getAllByRole("listitem").map((li) => li.textContent);
+    expect(items).toEqual(["Prefers concise answers.", "Deploys with Bazel."]);
+    // Non-injected snapshot facts never render.
+    expect(screen.queryByText("Works in the Europe/Berlin timezone.")).toBeNull();
+
+    await user.click(toggle);
+    expect(toggle.getAttribute("aria-expanded")).toBe("false");
+    expect(screen.queryByRole("listitem")).toBeNull();
+  });
+
+  it("keeps the summary count honest when an id cannot be resolved", async () => {
+    // Contractually impossible (injected ids ⊂ snapshot, the merge path's
+    // never-invent pin) — but if it ever happens, the count stays the wire
+    // truth and the list simply omits the unresolvable entry.
+    const report = makeReport({ injectedMemoryIds: ["mem_b", "mem_ghost"] });
+    render(<RecalledMemoriesCard report={report} facts={SNAPSHOT} />);
+
+    expect(screen.getByRole("status", { name: "Recalled 2 of 4 memories" })).toBeTruthy();
+    await userEvent.setup().click(screen.getByRole("button"));
+    expect(screen.getAllByRole("listitem")).toHaveLength(1);
+  });
+});

package/src/execution/__tests__/message-thread-recalled-memories.test.tsx

@@ -0,0 +1,216 @@
+// Thread emission rules for the retriever transparency card
+// (stigmer/stigmer#293 Phase 3a, DD-008 D5). The load-bearing pins:
+//
+//   1. The card is a PER-SEGMENT item derived from each execution's own
+//      spec+status — NOT a live-only tail indicator like setup-progress.
+//      A historical (non-active) execution keeps its card forever; that
+//      is the audit property, and the regression this file exists to
+//      catch (a live-only mechanism would render correctly during
+//      streaming and silently lose the record afterwards).
+//   2. Absent report and selection_active=false both render NOTHING —
+//      wholesale is the unchanged majority behavior and earns no noise.
+//   3. The card is gated on the REPORT, not the prompt bubble:
+//      syntheticUserPrompt deliberately skips some user turns (empty
+//      prompt), and those executions can still be selection-active.
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, screen, cleanup } from "@testing-library/react";
+import { create } from "@bufbuild/protobuf";
+import {
+  AgentExecutionSchema,
+  AgentExecutionStatusSchema,
+  RecalledMemoriesReportSchema,
+  type AgentExecution,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import {
+  AgentExecutionSpecSchema,
+  RecalledMemoriesSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+import { AgentMessageSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import {
+  ExecutionPhase,
+  MessageType,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+import { MessageThread } from "../MessageThread";
+
+// useAutoScroll depends on browser APIs not available in happy-dom.
+beforeEach(() => {
+  vi.stubGlobal(
+    "IntersectionObserver",
+    vi.fn(() => ({
+      observe: vi.fn(),
+      unobserve: vi.fn(),
+      disconnect: vi.fn(),
+      takeRecords: vi.fn(() => []),
+      root: null,
+      rootMargin: "",
+      thresholds: [0],
+    })),
+  );
+  vi.stubGlobal(
+    "ResizeObserver",
+    vi.fn(() => ({ observe: vi.fn(), unobserve: vi.fn(), disconnect: vi.fn() })),
+  );
+});
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+function makeExecution(opts: {
+  id: string;
+  specMessage?: string;
+  facts?: ReadonlyArray<{ id: string; content: string }>;
+  report?: { selectionActive: boolean; injectedMemoryIds?: string[] };
+}): AgentExecution {
+  const exec = create(AgentExecutionSchema);
+  exec.metadata = create(ApiResourceMetadataSchema, { id: opts.id });
+
+  const spec = create(AgentExecutionSpecSchema);
+  spec.message = opts.specMessage ?? "Hello";
+  if (opts.facts) {
+    spec.recalledMemories = create(RecalledMemoriesSchema, {
+      enabled: true,
+      facts: opts.facts.map((f) => ({ memoryId: f.id, content: f.content })),
+    });
+  }
+  exec.spec = spec;
+
+  const status = create(AgentExecutionStatusSchema);
+  status.phase = ExecutionPhase.EXECUTION_COMPLETED;
+  status.messages = [
+    create(AgentMessageSchema, { type: MessageType.MESSAGE_AI, content: "Done." }),
+  ];
+  if (opts.report) {
+    status.recalledMemoriesReport = create(RecalledMemoriesReportSchema, {
+      selectionActive: opts.report.selectionActive,
+      injectedMemoryIds: opts.report.injectedMemoryIds ?? [],
+      embeddingModel: opts.report.selectionActive ? "text-embedding-3-small" : "",
+    });
+  }
+  exec.status = status;
+  return exec;
+}
+
+const FACTS = [
+  { id: "mem_a", content: "Prefers concise answers." },
+  { id: "mem_b", content: "Deploys with Bazel." },
+  { id: "mem_c", content: "Reviews PRs on Fridays." },
+];
+
+describe("MessageThread recalled-memories item", () => {
+  it("emits the card inside a selection-active execution's segment, after the user turn", () => {
+    render(
+      <MessageThread
+        executions={[
+          makeExecution({
+            id: "e1",
+            specMessage: "prompt text",
+            facts: FACTS,
+            report: { selectionActive: true, injectedMemoryIds: ["mem_a", "mem_c"] },
+          }),
+        ]}
+      />,
+    );
+
+    const card = screen.getByRole("status", { name: "Recalled 2 of 3 memories" });
+    const userBubble = screen.getByRole("article", { name: "User message" });
+    // Segment order: user turn first, then the card the turn's prompt selected.
+    expect(
+      userBubble.compareDocumentPosition(card) & Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+  });
+
+  it("emits nothing for an absent report (pre-3a and no-injection executions read identically)", () => {
+    render(
+      <MessageThread
+        executions={[makeExecution({ id: "e1", facts: FACTS })]}
+      />,
+    );
+    expect(screen.queryByRole("status", { name: /Recalled/ })).toBeNull();
+  });
+
+  it("emits nothing for a wholesale report (selection_active=false)", () => {
+    render(
+      <MessageThread
+        executions={[
+          makeExecution({
+            id: "e1",
+            facts: FACTS,
+            report: { selectionActive: false },
+          }),
+        ]}
+      />,
+    );
+    expect(screen.queryByRole("status", { name: /Recalled/ })).toBeNull();
+  });
+
+  it("keeps the card on a HISTORICAL execution while another execution streams", () => {
+    // The audit pin: the card derives from the execution's own segment, so
+    // it must survive the execution no longer being the active stream — a
+    // live-only mechanism (the setup-progress shape) would lose it here.
+    const historical = makeExecution({
+      id: "e-old",
+      specMessage: "earlier turn",
+      facts: FACTS,
+      report: { selectionActive: true, injectedMemoryIds: ["mem_b"] },
+    });
+    const live = makeExecution({ id: "e-live", specMessage: "current turn" });
+    live.status!.phase = ExecutionPhase.EXECUTION_IN_PROGRESS;
+
+    render(
+      <MessageThread executions={[historical]} activeStreamExecution={live} />,
+    );
+
+    expect(
+      screen.getByRole("status", { name: "Recalled 1 of 3 memories" }),
+    ).toBeTruthy();
+  });
+
+  it("emits one card per selection-active execution", () => {
+    render(
+      <MessageThread
+        executions={[
+          makeExecution({
+            id: "e1",
+            facts: FACTS,
+            report: { selectionActive: true, injectedMemoryIds: ["mem_a"] },
+          }),
+          makeExecution({ id: "e2", facts: FACTS }),
+          makeExecution({
+            id: "e3",
+            facts: FACTS,
+            report: { selectionActive: true, injectedMemoryIds: ["mem_a", "mem_b"] },
+          }),
+        ]}
+      />,
+    );
+
+    expect(screen.getByRole("status", { name: "Recalled 1 of 3 memories" })).toBeTruthy();
+    expect(screen.getByRole("status", { name: "Recalled 2 of 3 memories" })).toBeTruthy();
+    expect(screen.getAllByRole("status", { name: /Recalled/ })).toHaveLength(2);
+  });
+
+  it("emits the card even when the user-turn bubble is skipped (empty prompt)", () => {
+    render(
+      <MessageThread
+        executions={[
+          makeExecution({
+            id: "e1",
+            specMessage: "",
+            facts: FACTS,
+            report: { selectionActive: true, injectedMemoryIds: ["mem_c"] },
+          }),
+        ]}
+      />,
+    );
+
+    expect(screen.queryByRole("article", { name: "User message" })).toBeNull();
+    expect(
+      screen.getByRole("status", { name: "Recalled 1 of 3 memories" }),
+    ).toBeTruthy();
+  });
+});