@vellumai/assistant 0.7.1 → 0.7.3

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 {
@@ -66,13 +67,11 @@ import {
   type MemoryJob,
   type MemoryJobType,
 } from "../jobs-store.js";
+import { MEMORY_V2_CONSOLIDATION_SOURCE } from "./constants.js";
 import { resolveConsolidationPrompt } from "./prompts/consolidation.js";
 
 const log = getLogger("memory-v2-consolidate");
 
-/** Source string identifying this wake in `agent-wake` logs and surfaces. */
-const WAKE_SOURCE = "memory_v2_consolidation";
-
 /**
  * Follow-up jobs to fan out after a successful consolidation.
  *
@@ -144,7 +143,7 @@ export async function memoryV2ConsolidateJob(
     // writes in the assistant's voice.
     const conversation = bootstrapConversation({
       conversationType: "background",
-      source: WAKE_SOURCE,
+      source: MEMORY_V2_CONSOLIDATION_SOURCE,
       origin: "memory_consolidation",
       systemHint: "Running memory consolidation",
       groupId: "system:background",
@@ -159,7 +158,7 @@ export async function memoryV2ConsolidateJob(
           config.memory.v2.consolidation_prompt_path,
           cutoff,
         ),
-        source: WAKE_SOURCE,
+        source: MEMORY_V2_CONSOLIDATION_SOURCE,
         trustContext: INTERNAL_GUARDIAN_TRUST_CONTEXT,
       });
       wakeInvoked = result.invoked;
@@ -242,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.
+ *
+ * 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.
  *
- * 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.
+ * 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
@@ -257,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;
@@ -269,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);
@@ -286,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

package/src/memory/v2/constants.ts

@@ -0,0 +1,7 @@
+/**
+ * Canonical `conversations.source` string for background memory v2
+ * consolidation runs. Lives in a tiny constants module so the route layer can
+ * recognize consolidation conversations without importing the consolidation
+ * job (which pulls in agent-wake + bootstrap dependencies).
+ */
+export const MEMORY_V2_CONSOLIDATION_SOURCE = "memory_v2_consolidation";

package/src/memory/v2/injection.ts

@@ -29,22 +29,18 @@ import { getWorkspaceDir } from "../../util/platform.js";
 import type { DrizzleDb } from "../db-connection.js";
 import {
   type MemoryV2ConceptRowRecord,
-  type MemoryV2SkillRowRecord,
   recordMemoryV2ActivationLog,
 } from "../memory-v2-activation-log-store.js";
 import {
   computeOwnActivation,
-  computeSkillActivation,
   selectCandidates,
   selectInjections,
-  selectSkillCandidates,
-  selectSkillInjections,
   spreadActivation,
 } from "./activation.js";
 import { hydrate, save } from "./activation-store.js";
 import { getEdgeIndex } from "./edge-index.js";
 import { readPage, renderPageContent } from "./page-store.js";
-import { getSkillCapability } from "./skill-store.js";
+import { getSkillCapability, isSkillSlug } from "./skill-store.js";
 import type { ActivationState, EverInjectedEntry } from "./types.js";
 
 const log = getLogger("memory-v2-injection");
@@ -85,14 +81,16 @@ export interface InjectMemoryV2BlockParams {
    */
   mode?: InjectMemoryV2Mode;
   config: AssistantConfig;
+  signal?: AbortSignal;
 }
 
 export interface InjectMemoryV2BlockResult {
   /**
-   * Rendered `<memory>` block, ready to prepend to the current
-   * user message — or `null` when nothing new is eligible for injection.
-   * `null` is the cache-stable default: the caller adds nothing to the new
-   * user message and prior attachments stay byte-identical.
+   * Inner content for the `<memory>` block, ready for the caller to wrap
+   * exactly once at injection time — or `null` when nothing new is eligible
+   * for injection. `null` is the cache-stable default: the caller adds
+   * nothing to the new user message and prior attachments stay
+   * byte-identical.
    */
   block: string | null;
   /**
@@ -127,30 +125,36 @@ export async function injectMemoryV2Block(
     nowText,
     messageId,
     config,
+    signal,
   } = params;
 
   const workspaceDir = getWorkspaceDir();
 
   // (1) Hydrate. Missing rows are normal at conversation start — proceed
   // with an effective empty prior state so the first turn can still inject.
+  throwIfAborted(signal);
   const priorState = await hydrate(database, conversationId);
 
   // (2) Topology. `getEdgeIndex` walks concept-page frontmatter and caches
   // the result module-locally; an empty workspace yields an empty index.
+  throwIfAborted(signal);
   const edgeIndex = await getEdgeIndex(workspaceDir);
 
   // (3) Candidate set: prior-state survivors above epsilon ∪ ANN top-50.
   // `selectCandidates` also returns `fromPrior` / `fromAnn` provenance sets so
   // telemetry can attribute each candidate back to its source.
+  throwIfAborted(signal);
   const { candidates, fromPrior, fromAnn } = await selectCandidates({
     priorState,
     userText: userMessage,
     assistantText: assistantMessage,
     nowText,
     config,
+    signal,
   });
 
   // (4) Own activation: A_o = d·prev + c_user·sim_u + c_a·sim_a + c_now·sim_n.
+  throwIfAborted(signal);
   const { activation: ownActivation, breakdown: ownBreakdown } =
     await computeOwnActivation({
       candidates,
@@ -159,9 +163,11 @@ export async function injectMemoryV2Block(
       assistantText: assistantMessage,
       nowText,
       config,
+      signal,
     });
 
   // (5) Spreading activation across the edge graph (k, hops from config).
+  throwIfAborted(signal);
   const { k, hops, top_k, epsilon } = config.memory.v2;
   const { final: finalActivation, contribution: spreadContribution } =
     spreadActivation(ownActivation, edgeIndex, k, hops);
@@ -182,30 +188,6 @@ export async function injectMemoryV2Block(
   });
   const slugsToRender = mode === "context-load" ? topNow : toInject;
 
-  // (6b) Skill pipeline — a sibling pipeline to the concept-page one above.
-  // Skills are stateless: no decay carry-over, no spread, no `everInjected`
-  // dedup. The top-K relevant skills are re-presented every turn so the
-  // agent can drop and pick them up freely.
-  const skillCandidates = await selectSkillCandidates({
-    userText: userMessage,
-    assistantText: assistantMessage,
-    nowText,
-    config,
-    topK: config.memory.v2.top_k_skills,
-  });
-  const { activation: skillActivation, breakdown: skillBreakdown } =
-    await computeSkillActivation({
-      candidates: skillCandidates,
-      userText: userMessage,
-      assistantText: assistantMessage,
-      nowText,
-      config,
-    });
-  const { topNow: topSkillIds } = selectSkillInjections({
-    A: skillActivation,
-    topK: config.memory.v2.top_k_skills,
-  });
-
   // Build the next persisted state regardless of whether we render anything:
   // even on a "no new injection" turn, prior-state activations decay via the
   // candidate-set carry-forward and need to be rewritten so `epsilon`-trimmed
@@ -220,8 +202,10 @@ export async function injectMemoryV2Block(
   // just rendered all of them); on per-turn it's just the newly added slugs.
   // We append rather than reset so that compaction-driven eviction
   // (`evictCompactedTurns`) is the only path that can re-enable a previously-
-  // injected slug. Skills do NOT enter `everInjected` — they are stateless
-  // and re-presented every turn.
+  // injected slug. Skill slugs (`skills/<id>`) participate in this dedup just
+  // like concept slugs — once attached on a turn, the cached attachment lives
+  // on that user message and the agent keeps seeing it across subsequent turns
+  // until compaction evicts the turn.
   const everInjectedSet = new Set(priorEverInjected.map((entry) => entry.slug));
   const newlyInjected = slugsToRender.filter(
     (slug) => !everInjectedSet.has(slug),
@@ -241,12 +225,31 @@ export async function injectMemoryV2Block(
 
   await save(database, conversationId, nextActivationState);
 
-  // Record per-turn activation telemetry. This runs *before* the cache-stable
-  // empty-block return so we capture diagnostics even on no-op turns. Failures
-  // are warn-logged and never block memory injection.
+  // Render before recording telemetry so the activation log can mark slugs
+  // whose backing file is gone — those are no-op renders that would otherwise
+  // be indistinguishable from successful "injected" rows in the log.
+  // `renderInjectionBlock` itself short-circuits on empty inputs.
+  const { block, missingSlugs } = await renderInjectionBlock(
+    workspaceDir,
+    slugsToRender,
+  );
+  const missingSlugSet = new Set(missingSlugs);
+  if (missingSlugs.length > 0) {
+    log.warn(
+      {
+        conversationId,
+        turn: currentTurn,
+        missingSlugs,
+        renderedCount: slugsToRender.length - missingSlugs.length,
+      },
+      "Memory v2 injection skipped slugs whose page was missing on disk — Qdrant index may be stale; consider reembed",
+    );
+  }
+
+  // Record per-turn activation telemetry. Failures are warn-logged and never
+  // block memory injection.
   const toInjectSet = new Set(toInject);
   const renderedSet = new Set(slugsToRender);
-  const topSkillIdSet = new Set(topSkillIds);
   const conceptRows: MemoryV2ConceptRowRecord[] = [...candidates].map(
     (slug) => {
       const breakdown = ownBreakdown.get(slug);
@@ -260,6 +263,10 @@ export async function injectMemoryV2Block(
       //   - per-turn: cached attachments from prior turns are still on the
       //     user message, so prior-everInjected slugs are `in_context` and
       //     the delta (`toInject`) is `injected`.
+      // `page_missing` overrides any "would-have-been-injected" status when
+      // `readPage` returned null for the slug — telemetry surfaces stale
+      // ANN/edge entries instead of silently masquerading as a successful
+      // injection.
       let status: MemoryV2ConceptRowRecord["status"];
       if (mode === "context-load") {
         status = renderedSet.has(slug) ? "injected" : "not_injected";
@@ -270,6 +277,9 @@ export async function injectMemoryV2Block(
       } else {
         status = "not_injected";
       }
+      if (status === "injected" && missingSlugSet.has(slug)) {
+        status = "page_missing";
+      }
       return {
         slug,
         finalActivation: finalActivation.get(slug) ?? 0,
@@ -278,6 +288,9 @@ export async function injectMemoryV2Block(
         simUser: breakdown?.simUser ?? 0,
         simAssistant: breakdown?.simAssistant ?? 0,
         simNow: breakdown?.simNow ?? 0,
+        simUserRerankBoost: breakdown?.simUserRerankBoost ?? 0,
+        simAssistantRerankBoost: breakdown?.simAssistantRerankBoost ?? 0,
+        inRerankPool: breakdown?.inRerankPool ?? false,
         spreadContribution: spreadContribution.get(slug) ?? 0,
         source:
           inPrior && inAnn ? "both" : inPrior ? "prior_state" : "ann_top50",
@@ -287,19 +300,6 @@ export async function injectMemoryV2Block(
   );
   conceptRows.sort((a, b) => b.finalActivation - a.finalActivation);
 
-  const skillRows: MemoryV2SkillRowRecord[] = [...skillCandidates].map((id) => {
-    const breakdown = skillBreakdown.get(id);
-    return {
-      id,
-      activation: skillActivation.get(id) ?? 0,
-      simUser: breakdown?.simUser ?? 0,
-      simAssistant: breakdown?.simAssistant ?? 0,
-      simNow: breakdown?.simNow ?? 0,
-      status: topSkillIdSet.has(id) ? "injected" : "not_injected",
-    };
-  });
-  skillRows.sort((a, b) => b.activation - a.activation);
-
   const v2Cfg = config.memory.v2;
   try {
     recordMemoryV2ActivationLog({
@@ -307,7 +307,6 @@ export async function injectMemoryV2Block(
       turn: currentTurn,
       mode,
       concepts: conceptRows,
-      skills: skillRows,
       config: {
         d: v2Cfg.d,
         c_user: v2Cfg.c_user,
@@ -316,7 +315,6 @@ export async function injectMemoryV2Block(
         k: v2Cfg.k,
         hops: v2Cfg.hops,
         top_k: v2Cfg.top_k,
-        top_k_skills: v2Cfg.top_k_skills,
         epsilon: v2Cfg.epsilon,
       },
     });
@@ -327,51 +325,68 @@ export async function injectMemoryV2Block(
     );
   }
 
-  // (7) Cache-stable empty path: nothing to render AND no ranked skills.
-  if (slugsToRender.length === 0 && topSkillIds.length === 0) {
-    return { block: null, toInject: [] };
-  }
-
-  // (8) Render. Both `topNow` and `toInject` are activation-descending
-  // (selectInjections sorts before slicing), so `slugsToRender` doubles as
-  // the render order. Per-turn: only the new slugs render (prior turns'
-  // attachments stay cached on prior user messages). Context-load: full
-  // top-K renders so the fresh user message gets a complete activation dump.
-  // Skills are appended after concept-page sections.
-  const block = await renderInjectionBlock(
-    workspaceDir,
-    slugsToRender,
-    topSkillIds,
-  );
-
   return { block, toInject: newlyInjected };
 }
 
+function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) {
+    throw new DOMException("Aborted", "AbortError");
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
 
+interface RenderInjectionBlockResult {
+  /**
+   * Inner content for the `<memory>` block (concept-page sections + optional
+   * skills suffix), or `null` when both the concept-page list and the skill
+   * list collapse to empty after cache misses (no on-disk pages, no
+   * resolvable skill ids). Returned unwrapped so the caller can wrap it
+   * exactly once at injection time, matching v1's contract: callers that
+   * cache the value (`lastInjectedBlock`) or persist it (`memoryInjectedBlock`
+   * in message metadata) re-wrap on use, and storing the wrapped form here
+   * caused a double wrap on reinject after compaction and on rehydrate from
+   * DB.
+   */
+  block: string | null;
+  /**
+   * Slugs that `readPage` returned null for. Surfaced so the caller can
+   * mark them in the activation log (`status: "page_missing"`) and emit
+   * a warning — silent drops here previously masked stale Qdrant /
+   * edge-index entries that pointed at pages no longer on disk.
+   */
+  missingSlugs: string[];
+}
+
 /**
- * Render the `<memory>` block for a list of slugs and a list of
- * ranked skill ids.
+ * Render the inner content of the `<memory>` block for a list of slugs.
+ * The caller wraps the result in `<memory>...</memory>` exactly once at
+ * injection time.
+ *
+ * The slug list is partitioned by prefix: slugs starting with `skills/`
+ * resolve to a `SkillEntry` via `getSkillCapability` and render under the
+ * trailing `### Skills You Can Use` subsection; everything else is read
+ * from disk via `readPage` and rendered as a concept-page section.
  *
  * Concept pages are read in parallel via `readPage`. Pages whose file has
  * gone missing between selection and render (e.g. consolidation deleted
- * them) are silently dropped — the activation state still records them in
- * `everInjected` so we don't keep re-attempting on every turn.
+ * them, folder reorg renamed the slug) are dropped from the rendered
+ * block but reported back via `missingSlugs` so callers can surface the
+ * divergence.
  *
- * Skill ids are looked up via `getSkillCapability`. Ids that the cache no
- * longer knows (e.g. uninstalled mid-run) are silently dropped, mirroring
- * the missing-pages behavior.
+ * Skill slugs whose entry the cache no longer knows (e.g. uninstalled
+ * mid-run) are silently dropped, mirroring the missing-pages behavior but
+ * without entering `missingSlugs` — the skill catalog is the source of
+ * truth for skill availability, not on-disk concept pages, so a missing
+ * skill is an expected catalog-level outcome rather than a stale-index
+ * bug.
  *
- * The block shape is the §5 layout from the design doc, with an optional
- * trailing skills subsection. Each concept-page section reproduces the page
- * as it lives on disk — frontmatter (`edges`, `ref_files`) plus body — so
- * the agent sees the page's edges and any referenced media paths alongside
- * the prose:
+ * The block shape mirrors the §5 layout — concept-page sections first,
+ * skills subsection last — preserving the prompt format the agent sees:
  *
- *   <memory>
- *   ### <slug-1>
+ *   ### <concept-slug-1>
  *   ---
  *   edges:
  *     - <neighbor-slug>
@@ -380,7 +395,7 @@ export async function injectMemoryV2Block(
  *   ---
  *   <body-1>
  *
- *   ### <slug-2>
+ *   ### <concept-slug-2>
  *   ---
  *   edges: []
  *   ref_files: []
@@ -390,34 +405,36 @@ export async function injectMemoryV2Block(
  *   ### Skills You Can Use
  *   - <skill-1 content>
  *   - <skill-2 content>
- *   </memory>
- *
- * Returns `null` when both lists collapse to empty after cache misses so
- * the caller can fall through to its empty-block path instead of attaching
- * an empty `<memory>` wrapper.
  */
 async function renderInjectionBlock(
   workspaceDir: string,
   slugs: string[],
-  skillIds: string[],
-): Promise<string | null> {
+): Promise<RenderInjectionBlockResult> {
+  const conceptSlugs = slugs.filter((s) => !isSkillSlug(s));
+  const skillSlugs = slugs.filter((s) => isSkillSlug(s));
+
   const pages = await Promise.all(
-    slugs.map(async (slug) => {
+    conceptSlugs.map(async (slug) => {
       const page = await readPage(workspaceDir, slug);
-      return page ? { slug, content: renderPageContent(page).trim() } : null;
+      return { slug, page };
     }),
   );
 
   const sections: string[] = [];
-  for (const entry of pages) {
-    if (!entry || entry.content.length === 0) continue;
-    sections.push(`### ${entry.slug}\n${entry.content}`);
+  const missingSlugs: string[] = [];
+  for (const { slug, page } of pages) {
+    if (!page) {
+      missingSlugs.push(slug);
+      continue;
+    }
+    const content = renderPageContent(page).trim();
+    if (content.length === 0) continue;
+    sections.push(`### ${slug}\n${content}`);
   }
 
-  // v2's skills collection is skills-only, so the activation suffix always applies.
   const skillLines: string[] = [];
-  for (const id of skillIds) {
-    const entry = getSkillCapability(id);
+  for (const slug of skillSlugs) {
+    const entry = getSkillCapability(slug);
     if (!entry) continue;
     skillLines.push(`- ${entry.content} → use skill_load to activate`);
   }
@@ -425,7 +442,10 @@ async function renderInjectionBlock(
     sections.push(`### Skills You Can Use\n${skillLines.join("\n")}`);
   }
 
-  if (sections.length === 0) return null;
+  if (sections.length === 0) return { block: null, missingSlugs };
 
-  return `<memory>\n${sections.join("\n\n")}\n</memory>`;
+  return {
+    block: sections.join("\n\n"),
+    missingSlugs,
+  };
 }