@vellumai/assistant 0.12.2 → 0.12.3-staging.2

package/src/plugins/defaults/memory/__tests__/buffer-file.test.ts

@@ -0,0 +1,365 @@
+/**
+ * Tests for `buffer-file.ts`: the two writers of `memory/buffer.md`.
+ *
+ * The consume cases pin the invariant the module exists for: an entry saved
+ * at any point while a consolidation run is in flight is either the run's
+ * own material or still in the buffer afterwards, never destroyed. The
+ * cross-process case is the reason to believe it: a child process appends
+ * as fast as it can while this process consumes in a loop, and every tagged
+ * entry must end up consumed or present. The harness's accounting is proven
+ * against a naive read-modify-write consume with the losing interleaving
+ * forced, not raced, so the proof does not depend on scheduling.
+ */
+
+import {
+  appendFileSync,
+  chmodSync,
+  closeSync,
+  existsSync,
+  mkdtempSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  afterAll,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  test,
+} from "bun:test";
+
+import {
+  appendBufferAndArchive,
+  consumeBufferEntries,
+} from "../buffer-file.js";
+import {
+  type BufferEntryLines,
+  bufferEntryText,
+  formatRememberEntry,
+  joinBufferEntries,
+  splitBufferContent,
+} from "../buffer-format.js";
+
+let tmp: string;
+beforeAll(() => {
+  tmp = mkdtempSync(join(tmpdir(), "memory-buffer-file-test-"));
+});
+afterAll(() => {
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+let memoryDir: string;
+let bufferPath: string;
+beforeEach(() => {
+  memoryDir = mkdtempSync(join(tmp, "memory-"));
+  bufferPath = join(memoryDir, "buffer.md");
+});
+
+const A = "- [Apr 27, 9:00 AM] Alice prefers VS Code.";
+const B = "- [Apr 27, 9:01 AM] Bob shared a snippet:\n  line two\n  line three";
+const C = "- [Apr 27, 9:02 AM] Carol loves jazz.";
+const D = "- [Apr 27, 9:03 AM] Dave runs marathons.";
+
+function file(...entries: string[]): string {
+  return entries.map((e) => `${e}\n`).join("");
+}
+function entries(content: string): BufferEntryLines[] {
+  return splitBufferContent(content);
+}
+function texts(): string[] {
+  return entries(readFileSync(bufferPath, "utf-8")).map(bufferEntryText);
+}
+
+describe("appendBufferAndArchive", () => {
+  test("appends to the buffer and the dated archive, seeding the archive header once", () => {
+    const now = new Date(2026, 3, 27, 9, 0);
+    const entry = formatRememberEntry("Alice prefers VS Code.", now);
+    const first = appendBufferAndArchive({ rootDir: memoryDir, entry, now });
+    appendBufferAndArchive({ rootDir: memoryDir, entry, now });
+
+    expect(first.bufferPath).toBe(bufferPath);
+    expect(readFileSync(bufferPath, "utf-8")).toBe(entry + entry);
+    expect(first.archivePath).toBe(join(memoryDir, "archive", "2026-04-27.md"));
+    expect(readFileSync(first.archivePath, "utf-8")).toBe(
+      `# Apr 27, 2026\n\n${entry}${entry}`,
+    );
+  });
+});
+
+describe("consumeBufferEntries", () => {
+  test("removes exactly the consumed entries and keeps the rest verbatim and in order", async () => {
+    writeFileSync(bufferPath, file(A, B, C, D));
+    const pass = entries(file(A, B));
+
+    const result = await consumeBufferEntries(bufferPath, pass, {
+      lateAppendGraceMs: 0,
+    });
+
+    expect(result).toEqual({
+      removed: 2,
+      alreadyAbsent: 0,
+      lateAppendBytesRecovered: 0,
+      unrecoveredLateAppendBytes: 0,
+      lateAppendDrainFailed: false,
+    });
+    expect(readFileSync(bufferPath, "utf-8")).toBe(file(C, D));
+  });
+
+  test("entries appended after the snapshot survive, including one that duplicates a consumed entry", async () => {
+    // The snapshot held one copy of A; the same fact was remembered again
+    // during the run. Multiset semantics: one copy goes, one stays.
+    writeFileSync(bufferPath, file(A, B));
+    const pass = entries(file(A, B));
+    appendFileSync(bufferPath, file(C, A));
+
+    const result = await consumeBufferEntries(bufferPath, pass, {
+      lateAppendGraceMs: 0,
+    });
+
+    expect(result.removed).toBe(2);
+    expect(texts()).toEqual([C, A]);
+  });
+
+  test("a consumed entry missing from the live file is counted, not searched for", async () => {
+    writeFileSync(bufferPath, file(B, C));
+    const pass = entries(file(A, B));
+
+    const result = await consumeBufferEntries(bufferPath, pass, {
+      lateAppendGraceMs: 0,
+    });
+
+    expect(result).toMatchObject({ removed: 1, alreadyAbsent: 1 });
+    expect(texts()).toEqual([C]);
+  });
+
+  test("a missing buffer file consumes nothing and creates nothing", async () => {
+    const result = await consumeBufferEntries(bufferPath, entries(file(A)), {
+      lateAppendGraceMs: 0,
+    });
+
+    expect(result).toEqual({
+      removed: 0,
+      alreadyAbsent: 1,
+      lateAppendBytesRecovered: 0,
+      unrecoveredLateAppendBytes: 0,
+      lateAppendDrainFailed: false,
+    });
+    expect(existsSync(bufferPath)).toBe(false);
+  });
+
+  test("consuming everything leaves an empty file and no temp file behind", async () => {
+    writeFileSync(bufferPath, file(A, B));
+
+    await consumeBufferEntries(bufferPath, entries(file(A, B)), {
+      lateAppendGraceMs: 0,
+    });
+
+    expect(readFileSync(bufferPath, "utf-8")).toBe("");
+    expect(readdirSync(memoryDir)).toEqual(["buffer.md"]);
+  });
+
+  test("an append that landed on the replaced inode is drained back into the buffer", async () => {
+    // An appender that opened the file before the rename writes to the old
+    // inode. The consumer holds that inode open and copies the late bytes
+    // over. The test plays the appender: open before, write after the
+    // synchronous phase, before the grace-window drain.
+    writeFileSync(bufferPath, file(A, B));
+    const lateFd = openSync(bufferPath, "a");
+    const consuming = consumeBufferEntries(bufferPath, entries(file(A)), {
+      lateAppendGraceMs: 50,
+    });
+    // The synchronous phase (read, rewrite, rename) ran before the first
+    // await inside consume, so this write lands on the orphaned inode.
+    appendFileSync(lateFd, file(C));
+    closeSync(lateFd);
+
+    const result = await consuming;
+
+    expect(result.removed).toBe(1);
+    expect(result.lateAppendBytesRecovered).toBe(file(C).length);
+    expect(result.unrecoveredLateAppendBytes).toBe(0);
+    expect(texts()).toEqual([B, C]);
+  });
+
+  test("a late append the drain cannot copy back is reported, not thrown, and the pass stays consumed", async () => {
+    // The rename has committed when the drain runs, so a failing copy must
+    // not surface as "nothing happened". The test makes the rewritten
+    // buffer read-only before the late bytes land, so every copy attempt
+    // fails.
+    writeFileSync(bufferPath, file(A, B));
+    const lateFd = openSync(bufferPath, "a");
+    const consuming = consumeBufferEntries(bufferPath, entries(file(A)), {
+      lateAppendGraceMs: 50,
+    });
+    chmodSync(bufferPath, 0o444);
+    appendFileSync(lateFd, file(C));
+    closeSync(lateFd);
+
+    try {
+      const result = await consuming;
+      expect(result.removed).toBe(1);
+      expect(result.lateAppendBytesRecovered).toBe(0);
+      expect(result.unrecoveredLateAppendBytes).toBe(file(C).length);
+      expect(result.lateAppendDrainFailed).toBe(false);
+      expect(texts()).toEqual([B]);
+    } finally {
+      chmodSync(bufferPath, 0o644);
+    }
+  });
+});
+
+/**
+ * The cross-process invariant. A child appends `count` tagged entries as
+ * fast as it can through `appendFileSync`; this process consumes the leading
+ * entries (up to `passSize` at a time) in a loop through `consume`. Returns
+ * the tags that were neither consumed by a pass nor left in the buffer: the
+ * entries the consume destroyed.
+ */
+async function lostUnder(
+  consume: (path: string, pass: BufferEntryLines[]) => Promise<unknown>,
+  count: number,
+  passSize: number,
+): Promise<{ lost: string[]; duplicated: string[]; passes: number }> {
+  const tag = `t${Math.random().toString(36).slice(2, 8)}`;
+  writeFileSync(bufferPath, "");
+  const child = Bun.spawn(
+    [
+      process.execPath,
+      join(import.meta.dir, "fixtures", "buffer-appender.ts"),
+      bufferPath,
+      String(count),
+      tag,
+    ],
+    { stdout: "ignore", stderr: "inherit" },
+  );
+  const consumed: string[] = [];
+  let passes = 0;
+  let childDone = false;
+  void child.exited.then(() => {
+    childDone = true;
+  });
+  while (!childDone) {
+    const snapshot = entries(readFileSync(bufferPath, "utf-8"));
+    const pass = snapshot.slice(0, passSize);
+    if (pass.length === 0) {
+      await Bun.sleep(1);
+      continue;
+    }
+    await consume(bufferPath, pass);
+    consumed.push(...pass.map(bufferEntryText));
+    passes += 1;
+  }
+  await child.exited;
+  return { ...accountFor(count, tag, consumed), passes };
+}
+
+/** A tagged entry as the appender writes it. */
+function taggedEntry(tag: string, i: number): string {
+  return `- [Apr 27, 9:00 AM] ${tag}-${i}`;
+}
+
+/**
+ * The harness's verdict: of `count` tagged entries, which were neither
+ * consumed by a pass nor left in the buffer (lost), and which were both
+ * (duplicated).
+ */
+function accountFor(
+  count: number,
+  tag: string,
+  consumed: readonly string[],
+): { lost: string[]; duplicated: string[] } {
+  const seen = new Map<string, number>();
+  for (const text of [...consumed, ...texts()]) {
+    seen.set(text, (seen.get(text) ?? 0) + 1);
+  }
+  const lost: string[] = [];
+  const duplicated: string[] = [];
+  for (let i = 0; i < count; i++) {
+    const text = taggedEntry(tag, i);
+    const n = seen.get(text) ?? 0;
+    if (n === 0) {
+      lost.push(text);
+    } else if (n > 1) {
+      duplicated.push(text);
+    }
+  }
+  return { lost, duplicated };
+}
+
+/**
+ * A read-modify-write consume, the shape the production consume is measured
+ * against: an append that lands between its read and its write is destroyed.
+ * `betweenReadAndWrite` runs in exactly that window.
+ */
+async function naiveConsume(
+  path: string,
+  pass: BufferEntryLines[],
+  betweenReadAndWrite?: () => void,
+): Promise<void> {
+  const pending = pass.map(bufferEntryText);
+  const remaining = entries(readFileSync(path, "utf-8")).filter((entry) => {
+    const index = pending.indexOf(bufferEntryText(entry));
+    if (index === -1) {
+      return true;
+    }
+    pending.splice(index, 1);
+    return false;
+  });
+  betweenReadAndWrite?.();
+  writeFileSync(path, joinBufferEntries(remaining), "utf-8");
+}
+
+describe("consumeBufferEntries under a concurrent appender in another process", () => {
+  const APPENDS = 4000;
+
+  test("no entry appended during consumption is lost or duplicated", async () => {
+    // Runs the consume exactly as production does, grace window included:
+    // the window is what makes the invariant hold, and a loaded machine
+    // can deschedule the appender between its open and its write for
+    // longer than a token grace would cover. Larger passes keep the run
+    // short with the full grace paid per pass.
+    const outcome = await lostUnder(
+      (path, pass) => consumeBufferEntries(path, pass),
+      APPENDS,
+      500,
+    );
+    expect(outcome.passes).toBeGreaterThan(0);
+    expect(outcome.lost).toEqual([]);
+    expect(outcome.duplicated).toEqual([]);
+  }, 60_000);
+
+  test("the accounting reports an entry the naive consume destroys, and one a pass duplicates", async () => {
+    // Sensitivity check for the harness: the case above is only evidence if
+    // the accounting can see a loss. The losing interleaving is forced (an
+    // append lands between the naive consume's read and its write) rather
+    // than raced against another process, so whether it happens never
+    // depends on scheduling.
+    const tag = "sens";
+    writeFileSync(bufferPath, file(taggedEntry(tag, 0)));
+    const pass = entries(readFileSync(bufferPath, "utf-8"));
+
+    await naiveConsume(bufferPath, pass, () => {
+      appendFileSync(bufferPath, `${taggedEntry(tag, 1)}\n`, "utf-8");
+    });
+
+    expect(texts()).toEqual([]);
+    const consumed = pass.map(bufferEntryText);
+    expect(accountFor(2, tag, consumed)).toEqual({
+      lost: [taggedEntry(tag, 1)],
+      duplicated: [],
+    });
+
+    // A pass that consumed an entry the buffer still holds is a duplicate.
+    appendFileSync(bufferPath, `${taggedEntry(tag, 0)}\n`, "utf-8");
+    expect(accountFor(2, tag, consumed)).toEqual({
+      lost: [taggedEntry(tag, 1)],
+      duplicated: [taggedEntry(tag, 0)],
+    });
+  });
+});

package/src/plugins/defaults/memory/__tests__/buffer-format.test.ts

@@ -10,10 +10,13 @@
 import { describe, expect, test } from "bun:test";
 
 import {
+  bufferEntryText,
   formatBufferTimestamp,
   formatRememberEntry,
   isBufferEntryStart,
+  joinBufferEntries,
   matchBufferEntryStart,
+  splitBufferContent,
   splitBufferEntries,
 } from "../buffer-format.js";
 
@@ -202,3 +205,43 @@ describe("splitBufferEntries", () => {
     expect(splitBufferEntries([])).toEqual([]);
   });
 });
