@vellumai/assistant 0.12.1 → 0.12.2-staging.1

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

@@ -31,7 +31,7 @@
 // accounting; once newer real messages arrive it is copied into the next
 // run's fork as inert prefix context.
 
-import { and, eq, gt, like, or } from "drizzle-orm";
+import { and, eq, like, or } from "drizzle-orm";
 
 import {
   countMessagesAfter,
@@ -43,6 +43,11 @@ import {
   SIGHT_FRAME_ATTACHMENT_IDS_KEY,
 } from "../../../persistence/conversation-types.js";
 import { getDb } from "../../../persistence/db-connection.js";
+import {
+  messagesAfterBoundFilter,
+  type MessagesAfterRef,
+  resolveMessagesAfterBound,
+} from "../../../persistence/message-cursor.js";
 import { messages } from "../../../persistence/schema/index.js";
 import { SKILL_CARD_MESSAGE_KIND } from "./memory-retrospective-constants.js";
 
@@ -98,9 +103,9 @@ export function isSkillCardMessage(row: { metadata: string | null }): boolean {
  */
 export function getRetrospectiveMessagesAfter(
   conversationId: string,
-  afterMessageId: string | null,
+  after: MessagesAfterRef,
 ): MessageRow[] {
-  const rows = getMessagesAfter(conversationId, afterMessageId);
+  const rows = getMessagesAfter(conversationId, after);
   const firstUnfinalized = rows.findIndex((row) => row.finalized !== 1);
   const bounded =
     firstUnfinalized === -1 ? rows : rows.slice(0, firstUnfinalized);
@@ -116,13 +121,13 @@ export function getRetrospectiveMessagesAfter(
  */
 export function countRetrospectiveMessagesAfter(
   conversationId: string,
-  afterMessageId: string | null,
+  after: MessagesAfterRef,
 ): number {
-  const total = countMessagesAfter(conversationId, afterMessageId);
+  const total = countMessagesAfter(conversationId, after);
   if (total === 0) {
     return 0;
   }
-  const excluded = countExcludedMessagesAfter(conversationId, afterMessageId);
+  const excluded = countExcludedMessagesAfter(conversationId, after);
   return Math.max(0, total - excluded);
 }
 
@@ -167,7 +172,8 @@ export function messagesHaveUserActivity(
  * a non-tool_result block. Powers the `memory.retrospective.requireUserActivity`
  * enqueue gate, so only user rows are loaded. Cursor semantics mirror
  * `countMessagesAfter`: a null/`""` reference scans the whole conversation,
- * and a vanished reference means no new work.
+ * a cursor whose row is gone falls back to the timestamp it carries, and a
+ * bare id whose row is gone means no new work.
  *
  * Operates on the raw `content` column: rows that do not parse to a block
  * array (file-backed `{ ref }` rows, legacy plain strings) count as
@@ -177,37 +183,15 @@ export function messagesHaveUserActivity(
  */
 export function hasQualifyingUserMessageAfter(
   conversationId: string,
-  afterMessageId: string | null,
+  after: MessagesAfterRef,
 ): boolean {
-  const cursorId =
-    afterMessageId === null || afterMessageId === "" ? null : afterMessageId;
-  const db = getDb();
-
-  let ref: { createdAt: number } | undefined;
-  if (cursorId !== null) {
-    ref = db
-      .select({ createdAt: messages.createdAt })
-      .from(messages)
-      .where(eq(messages.id, cursorId))
-      .get();
-    if (!ref) {
-      return false;
-    }
+  const start = resolveMessagesAfterBound(after);
+  if (start.kind === "vanished") {
+    return false;
   }
-
   const afterCursor =
-    cursorId !== null && ref
-      ? [
-          or(
-            gt(messages.createdAt, ref.createdAt),
-            and(
-              eq(messages.createdAt, ref.createdAt),
-              gt(messages.id, cursorId),
-            ),
-          ),
-        ]
-      : [];
-  const rows = db
+    start.kind === "after" ? [messagesAfterBoundFilter(start.bound)] : [];
+  const rows = getDb()
     .select({ content: messages.content, metadata: messages.metadata })
     .from(messages)
     .where(
@@ -248,18 +232,14 @@ function rawUserContentCarriesActivity(raw: string | null): boolean {
  * — at most one per successful retrospective run); each candidate is then
  * JSON-verified by {@link isSkillCardMessage} so an incidental substring
  * match in unrelated metadata can never exclude a real message from
- * accounting. The cursor comparison mirrors `countMessagesAfter`'s
- * tie-breaker semantics, including the null/`""` "count everything" cases
- * and the vanished-reference "no new work" case.
+ * accounting. The cursor resolves exactly as `countMessagesAfter`'s does,
+ * including the null/`""` "count everything" cases and the vanished-reference
+ * "no new work" case.
  */
 function countExcludedMessagesAfter(
   conversationId: string,
-  afterMessageId: string | null,
+  after: MessagesAfterRef,
 ): number {
-  // The `""` sentinel (failure-only state rows) counts everything, matching
-  // `countMessagesAfter`.
-  const cursorId =
-    afterMessageId === null || afterMessageId === "" ? null : afterMessageId;
   const db = getDb();
   const candidates = db
     .select({
@@ -282,18 +262,11 @@ function countExcludedMessagesAfter(
     return 0;
   }
 
-  let ref: { createdAt: number } | undefined;
-  if (cursorId !== null) {
-    ref = db
-      .select({ createdAt: messages.createdAt })
-      .from(messages)
-      .where(eq(messages.id, cursorId))
-      .get();
-    // Vanished reference: `countMessagesAfter` reported 0, so there is
-    // nothing to subtract from.
-    if (!ref) {
-      return 0;
-    }
+  const start = resolveMessagesAfterBound(after);
+  // Vanished reference: `countMessagesAfter` reported 0, so there is nothing
+  // to subtract from.
+  if (start.kind === "vanished") {
+    return 0;
   }
 
   let count = 0;
@@ -301,11 +274,12 @@ function countExcludedMessagesAfter(
     if (!isExcludedFromRetrospectiveAccounting(row)) {
       continue;
     }
-    if (cursorId !== null && ref) {
-      const after =
-        row.createdAt > ref.createdAt ||
-        (row.createdAt === ref.createdAt && row.id > cursorId);
-      if (!after) {
+    if (start.kind === "after") {
+      const { createdAt, id } = start.bound;
+      const isAfter =
+        row.createdAt > createdAt ||
+        (row.createdAt === createdAt && row.id > id);
+      if (!isAfter) {
         continue;
       }
     }

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),
   });

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

@@ -223,7 +223,7 @@ If your review window contains a PROCEDURE you actually carried out — a sequen
 
 When you do capture a procedure:
 
-1. Deduplicate against existing skills first. Call \`find_similar_skills\` with the procedure's goal as its \`goal\` argument. Each hit carries a \`source\` (bundled, managed, plugin, workspace, or extra), and a managed hit also carries \`author\` (\`"assistant"\` if you authored it, \`"user"\` if a person did, omitted if untagged). You may only overwrite or refine a skill YOU authored — a hit with \`source: "managed"\` AND \`author: "assistant"\`. ANY other hit means the procedure is ALREADY COVERED: a non-managed source (bundled, plugin, workspace, or extra), OR a managed skill that is NOT \`author: "assistant"\` (a person wrote it, or it is untagged). For an ALREADY COVERED hit do not \`overwrite\` it, do not shadow it by creating a skill with its \`skill_id\`, and do not create a near-duplicate — skip it. Only when a returned skill is one of your own (\`source: "managed"\`, \`author: "assistant"\`) and is the SAME procedure, UPDATE it: call \`scaffold_managed_skill\` with that \`skill_id\` and \`overwrite: true\`, rewriting \`body_markdown\` from what you actually observed in the trace. Only CREATE a new skill (fresh \`skill_id\`) when no existing skill of any source covers the procedure. Bias strongly toward reusing or refining your own skills over spawning near-duplicates.
+1. Deduplicate against existing skills first. Call \`find_similar_skills\` with the procedure's goal as its \`goal\` argument. Each hit carries a \`source\` (bundled, managed, plugin, workspace, or extra), and a managed hit also carries \`author\` (\`"assistant"\` if you authored it, \`"user"\` if a person did, omitted if untagged). You may only overwrite or refine a skill YOU authored: a hit with \`source: "managed"\` AND \`author: "assistant"\`. ANY other hit means the procedure is ALREADY COVERED: a non-managed source (bundled, plugin, workspace, or extra), OR a managed skill that is NOT \`author: "assistant"\` (a person wrote it, or it is untagged). For an ALREADY COVERED hit do not \`overwrite\` it, do not shadow it by creating a skill with its \`skill_id\`, and do not create a near-duplicate. Skip it. Only when a returned skill is one of your own (\`source: "managed"\`, \`author: "assistant"\`) and is the SAME procedure, UPDATE it: call \`scaffold_managed_skill\` with that \`skill_id\` and \`overwrite: true\`, rewriting \`body_markdown\` from what you actually observed in the trace, and pass \`change_summary\` (the update is rejected without it): one or two short sentences (under 200 characters) for the person who reads the "Skill updated" notice, naming what you changed and what in the trace prompted it (for example "Added the retry after an expired session and the export endpoint that held steady."). The notice shows nothing else about the change, so name the concrete step, value, or gotcha rather than saying the skill was refined. Only CREATE a new skill (fresh \`skill_id\`) when no existing skill of any source covers the procedure. Bias strongly toward reusing or refining your own skills over spawning near-duplicates.
 
 2. Capture procedure-scoped knowledge alongside the body. Failure modes, gotchas, and cached values you observed in the trace (error signatures and how you recovered, preconditions, IDs/paths/endpoints that held steady) belong in companion files passed via \`scaffold_managed_skill\`'s \`files\` input (for example \`references/failure-modes.md\`), and the SKILL.md body should reference them so a future load surfaces them.