@vellumai/assistant 0.12.0 → 0.12.1-dev.202609141913.5e16607

package/src/plugins/defaults/memory/memory-retrospective-cursor-backfill.ts

@@ -0,0 +1,126 @@
+// ---------------------------------------------------------------------------
+// Memory retrospective: cursor timestamp backfill.
+// ---------------------------------------------------------------------------
+//
+// State rows written before `last_processed_created_at` existed carry an
+// id-only cursor, which stops bounding reads the moment its row is deleted
+// (see `memory-retrospective-state.ts`). This pass copies `createdAt` from
+// each such row's message while the message still exists. Rows whose message
+// is already gone stay NULL: nothing remains to recover, and they are counted
+// so the stall is visible in the log. Runs detached at daemon init (ahead of
+// any client regenerating a reply) and again at memory-worker startup;
+// idempotent, keyset-paginated by conversation id, and yielding between pages.
+
+import { and, asc, eq, gt, isNull, ne } from "drizzle-orm";
+
+import { messageCreatedAtByIds } from "../../../persistence/message-reads.js";
+import { memoryRetrospectiveState } from "../../../persistence/schema/index.js";
+import { withSqliteRetry } from "./host-utils.js";
+import { getLogger } from "./logging.js";
+import { memoryDbOrNull } from "./memory-db.js";
+import { ensureRetrospectiveCursorColumn } from "./memory-retrospective-state.js";
+
+const log = getLogger("memory-retrospective-cursor-backfill");
+
+const DEFAULT_PAGE_SIZE = 500;
+
+export interface CursorBackfillResult {
+  /** Rows with a cursor id but no timestamp. */
+  scanned: number;
+  /** Rows whose message still exists and received its `createdAt`. */
+  backfilled: number;
+  /** Rows whose cursor message no longer exists; left NULL. */
+  unrecoverable: number;
+}
+
+/**
+ * Fill `last_processed_created_at` on every state row that has a cursor id
+ * but no timestamp. Best-effort: a missing memory connection or column is a
+ * no-op, and a row the job rewrites mid-pass is skipped by the update's
+ * `IS NULL` guard rather than stomped. Pages by conversation id so a large
+ * backlog never materializes at once or holds the event loop.
+ */
+export async function backfillRetrospectiveCursorTimestamps(opts?: {
+  pageSize?: number;
+}): Promise<CursorBackfillResult> {
+  const pageSize = opts?.pageSize ?? DEFAULT_PAGE_SIZE;
+  const result: CursorBackfillResult = {
+    scanned: 0,
+    backfilled: 0,
+    unrecoverable: 0,
+  };
+  const context = "backfillRetrospectiveCursorTimestamps";
+  const mdb = memoryDbOrNull(context);
+  if (!mdb || !ensureRetrospectiveCursorColumn(context)) {
+    return result;
+  }
+
+  let afterConversationId = "";
+  for (;;) {
+    const page = mdb
+      .select({
+        conversationId: memoryRetrospectiveState.conversationId,
+        messageId: memoryRetrospectiveState.lastProcessedMessageId,
+      })
+      .from(memoryRetrospectiveState)
+      .where(
+        and(
+          isNull(memoryRetrospectiveState.lastProcessedCreatedAt),
+          ne(memoryRetrospectiveState.lastProcessedMessageId, ""),
+          gt(memoryRetrospectiveState.conversationId, afterConversationId),
+        ),
+      )
+      .orderBy(asc(memoryRetrospectiveState.conversationId))
+      .limit(pageSize)
+      .all();
+    if (page.length === 0) {
+      break;
+    }
+    afterConversationId = page[page.length - 1]!.conversationId;
+    result.scanned += page.length;
+
+    const createdAtById = messageCreatedAtByIds(
+      page.map((row) => row.messageId),
+    );
+    const recoverable = page.flatMap((row) => {
+      const createdAt = createdAtById.get(row.messageId);
+      return createdAt === undefined ? [] : [{ ...row, createdAt }];
+    });
+    result.unrecoverable += page.length - recoverable.length;
+
+    if (recoverable.length > 0) {
+      await withSqliteRetry(
+        () => {
+          mdb.transaction((tx) => {
+            for (const row of recoverable) {
+              tx.update(memoryRetrospectiveState)
+                .set({ lastProcessedCreatedAt: row.createdAt })
+                .where(
+                  and(
+                    eq(
+                      memoryRetrospectiveState.conversationId,
+                      row.conversationId,
+                    ),
+                    eq(
+                      memoryRetrospectiveState.lastProcessedMessageId,
+                      row.messageId,
+                    ),
+                    isNull(memoryRetrospectiveState.lastProcessedCreatedAt),
+                  ),
+                )
+                .run();
+            }
+          });
+        },
+        { op: context, context: { afterConversationId } },
+      );
+      result.backfilled += recoverable.length;
+    }
+    await Bun.sleep(0);
+  }
+
+  if (result.backfilled > 0 || result.unrecoverable > 0) {
+    log.info(result, "Retrospective cursor timestamps backfilled");
+  }
+  return result;
+}

