@vellumai/assistant 0.12.2 → 0.12.3-staging.2

package/src/plugins/defaults/memory/v3/orchestrate.ts

@@ -67,7 +67,9 @@
  *   3. A SINGLE forced-tool select (`selectPool`) over the whole pool. The
  *      result is this turn's selections — current turn only. Cross-turn
  *      persistence is the injector's job (net-new blocks frozen into history),
- *      not a per-turn re-rendered carry set.
+ *      not a per-turn re-rendered carry set. When the call site resolves to
+ *      TypeSafe, `selectPool` asks one System One noul per numbered candidate
+ *      instead of forcing `select_pages`.
  */
 
 import type { AssistantConfig } from "../../../../config/schema.js";
@@ -89,7 +91,11 @@ import type {
   SelectorPool,
   StableCandidate,
 } from "./pool-select.js";
-import { selectAllPoolCandidates, selectPool } from "./pool-select.js";
+import {
+  MemoryV3RetrievalUnavailableError,
+  selectAllPoolCandidates,
+  selectPool,
+} from "./pool-select.js";
 import {
   type RareTermHit,
   rareTermLane,
@@ -334,17 +340,40 @@ export interface OrchestrateResult {
    *  carried-forward set unioned in. */
   selections: SelectedPage[];
   /** The candidate lanes in cache order; see {@link OrchestrateLanes}. Consumed
-   *  by the selection telemetry (lane attribution), the per-turn pool record
-   *  (`pool-log-store.ts`), and the downstream selector rendering. */
+   *  by selection telemetry for lane attribution and retained as the complete
+   *  retrieval diagnostics even when selector budgeting trims `pool`. */
   lanes: OrchestrateLanes;
   /** Whether the selector LLM judged a non-empty pool this turn (the
    *  `selector_ran` telemetry field). False when the pool was empty, when the
-   *  disabled-selector passthrough kept every candidate, and when a closed
-   *  injection gate hard-skipped selection. On that last path `lanes` still
-   *  carries the stable prefix as computed, but no pool was ever assembled,
-   *  so a false value with empty `selections` means the selector was given
-   *  nothing. */
+   *  disabled-selector passthrough kept every candidate, when a closed
+   *  injection gate hard-skipped selection, and when the selector's provider
+   *  failed and the retained stable candidates were kept unjudged
+   *  (`selectorFailure`). A false value with empty `selections` means the
+   *  selector was given nothing only when `pool` is absent; a failed attempt
+   *  can carry a finder-only pool with no fallback selections. */
   selectorRan: boolean;
+  /** Set when the selector could not be run this turn (provider unavailable,
+   *  or no usable tool call after the re-prompt retries). `selections` then
+   *  holds the retained stable candidates unjudged; finder candidates are
+   *  dropped because they are evidence for a judge, not evidence to inject on
+   *  their own. The
+   *  live injector queues a notice so the person knows this turn drew on
+   *  core memories only. */
+  selectorFailure?: MemoryV3RetrievalUnavailableError;
+  /** The pool as the selector was given it, in one numbering: the
+   *  stable-prefix cards, then the finder lines. Absent when no pool was
+   *  assembled this turn (a closed gate's hard skip). Read by the pool record
+   *  and input capture (`pool-log-store.ts`). */
+  pool?: SelectorPool;
+  /** The exact context strings rendered for the selector request. Absent when
+   *  no selector pool was assembled. */
+  selectorTurn?: MemoryRoutingTurn;
+  /** Whether the selector's recall-safe keep-all fallback fired
+   *  (`selectPool`'s `keptAll`). Absent when no pool was assembled. */
+  keptAll?: boolean;
+  /** The injection gate's reason code for this turn. Absent when the gate
+   *  did not run. */
+  gateReason?: string;
 }
 
 /** Stable-order de-duplication preserving first occurrence. */
@@ -381,7 +410,12 @@ export async function orchestrate(
   // the byte-stable-prefix contract). Built lazily so the gate's bypass path can
   // reuse the exact same construction as the normal step-2 pool assembly.
   const buildStable = (): StableCandidate[] =>
-    [...core, ...hot, ...fresh, ...always].map((slug) => {
+    [
+      ...core.map((slug) => ({ slug, lane: "core" as const })),
+      ...hot.map((slug) => ({ slug, lane: "hot" as const })),
+      ...fresh.map((slug) => ({ slug, lane: "fresh" as const })),
+      ...always.map((slug) => ({ slug, lane: "always" as const })),
+    ].map(({ slug, lane }) => {
       const card = deps.prefixCards.get(slug);
       if (card === undefined) {
         // Lane init renders a card for every core/hot slug; a hole here means
@@ -392,7 +426,7 @@ export async function orchestrate(
           `memory-v3: no pre-rendered card for stable-prefix slug "${slug}"`,
         );
       }
-      return { slug, card };
+      return { slug, card, lane };
     });
 
   // Run the selector over a pool, or pass its candidates straight through when
@@ -402,19 +436,67 @@ export async function orchestrate(
   // selector's recall-safe fallback ONLY — the disabled passthrough is not a
   // selector judgment, so it reports `false` (its turns are excluded from any
   // relevance read by `selector_ran` anyway).
+  //
+  // A selector that cannot run at all (provider unavailable, or no usable
+  // tool call after the re-prompt retries) keeps the stable prefix unjudged
+  // and drops the finder candidates: the stable cards are
+  // conversation-independent and already sit in every turn's pool, while a
+  // finder line is evidence for a judge, not evidence to inject on its own.
+  // The failure rides the result so the injector can tell the person this
+  // turn drew on core memories only.
   const runSelection = (
     pool: SelectorPool,
-  ): Promise<{ selections: SelectedPage[]; keptAll: boolean }> =>
+  ): Promise<{
+    selections: SelectedPage[];
+    keptAll: boolean;
+    pool: SelectorPool;
+    selectorTurn: MemoryRoutingTurn;
+    failure?: MemoryV3RetrievalUnavailableError;
+  }> =>
     timeLatencySubSpan("v3_selection", "Memory selection", async () => {
       if (deps.selectorEnabled === false) {
-        return { selections: selectAllPoolCandidates(pool), keptAll: false };
+        return {
+          selections: selectAllPoolCandidates(pool),
+          keptAll: false,
+          pool,
+          selectorTurn: turn,
+        };
+      }
+      try {
+        const selection = await selectPool(pool, turn, deps.selectorPrompt);
+        return {
+          selections: selection.pages,
+          keptAll: selection.keptAll,
+          pool: selection.pool,
+          selectorTurn: selection.turn,
+        };
+      } catch (err) {
+        if (!(err instanceof MemoryV3RetrievalUnavailableError)) {
+          throw err;
+        }
+        const attemptedPool = err.pool ?? pool;
+        const attemptedTurn = err.turn ?? turn;
+        log.warn(
+          {
+            conversationId: turn.conversationId,
+            turnNumber: turn.turnNumber,
+            stableCount: attemptedPool.stable.length,
+            finderCount: attemptedPool.finder.length,
+            err: err.message,
+          },
+          "memory-v3 selector unavailable; keeping the stable prefix unjudged",
+        );
+        return {
+          selections: selectAllPoolCandidates({
+            stable: attemptedPool.stable,
+            finder: [],
+          }),
+          keptAll: false,
+          pool: attemptedPool,
+          selectorTurn: attemptedTurn,
+          failure: err,
+        };
       }
-      const { pages, keptAll } = await selectPool(
-        pool,
-        turn,
-        deps.selectorPrompt,
-      );
-      return { selections: pages, keptAll };
     });
 
   // Step 1: needle (sync BM25) and the enabled dense lane (async embed +
@@ -760,17 +842,22 @@ export async function orchestrate(
   //     Omitted when the caller did not supply `isResident` (tests,
   //     shadow-less paths). The count reads the same units the injector will
   //     (a closed gate's selections carry no sections, so it counts leads).
-  const selectorRanOver = (poolSize: number): boolean =>
-    deps.selectorEnabled !== false && poolSize > 0;
+  const selectorRanOver = (
+    poolSize: number,
+    failure?: MemoryV3RetrievalUnavailableError,
+  ): boolean =>
+    deps.selectorEnabled !== false && poolSize > 0 && failure === undefined;
   const recordSelection = (
     selections: SelectedPage[],
     poolSize: number,
     keptAll: boolean,
+    failure?: MemoryV3RetrievalUnavailableError,
   ): void => {
     const detail: Record<string, unknown> = {
       gate_reason: gateOutcome?.reason ?? null,
       gate_pass: gateOutcome?.pass ?? null,
-      selector_ran: selectorRanOver(poolSize),
+      selector_ran: selectorRanOver(poolSize, failure),
+      selector_failed: failure !== undefined,
       selector_kept_all: keptAll,
       selected_count: selections.length,
       pool_size: poolSize,
@@ -845,10 +932,25 @@ export async function orchestrate(
           const closed = (
             selections: SelectedPage[],
             selectorRan: boolean,
+            selectorFailure?: MemoryV3RetrievalUnavailableError,
+            judged?: {
+              pool: SelectorPool;
+              selectorTurn: MemoryRoutingTurn;
+              keptAll: boolean;
+            },
           ): OrchestrateResult => ({
             selections,
             lanes: { core, hot, fresh, always, finder: [] },
             selectorRan,
+            gateReason: gate.reason,
+            ...(judged
+              ? {
+                  pool: judged.pool,
+                  selectorTurn: judged.selectorTurn,
+                  keptAll: judged.keptAll,
+                }
+              : {}),
+            ...(selectorFailure ? { selectorFailure } : {}),
           });
           if (deps.gateConfig.bypassForCore) {
             // Select over the stable prefix only. `runSelection` mirrors the
@@ -860,13 +962,26 @@ export async function orchestrate(
             // explicitly configured with `selectorEnabled: false` AND
             // `denseK > 0` (the dense-gated gate only runs with dense hits; the
             // new-user profile sets `denseK: 0`, so the gate never runs for it).
-            const stableOnly = buildStable();
-            const { selections: bypassed, keptAll } = await runSelection({
-              stable: stableOnly,
+            const stableOnly: SelectorPool = {
+              stable: buildStable(),
               finder: [],
-            });
-            recordSelection(bypassed, stableOnly.length, keptAll);
-            return closed(bypassed, selectorRanOver(stableOnly.length));
+            };
+            const {
+              selections: bypassed,
+              keptAll,
+              pool: selectedPool,
+              selectorTurn,
+              failure,
+            } = await runSelection(stableOnly);
+            const selectedPoolSize =
+              selectedPool.stable.length + selectedPool.finder.length;
+            recordSelection(bypassed, selectedPoolSize, keptAll, failure);
+            return closed(
+              bypassed,
+              selectorRanOver(selectedPoolSize, failure),
+              failure,
+              { pool: selectedPool, selectorTurn, keptAll },
+            );
           }
           // Hard skip: the selector is never consulted, so this is a zero
           // selection BY CONSTRUCTION, not a judgment that nothing was relevant.
@@ -971,14 +1086,26 @@ export async function orchestrate(
     "Gate & edge expansion",
     Date.now() - expandStartedAt,
   );
-  const poolSize = stable.length + finderTail.length;
-  const { selections, keptAll } = await runSelection(pool);
-  recordSelection(selections, poolSize, keptAll);
+  const {
+    selections,
+    keptAll,
+    pool: selectedPool,
+    selectorTurn,
+    failure,
+  } = await runSelection(pool);
+  const selectedPoolSize =
+    selectedPool.stable.length + selectedPool.finder.length;
+  recordSelection(selections, selectedPoolSize, keptAll, failure);
 
   return {
     selections,
     lanes: { core, hot, fresh, always, finder },
-    selectorRan: selectorRanOver(poolSize),
+    selectorRan: selectorRanOver(selectedPoolSize, failure),
+    pool: selectedPool,
+    selectorTurn,
+    keptAll,
+    ...(gateOutcome ? { gateReason: gateOutcome.reason } : {}),
+    ...(failure ? { selectorFailure: failure } : {}),
   };
 }
 

package/src/plugins/defaults/memory/v3/plugin-schema.ts

@@ -1,7 +1,8 @@
 /**
  * The memory-v3 plugin's own schema on the dedicated memory connection
- * (`assistant-memory.db`): the `memory_v3_pools` and
- * `memory_v3_injected_sections` tables, and the `section_key` column of
+ * (`assistant-memory.db`): the `memory_v3_pools`, `memory_v3_pool_inputs`,
+ * `memory_v3_pool_texts`, and `memory_v3_injected_sections` tables, and the
+ * `section_key` column of
  * `memory_v3_selections`. Plugin storage is created by the plugin,
  * idempotently and fail-open, never by the global migration chain that gates
  * database readiness: the memory plugin's `init` hook runs every ensure on
@@ -153,6 +154,53 @@ export const ensureMemoryV3PoolsSchemaOnce = ensureOncePerConnection(
   "failed to ensure memory_v3_pools; pool logging degraded",
 );
 
+const POOL_INPUTS_TABLE = "memory_v3_pool_inputs";
+const POOL_TEXTS_TABLE = "memory_v3_pool_texts";
+
+/**
+ * Create the pool input capture tables, written only under
+ * `memory.v3.poolLog.captureInput` (`pool-log-store.ts`):
+ * `memory_v3_pool_inputs`, one row per `(conversation, turn)` holding the
+ * context strings the selector was given, the gate and keep-all facts, and
+ * the content hash of every pooled candidate's rendered text in pool order
+ * (aligned with the turn's `memory_v3_pools` candidates); and
+ * `memory_v3_pool_texts`, each rendered text once, keyed by that hash, so a
+ * stable-prefix card repeated across turns is stored once. Idempotent
+ * (`IF NOT EXISTS`).
+ */
+export function ensureMemoryV3PoolInputsSchema(memoryRaw: MemorySqlite): void {
+  memoryRaw.exec(/*sql*/ `
+    CREATE TABLE IF NOT EXISTS ${POOL_INPUTS_TABLE} (
+      conversation_id TEXT NOT NULL,
+      turn INTEGER NOT NULL,
+      created_at INTEGER NOT NULL,
+      situational_context TEXT,
+      recent_context TEXT NOT NULL,
+      current_message TEXT NOT NULL,
+      previous_assistant_message TEXT,
+      selector_prompt_hash TEXT,
+      kept_all INTEGER NOT NULL DEFAULT 0,
+      gate_reason TEXT,
+      candidate_text_hashes_json TEXT NOT NULL,
+      PRIMARY KEY (conversation_id, turn)
+    )
+  `);
+  memoryRaw.exec(/*sql*/ `
+    CREATE TABLE IF NOT EXISTS ${POOL_TEXTS_TABLE} (
+      text_hash TEXT PRIMARY KEY,
+      text TEXT NOT NULL,
+      created_at INTEGER NOT NULL
+    )
+  `);
+}
+
+/** {@link ensureMemoryV3PoolInputsSchema} once per connection in this
+ *  process, for the pool input capture's writer and readers. */
+export const ensureMemoryV3PoolInputsSchemaOnce = ensureOncePerConnection(
+  ensureMemoryV3PoolInputsSchema,
+  "failed to ensure memory_v3_pool_inputs; pool input capture degraded",
+);
+
 const SECTIONS_TABLE = "memory_v3_injected_sections";
 const LEGACY_CARDS_TABLE = "memory_v3_ever_injected";
 
@@ -331,8 +379,9 @@ export const ensureMemoryV3SelectionsSectionKeyOnce = ensureOncePerConnection(
 
 /**
  * Ensure the whole plugin-owned schema on the memory connection of this
- * process, for the memory plugin's `init` hook: the pools and
- * injected-sections tables and the selection log's `section_key` column,
+ * process, for the memory plugin's `init` hook: the pools, pool input
+ * capture, and injected-sections tables and the selection log's
+ * `section_key` column,
  * each through its once-per-connection wrapper so a store's first use on
  * the same connection is a no-op. No-op when the connection is unavailable
  * (the stores degrade to no-ops as on any turn).
@@ -340,6 +389,7 @@ export const ensureMemoryV3SelectionsSectionKeyOnce = ensureOncePerConnection(
 export function ensureMemoryV3PluginSchema(): void {
   ensuredMemorySqlite("ensureMemoryV3PluginSchema", (raw) => {
     ensureMemoryV3PoolsSchemaOnce(raw);
+    ensureMemoryV3PoolInputsSchemaOnce(raw);
     ensureMemoryV3InjectedSectionsSchemaOnce(raw);
     ensureMemoryV3SelectionsSectionKeyOnce(raw);
   });