+
+describe("splitBufferContent / joinBufferEntries", () => {
+  const content =
+    formatRememberEntry("Alice prefers dark mode", new Date(2026, 0, 1, 9, 0)) +
+    formatRememberEntry(
+      "Bob's plan:\n- [ ] step one\n\nend",
+      new Date(2026, 0, 1, 9, 1),
+    );
+
+  test("round-trips newline-terminated content byte for byte", () => {
+    expect(joinBufferEntries(splitBufferContent(content))).toBe(content);
+  });
+
+  test("an entry's text is the same whether or not it is last in the file", () => {
+    const [first] = splitBufferContent(content);
+    const [alone] = splitBufferContent(
+      formatRememberEntry(
+        "Alice prefers dark mode",
+        new Date(2026, 0, 1, 9, 0),
+      ),
+    );
+    expect(bufferEntryText(alone!)).toBe(bufferEntryText(first!));
+    expect(bufferEntryText(alone!)).toBe(
+      "- [Jan 1, 9:00 AM] Alice prefers dark mode",
+    );
+  });
+
+  test("empty content has no entries and joins back to empty", () => {
+    expect(splitBufferContent("")).toEqual([]);
+    expect(joinBufferEntries([])).toBe("");
+  });
+
+  test("content without a terminating newline keeps its last line intact", () => {
+    const entries = splitBufferContent("- [Jan 1, 9:00 AM] partial appe");
+    expect(entries).toHaveLength(1);
+    expect(bufferEntryText(entries[0]!)).toBe(
+      "- [Jan 1, 9:00 AM] partial appe",
+    );
+  });
+});

