@vellumai/assistant 0.8.4 → 0.8.5

package/src/memory/v3/gate.ts

@@ -0,0 +1,334 @@
+/**
+ * Memory v3 — selection gate.
+ *
+ * The gate is the final step of one retrieval pass. After the scouts, the tree
+ * walk, the edge expansion, and the sticky carry-over have each contributed
+ * candidate page slugs, the gate makes one capable LLM call over the *unioned*
+ * candidate set and decides:
+ *
+ *   - **ready** — finalize the selection and inject for the next reply, or
+ *   - **more**  — the candidates don't yet cover the turn; emit follow-up
+ *     questions that seed the next pass. These questions are the gate's own
+ *     *generated* queries (a refined sub-question), NOT a replay of the
+ *     original user message — the loop feeds them back to the scouts/tree on
+ *     the next iteration.
+ *
+ * The gate also returns the final ordered `selectedSlugs` (the order the model
+ * returned, with sticky slugs guaranteed present). Sticky pages are never
+ * dropped: they were injected on a prior turn and removing them mid-conversation
+ * would silently amnesia the assistant, so we union them back in even when the
+ * model omits them.
+ *
+ * Scope — brief generation is deferred. The full v3 design pairs the selection
+ * with a ~1000-token voice brief, but that brief is only consumed when v3 is
+ * actually injected (a later cutover). In shadow mode the harness injects v2
+ * and only compares selections, so this module produces the selection +
+ * `GateDecision` only — matching what the harness trace already models. The
+ * brief-generation seam is marked below; do not build voice synthesis here.
+ *
+ * Fail-safe. If no provider is configured or the provider call errors/returns
+ * an unusable response, the gate fails *open*: it returns
+ * `decision: { decision: "ready" }` and selects every candidate. A retrieval
+ * loop that can't reach the model should still inject what it found rather than
+ * inject nothing.
+ *
+ * This module is currently unwired — a later PR composes it into the loop.
+ */
+
+import { z } from "zod";
+
+import {
+  extractToolUse,
+  getConfiguredProvider,
+} from "../../providers/provider-send-message.js";
+import type {
+  Message,
+  Provider,
+  ToolDefinition,
+} from "../../providers/types.js";
+import { getLogger } from "../../util/logger.js";
+import type { RetrievalInput } from "../v2/harness/retriever.js";
+import type { GateDecision } from "../v2/harness/trace.js";
+import type { LlmCallSink } from "./llm-capture.js";
+import { renderConversationContext } from "./prompt-context.js";
+import {
+  GATE_SYSTEM_PROMPT,
+  resolveV3SystemPrompt,
+} from "./prompts/system-prompts.js";
+
+const log = getLogger("memory-v3-gate");
+
+/** Tool name forced via `tool_choice`. Shared constant so tests can match it. */
+const GATE_TOOL_NAME = "decide_selection";
+
+/**
+ * Arguments to one gate invocation.
+ *
+ * `candidates` is the accumulated candidate set for this pass — the union of
+ * scouts-kept, tree pages, edge-pulled, and sticky slugs. `sticky` is the
+ * subset that was injected on a prior turn and must survive: it is always a
+ * subset of `candidates` in practice, but the gate unions it back into both
+ * the prompt and the final selection defensively.
+ */
+export interface RunGateArgs {
+  input: RetrievalInput;
+  candidates: Set<string>;
+  sticky: Set<string>;
+  passNumber: number;
+  /**
+   * Per-candidate one-line summaries, keyed by slug. When present, candidates
+   * are rendered to the model as `slug — summary` so the gate can judge
+   * relevance on page content rather than the slug alone. Missing entries fall
+   * back to the bare slug; the forced tool's `selected_slugs` enum stays
+   * slug-only. The loop passes this only when `memory.v3.gateCandidateSummaries`
+   * is set.
+   */
+  summaryBySlug?: ReadonlyMap<string, string>;
+  /** Optional debug sink — emits one record for the gate's LLM call. */
+  capture?: LlmCallSink;
+  /**
+   * Provider override seam for tests. Production leaves this unset and the
+   * gate resolves `getConfiguredProvider("memoryV3Gate")`. `null` is distinct
+   * from `undefined`: passing `null` simulates "no provider configured" and
+   * exercises the fail-safe path without resolving the real registry.
+   */
+  provider?: Provider | null;
+}
+
+export interface RunGateResult {
+  decision: GateDecision;
+  /** Final page slugs in the model's returned order; sticky guaranteed present. */
+  selectedSlugs: string[];
+}
+
+/**
+ * Build the forced tool definition. `selected_slugs` is the ordered final
+ * selection; `decision` is the ready/more verdict; `questions` carries the
+ * generated follow-up queries on "more" (ignored on "ready"). Mirrors the
+ * forced-tool pattern of v2's `select_pages_to_inject`.
+ */
+function buildGateTool(candidateSlugs: readonly string[]): ToolDefinition {
+  return {
+    name: GATE_TOOL_NAME,
+    description:
+      "Decide whether the accumulated candidate pages are sufficient to answer " +
+      "the next turn. Return decision='ready' with the final ordered selection " +
+      "when the candidates cover the turn; return decision='more' with one or " +
+      "more generated follow-up questions (NOT the original message) to seed " +
+      "another retrieval pass when coverage is incomplete.",
+    input_schema: {
+      type: "object",
+      properties: {
+        decision: { type: "string", enum: ["ready", "more"] },
+        selected_slugs: {
+          type: "array",
+          items: { type: "string", enum: [...candidateSlugs] },
+          description:
+            "Final ordered page slugs to inject. Each candidate is listed as " +
+            "`slug — summary` when summaries are available; return only the slug " +
+            "(left of the em-dash), and only from the candidate set. Prefer keeping " +
+            "a plausibly-relevant page over dropping it; for a list / 'all of X' / " +
+            "breadth request, include every candidate that plausibly applies rather " +
+            "than trimming to the most prominent few.",
+        },
+        questions: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "When decision='more', the generated follow-up questions seeding the next pass.",
+        },
+        reasoning: {
+          type: "string",
+          description:
+            "One short sentence: why this ready/more verdict, and which " +
+            "candidates were kept or dropped.",
+        },
+      },
+      required: ["decision"],
+    },
+  };
+}
+
+const GateToolResultSchema = z.object({
+  decision: z.enum(["ready", "more"]),
+  selected_slugs: z.array(z.string()).optional(),
+  questions: z.array(z.string()).optional(),
+  reasoning: z.string().optional(),
+});
+
+/**
+ * Render the candidate list for the prompt. With summaries available each line
+ * is `slug — summary` so the model can judge relevance on content; without them
+ * it falls back to the bare slug. The slug (left of the em-dash) is what the
+ * `selected_slugs` enum constrains, so the model always answers in slugs.
+ */
+function renderCandidateLines(
+  slugs: readonly string[],
+  summaryBySlug: ReadonlyMap<string, string> | undefined,
+): string {
+  return slugs
+    .map((slug) => {
+      const summary = summaryBySlug?.get(slug);
+      return summary ? `${slug} — ${summary}` : slug;
+    })
+    .join("\n");
+}
+
+/**
+ * Order a slug selection: keep the model's returned order, restricted to the
+ * candidate set, then append any sticky slugs the model omitted (sticky is
+ * never dropped). De-duplicates while preserving first-seen order.
+ */
+function orderSelection(
+  modelSlugs: readonly string[],
+  candidates: Set<string>,
+  sticky: Set<string>,
+): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const slug of modelSlugs) {
+    if (!candidates.has(slug)) continue; // model can only pick from candidates
+    if (seen.has(slug)) continue;
+    seen.add(slug);
+    out.push(slug);
+  }
+  for (const slug of sticky) {
+    if (seen.has(slug)) continue;
+    seen.add(slug);
+    out.push(slug);
+  }
+  return out;
+}
+
+/**
+ * Fail-safe result: inject every candidate and declare the pass ready. Used
+ * when the provider is unavailable or the call cannot produce a usable
+ * decision. Ordering puts sticky last via `orderSelection` with an empty
+ * model selection, so candidates come first then any sticky not already in
+ * the set.
+ */
+function failSafe(candidates: Set<string>, sticky: Set<string>): RunGateResult {
+  return {
+    decision: { decision: "ready" },
+    selectedSlugs: orderSelection([...candidates], candidates, sticky),
+  };
+}
+
+/**
+ * Run the gate for one pass.
+ *
+ * Makes one forced-tool LLM call over the candidate set and maps the result to
+ * a `GateDecision` plus the final ordered selection. Sticky slugs are always
+ * present in the selection. Any failure (no provider, provider throw, missing
+ * tool_use, schema mismatch) falls back to selecting all candidates with a
+ * "ready" decision.
+ */
+export async function runGate(args: RunGateArgs): Promise<RunGateResult> {
+  const { input, candidates, sticky, passNumber } = args;
+
+  const candidateSlugs = [...candidates];
+
+  // Resolve the provider. A `provider` key in args (including explicit `null`)
+  // takes precedence so tests inject a stub; production omits it and resolves
+  // the configured `memoryV3Gate` call site.
+  const provider =
+    args.provider !== undefined
+      ? args.provider
+      : await getConfiguredProvider("memoryV3Gate");
+
+  if (!provider) {
+    log.warn("memoryV3Gate provider unavailable; gate failing open (ready)");
+    return failSafe(candidates, sticky);
+  }
+
+  const systemPrompt = resolveV3SystemPrompt(
+    GATE_SYSTEM_PROMPT,
+    input.config.memory?.v3?.prompts?.gate,
+    input.workspaceDir,
+  );
+
+  const stickySlugs = [...sticky];
+  const userMsg: Message = {
+    role: "user",
+    content: [
+      {
+        type: "text",
+        text: renderConversationContext(input),
+      },
+      {
+        type: "text",
+        text:
+          `<pass_number>${passNumber}</pass_number>\n\n` +
+          `<sticky_slugs>\n${stickySlugs.join("\n")}\n</sticky_slugs>\n\n` +
+          `<candidates>\n` +
+          `${renderCandidateLines(candidateSlugs, args.summaryBySlug)}\n` +
+          `</candidates>`,
+      },
+    ],
+  };
+
+  const gateTool = buildGateTool(candidateSlugs);
+
+  const startedAt = Date.now();
+  let response;
+  try {
+    response = await provider.sendMessage([userMsg], [gateTool], systemPrompt, {
+      config: {
+        callSite: "memoryV3Gate" as const,
+        tool_choice: { type: "tool" as const, name: GATE_TOOL_NAME },
+      },
+      ...(input.signal ? { signal: input.signal } : {}),
+    });
+  } catch (err) {
+    log.warn({ err }, "Gate provider call threw; failing open (ready)");
+    return failSafe(candidates, sticky);
+  }
+
+  args.capture?.({
+    lane: "gate",
+    callSite: "memoryV3Gate",
+    request: { systemPrompt, messages: [userMsg], tools: [gateTool] },
+    response,
+    ms: Date.now() - startedAt,
+  });
+
+  const toolBlock = extractToolUse(response);
+  if (!toolBlock || toolBlock.name !== GATE_TOOL_NAME) {
+    log.warn(
+      { stopReason: response.stopReason },
+      "Gate model returned no decide_selection tool_use; failing open (ready)",
+    );
+    return failSafe(candidates, sticky);
+  }
+
+  const parsed = GateToolResultSchema.safeParse(toolBlock.input);
+  if (!parsed.success) {
+    log.warn(
+      { error: parsed.error.message },
+      "Gate tool input did not match schema; failing open (ready)",
+    );
+    return failSafe(candidates, sticky);
+  }
+
+  const selectedSlugs = orderSelection(
+    parsed.data.selected_slugs ?? [],
+    candidates,
+    sticky,
+  );
+
+  if (parsed.data.decision === "more") {
+    const questions = (parsed.data.questions ?? []).filter(
+      (q) => q.trim().length > 0,
+    );
+    const decision: GateDecision =
+      questions.length > 0
+        ? { decision: "more", questions }
+        : { decision: "more" };
+    return { decision, selectedSlugs };
+  }
+
+  // brief generation lands at cutover (P5) — shadow mode injects v2, so this
+  // gate produces only the selection + decision. Do NOT synthesize a voice
+  // brief here.
+  return { decision: { decision: "ready" }, selectedSlugs };
+}

