@vellumai/assistant 0.11.2 → 0.11.3-staging.2

package/src/plugins/defaults/image-recovery/recover.ts

@@ -75,9 +75,9 @@ export const UNSENDABLE_IMAGE_NOTE =
  * in context, so without it the original rejected block rehydrates and
  * re-rejects on every later turn.
  */
-export function unsendableImageReplacement(
+export async function unsendableImageReplacement(
   block: Extract<ContentBlock, { type: "image" }>,
-): ContentBlock | null {
+): Promise<ContentBlock | null> {
   // Resolve reference sources to their bytes so a reloaded (referenced) image
   // is gated on the same payload/dimension caps as an inline one. When the
   // attachment can no longer be read, leave the block untouched.
@@ -118,8 +118,8 @@ export function unsendableImageReplacement(
   // pre-send — the upscale runs only here, in response to an actual
   // provider rejection. Oversized images reuse the transport downscale.
   const optimized = belowMinDimension
-    ? upscaleImageToMinimum(resolved.data, effectiveMediaType)
-    : optimizeImageForTransport(resolved.data, effectiveMediaType);
+    ? await upscaleImageToMinimum(resolved.data, effectiveMediaType)
+    : await optimizeImageForTransport(resolved.data, effectiveMediaType);
   if (optimized && optimized.data !== resolved.data) {
     return {
       type: "image",
@@ -145,9 +145,9 @@ export function unsendableImageReplacement(
  * image, so neither matches on a second run. Returns the number of rewritten
  * messages.
  */
-export function persistUnsendableImageDowngrades(
+export async function persistUnsendableImageDowngrades(
   conversationId: string,
-): number {
+): Promise<number> {
   let rewritten = 0;
   for (const row of getMessages(conversationId)) {
     const hasImageBlock = row.content.some(
@@ -163,39 +163,47 @@ export function persistUnsendableImageDowngrades(
     const parsed = row.content;
 
     let changed = false;
-    const next = (parsed as ContentBlock[]).map((block): ContentBlock => {
+    const next: ContentBlock[] = [];
+    for (const block of parsed as ContentBlock[]) {
       if (block.type === "image") {
-        const replacement = unsendableImageReplacement(block);
+        const replacement = await unsendableImageReplacement(block);
         if (!replacement) {
-          return block;
+          next.push(block);
+          continue;
         }
         changed = true;
-        return replacement;
+        next.push(replacement);
+        continue;
       }
       // Images returned by a tool (e.g. browser_screenshot) live inside the
       // tool_result's contentBlocks, not as top-level blocks. Downgrade them
       // in place so the tool_use/tool_result pairing stays intact.
       if (block.type === "tool_result" && block.contentBlocks?.length) {
         let nestedChanged = false;
-        const contentBlocks = block.contentBlocks.map((cb): ContentBlock => {
+        const contentBlocks: ContentBlock[] = [];
+        for (const cb of block.contentBlocks) {
           if (cb.type !== "image") {
-            return cb;
+            contentBlocks.push(cb);
+            continue;
           }
-          const replacement = unsendableImageReplacement(cb);
+          const replacement = await unsendableImageReplacement(cb);
           if (!replacement) {
-            return cb;
+            contentBlocks.push(cb);
+            continue;
           }
           nestedChanged = true;
-          return replacement;
-        });
+          contentBlocks.push(replacement);
+        }
         if (!nestedChanged) {
-          return block;
+          next.push(block);
+          continue;
         }
         changed = true;
-        return { ...block, contentBlocks };
+        next.push({ ...block, contentBlocks });
+        continue;
       }
-      return block;
-    });
+      next.push(block);
+    }
     if (!changed) {
       continue;
     }
@@ -240,50 +248,52 @@ function messageHasImageBlock(content: ReadonlyArray<ContentBlock>): boolean {
  * caller must not retry an unchanged history: it would resend the identical
  * rejected image and falsely report a correction.
  */
-export function recoverUnsendableImages(messages: ReadonlyArray<Message>): {
+export async function recoverUnsendableImages(
+  messages: ReadonlyArray<Message>,
+): Promise<{
   messages: Message[];
   changed: boolean;
-} {
+}> {
   let changed = false;
-  const recovered = messages.map((msg) => {
-    if (!Array.isArray(msg.content)) {
-      return msg;
-    }
-    if (!messageHasImageBlock(msg.content)) {
-      return msg;
+  const recovered: Message[] = [];
+  for (const msg of messages) {
+    if (!Array.isArray(msg.content) || !messageHasImageBlock(msg.content)) {
+      recovered.push(msg);
+      continue;
     }
-    return {
-      ...msg,
-      content: msg.content.flatMap((b): ContentBlock[] => {
-        if (b.type === "image") {
-          const replacement = unsendableImageReplacement(b);
+    const content: ContentBlock[] = [];
+    for (const b of msg.content) {
+      if (b.type === "image") {
+        const replacement = await unsendableImageReplacement(b);
+        if (replacement) {
+          changed = true;
+          content.push(replacement);
+        } else {
+          content.push(b);
+        }
+        continue;
+      }
+      if (b.type === "tool_result" && b.contentBlocks?.length) {
+        const contentBlocks: ContentBlock[] = [];
+        for (const cb of b.contentBlocks) {
+          if (cb.type !== "image") {
+            contentBlocks.push(cb);
+            continue;
+          }
+          const replacement = await unsendableImageReplacement(cb);
           if (replacement) {
             changed = true;
-            return [replacement];
+            contentBlocks.push(replacement);
+          } else {
+            contentBlocks.push(cb);
           }
-          return [b];
         }
-        if (b.type === "tool_result" && b.contentBlocks?.length) {
-          return [
-            {
-              ...b,
-              contentBlocks: b.contentBlocks.map((cb) => {
-                if (cb.type !== "image") {
-                  return cb;
-                }
-                const replacement = unsendableImageReplacement(cb);
-                if (replacement) {
-                  changed = true;
-                  return replacement;
-                }
-                return cb;
-              }),
-            },
-          ];
-        }
-        return [b];
-      }),
-    };
-  });
+        content.push({ ...b, contentBlocks });
+        continue;
+      }
+      content.push(b);
+    }
+    recovered.push({ ...msg, content });
+  }
   return { messages: recovered, changed };
 }

package/src/plugins/defaults/index.ts

@@ -356,7 +356,7 @@ export const defaultToolErrorPlugin: Plugin = {
  * file_list) with no user-facing text, or (on loop-prone models such as Kimi
  * K2.6 and MiniMax M3) the model re-issuing a byte-identical exploration call — and nudges
  * the model via `additionalContext` to summarize progress for the user and
- * delegate the remaining investigation to an `investigator` subagent rather
+ * delegate the remaining investigation to a `researcher` subagent rather
  * than continuing inline.
  */
 export const defaultExplorationDriftPlugin: Plugin = {

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

@@ -396,7 +396,7 @@ describe("countConversations", () => {
     const priv = createConversation("private-1");
     setConversationType(priv.id, "private");
 
-    expect(countConversations("background")).toBe(2);
+    expect(countConversations({ conversationType: "background" })).toBe(2);
   });
 
   test("includes standard conversations with group_id system:background in background count", () => {
@@ -411,13 +411,13 @@ describe("countConversations", () => {
     createConversation("foreground-1");
 
     // WHEN counting background conversations
-    const bgCount = countConversations("background");
+    const bgCount = countConversations({ conversationType: "background" });
 
     // THEN the heartbeat conversation is included
     expect(bgCount).toBe(1);
 
     // AND excluded from the foreground count
-    expect(countConversations("standard")).toBe(1);
+    expect(countConversations({ conversationType: "standard" })).toBe(1);
   });
 
   test("excludes standard conversations with group_id system:background from foreground count", () => {
@@ -432,7 +432,7 @@ describe("countConversations", () => {
 
     // WHEN counting foreground conversations
     // THEN the heartbeat is excluded
-    expect(countConversations("standard")).toBe(2);
+    expect(countConversations({ conversationType: "standard" })).toBe(2);
   });
 
   test('"scheduled" count returns only scheduled rows', () => {
@@ -443,7 +443,7 @@ describe("countConversations", () => {
 
     // WHEN counting scheduled conversations
     // THEN only the scheduled row is counted (background is excluded)
-    expect(countConversations("scheduled")).toBe(1);
+    expect(countConversations({ conversationType: "scheduled" })).toBe(1);
   });
 
   describe("archiveStatus", () => {
@@ -473,7 +473,12 @@ describe("countConversations", () => {
         a2.id,
       );
 
-      expect(countConversations("standard", "archived")).toBe(2);
+      expect(
+        countConversations({
+          conversationType: "standard",
+          archiveStatus: "archived",
+        }),
+      ).toBe(2);
     });
 
     test('archiveStatus "all" returns both', () => {
@@ -486,7 +491,12 @@ describe("countConversations", () => {
         archived.id,
       );
 
-      expect(countConversations("standard", "all")).toBe(2);
+      expect(
+        countConversations({
+          conversationType: "standard",
+          archiveStatus: "all",
+        }),
+      ).toBe(2);
     });
   });
 });
@@ -511,7 +521,10 @@ describe("listConversations", () => {
     createConversation("foreground-1");
 
     // WHEN listing background conversations
-    const bgList = listConversations(100, "background");
+    const bgList = listConversations({
+      limit: 100,
+      conversationType: "background",
+    });
 
     // THEN both background and heartbeat conversations are returned
     expect(bgList).toHaveLength(2);
@@ -532,7 +545,10 @@ describe("listConversations", () => {
     createConversation("foreground-1");
 
     // WHEN listing foreground conversations
-    const fgList = listConversations(100, "standard");
+    const fgList = listConversations({
+      limit: 100,
+      conversationType: "standard",
+    });
 
     // THEN only the foreground conversation is returned
     expect(fgList).toHaveLength(1);
@@ -549,14 +565,20 @@ describe("listConversations", () => {
     );
 
     // WHEN listing background conversations
-    const bgList = listConversations(100, "background");
+    const bgList = listConversations({
+      limit: 100,
+      conversationType: "background",
+    });
 
     // THEN it appears in the background list
     expect(bgList).toHaveLength(1);
     expect(bgList[0]!.title).toBe("schedule-routed");
 
     // AND not in the foreground list
-    const fgList = listConversations(100, "standard");
+    const fgList = listConversations({
+      limit: 100,
+      conversationType: "standard",
+    });
     expect(fgList).toHaveLength(0);
   });
 
@@ -567,7 +589,10 @@ describe("listConversations", () => {
     createConversation("foreground-1");
 
     // WHEN listing scheduled conversations
-    const scheduledList = listConversations(100, "scheduled");
+    const scheduledList = listConversations({
+      limit: 100,
+      conversationType: "scheduled",
+    });
 
     // THEN only the scheduled conversation is returned
     expect(scheduledList).toHaveLength(1);
@@ -592,7 +617,10 @@ describe("listConversations", () => {
     );
 
     // WHEN listing scheduled conversations
-    const scheduledList = listConversations(100, "scheduled");
+    const scheduledList = listConversations({
+      limit: 100,
+      conversationType: "scheduled",
+    });
 
     // THEN only the system:scheduled row appears
     expect(scheduledList).toHaveLength(1);
@@ -608,7 +636,10 @@ describe("listConversations", () => {
     });
 
     // WHEN listing scheduled conversations
-    const scheduledList = listConversations(100, "scheduled");
+    const scheduledList = listConversations({
+      limit: 100,
+      conversationType: "scheduled",
+    });
 
     // THEN the subagent run is excluded
     expect(scheduledList).toHaveLength(0);
@@ -627,7 +658,10 @@ describe("listConversations", () => {
       );
 
       // WHEN listing without an explicit archiveStatus
-      const rows = listConversations(100, "standard");
+      const rows = listConversations({
+        limit: 100,
+        conversationType: "standard",
+      });
 
       // THEN only the live conversation appears
       expect(rows).toHaveLength(1);
@@ -646,7 +680,11 @@ describe("listConversations", () => {
       );
 
       // WHEN listing with archiveStatus "archived"
-      const rows = listConversations(100, "standard", 0, "archived");
+      const rows = listConversations({
+        limit: 100,
+        conversationType: "standard",
+        archiveStatus: "archived",
+      });
 
       // THEN only the archived conversation appears
       expect(rows).toHaveLength(1);
@@ -665,7 +703,11 @@ describe("listConversations", () => {
       );
 
       // WHEN listing with archiveStatus "all"
-      const rows = listConversations(100, "standard", 0, "all");
+      const rows = listConversations({
+        limit: 100,
+        conversationType: "standard",
+        archiveStatus: "all",
+      });
 
       // THEN both conversations appear
       expect(rows).toHaveLength(2);
@@ -690,7 +732,11 @@ describe("listConversations", () => {
       );
 
       // WHEN listing archived background conversations
-      const rows = listConversations(100, "background", 0, "archived");
+      const rows = listConversations({
+        limit: 100,
+        conversationType: "background",
+        archiveStatus: "archived",
+      });
 
       // THEN only the archived background row appears
       expect(rows).toHaveLength(1);

package/src/plugins/defaults/memory/__tests__/jobs-worker-outcome-contract.test.ts

@@ -0,0 +1,242 @@
+/**
+ * Outcome-truthfulness contract between job handlers and the jobs worker.
+ *
+ * Handlers that report failure through a RETURNED domain outcome (the
+ * retrospective's `wake_failed` / `no_usable_output` / `source_processing`,
+ * the consolidation's `run_failed`) must not leave their job rows reading
+ * `completed` with a null `last_error`. The registration-site adapters in
+ * `job-handlers.ts` translate domain outcomes into `JobQueueResolution`s and
+ * the worker applies them, so the persisted `memory_jobs.status` reflects the
+ * handler's actual outcome.
+ *
+ * Also covers the store-level late-transition guards: once the stalled-job
+ * watchdog fails a row, a late `completeMemoryJob` from the abandoned
+ * execution must not flip it back to `completed`.
+ */
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  afterAll,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  test,
+} from "bun:test";
+
+import { eq } from "drizzle-orm";
+
+import type { MemoryRetrospectiveOutcome } from "../memory-retrospective-job.js";
+import type { ConsolidationOutcome } from "../substrate/consolidation-job.js";
+
+// Scripted handler outcomes, set per-test.
+let retrospectiveOutcome: MemoryRetrospectiveOutcome = {
+  kind: "no_new_messages",
+};
+let consolidationOutcome: ConsolidationOutcome = { kind: "empty_buffer" };
+
+mock.module("../memory-retrospective-job.js", () => ({
+  memoryRetrospectiveJob: async () => retrospectiveOutcome,
+  STALE_SOURCE_PROCESSING_OVERRIDE_MS: 6 * 60 * 60 * 1000,
+}));
+
+mock.module("../substrate/consolidation-job.js", () => ({
+  memoryV2ConsolidateJob: async () => consolidationOutcome,
+  // Scheduler helpers the worker reads on every pass.
+  countBufferLines: () => 0,
+  readConsolidationFailureState: () => null,
+}));
+
+mock.module("../graph/graph-search.js", () => ({
+  embedGraphNodeDirect: async () => {},
+  embedGraphNodeJob: async (): Promise<void> => {},
+  enqueueGraphNodeEmbed: () => {},
+  embedGraphTriggerJob: async (): Promise<void> => {},
+  enqueueGraphTriggerEmbed: () => {},
+}));
+
+mock.module("../v1/graph/graph-search.js", () => ({
+  searchGraphNodes: async () => [],
+}));
+
+mock.module("../../../../persistence/db-maintenance.js", () => ({
+  maybeRunDbMaintenance: async () => {},
+  maybeRunPassiveWalCheckpoint: async () => {},
+}));
+
+const tmpWorkspace = mkdtempSync(
+  join(tmpdir(), "jobs-worker-outcome-contract-"),
+);
+const previousWorkspaceEnv = process.env.VELLUM_WORKSPACE_DIR;
+process.env.VELLUM_WORKSPACE_DIR = tmpWorkspace;
+
+import { getMemoryDb } from "../../../../persistence/db-connection.js";
+import { initializeDb } from "../../../../persistence/db-init.js";
+import { _resetQdrantBreaker } from "../../../../persistence/embeddings/qdrant-circuit-breaker.js";
+import {
+  completeMemoryJob,
+  enqueueMemoryJob,
+  failStalledJobs,
+} from "../../../../persistence/jobs-store.js";
+import { memoryJobs } from "../../../../persistence/schema/index.js";
+import { registerMemoryPluginJobHandlers } from "../job-handler-registration.js";
+import { runMemoryJobsOnce } from "../jobs-worker.js";
+
+function jobRow(jobId: string) {
+  return getMemoryDb()!
+    .select()
+    .from(memoryJobs)
+    .where(eq(memoryJobs.id, jobId))
+    .get();
+}
+
+describe("job outcome truthfulness", () => {
+  beforeAll(async () => {
+    registerMemoryPluginJobHandlers();
+    await initializeDb();
+  });
+
+  afterAll(() => {
+    if (previousWorkspaceEnv === undefined) {
+      delete process.env.VELLUM_WORKSPACE_DIR;
+    } else {
+      process.env.VELLUM_WORKSPACE_DIR = previousWorkspaceEnv;
+    }
+    rmSync(tmpWorkspace, { recursive: true, force: true });
+  });
+
+  beforeEach(() => {
+    getMemoryDb()!.run("DELETE FROM memory_jobs");
+    _resetQdrantBreaker();
+    retrospectiveOutcome = { kind: "no_new_messages" };
+    consolidationOutcome = { kind: "empty_buffer" };
+  });
+
+  test("retrospective wake_failed dead-letters the row with an honest last_error", async () => {
+    retrospectiveOutcome = { kind: "wake_failed", reason: "run_error" };
+    const jobId = enqueueMemoryJob("memory_retrospective", {
+      conversationId: "conv-1",
+    });
+
+    await runMemoryJobsOnce();
+
+    const row = jobRow(jobId);
+    expect(row?.status).toBe("failed");
+    expect(row?.lastError).toContain("retrospective wake failed");
+    expect(row?.lastError).toContain("run_error");
+  });
+
+  test("retrospective no_usable_output dead-letters the row with the failure detail", async () => {
+    retrospectiveOutcome = {
+      kind: "no_usable_output",
+      reason: "run persisted no memory-writing tool call",
+    };
+    const jobId = enqueueMemoryJob("memory_retrospective", {
+      conversationId: "conv-1",
+    });
+
+    await runMemoryJobsOnce();
+
+    const row = jobRow(jobId);
+    expect(row?.status).toBe("failed");
+    expect(row?.lastError).toContain("no usable output");
+  });
+
+  test("retrospective source_processing defers the SAME row on the deferral counter", async () => {
+    retrospectiveOutcome = { kind: "source_processing" };
+    const jobId = enqueueMemoryJob("memory_retrospective", {
+      conversationId: "conv-1",
+    });
+
+    const before = Date.now();
+    await runMemoryJobsOnce();
+
+    const row = jobRow(jobId);
+    expect(row?.status).toBe("pending");
+    expect(row?.deferrals).toBe(1);
+    expect(row?.attempts).toBe(0);
+    expect(row!.runAfter).toBeGreaterThan(before);
+    // Exactly one row for the conversation: no fresh row minted per attempt.
+    const rows = getMemoryDb()!
+      .select()
+      .from(memoryJobs)
+      .where(eq(memoryJobs.type, "memory_retrospective"))
+      .all();
+    expect(rows).toHaveLength(1);
+  });
+
+  test("source_processing deferral budget exhausts into an honest terminal failure", async () => {
+    retrospectiveOutcome = { kind: "source_processing" };
+    const jobId = enqueueMemoryJob("memory_retrospective", {
+      conversationId: "conv-1",
+    });
+    // Spend 49 of the 50 deferrals up front; the next pass is the last one.
+    getMemoryDb()!
+      .update(memoryJobs)
+      .set({ deferrals: 49 })
+      .where(eq(memoryJobs.id, jobId))
+      .run();
+
+    await runMemoryJobsOnce();
+
+    const row = jobRow(jobId);
+    expect(row?.status).toBe("failed");
+    expect(row?.lastError).toContain("mid-turn");
+  });
+
+  test("retrospective success and benign no-ops still complete", async () => {
+    retrospectiveOutcome = { kind: "no_new_messages" };
+    const jobId = enqueueMemoryJob("memory_retrospective", {
+      conversationId: "conv-1",
+    });
+
+    await runMemoryJobsOnce();
+
+    expect(jobRow(jobId)?.status).toBe("completed");
+  });
+
+  test("consolidation run_failed dead-letters the row with the failure reason", async () => {
+    consolidationOutcome = { kind: "run_failed", reason: "timeout" };
+    const jobId = enqueueMemoryJob("memory_v2_consolidate", {});
+
+    await runMemoryJobsOnce();
+
+    const row = jobRow(jobId);
+    expect(row?.status).toBe("failed");
+    expect(row?.lastError).toContain("consolidation run failed");
+    expect(row?.lastError).toContain("timeout");
+  });
+
+  test("consolidation skips (locked/empty) still complete", async () => {
+    consolidationOutcome = { kind: "locked", holder: "1234 0 consolidation" };
+    const jobId = enqueueMemoryJob("memory_v2_consolidate", {});
+
+    await runMemoryJobsOnce();
+
+    expect(jobRow(jobId)?.status).toBe("completed");
+  });
+
+  test("late completion cannot overwrite a watchdog-failed row", async () => {
+    const jobId = enqueueMemoryJob("memory_retrospective", {
+      conversationId: "conv-1",
+    });
+    // Simulate a claimed row whose execution went silent long enough for the
+    // stalled-job watchdog to fail it.
+    getMemoryDb()!
+      .update(memoryJobs)
+      .set({ status: "running", startedAt: Date.now() - 60 * 60 * 1000 })
+      .where(eq(memoryJobs.id, jobId))
+      .run();
+    expect(failStalledJobs(30 * 60 * 1000)).toBe(1);
+    expect(jobRow(jobId)?.status).toBe("failed");
+
+    // The abandoned execution finally returns and reports success.
+    completeMemoryJob(jobId);
+
+    const row = jobRow(jobId);
+    expect(row?.status).toBe("failed");
+    expect(row?.lastError).toContain("timed out");
+  });
+});

package/src/plugins/defaults/memory/__tests__/jobs-worker-retrospective-sweep.test.ts

@@ -39,12 +39,15 @@ getMemoryDb();
 const SWEEP_INTERVAL_MS = 8 * 60 * 60 * 1000; // 8h default
 
 function buildConfig(
-  overrides: { memoryEnabled?: boolean } = {},
+  overrides: { memoryEnabled?: boolean; retrospectiveEnabled?: boolean } = {},
 ): AssistantConfig {
   const config = applyNestedDefaults({}) as unknown as AssistantConfig;
   if (overrides.memoryEnabled !== undefined) {
     config.memory.enabled = overrides.memoryEnabled;
   }
+  if (overrides.retrospectiveEnabled !== undefined) {
+    config.memory.retrospective.enabled = overrides.retrospectiveEnabled;
+  }
   return config;
 }
 
@@ -118,6 +121,26 @@ describe("maybeEnqueueRetrospectiveSweepJob", () => {
     expect(countSweepJobs()).toBe(0);
   });
 
+  test("does not enqueue when retrospectives are disabled, and leaves the checkpoint alone", () => {
+    const now = Date.now();
+    const stale = staleCheckpoint(now);
+    setMemoryCheckpoint(RETROSPECTIVE_SWEEP_CHECKPOINT, stale);
+
+    const enqueued = maybeEnqueueRetrospectiveSweepJob(
+      buildConfig({ retrospectiveEnabled: false }),
+      now,
+    );
+
+    expect(enqueued).toBe(false);
+    expect(countSweepJobs()).toBe(0);
+    // Checkpoint untouched, so re-enabling sweeps on the next tick rather
+    // than waiting out another full interval.
+    expect(getMemoryCheckpoint(RETROSPECTIVE_SWEEP_CHECKPOINT)).toBe(stale);
+
+    expect(maybeEnqueueRetrospectiveSweepJob(buildConfig(), now)).toBe(true);
+    expect(countSweepJobs()).toBe(1);
+  });
+
   test("does not stack a second sweep while one is still in flight, but advances the checkpoint", () => {
     const now = Date.now();
     // A prior sweep is already pending.