@vellumai/assistant 0.8.5 → 0.8.7

package/src/memory/v3/edges.ts

@@ -1,249 +0,0 @@
-/**
- * Memory v3 — Curated edge-expansion lane.
- *
- * Given a set of confident seed slugs, pull their 1–2 hop *outgoing*
- * neighborhood from the curated `edges:` graph (each concept page's
- * frontmatter `edges:` list, surfaced by v2's `getEdgeIndex`). This is a
- * provider-free, read-only structural expansion — no LLM, no scoring. It
- * answers "given that we're confident about A, what does A's curated graph
- * say we should also pull in?".
- *
- * The optional `extraAdjacency` parameter is the seam a later PR uses to inject
- * above-threshold *weighted auto-edges* (edges the system learned, not ones a
- * human curated) WITHOUT modifying this module. When supplied, it is treated as
- * additional out-edges merged with the curated graph during traversal: the
- * effective out-neighborhood of a node is `curated[node] ∪ extraAdjacency[node]`.
- *
- * The result is the union of every seed's reachable neighborhood (`pulled`,
- * with seeds themselves excluded) plus a per-seed `EdgeExpansion[]` trace so a
- * harness can attribute each pulled slug to the seed it came from.
- */
-
-import { getEdgeIndex, getReachable } from "../v2/edge-index.js";
-import type { EdgeExpansion } from "../v2/harness/trace.js";
-
-/** Default hop budget. The design calls for a 1–2 hop walk; 2 is the ceiling. */
-const DEFAULT_HOPS = 2;
-
-// ---------------------------------------------------------------------------
-// Expansion bounds
-// ---------------------------------------------------------------------------
-//
-// The seed set handed to this lane is the *union* of every upstream lane's
-// candidates (scouts + dense filter + tree-walk descent), so on a mature corpus
-// it can run to one-to-two-thousand slugs. Expanding all of them — each to its
-// full 1–2 hop neighborhood — pulls in tens of thousands of slugs, which inflates
-// the downstream selection gate's candidate pool toward the entire corpus and
-// drowns the high-confidence signal. The expansion is also purely structural
-// (no scoring), so a larger pool buys no precision; it only adds gate cost.
-//
-// These bounds keep the lane's output proportional to a curated neighborhood
-// rather than the corpus. They are module-level constants (mirroring
-// `LANE_QUERY_LIMIT` in `scouts.ts`) rather than config fields so the lane stays
-// self-contained — the caps protect the gate regardless of how callers compose
-// the seed union. Truncation is deterministic (sorted slugs) so a given seed
-// graph always yields the same bounded result.
-
-/**
- * Cap on the number of distinct seeds expanded. Seeds are processed in
- * first-seen order; once this many have been expanded the rest are dropped. The
- * upstream lanes already rank their hits, so the earliest seeds are the most
- * confident — truncating the long tail costs little recall.
- */
-const MAX_SEEDS_EXPANDED = 150;
-
-/**
- * Cap on how many slugs a single seed may contribute. A hub node in a dense
- * curated graph can reach a large 2-hop neighborhood on its own; without this a
- * single highly-connected seed could dominate the union. The per-seed
- * neighborhood is truncated to its lexicographically-first slugs.
- */
-const MAX_PULLS_PER_SEED = 32;
-
-/**
- * Hard ceiling on the size of the unioned `pulled` set. This is the load-bearing
- * bound: it caps the lane's contribution to the gate's pool to a few hundred
- * slugs no matter how many seeds or how dense the graph. Once reached, no
- * further seeds are expanded.
- */
-const MAX_TOTAL_PULLS = 400;
-
-// ---------------------------------------------------------------------------
-// Seed ranking
-// ---------------------------------------------------------------------------
-
-/**
- * Lane-trust order used to rank seeds *before* the {@link MAX_SEEDS_EXPANDED}
- * cap (lower = expanded first). The seed union arrives in lane order (hot
- * first), so without reordering the seed budget is spent on the hot recency
- * lane and the LLM-vetted tree/dense seeds — the most query-relevant — are the
- * ones truncated. Ranking tree > dense > sparse > hot spends the budget on
- * relevance first. A seed whose lane is unknown/absent (or edge-pulled) ranks
- * last. Requires `laneBySlug`; without it the incoming order is kept.
- */
-const SEED_LANE_RANK: Readonly<Record<string, number>> = {
-  tree: 0,
-  dense: 1,
-  sparse: 2,
-  hot: 3,
-};
-const SEED_LANE_RANK_LAST = 4;
-
-function seedRank(
-  slug: string,
-  laneBySlug: ReadonlyMap<string, string>,
-): number {
-  const lane = laneBySlug.get(slug);
-  return lane !== undefined
-    ? (SEED_LANE_RANK[lane] ?? SEED_LANE_RANK_LAST)
-    : SEED_LANE_RANK_LAST;
-}
-
-export interface ExpandEdgesArgs {
-  workspaceDir: string;
-  /** Confident seed slugs to expand from. */
-  seeds: Iterable<string>;
-  /**
-   * Per-seed lane provenance (slug → first lane that surfaced it). When present,
-   * seeds are ranked by lane trust ({@link SEED_LANE_RANK}) before the seed cap,
-   * so the budget is spent on query-relevant seeds rather than recency. Typed as
-   * a plain string map to avoid importing the loop's `LaneSource` (circular).
-   */
-  laneBySlug?: ReadonlyMap<string, string>;
-  /** Hop budget for the outgoing walk. Defaults to {@link DEFAULT_HOPS}. */
-  hops?: number;
-  /**
-   * Extra *outgoing* adjacency (`from → Set<to>`) merged with the curated graph
-   * during traversal. The injection seam for learned weighted auto-edges; this
-   * module never reads or thresholds weights itself — the caller pre-filters to
-   * above-threshold edges before passing them in.
-   */
-  extraAdjacency?: ReadonlyMap<string, ReadonlySet<string>>;
-}
-
-export interface ExpandEdgesResult {
-  /** Union of every seed's reachable neighborhood, seeds excluded. */
-  pulled: Set<string>;
-  /** Per-seed attribution: which slugs each seed pulled in. */
-  expansions: EdgeExpansion[];
-}
-
-/**
- * BFS the outgoing neighborhood of `seed` within `hops`, walking the union of
- * the curated `outgoing` adjacency and any `extraAdjacency`. Mirrors v2's
- * `getReachable` semantics — start excluded, bounded by `hops` and a visited
- * set so cycles can't loop — but over a merged adjacency view.
- */
-function reachableMerged(
-  curated: ReadonlyMap<string, ReadonlySet<string>>,
-  extra: ReadonlyMap<string, ReadonlySet<string>>,
-  seed: string,
-  hops: number,
-): Set<string> {
-  const result = new Set<string>();
-  if (hops <= 0) return result;
-
-  const visited = new Set<string>([seed]);
-  let frontier: string[] = [seed];
-
-  for (let depth = 0; depth < hops && frontier.length > 0; depth++) {
-    const next: string[] = [];
-    for (const node of frontier) {
-      const curatedNeighbors = curated.get(node);
-      const extraNeighbors = extra.get(node);
-      for (const neighbors of [curatedNeighbors, extraNeighbors]) {
-        if (!neighbors) continue;
-        for (const neighbor of neighbors) {
-          if (visited.has(neighbor)) continue;
-          visited.add(neighbor);
-          result.add(neighbor);
-          next.push(neighbor);
-        }
-      }
-    }
-    frontier = next;
-  }
-
-  return result;
-}
-
-/**
- * Expand a set of confident seed slugs to their 1–2 hop curated neighborhood.
- *
- * Each expanded seed produces one `EdgeExpansion { from, pulled }` entry (sorted
- * slugs for deterministic output); the seed itself is never in its own `pulled`.
- * The top-level `pulled` set is the union across all expanded seeds — a slug
- * pulled by more than one seed appears once there but in each contributing
- * seed's expansion.
- *
- * Bounded by {@link MAX_SEEDS_EXPANDED}, {@link MAX_PULLS_PER_SEED}, and
- * {@link MAX_TOTAL_PULLS} so a large seed union or a dense graph can't balloon
- * the downstream gate's pool — see the bounds block above. Seeds past the count
- * cap, or any seed reached after the union ceiling is full, are skipped entirely
- * and get no expansion entry; every entry that is emitted lists exactly the
- * slugs that seed contributed to the bounded union, so the trace stays faithful.
- *
- * Provider-free and read-only: the only I/O is `getEdgeIndex`, which reads
- * concept-page frontmatter from disk (and caches module-locally in v2).
- */
-export async function expandEdges(
-  args: ExpandEdgesArgs,
-): Promise<ExpandEdgesResult> {
-  const {
-    workspaceDir,
-    seeds,
-    hops = DEFAULT_HOPS,
-    extraAdjacency,
-    laneBySlug,
-  } = args;
-
-  const index = await getEdgeIndex(workspaceDir);
-  const pulled = new Set<string>();
-  const expansions: EdgeExpansion[] = [];
-
-  // Rank seeds by lane trust before the seed cap so the budget goes to the most
-  // query-relevant seeds (tree/dense/sparse) rather than recency (hot), which
-  // leads the incoming candidate order. `Array.prototype.sort` is stable, so
-  // seeds within a tier keep their candidate order. Without `laneBySlug` the
-  // incoming order is preserved.
-  const orderedSeeds = [...seeds];
-  if (laneBySlug) {
-    orderedSeeds.sort(
-      (a, b) => seedRank(a, laneBySlug) - seedRank(b, laneBySlug),
-    );
-  }
-
-  // De-dupe seeds while preserving (ranked) order for a stable trace.
-  const seenSeeds = new Set<string>();
-
-  for (const seed of orderedSeeds) {
-    if (seenSeeds.has(seed)) continue;
-    seenSeeds.add(seed);
-
-    // Bound the number of seeds expanded, and stop once the union is full —
-    // the remaining seeds would only inflate the gate's pool. Checked before
-    // doing any per-seed work so an oversized seed set is cheap to truncate.
-    if (seenSeeds.size > MAX_SEEDS_EXPANDED || pulled.size >= MAX_TOTAL_PULLS) {
-      break;
-    }
-
-    const reachable = extraAdjacency
-      ? reachableMerged(index.outgoing, extraAdjacency, seed, hops)
-      : getReachable(index, seed, hops, "out");
-
-    // Per-seed fan-out cap, then trim to the union's remaining headroom so the
-    // total ceiling is hard (never overshot) and the trace entry lists exactly
-    // the slugs this seed contributed to the bounded union. Sorting first keeps
-    // truncation deterministic — a hub seed always yields the same slice. Slugs
-    // already pulled by an earlier seed don't consume headroom (the union Set
-    // de-dupes), so this is a conservative upper bound on what's admitted.
-    const remaining = MAX_TOTAL_PULLS - pulled.size;
-    const perSeedCap = Math.min(MAX_PULLS_PER_SEED, remaining);
-    const seedPulled = [...reachable].sort().slice(0, perSeedCap);
-
-    expansions.push({ from: seed, pulled: seedPulled });
-    for (const slug of seedPulled) pulled.add(slug);
-  }
-
-  return { pulled, expansions };
-}

