@vellumai/assistant 0.11.2 → 0.11.3-staging.2

package/src/plugins/defaults/memory/job-handlers.ts

@@ -20,7 +20,7 @@
 import { isMemoryV1Active } from "../../../config/memory-v3-gate.js";
 import type { AssistantConfig } from "../../../config/types.js";
 import type { MemoryJob } from "../../../persistence/jobs-store.js";
-import type { JobHandlerEntry } from "../../types.js";
+import type { JobHandlerEntry, JobQueueResolution } from "../../types.js";
 // The all-tier graph store: `embedGraphNodeJob` serves the V1 section,
 // `embedGraphTriggerJob` the SUBSTRATE one.
 import {
@@ -31,11 +31,17 @@ import {
 import { embedConceptPageJob } from "./jobs/embed-concept-page.js";
 import { getLogger } from "./logging.js";
 // RETROSPECTIVE (all tiers).
-import { memoryRetrospectiveJob } from "./memory-retrospective-job.js";
+import {
+  memoryRetrospectiveJob,
+  type MemoryRetrospectiveOutcome,
+} from "./memory-retrospective-job.js";
 import { skillCardInsertJob } from "./memory-retrospective-skill-card.js";
 import { memoryRetrospectiveSweepJob } from "./memory-retrospective-sweep.js";
 // SUBSTRATE (v2+v3).
-import { memoryV2ConsolidateJob } from "./substrate/consolidation-job.js";
+import {
+  type ConsolidationOutcome,
+  memoryV2ConsolidateJob,
+} from "./substrate/consolidation-job.js";
 import { memoryV2ReembedJob } from "./substrate/reembed-job.js";
 import { memoryV2SweepJob } from "./substrate/sweep-job.js";
 // V1 — delete with v1.
@@ -269,7 +275,8 @@ export const memoryJobHandlers: readonly JobHandlerEntry[] = [
   },
   {
     type: "memory_v2_consolidate",
-    handler: (job, config) => memoryV2ConsolidateJob(job, config),
+    handler: async (job, config) =>
+      resolveConsolidationOutcome(await memoryV2ConsolidateJob(job, config)),
   },
   {
     type: "memory_v2_reembed",
@@ -303,7 +310,8 @@ export const memoryJobHandlers: readonly JobHandlerEntry[] = [
   // v3 but is owned by the retrospective, so it groups here.
   {
     type: "memory_retrospective",
-    handler: (job, config) => memoryRetrospectiveJob(job, config),
+    handler: async (job, config) =>
+      resolveRetrospectiveOutcome(await memoryRetrospectiveJob(job, config)),
   },
   {
     type: "memory_retrospective_sweep",
@@ -314,3 +322,77 @@ export const memoryJobHandlers: readonly JobHandlerEntry[] = [
     handler: (job) => skillCardInsertJob(job),
   },
 ];
+
+/**
+ * Terminal `last_error` for a retrospective row whose source conversation
+ * stayed mid-turn through the whole deferral budget. Named so the dead-letter
+ * row points at the stranded `processing_started_at` flag rather than a
+ * generic backend message; the sweep re-enqueues a fresh row once the source
+ * is eligible again.
+ */
+const SOURCE_PROCESSING_EXHAUSTED_MESSAGE =
+  "source conversation stayed mid-turn through the deferral budget " +
+  "(processing_started_at may be stranded); the retrospective sweep will re-enqueue";
+
+/**
+ * Translate the retrospective handler's domain outcome into the queue
+ * resolution persisted on its job row. The domain outcome is the source of
+ * truth for what happened; this mapping owns only how the row reads
+ * afterward:
+ *
+ * - benign no-ops and successful runs complete;
+ * - a mid-turn source defers the SAME row on the bounded deferral counter
+ *   (the turn-end trigger check's upsert coalesces onto this row, so the
+ *   event-driven retry keeps its immediacy) instead of completing it and
+ *   re-upserting a fresh row per attempt;
+ * - a failed or unusable wake dead-letters the row with an honest
+ *   `last_error`. Retry stays event-driven (cooldown + re-enqueue), so the
+ *   queue's attempt budget is deliberately not double-driving it.
+ */
+function resolveRetrospectiveOutcome(
+  outcome: MemoryRetrospectiveOutcome,
+): JobQueueResolution {
+  switch (outcome.kind) {
+    case "source_processing": {
+      return {
+        queueResolution: "deferred",
+        deferralExhaustedMessage: SOURCE_PROCESSING_EXHAUSTED_MESSAGE,
+      };
+    }
+    case "wake_failed": {
+      return {
+        queueResolution: "failed",
+        errorMessage: `retrospective wake failed: ${outcome.reason ?? "unknown"}`,
+      };
+    }
+    case "no_usable_output": {
+      return {
+        queueResolution: "failed",
+        errorMessage: `retrospective run produced no usable output: ${outcome.reason ?? "unknown"}`,
+      };
+    }
+    default: {
+      return { queueResolution: "completed" };
+    }
+  }
+}
+
+/**
+ * Translate the consolidation handler's domain outcome into the queue
+ * resolution persisted on its job row. A `run_failed` dead-letters the row
+ * with the failure reason; retry cadence is owned by the durable
+ * consolidation failure-state checkpoint (`memory_v2_consolidate_failure_state`),
+ * not the queue's attempt budget. Skips (disabled / locked / empty buffer)
+ * and successful runs complete.
+ */
+function resolveConsolidationOutcome(
+  outcome: ConsolidationOutcome,
+): JobQueueResolution {
+  if (outcome.kind === "run_failed") {
+    return {
+      queueResolution: "failed",
+      errorMessage: `consolidation run failed: ${outcome.reason ?? "unknown"}`,
+    };
+  }
+  return { queueResolution: "completed" };
+}

package/src/plugins/defaults/memory/jobs-worker.ts

@@ -59,7 +59,7 @@ import {
   resetRunningJobsToPending,
   SLOW_LLM_JOB_TYPES,
 } from "../../../persistence/jobs-store.js";
-import type { JobHandler } from "../../types.js";
+import { isJobQueueResolution, type JobHandler } from "../../types.js";
 import { sweepOrphanConversationMemoryTables } from "./conversation-memory-orphan-sweep.js";
 import { getLogger } from "./logging.js";
 import { sweepOrphanMemoryRetrospectiveConversations } from "./memory-retrospective-startup-cleanup.js";
@@ -425,8 +425,8 @@ export async function runMemoryJobsOnce(
     let groupProcessed = 0;
     for (const job of group) {
       try {
-        await processJob(job, config);
-        completeMemoryJob(job.id);
+        const resolution = await processJob(job, config);
+        applyQueueResolution(job, resolution);
         groupProcessed += 1;
       } catch (err) {
         try {
@@ -654,10 +654,55 @@ function handleJobError(job: MemoryJob, err: unknown): void {
 
 // ── Job dispatch ───────────────────────────────────────────────────
 
+/**
+ * Apply a handler's returned {@link JobQueueResolution} to its claimed row.
+ * Handlers that return anything else resolve as `completed` (the historical
+ * contract: failure is signaled by throwing). This is the worker's half of
+ * the outcome-truthfulness boundary: the persisted `memory_jobs.status` must
+ * reflect the handler's actual outcome, so a handler that reports failure
+ * through a returned value (e.g. the retrospective's `wake_failed`, the
+ * consolidation's `run_failed`) dead-letters or retries instead of silently
+ * completing.
+ */
+function applyQueueResolution(job: MemoryJob, resolution: unknown): void {
+  if (!isJobQueueResolution(resolution)) {
+    completeMemoryJob(job.id);
+    return;
+  }
+  switch (resolution.queueResolution) {
+    case "completed": {
+      completeMemoryJob(job.id);
+      return;
+    }
+    case "failed": {
+      failMemoryJob(job.id, resolution.errorMessage ?? "handler failed", {
+        maxAttempts: 1,
+      });
+      return;
+    }
+    case "retryable": {
+      failMemoryJob(job.id, resolution.errorMessage ?? "handler failed", {
+        retryDelayMs:
+          resolution.retryDelayMs ?? retryDelayForAttempt(job.attempts + 1),
+        maxAttempts: RETRY_MAX_ATTEMPTS,
+      });
+      return;
+    }
+    case "deferred": {
+      deferMemoryJob(job.id, {
+        ...(resolution.deferralExhaustedMessage
+          ? { exhaustedMessage: resolution.deferralExhaustedMessage }
+          : {}),
+      });
+      return;
+    }
+  }
+}
+
 async function processJob(
   job: MemoryJob,
   config: AssistantConfig,
-): Promise<void> {
+): Promise<unknown> {
   // Dispatch-level half of the v1-staleness guard, on the same condition the
   // handler-level half uses (`isStaleV1GraphJob` in `job-handlers.ts`): v1 work
   // runs only while v1 is the live tier, which memory being off is not (see
@@ -674,8 +719,7 @@ async function processJob(
   }
   const handler = jobHandlers.get(job.type);
   if (handler) {
-    await handler(job, config);
-    return;
+    return await handler(job, config);
   }
 
   const rawType = (job as { type: string }).type;
@@ -879,6 +923,12 @@ export const RETROSPECTIVE_SWEEP_CHECKPOINT = "retro_sweep:last_run";
  * Deduped against an in-flight sweep so a slow scan can't stack copies; the
  * checkpoint still advances in that case to hold the cadence steady.
  *
+ * `memory.retrospective.enabled` is checked here as well as inside the
+ * enqueue funnel, so a disabled retrospective costs no scan at all rather
+ * than a full conversation scan whose every enqueue is then declined. The
+ * checkpoint is left untouched while disabled, so re-enabling fires the
+ * first sweep on the next tick, which is the desired catch-up.
+ *
  * Exported for tests; the worker calls it on every idle/drain tick. Returns
  * true if a sweep job was enqueued this call.
  */
@@ -890,6 +940,10 @@ export function maybeEnqueueRetrospectiveSweepJob(
     return false;
   }
 
+  if (!config.memory.retrospective.enabled) {
+    return false;
+  }
+
   const checkpoint = getMemoryCheckpoint(RETROSPECTIVE_SWEEP_CHECKPOINT);
   if (checkpoint === null) {
     setMemoryCheckpoint(RETROSPECTIVE_SWEEP_CHECKPOINT, String(nowMs));

package/src/plugins/defaults/memory/memory-retrospective-constants.ts

@@ -78,3 +78,14 @@ export const MEMORY_RETROSPECTIVE_ORIGIN = "memory_retrospective";
  * set from turn 1, and matched by the permission checker's origin-scoped grant.
  */
 export const SKILL_MANAGEMENT_SKILL_ID = "skill-management";
+
+/**
+ * The exact reply the fork instruction mandates when a reviewed window
+ * contains nothing worth saving. The finalizer treats a persisted assistant
+ * text block that trims to exactly this phrase (with no memory-writing tool
+ * attempts in the run) as the positive artifact of a legitimate no-findings
+ * review, advancing the cursor without fabricating a memory write. Compared
+ * by strict whole-block equality so analysis prose that merely mentions the
+ * phrase does not qualify.
+ */
+export const MEMORY_RETROSPECTIVE_NO_FINDINGS_TEXT = "Nothing new to save.";

package/src/plugins/defaults/memory/memory-retrospective-enqueue.ts

@@ -3,6 +3,8 @@
 // ---------------------------------------------------------------------------
 //
 // Enqueue a `memory_retrospective` job for the given conversation. Gates on:
+//   - `memory.enabled` (the whole memory system) and
+//     `memory.retrospective.enabled` (this pass alone).
 //   - Source conversation isn't a memory-retrospective conversation itself
 //     (recursion guard — we never run a retrospective over reflective
 //     musings from the retrospective agent's own writes).
@@ -72,6 +74,14 @@ export function enqueueMemoryRetrospectiveIfEnabled(args: {
     return false;
   }
 
+  if (!isRetrospectiveEnabled()) {
+    log.debug(
+      { conversationId, trigger },
+      "Skipping memory-retrospective enqueue: memory.retrospective.enabled is false",
+    );
+    return false;
+  }
+
   if (isMemoryRetrospectiveConversation(conversationId)) {
     log.debug(
       { conversationId, trigger },
@@ -107,6 +117,25 @@ export function enqueueMemoryRetrospectiveIfEnabled(args: {
   return true;
 }
 
+/**
+ * The `memory.retrospective.enabled` kill switch. Deliberately fails CLOSED,
+ * unlike the heuristic gates around it: this flag exists to stop a
+ * fork-driven write burst from locking the DB, so an unreadable config must
+ * not resurrect the very work an operator turned off. A read that throws is
+ * logged rather than swallowed silently.
+ */
+function isRetrospectiveEnabled(): boolean {
+  try {
+    return getConfig().memory.retrospective.enabled;
+  } catch (err) {
+    log.warn(
+      { err },
+      "Could not read memory.retrospective.enabled; treating retrospectives as disabled",
+    );
+    return false;
+  }
+}
+
 /**
  * The `memory.retrospective.requireUserActivity` gate: pass when the config
  * is off or the unprocessed tail (everything after the conversation's