package/src/memory/v3/index-composition.ts

@@ -0,0 +1,113 @@
+/**
+ * Memory v3 — Compositional index rendering.
+ *
+ * A v3 tree node has no stored "index" of its own. Instead, a parent node's
+ * index is *composed at read time* by concatenating one description line per
+ * child (a `node:` sub-node's summary or a `page:` leaf's summary) plus a thin
+ * `Routing hints:` trailer drawn from the node's own frontmatter. Nothing here
+ * is persisted — the block is generated fresh every time a descent prompt needs
+ * it, so it always reflects the current state of the children.
+ *
+ * {@link composeNodeIndex} is a **pure function** over an already-built
+ * {@link TreeIndex} (from `tree-index.ts`) and {@link PageIndex} (from
+ * `../v2/page-index.ts`). It does no I/O: the tree walk / driver PR is
+ * responsible for building those indices and feeding them in.
+ *
+ * Resolution rules, per child ref of `nodeId` (in authored order):
+ *   - `kind:"node"` → look up the child in `tree.nodes`; emit
+ *     `"[node:<id>] <summary>"` where summary is the child's
+ *     `frontmatter.summary` if non-empty, else the first non-empty line of its
+ *     body. A node with neither still emits its header (`"[node:<id>]"`).
+ *   - `kind:"page"` → look up `pages.bySlug.get(ref)`; emit
+ *     `"[page:<slug>] <entry.summary>"`.
+ *   - Either lookup missing → emit nothing for that ref. Reporting dangling
+ *     refs is validation's job, not this renderer's.
+ *
+ * The node's own `routing_hints` (when present) are appended last under a
+ * `Routing hints:` trailer. A node with no resolvable children and no routing
+ * hints composes to the empty string.
+ */
+
+import type { PageIndex } from "../v2/page-index.js";
+import type { TreeIndex } from "./tree-index.js";
+import type { TreeNode } from "./types.js";
+
+/** Trailer label introducing a node's own routing hints. */
+const ROUTING_HINTS_LABEL = "Routing hints:";
+
+/**
+ * Resolve a node's display summary: its frontmatter `summary` if non-empty,
+ * otherwise the first non-empty line of its body, otherwise the empty string.
+ * Whitespace is trimmed so a leading blank line in the body never wins.
+ */
+function nodeSummary(node: TreeNode): string {
+  const summary = node.frontmatter.summary?.trim();
+  if (summary) return summary;
+  for (const line of node.body.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed) return trimmed;
+  }
+  return "";
+}
+
+/**
+ * Render one child ref into its index line, or `null` when the ref's target is
+ * absent from the supplied indices (validation owns reporting those).
+ *
+ * A resolvable `node:` child always yields a line — its header (`[node:<id>]`)
+ * with a trailing summary when one exists. A `page:` child yields
+ * `[page:<slug>] <summary>`; the v2 page index already truncates `summary`.
+ */
+function renderChild(
+  kind: "page" | "node",
+  ref: string,
+  tree: TreeIndex,
+  pages: PageIndex,
+): string | null {
+  if (kind === "node") {
+    const child = tree.nodes.get(ref);
+    if (!child) return null;
+    const summary = nodeSummary(child);
+    return summary ? `[node:${ref}] ${summary}` : `[node:${ref}]`;
+  }
+  const entry = pages.bySlug.get(ref);
+  if (!entry) return null;
+  return `[page:${ref}] ${entry.summary}`;
+}
+
+/**
+ * Compose the prompt-ready index block for `nodeId` from its children's
+ * descriptions plus the node's own routing hints.
+ *
+ * Pure and deterministic: children are emitted in authored order (the order
+ * `tree.childrenByNode` preserves from the node's `children` frontmatter), refs
+ * whose targets are absent are silently skipped, and the node's
+ * `routing_hints` (if present) are appended under a {@link ROUTING_HINTS_LABEL}
+ * trailer. A node with no entry in `childrenByNode`, no resolvable children,
+ * and no routing hints composes to the empty string.
+ *
+ * The result is a plain string with no trailing newline, suitable to drop
+ * directly into an LLM descent prompt.
+ */
+export function composeNodeIndex(
+  nodeId: string,
+  tree: TreeIndex,
+  pages: PageIndex,
+): string {
+  const blocks: string[] = [];
+
+  const childRefs = tree.childrenByNode.get(nodeId) ?? [];
+  for (const { kind, ref } of childRefs) {
+    const line = renderChild(kind, ref, tree, pages);
+    if (line !== null) blocks.push(line);
+  }
+
+  const routingHints = tree.nodes
+    .get(nodeId)
+    ?.frontmatter.routing_hints?.trim();
+  if (routingHints) {
+    blocks.push(`${ROUTING_HINTS_LABEL} ${routingHints}`);
+  }
+
+  return blocks.join("\n");
+}