package/src/plugins/defaults/memory/memory-retrospective-cursor-preserve.ts

@@ -0,0 +1,79 @@
+// ---------------------------------------------------------------------------
+// Memory retrospective: keep the cursor's timestamp when its row is deleted.
+// ---------------------------------------------------------------------------
+//
+// The cursor normally sits on the latest assistant reply, and the retry route
+// deletes exactly that row when the user regenerates it. A cursor written
+// before the timestamp column existed carries only the id, so once the row is
+// gone nothing can place it. The `message-deleted` hook delivers each deleted
+// row's `(createdAt, id)` here: when the conversation's cursor is among the
+// rows and has no timestamp yet, the row's `createdAt` is recorded. The
+// timestamps travel in the call, so the write does not need the rows to
+// still exist.
+
+import { and, eq, isNull } from "drizzle-orm";
+
+import { memoryRetrospectiveState } from "../../../persistence/schema/index.js";
+import { withSqliteRetry } from "./host-utils.js";
+import { getLogger } from "./logging.js";
+import { memoryDbOrNull } from "./memory-db.js";
+import { ensureRetrospectiveCursorColumn } from "./memory-retrospective-state.js";
+
+const log = getLogger("memory-retrospective-cursor-preserve");
+
+/**
+ * Record `createdAt` on the conversation's retrospective cursor when it points
+ * at one of `rows` and has no timestamp yet. Best-effort: an unavailable
+ * memory connection or column is a no-op, and a cursor the job has moved
+ * since the caller read it is skipped by the `IS NULL` guard.
+ */
+export async function preserveRetrospectiveCursorTimestamps(
+  conversationId: string,
+  rows: ReadonlyArray<{ id: string; createdAt: number }>,
+): Promise<void> {
+  if (rows.length === 0) {
+    return;
+  }
+  const context = "preserveRetrospectiveCursorTimestamps";
+  try {
+    const mdb = memoryDbOrNull(context);
+    if (!mdb || !ensureRetrospectiveCursorColumn(context)) {
+      return;
+    }
+    const state = mdb
+      .select({
+        messageId: memoryRetrospectiveState.lastProcessedMessageId,
+        createdAt: memoryRetrospectiveState.lastProcessedCreatedAt,
+      })
+      .from(memoryRetrospectiveState)
+      .where(eq(memoryRetrospectiveState.conversationId, conversationId))
+      .get();
+    if (!state || state.createdAt !== null) {
+      return;
+    }
+    const row = rows.find((candidate) => candidate.id === state.messageId);
+    if (!row) {
+      return;
+    }
+    await withSqliteRetry(
+      () =>
+        mdb
+          .update(memoryRetrospectiveState)
+          .set({ lastProcessedCreatedAt: row.createdAt })
+          .where(
+            and(
+              eq(memoryRetrospectiveState.conversationId, conversationId),
+              eq(memoryRetrospectiveState.lastProcessedMessageId, row.id),
+              isNull(memoryRetrospectiveState.lastProcessedCreatedAt),
+            ),
+          )
+          .run(),
+      { op: context, context: { conversationId } },
+    );
+  } catch (err) {
+    log.warn(
+      { err, conversationId },
+      "could not preserve the retrospective cursor timestamp before its row was deleted",
+    );
+  }
+}

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

@@ -0,0 +1,28 @@
+// ---------------------------------------------------------------------------
+// Memory retrospective: the cursor a state row hands to the messages-after
+// reads.
+// ---------------------------------------------------------------------------
+
+import type { MessageCursor } from "../../../persistence/message-cursor.js";
+
+/**
+ * The `(createdAt, id)` cursor a retrospective state row carries, or null
+ * when nothing has been processed yet (no row, or the `""` sentinel left by
+ * failure-only attempts). The timestamp lets the reads keep their bound after
+ * the cursor's row is deleted, which is what a regenerated reply does to the
+ * latest assistant message the cursor usually sits on.
+ */
+export function retrospectiveCursor(
+  state: {
+    lastProcessedMessageId: string;
+    lastProcessedCreatedAt?: number | null;
+  } | null,
+): MessageCursor | null {
+  if (!state || state.lastProcessedMessageId === "") {
+    return null;
+  }
+  return {
+    id: state.lastProcessedMessageId,
+    createdAt: state.lastProcessedCreatedAt ?? null,
+  };
+}

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