package/src/plugins/defaults/memory/__tests__/conversation-memory-purge.test.ts

@@ -60,6 +60,7 @@ describe("conversation memory purge", () => {
         "memory_v2_activation_logs",
         "memory_v3_ever_injected",
         "memory_v3_injected_sections",
+        "memory_v3_pool_inputs",
         "memory_v3_pools",
         "memory_v3_selections",
       ].sort(),

package/src/plugins/defaults/memory/__tests__/db-memory-attach.test.ts

@@ -68,6 +68,8 @@ describe("memory database connection", () => {
     "memory_recall_logs",
     "memory_v3_selections",
     "memory_v3_pools",
+    "memory_v3_pool_inputs",
+    "memory_v3_pool_texts",
     "activation_sessions",
     "activation_state",
     "conversation_graph_memory_state",

package/src/plugins/defaults/memory/__tests__/fixtures/buffer-appender.ts

@@ -0,0 +1,17 @@
+// Child process for the buffer-file cross-process test: appends `count`
+// uniquely tagged entries to `bufferPath` as fast as it can, through the same
+// `appendFileSync` call the production appender uses. Hand-formats the entry
+// line so the fixture imports nothing from `src/`.
+//
+// usage: bun buffer-appender.ts <bufferPath> <count> <tag>
+
+import { appendFileSync } from "node:fs";
+
+const [bufferPath, countArg, tag] = process.argv.slice(2);
+if (!bufferPath || !countArg || !tag) {
+  throw new Error("usage: buffer-appender <bufferPath> <count> <tag>");
+}
+const count = Number.parseInt(countArg, 10);
+for (let i = 0; i < count; i++) {
+  appendFileSync(bufferPath, `- [Apr 27, 9:00 AM] ${tag}-${i}\n`, "utf-8");
+}

package/src/plugins/defaults/memory/__tests__/memory-retrospective-job.test.ts

@@ -117,6 +117,21 @@ let loadedConversations: Record<string, { processing: boolean }> = {};
 // the stale-flag override's age check. Absent ids read as null (stampless).
 let processingStartedAtById: Record<string, number | null> = {};
 
+// The source conversation's recorded wire surface (what its last live turn
+// sent to the provider, and whether that turn's prompt rendered the
+// delegation section). `null` = no live turn has recorded one yet.
+let mockSourceToolSurface: {
+  tools: Array<Record<string, unknown>>;
+  delegateIndependentTasks: boolean | null;
+} | null = null;
+let toolSurfaceReads: string[] = [];
+mock.module("../../../../persistence/conversation-tool-surface.js", () => ({
+  getConversationToolSurface: (conversationId: string) => {
+    toolSurfaceReads.push(conversationId);
+    return mockSourceToolSurface;
+  },
+}));
+
 const watchdogEvents: Array<{
   checkName: string;
   value?: number | null;
@@ -509,6 +524,8 @@ describe("memoryRetrospectiveJob", () => {
     resolveUserSlugCalls = [];
     mockV3TierActive = true;
     mockSkillImprovementActive = false;
+    mockSourceToolSurface = null;
+    toolSurfaceReads = [];
   });
 
   test("first-run happy path: no state row, no prior retrospective, both pointer fields set on success", async () => {
@@ -1842,6 +1859,63 @@ describe("memoryRetrospectiveJob", () => {
     });
   });
 
+  test("replays the source's recorded wire tool surface verbatim on the fork wake", async () => {
+    mockSourceToolSurface = {
+      tools: [
+        { name: "bash", description: "Run", input_schema: {} },
+        { name: "remember", description: "Save", input_schema: {} },
+        { name: "bell_jingle", description: "Ring", input_schema: {} },
+        { type: "web_search_20250305", name: "web_search", max_uses: 5 },
+      ],
+      delegateIndependentTasks: true,
+    };
+
+    await memoryRetrospectiveJob(makeJob(), stubConfig);
+
+    expect(toolSurfaceReads).toEqual(["src-conv-1"]);
+    expect(wakeCalls).toHaveLength(1);
+    // The exact recorded array rides to the wake; the fork sends it in place
+    // of the surface it would resolve for itself.
+    expect(wakeCalls[0]!.opts.wireToolDefinitions).toEqual(
+      mockSourceToolSurface.tools,
+    );
+    // The delegation-section state the source's prompt rendered rides with
+    // it, so the fork's system prompt matches too.
+    expect(wakeCalls[0]!.opts.delegateIndependentTasks).toBe(true);
+    // The execution-side pin still rides alongside it.
+    expect(wakeCalls[0]!.opts.toolGateMode).toBe("execution");
+    expect(wakeCalls[0]!.opts.toolContextPin).toBeDefined();
+  });
+
+  test("a surface recorded without the delegation state leaves the fork to derive the section", async () => {
+    // A row written before the state was recorded: the array still replays,
+    // and the prompt gate falls back to the wake's own answer.
+    mockSourceToolSurface = {
+      tools: [{ name: "remember", description: "Save", input_schema: {} }],
+      delegateIndependentTasks: null,
+    };
+
+    await memoryRetrospectiveJob(makeJob(), stubConfig);
+
+    expect(wakeCalls).toHaveLength(1);
+    expect(wakeCalls[0]!.opts.wireToolDefinitions).toEqual(
+      mockSourceToolSurface.tools,
+    );
+    expect("delegateIndependentTasks" in wakeCalls[0]!.opts).toBe(false);
+  });
+
+  test("no recorded source surface → no wireToolDefinitions; the pin alone shapes the wire", async () => {
+    mockSourceToolSurface = null;
+
+    await memoryRetrospectiveJob(makeJob(), stubConfig);
+
+    expect(toolSurfaceReads).toEqual(["src-conv-1"]);
+    expect(wakeCalls).toHaveLength(1);
+    expect("wireToolDefinitions" in wakeCalls[0]!.opts).toBe(false);
+    expect("delegateIndependentTasks" in wakeCalls[0]!.opts).toBe(false);
+    expect(wakeCalls[0]!.opts.toolContextPin).toBeDefined();
+  });
+
   test("execution mode is unconditional → toolContextPin rides even without a resolved profile", async () => {
     await memoryRetrospectiveJob(
       makeJob(),