package/src/memory/v3/llm-capture.ts

@@ -0,0 +1,46 @@
+/**
+ * Memory v3 — LLM-call capture types.
+ *
+ * A debugging seam: when a sink is threaded into the retrieval loop, every v3
+ * LLM call (dense filter, each tree-walk descender call, the gate) emits one
+ * {@link LlmCallRecord} carrying the full input it sent and the raw response it
+ * got back. The `simulate` path collects these so an operator can inspect what
+ * each call actually saw and returned. Nothing here is persisted, and the sink
+ * is `undefined` on every non-simulate path, so production pays zero cost.
+ *
+ * Leaf module: it imports only provider types, so the lanes and the loop can
+ * depend on it without a cycle.
+ */
+
+import type {
+  Message,
+  ProviderResponse,
+  ToolDefinition,
+} from "../../providers/types.js";
+
+/**
+ * One captured v3 LLM call — its full input (system prompt, messages, tool
+ * schema) and raw output (provider response). `pass` is the 1-based retrieval
+ * pass the call ran in; `node` is set only for the tree-walk descender (the
+ * node whose composed index it judged). `ms` is the provider round-trip time.
+ */
+export interface LlmCallRecord {
+  pass: number;
+  lane: "filter" | "descent" | "gate";
+  callSite: string;
+  node?: string;
+  request: {
+    systemPrompt: string;
+    messages: Message[];
+    tools: ToolDefinition[];
+  };
+  response: ProviderResponse;
+  ms: number;
+}
+
+/**
+ * The sink a lane calls to emit a capture record. Lanes don't know their pass
+ * number, so they emit without `pass` and the loop wraps the sink to stamp the
+ * current pass. `undefined` on every non-capturing path (the common case).
+ */
+export type LlmCallSink = (record: Omit<LlmCallRecord, "pass">) => void;