@@ -47,6 +47,7 @@ import { resolveCapabilities } from "../../../runtime/capabilities.js";
 import { getLogger } from "./logging.js";
 import { hasQualifyingUserMessageAfter } from "./memory-retrospective-accounting.js";
 import { isMemoryRetrospectiveSource } from "./memory-retrospective-constants.js";
+import { retrospectiveCursor } from "./memory-retrospective-cursor.js";
 import { getRetrospectiveState } from "./memory-retrospective-state.js";
 
 const log = getLogger("memory-retrospective-enqueue");
@@ -139,7 +140,7 @@ function isRetrospectiveEnabled(): boolean {
 /**
  * The `memory.retrospective.requireUserActivity` gate: pass when the config
  * is off or the unprocessed tail (everything after the conversation's
- * `lastProcessedMessageId`) contains at least one user message carrying
+ * retrospective cursor) contains at least one user message carrying
  * non-tool_result content. A gate that cannot be evaluated (config or DB
  * unavailable) passes — an unevaluable gate must not silence retrospectives.
  */
@@ -153,10 +154,7 @@ function passesUserActivityGate(
     }
     const state = getRetrospectiveState(conversationId);
     if (
-      hasQualifyingUserMessageAfter(
-        conversationId,
-        state?.lastProcessedMessageId ?? null,
-      )
+      hasQualifyingUserMessageAfter(conversationId, retrospectiveCursor(state))
     ) {
       return true;
     }

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

@@ -58,7 +58,7 @@ import {
   parseClientOs,
   parseInterfaceId,
 } from "../../../channels/types.js";
-import { isV3TierActive } from "../../../config/memory-v3-gate.js";
+import { isSkillImprovementActive } from "../../../config/memory-v3-gate.js";
 import type { AssistantConfig } from "../../../config/types.js";
 import { warmGuardianBindings } from "../../../contacts/guardian-delivery-reader.js";
 import { extractTurnContextTimestamp } from "../../../context/compactor.js";
@@ -95,6 +95,7 @@ import {
   MEMORY_RETROSPECTIVE_SOURCE,
   SKILL_MANAGEMENT_SKILL_ID,
 } from "./memory-retrospective-constants.js";
+import { retrospectiveCursor } from "./memory-retrospective-cursor.js";
 import { loadRetrospectiveRunMessages } from "./memory-retrospective-fork-boundary.js";
 import { buildForkInstruction } from "./memory-retrospective-prompt.js";
 import {
@@ -357,7 +358,7 @@ export async function runForkBasedRetrospective(
   // `memory-retrospective-accounting.ts`.
   const newMessages = getRetrospectiveMessagesAfter(
     sourceConversationId,
-    lastProcessedMessageId,
+    retrospectiveCursor(state),
   );
 
   if (newMessages.length === 0) {
@@ -448,7 +449,7 @@ export async function runForkBasedRetrospective(
   }
   const forkId = forkConversationRow.id;
 
-  const procToSkillsActive = isV3TierActive(config);
+  const procToSkillsActive = isSkillImprovementActive(config);
   const instruction = buildForkInstruction({
     windowStartTimestamp,
     windowAnchorKind: turnContextTimestamp ? "turn_context" : "created_at",
@@ -650,6 +651,7 @@ export async function runForkBasedRetrospective(
         sourceConversationId,
         retrospectiveConversationId: forkId,
         cutoffMessageId,
+        cutoffCreatedAt: cutoffMessage.createdAt,
         newMessageCount: newMessages.length,
         prior,
         priorRemembers,
@@ -947,6 +949,11 @@ async function finalizeSuccessfulRetrospective(args: {
   sourceConversationId: string;
   retrospectiveConversationId: string;
   cutoffMessageId: string;
+  /**
+   * `createdAt` of the cutoff row, persisted beside its id so the cursor
+   * keeps bounding reads after the row is deleted.
+   */
+  cutoffCreatedAt: number;
   newMessageCount: number;
   prior: PriorRetrospective | null;
   priorRemembers: string[];
@@ -966,6 +973,7 @@ async function finalizeSuccessfulRetrospective(args: {
     sourceConversationId,
     retrospectiveConversationId,
     cutoffMessageId,
+    cutoffCreatedAt,
     newMessageCount,
     prior,
     priorRemembers,
@@ -977,6 +985,7 @@ async function finalizeSuccessfulRetrospective(args: {
   await upsertRetrospectiveState({
     conversationId: sourceConversationId,
     lastProcessedMessageId: cutoffMessageId,
+    lastProcessedCreatedAt: cutoffCreatedAt,
     lastRunAt: Date.now(),
     rememberedLog: appendToRememberedLog(priorRemembers, runRemembers),
   });