package/src/memory/v3/filter.ts

@@ -1,281 +0,0 @@
-/**
- * Memory v3 — fast dense-hit filter.
- *
- * The dense scout lane surfaces embedding-similarity candidates that span
- * subtrees: some are meaningful cross-domain associations worth carrying into
- * the gate, others are spurious near-neighbors that only crowd the slate. This
- * module makes **one cheap LLM call** to keep the meaningful associations and
- * drop the noise, *before* the more expensive selection gate runs.
- *
- * What it judges. Only the bounded dense candidate set (the scout lane is
- * already capped at ~50–200 by quota/MMR — the filter never sees the whole
- * corpus). Hot pages and near-exact sparse hits arrive via the scouts'
- * `sticky` / `bypass` sets and are **never judged**: a literal keyword hit or a
- * page the user has been touching is a strong enough signal that we shouldn't
- * make it earn its place through a fallible cheap judgment. They are unioned
- * straight into `kept`.
- *
- * Fail-open. If no provider is configured or the call errors / returns an
- * unusable response, the filter keeps *all* dense candidates and surfaces a
- * `failureReason` so the loop can record that the filter was bypassed. Dropping
- * candidates on a model outage would silently starve retrieval; keeping them is
- * the safe degradation (the downstream gate still narrows the slate).
- *
- * No LLM call when there is nothing to judge. An empty dense set short-circuits
- * to `kept` = the bypass-relevant slugs (no judged additions), with no provider
- * round-trip.
- *
- * 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 { ScoutResult } from "../v2/harness/trace.js";
-import type { LlmCallSink } from "./llm-capture.js";
-import { renderConversationContext } from "./prompt-context.js";
-import {
-  FILTER_SYSTEM_PROMPT,
-  resolveV3SystemPrompt,
-} from "./prompts/system-prompts.js";
-
-const log = getLogger("memory-v3-filter");
-
-/** Tool name forced via `tool_choice`. Shared constant so tests can match it. */
-const FILTER_TOOL_NAME = "filter_dense_hits";
-
-/**
- * Arguments to one filter invocation.
- *
- * `dense` is the bounded dense scout result; only its slugs that are *not*
- * already in `bypass` are judged. `sticky` is the broader keep-in-the-running
- * set (hot + near-exact sparse); `bypass` is the subset strong enough to skip
- * judgment entirely. Bypass slugs that also appear in the dense lane are kept
- * unconditionally and never sent to the model.
- */
-export interface FilterDenseHitsArgs {
-  input: RetrievalInput;
-  dense: ScoutResult;
-  sticky: Set<string>;
-  bypass: Set<string>;
-  /** Optional debug sink — emits one record for the filter's LLM call. */
-  capture?: LlmCallSink;
-  /**
-   * Provider override seam for tests. Production leaves this unset and the
-   * filter resolves `getConfiguredProvider("memoryV3Filter")`. `null` is
-   * distinct from `undefined`: passing `null` simulates "no provider
-   * configured" and exercises the fail-open path without resolving the real
-   * registry.
-   */
-  provider?: Provider | null;
-}
-
-export interface FilterDenseHitsResult {
-  /** Final kept slugs: bypass ∪ judged-kept. */
-  kept: string[];
-  /** Inspection trace: which dense slugs were judged and which were dropped. */
-  trace: { judged: string[]; dropped: string[] };
-  /**
-   * Non-null when the filter could not judge (no provider, provider throw,
-   * missing tool_use, schema mismatch) and therefore failed open by keeping all
-   * dense candidates. The loop can surface this to flag a bypassed filter.
-   */
-  failureReason?: string;
-}
-
-/**
- * Build the forced tool definition. `keep_slugs` is the model's subset of the
- * judged candidate set to retain; everything judged-but-not-kept is dropped.
- * Mirrors the forced-tool pattern of v2's `select_pages_to_inject`.
- */
-function buildFilterTool(judgedSlugs: readonly string[]): ToolDefinition {
-  return {
-    name: FILTER_TOOL_NAME,
-    description:
-      "From the candidate concept pages surfaced by embedding similarity for " +
-      "the current turn, keep the ones that are meaningful associations worth " +
-      "surfacing and drop the spurious near-neighbors. Return keep_slugs as the " +
-      "subset to retain — choose only from the candidate set. Lean toward " +
-      "keeping a plausible cross-domain association over dropping it.",
-    input_schema: {
-      type: "object",
-      properties: {
-        keep_slugs: {
-          type: "array",
-          items: { type: "string", enum: [...judgedSlugs] },
-          description:
-            "The subset of candidate page slugs to keep. Choose only from the candidate set.",
-        },
-        reasoning: {
-          type: "string",
-          description:
-            "One short sentence: why these hits were kept and the rest dropped.",
-        },
-      },
-      required: ["keep_slugs"],
-    },
-  };
-}
-
-const FilterToolResultSchema = z.object({
-  keep_slugs: z.array(z.string()),
-  reasoning: z.string().optional(),
-});
-
-/**
- * Compose the final result. `kept` = bypass slugs ∪ judged-kept (de-duplicated,
- * bypass first then judged-kept in the model's returned order). `trace` records
- * exactly which dense slugs were judged and which the model dropped.
- */
-function buildResult(
-  bypass: Set<string>,
-  judged: readonly string[],
-  judgedKept: readonly string[],
-  failureReason?: string,
-): FilterDenseHitsResult {
-  const keptSet = new Set<string>(bypass);
-  const kept: string[] = [...bypass];
-  for (const slug of judgedKept) {
-    if (keptSet.has(slug)) continue;
-    keptSet.add(slug);
-    kept.push(slug);
-  }
-  const keptJudged = new Set(judgedKept);
-  const dropped = judged.filter((slug) => !keptJudged.has(slug));
-  return {
-    kept,
-    trace: { judged: [...judged], dropped },
-    ...(failureReason !== undefined ? { failureReason } : {}),
-  };
-}
-
-/**
- * Run the fast dense-hit filter for one pass.
- *
- * Makes at most one forced-tool LLM call over the *judged* set (dense slugs not
- * already in `bypass`). Bypass slugs are kept unconditionally. On an empty
- * judged set no call is made. Any failure (no provider, provider throw, missing
- * tool_use, schema mismatch) fails open: every dense candidate is kept and a
- * `failureReason` is returned.
- */
-export async function filterDenseHits(
-  args: FilterDenseHitsArgs,
-): Promise<FilterDenseHitsResult> {
-  const { input, dense, bypass } = args;
-
-  // Dense slugs that bypass judgment (near-exact sparse / hot) are kept as-is;
-  // only the remainder is judged.
-  const judged = dense.slugs.filter((slug) => !bypass.has(slug));
-
-  // Nothing to judge → no LLM call. Kept is just the bypass-relevant slugs.
-  if (judged.length === 0) {
-    return buildResult(bypass, judged, judged);
-  }
-
-  // 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 `memoryV3Filter` call site.
-  const provider =
-    args.provider !== undefined
-      ? args.provider
-      : await getConfiguredProvider("memoryV3Filter");
-
-  if (!provider) {
-    log.warn(
-      "memoryV3Filter provider unavailable; failing open (keeping all dense)",
-    );
-    return buildResult(bypass, judged, judged, "no_provider");
-  }
-
-  const systemPrompt = resolveV3SystemPrompt(
-    FILTER_SYSTEM_PROMPT,
-    input.config.memory?.v3?.prompts?.filter,
-    input.workspaceDir,
-  );
-
-  const userMsg: Message = {
-    role: "user",
-    content: [
-      {
-        type: "text",
-        text: renderConversationContext(input),
-      },
-      {
-        type: "text",
-        text: `<candidate_slugs>\n${judged.join("\n")}\n</candidate_slugs>`,
-      },
-    ],
-  };
-
-  const filterTool = buildFilterTool(judged);
-
-  const startedAt = Date.now();
-  let response;
-  try {
-    response = await provider.sendMessage(
-      [userMsg],
-      [filterTool],
-      systemPrompt,
-      {
-        config: {
-          callSite: "memoryV3Filter" as const,
-          tool_choice: { type: "tool" as const, name: FILTER_TOOL_NAME },
-        },
-        ...(input.signal ? { signal: input.signal } : {}),
-      },
-    );
-  } catch (err) {
-    log.warn({ err }, "Filter provider call threw; failing open (keep all)");
-    return buildResult(bypass, judged, judged, "api_error");
-  }
-
-  args.capture?.({
-    lane: "filter",
-    callSite: "memoryV3Filter",
-    request: { systemPrompt, messages: [userMsg], tools: [filterTool] },
-    response,
-    ms: Date.now() - startedAt,
-  });
-
-  const toolBlock = extractToolUse(response);
-  if (!toolBlock || toolBlock.name !== FILTER_TOOL_NAME) {
-    log.warn(
-      { stopReason: response.stopReason },
-      "Filter model returned no filter_dense_hits tool_use; failing open (keep all)",
-    );
-    return buildResult(bypass, judged, judged, "tool_use_missing");
-  }
-
-  const parsed = FilterToolResultSchema.safeParse(toolBlock.input);
-  if (!parsed.success) {
-    log.warn(
-      { error: parsed.error.message },
-      "Filter tool input did not match schema; failing open (keep all)",
-    );
-    return buildResult(bypass, judged, judged, "schema_mismatch");
-  }
-
-  // Restrict the model's keep set to the judged candidates (it can only keep
-  // what it was shown) and preserve its returned order.
-  const judgedSet = new Set(judged);
-  const seen = new Set<string>();
-  const judgedKept: string[] = [];
-  for (const slug of parsed.data.keep_slugs) {
-    if (!judgedSet.has(slug)) continue;
-    if (seen.has(slug)) continue;
-    seen.add(slug);
-    judgedKept.push(slug);
-  }
-
-  return buildResult(bypass, judged, judgedKept);
-}