@vellumai/assistant 0.7.2 → 0.7.3

package/src/memory/v2/activation.ts

@@ -2,12 +2,15 @@
 // Memory v2 — Per-turn activation update
 // ---------------------------------------------------------------------------
 //
-// Implements the activation formula from §4 of the design doc:
+// Implements the activation formula from §4 of the design doc plus an
+// additive cross-encoder rerank boost on the unified top-K-by-A_o pool:
 //
 //   A_o(n, t+1) = d · A(n, t)
 //               + c_user      · sim(User_{t+1},  n)
 //               + c_assistant · sim(Assistant_t, n)
 //               + c_now       · sim(NOW.md,      n)
+//               + c_user      · α · r_norm(User_{t+1},  n)   [n ∈ topK]
+//               + c_assistant · α · r_norm(Assistant_t, n)   [n ∈ topK]
 //
 //   A(n, t+1) = [ A_o(n)
 //               + k  · Σ_{m∈in1(n)} A_o(m)
@@ -40,7 +43,8 @@ import {
 import { clampUnitInterval } from "../validation.js";
 import type { EdgeIndex } from "./edge-index.js";
 import { hybridQueryConceptPages } from "./qdrant.js";
-import { simBatch, simSkillBatch } from "./sim.js";
+import { rerankCandidates } from "./reranker.js";
+import { simBatch } from "./sim.js";
 import type { ActivationState, EverInjectedEntry } from "./types.js";
 
 /**
@@ -77,6 +81,7 @@ interface SelectCandidatesParams {
   /** NOW context string (essentials/threads/recent or NOW.md). */
   nowText: string;
   config: AssistantConfig;
+  signal?: AbortSignal;
 }
 
 interface SelectCandidatesResult {
@@ -104,7 +109,8 @@ interface SelectCandidatesResult {
 export async function selectCandidates(
   params: SelectCandidatesParams,
 ): Promise<SelectCandidatesResult> {
-  const { priorState, userText, assistantText, nowText, config } = params;
+  const { priorState, userText, assistantText, nowText, config, signal } =
+    params;
 
   const fromPrior = new Set<string>();
   const fromAnn = new Set<string>();
@@ -125,12 +131,16 @@ export async function selectCandidates(
     .join("\n");
 
   if (annQueryText.length > 0) {
-    const denseResult = await embedWithBackend(config, [annQueryText]);
+    throwIfAborted(signal);
+    const denseResult = await embedWithBackend(config, [annQueryText], {
+      signal,
+    });
     const dense = await applyCorrectionIfCalibrated(
       denseResult.vectors[0],
       denseResult.provider,
       denseResult.model,
     );
+    throwIfAborted(signal);
     const sparse = generateSparseEmbedding(annQueryText);
     const limit =
       config.memory.v2.ann_candidate_limit ?? UNLIMITED_ANN_CANDIDATE_LIMIT;
@@ -154,6 +164,7 @@ interface ComputeOwnActivationParams {
   assistantText: string;
   nowText: string;
   config: AssistantConfig;
+  signal?: AbortSignal;
 }
 
 /**
@@ -164,12 +175,18 @@ interface ComputeOwnActivationParams {
 interface OwnActivationBreakdown {
   /** `d * prev(slug)` — the decayed prior-turn activation contribution. */
   priorContribution: number;
-  /** Raw `sim(user, slug)` similarity, before `c_user` weighting. */
+  /** Raw fused `sim(user, slug)`, before `c_user` weighting. */
   simUser: number;
-  /** Raw `sim(assistant, slug)` similarity, before `c_assistant` weighting. */
+  /** Raw fused `sim(assistant, slug)`, before `c_assistant` weighting. */
   simAssistant: number;
-  /** Raw `sim(now, slug)` similarity, before `c_now` weighting. */
+  /** Raw fused `sim(now, slug)`, before `c_now` weighting. */
   simNow: number;
+  /** Rerank delta `α · r_norm_u`; 0 outside the top-K pool. Applied to `A_o` weighted by `c_user`. */
+  simUserRerankBoost: number;
+  /** Rerank delta `α · r_norm_a`; 0 outside the top-K pool. Applied to `A_o` weighted by `c_assistant`. NOW skips rerank. */
+  simAssistantRerankBoost: number;
+  /** True when this slug was in the unified top-K rerank pool. Lets the inspector distinguish "cross-encoder normalised to 0" from "rerank skipped this slug." */
+  inRerankPool: boolean;
 }
 
 interface ComputeOwnActivationResult {
@@ -181,21 +198,34 @@ interface ComputeOwnActivationResult {
 
 /**
  * Apply the own-activation formula
- *   A_o(n) = d · prev(n) + c_user · sim_u + c_assistant · sim_a + c_now · sim_n
- * over the candidate set. Returns a sparse map keyed by slug; slugs whose
- * computed value rounds to 0 are still included so callers can see the
- * candidate set explicitly. Also returns a per-slug breakdown of the raw
- * inputs (decayed prior + raw sims) so callers can render contribution
- * diagnostics without re-running the math.
+ *   A_o(n) = d · prev(n)
+ *          + c_user · sim_u + c_assistant · sim_a + c_now · sim_n
+ *          + c_user · α · r_norm_u + c_assistant · α · r_norm_a
+ * over the candidate set, where the rerank terms only fire for slugs that
+ * land in the unified top-K-by-pre-rerank-A_o window. Returns a sparse map
+ * keyed by slug; slugs whose computed value rounds to 0 are still included
+ * so callers can see the candidate set explicitly. Also returns a per-slug
+ * breakdown of the raw inputs (decayed prior + raw sims + rerank deltas) so
+ * callers can render contribution diagnostics without re-running the math.
  *
  * The three `simBatch` calls run concurrently — they hit independent named
- * vectors and embed independent query texts.
+ * vectors and embed independent query texts. Cross-encoder rerank then runs
+ * once on the unified top-K (selected by pre-rerank A_o, not per-channel
+ * fused sim) so an entry strong in both channels can't double-boost itself
+ * past entries that only land in one channel.
  */
 export async function computeOwnActivation(
   params: ComputeOwnActivationParams,
 ): Promise<ComputeOwnActivationResult> {
-  const { candidates, priorState, userText, assistantText, nowText, config } =
-    params;
+  const {
+    candidates,
+    priorState,
+    userText,
+    assistantText,
+    nowText,
+    config,
+    signal,
+  } = params;
 
   const activation = new Map<string, number>();
   const breakdown = new Map<string, OwnActivationBreakdown>();
@@ -204,30 +234,122 @@ export async function computeOwnActivation(
   const { d, c_user, c_assistant, c_now } = config.memory.v2;
   const slugList = [...candidates];
 
+  // NOW context is structured (timestamps, current focus) — outside the
+  // cross-encoder's training distribution, so it never participates in rerank.
   const [simUser, simAssistant, simNow] = await Promise.all([
-    simBatch(userText, slugList, config),
-    simBatch(assistantText, slugList, config),
-    simBatch(nowText, slugList, config),
+    simBatch(userText, slugList, config, { signal }),
+    simBatch(assistantText, slugList, config, { signal }),
+    simBatch(nowText, slugList, config, { signal }),
   ]);
 
-  for (const slug of slugList) {
+  interface SlugInputs {
+    slug: string;
+    priorContribution: number;
+    simU: number;
+    simA: number;
+    simN: number;
+    /** Pre-rerank A_o; ranking signal for the unified rerank pool. */
+    preRerank: number;
+  }
+  const inputs: SlugInputs[] = slugList.map((slug) => {
     const prev = priorState?.state[slug] ?? 0;
     const simU = simUser.get(slug) ?? 0;
     const simA = simAssistant.get(slug) ?? 0;
     const simN = simNow.get(slug) ?? 0;
-    const value = d * prev + c_user * simU + c_assistant * simA + c_now * simN;
-    activation.set(slug, clampUnitInterval(value));
-    breakdown.set(slug, {
-      priorContribution: d * prev,
-      simUser: simU,
-      simAssistant: simA,
-      simNow: simN,
+    const priorContribution = d * prev;
+    return {
+      slug,
+      priorContribution,
+      simU,
+      simA,
+      simN,
+      preRerank:
+        priorContribution + c_user * simU + c_assistant * simA + c_now * simN,
+    };
+  });
+
+  // Unified top-K by pre-rerank A_o. Both channels rerank against the **same**
+  // slug set, so a slug strong on user can't crowd out one strong on assistant
+  // by virtue of appearing in both per-channel top-Ks. Both channel queries
+  // ride in a single `rerankCandidates` call so the worker tokenizes and
+  // forward-passes them together — half the per-call overhead of two
+  // serialised round-trips.
+  let userRerankBoost: ReadonlyMap<string, number> = new Map();
+  let assistantRerankBoost: ReadonlyMap<string, number> = new Map();
+  let inPoolSet: ReadonlySet<string> = new Set();
+  const rerankCfg = config.memory.v2.rerank;
+  if (rerankCfg?.enabled) {
+    throwIfAborted(signal);
+    const topSlugs = inputs
+      .slice()
+      .sort((a, b) => b.preRerank - a.preRerank)
+      .slice(0, rerankCfg.top_k)
+      .map((e) => e.slug);
+    if (topSlugs.length > 0) {
+      inPoolSet = new Set(topSlugs);
+      const [userScores, assistantScores] = await rerankCandidates(
+        [userText, assistantText],
+        topSlugs,
+        config,
+      );
+      throwIfAborted(signal);
+      userRerankBoost = normalizeRerankScores(userScores, rerankCfg.alpha);
+      assistantRerankBoost = normalizeRerankScores(
+        assistantScores,
+        rerankCfg.alpha,
+      );
+    }
+  }
+
+  for (const e of inputs) {
+    const boostU = userRerankBoost.get(e.slug) ?? 0;
+    const boostA = assistantRerankBoost.get(e.slug) ?? 0;
+    activation.set(
+      e.slug,
+      clampUnitInterval(e.preRerank + c_user * boostU + c_assistant * boostA),
+    );
+    breakdown.set(e.slug, {
+      priorContribution: e.priorContribution,
+      simUser: e.simU,
+      simAssistant: e.simA,
+      simNow: e.simN,
+      simUserRerankBoost: boostU,
+      simAssistantRerankBoost: boostA,
+      inRerankPool: inPoolSet.has(e.slug),
     });
   }
 
   return { activation, breakdown };
 }
 
+/**
+ * Per-batch normalisation: divide raw cross-encoder scores by the channel's
+ * own max and return `alpha · r_norm` per slug. Empty input or all-zero
+ * scores yield an empty Map so the channel contributes 0 boost.
+ */
+function normalizeRerankScores(
+  rawScores: ReadonlyMap<string, number>,
+  alpha: number,
+): Map<string, number> {
+  const out = new Map<string, number>();
+  if (rawScores.size === 0) return out;
+  let maxScore = 0;
+  for (const v of rawScores.values()) {
+    if (v > maxScore) maxScore = v;
+  }
+  if (maxScore === 0) return out;
+  for (const [slug, raw] of rawScores) {
+    out.set(slug, alpha * (raw / maxScore));
+  }
+  return out;
+}
+
+function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) {
+    throw new DOMException("Aborted", "AbortError");
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Spreading activation
 // ---------------------------------------------------------------------------
@@ -411,132 +533,3 @@ export function selectInjections(
 
   return { topNow, toInject };
 }
-
-// ---------------------------------------------------------------------------
-// Skill autoinjection — candidate / activation / injection selection
-// ---------------------------------------------------------------------------
-//
-// Skills are stateless: there is no decay carry-over (`d · prev`), no
-// spreading activation, and no `everInjected` dedup. The agent re-presents
-// the top-K active skills every turn so it can drop or pick them up freely.
-// The pipeline therefore reduces to:
-//   1. ANN candidate selection against the dedicated skills collection.
-//   2. Pure similarity-only activation: A_skill = c_user·sim_u +
-//      c_assistant·sim_a + c_now·sim_n, clamped to [0, 1].
-//   3. Top-K by activation, lexicographic tie-break, no injection delta.
-//
-// The activation coefficients are reused from `config.memory.v2.{c_user,
-// c_assistant, c_now}` — the design doc (§9) deliberately shares them with
-// concept-page activation rather than introducing parallel knobs.
-
-interface ComputeSkillActivationParams {
-  candidates: ReadonlySet<string>;
-  userText: string;
-  assistantText: string;
-  nowText: string;
-  config: AssistantConfig;
-}
-
-/**
- * Per-skill breakdown of the raw similarity inputs, captured before any
- * coefficient weighting. Skills have no decay term, so the breakdown is just
- * the three raw sims. Surfaced for telemetry / inspector views.
- */
-interface SkillActivationBreakdown {
-  /** Raw `sim(user, skill)` similarity, before `c_user` weighting. */
-  simUser: number;
-  /** Raw `sim(assistant, skill)` similarity, before `c_assistant` weighting. */
-  simAssistant: number;
-  /** Raw `sim(now, skill)` similarity, before `c_now` weighting. */
-  simNow: number;
-}
-
-interface ComputeSkillActivationResult {
-  /** Final clamped skill-activation value per id. */
-  activation: Map<string, number>;
-  /** Per-skill breakdown of the raw sim inputs that fed into `activation`. */
-  breakdown: Map<string, SkillActivationBreakdown>;
-}
-
-/**
- * Apply the skill-side activation formula (no decay carry-over, no spread):
- *   A_skill(s) = clamp01(c_user · sim_u + c_assistant · sim_a + c_now · sim_n)
- *
- * Reuses the activation coefficients from `config.memory.v2`. The three
- * `simSkillBatch` calls run concurrently — they hit independent named
- * vectors and embed independent query texts. Returns a per-skill breakdown
- * of the raw sims alongside the activation map so callers can render
- * contribution diagnostics without re-running the math.
- *
- * Empty candidates short-circuits to an empty map without touching the
- * embedding backend or Qdrant.
- */
-export async function computeSkillActivation(
-  params: ComputeSkillActivationParams,
-): Promise<ComputeSkillActivationResult> {
-  const { candidates, userText, assistantText, nowText, config } = params;
-
-  const activation = new Map<string, number>();
-  const breakdown = new Map<string, SkillActivationBreakdown>();
-  if (candidates.size === 0) return { activation, breakdown };
-
-  const { c_user, c_assistant, c_now } = config.memory.v2;
-  const idList = [...candidates];
-
-  const [simUser, simAssistant, simNow] = await Promise.all([
-    simSkillBatch(userText, idList, config),
-    simSkillBatch(assistantText, idList, config),
-    simSkillBatch(nowText, idList, config),
-  ]);
-
-  for (const id of idList) {
-    const simU = simUser.get(id) ?? 0;
-    const simA = simAssistant.get(id) ?? 0;
-    const simN = simNow.get(id) ?? 0;
-    const value = c_user * simU + c_assistant * simA + c_now * simN;
-    activation.set(id, clampUnitInterval(value));
-    breakdown.set(id, { simUser: simU, simAssistant: simA, simNow: simN });
-  }
-
-  return { activation, breakdown };
-}
-
-interface SelectSkillInjectionsParams {
-  /** Final skill activation map. */
-  A: ReadonlyMap<string, number>;
-  /** Cap on the per-turn skill slate, e.g. `config.memory.v2.skills_top_k`. */
-  topK: number;
-}
-
-interface SelectSkillInjectionsResult {
-  /**
-   * Top-K skill ids by activation (descending), tie-broken lexicographically.
-   * Skills are re-presented every turn — no `toInject` delta — so the caller
-   * uses this list verbatim to render the skill slate.
-   */
-  topNow: string[];
-}
-
-/**
- * Pick the top-K skill ids by activation (descending; stable on ties via id
- * lexicographic order). Skills are stateless — there is no `everInjected`
- * dedup, so the same id can appear on consecutive turns.
- *
- * Returns `{ topNow: [] }` for an empty activation map or `topK <= 0`.
- */
-export function selectSkillInjections(
-  params: SelectSkillInjectionsParams,
-): SelectSkillInjectionsResult {
-  const { A, topK } = params;
-  if (A.size === 0 || topK <= 0) {
-    return { topNow: [] };
-  }
-
-  const ranked = [...A.entries()].sort(([idA, valA], [idB, valB]) => {
-    if (valB !== valA) return valB - valA; // higher activation first
-    return idA < idB ? -1 : idA > idB ? 1 : 0; // stable tie-break
-  });
-
-  const topNow = ranked.slice(0, topK).map(([id]) => id);
-  return { topNow };
-}

package/src/memory/v2/consolidation-job.ts

@@ -59,6 +59,7 @@ import { INTERNAL_GUARDIAN_TRUST_CONTEXT } from "../../daemon/trust-context.js";
 import { wakeAgentForOpportunity } from "../../runtime/agent-wake.js";
 import { getLogger } from "../../util/logger.js";
 import { getWorkspaceDir } from "../../util/platform.js";
+import { isProcessAlive } from "../../util/process-liveness.js";
 import { bootstrapConversation } from "../conversation-bootstrap.js";
 import { deleteConversation } from "../conversation-crud.js";
 import {
@@ -240,14 +241,20 @@ function readBufferContent(bufferPath: string): string {
 /**
  * Atomically create the lock file with `wx` (O_CREAT | O_EXCL) flags. Returns
  * `null` on success, or the current holder string (file contents, typically
- * `pid timestamp`) when the file already exists — the holder is surfaced for
- * log diagnostics so operators can identify a stuck lock without re-reading.
+ * `pid timestamp`) when the file already exists and the holder is still alive.
  *
- * Crash recovery: if the prior daemon died with the lock held, the file will
- * still be on disk on the next start. PR 20 keeps the lock simple per the
- * plan instructions; a future iteration can probe liveness via `kill(pid, 0)`
- * the way `snapshot-lock.ts` does. Until then, an operator can clear a
- * stale lock by removing the file.
+ * Stale-lock takeover: if the file exists but its holder PID is not running,
+ * unlink the stale file and retry the create exactly once. This recovers
+ * automatically from a crashed daemon that died with the lock held —
+ * otherwise every subsequent scheduled consolidation would skip with `locked`
+ * indefinitely until an operator manually removed the file.
+ *
+ * The simple takeover-then-retry is safe here (unlike `snapshot-lock.ts`'s
+ * full rename-aside dance) because only the assistant's jobs worker calls
+ * this lock, and at most one assistant process runs per workspace at any
+ * time. A holder with an unparseable / empty payload is treated as stale —
+ * the only writers ever produce a `<pid> <timestamp>` line, so an
+ * unparseable file is corruption from a partial write that crashed.
  */
 function tryAcquireLock(lockPath: string): string | null {
   // The workspace migration seeds `memory/.v2-state/`, but tests and
@@ -255,9 +262,40 @@ function tryAcquireLock(lockPath: string): string | null {
   // is idempotent, so the call is cheap when the dir already exists.
   mkdirSync(dirname(lockPath), { recursive: true });
 
+  const firstHolder = tryCreate(lockPath);
+  if (firstHolder === null) return null;
+  if (!isHolderStale(firstHolder)) return firstHolder;
+
+  log.info(
+    { lockPath, holder: firstHolder },
+    "consolidation: taking over stale lock (holder not running)",
+  );
+  try {
+    unlinkSync(lockPath);
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code !== "ENOENT") {
+      log.warn(
+        { err, lockPath },
+        "consolidation: failed to unlink stale lock; reporting as locked",
+      );
+      return firstHolder;
+    }
+  }
+  // After unlink, the next `wx` create should succeed. If a third party
+  // raced in and re-acquired (vanishingly unlikely with one writer per
+  // workspace), surface their holder string rather than overwriting.
+  return tryCreate(lockPath);
+}
+
+/**
+ * Atomically create the lock file. Returns `null` on success, or the holder
+ * string read from the file when it already exists (`"unknown"` if the read
+ * itself fails). Rethrows any non-EEXIST errno from `openSync`.
+ */
+function tryCreate(lockPath: string): string | null {
   let fd: number;
   try {
-    // `wx` = create-if-not-exists, fail with EEXIST if it does.
     fd = openSync(lockPath, "wx");
   } catch (err) {
     if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
@@ -267,13 +305,10 @@ function tryAcquireLock(lockPath: string): string | null {
       return "unknown";
     }
   }
-
-  // Best-effort PID + timestamp payload so a stale lock can be diagnosed.
-  // The worker only cares that the file exists; the contents are advisory.
   try {
     writeSync(fd, `${process.pid} ${Date.now()}\n`);
   } catch {
-    // best-effort
+    // best-effort — payload is advisory, the file's existence is the lock
   } finally {
     try {
       closeSync(fd);
@@ -284,6 +319,21 @@ function tryAcquireLock(lockPath: string): string | null {
   return null;
 }
 
+/**
+ * A holder string is stale when its PID parses to a non-running process.
+ * The payload format is `<pid> <timestamp>` (see `tryCreate`'s write), but
+ * an unparseable / empty / `"unknown"` payload is also treated as stale:
+ * the only writer is `tryCreate` itself, so corruption indicates a partial
+ * write from a crashed prior holder rather than a live writer mid-flush.
+ */
+function isHolderStale(holder: string): boolean {
+  const match = /^\d+/.exec(holder);
+  if (!match) return true;
+  const pid = Number.parseInt(match[0], 10);
+  if (!Number.isFinite(pid) || pid <= 0) return true;
+  return !isProcessAlive(pid);
+}
+
 /**
  * Idempotent unlink of the lock file. Called from the `finally` block so a
  * crash in the wake path doesn't leave the lock stranded. ENOENT is swallowed