@vellumai/assistant 0.5.13 → 0.5.14

package/src/memory/jobs-worker.ts

@@ -1,8 +1,9 @@
 import { getConfig } from "../config/loader.js";
 import type { AssistantConfig } from "../config/types.js";
 import { getLogger } from "../util/logger.js";
-import { rawRun } from "./db.js";
+import { rawAll, rawRun } from "./db.js";
 import { backfillJob } from "./job-handlers/backfill.js";
+import { batchExtractJob } from "./job-handlers/batch-extraction.js";
 import {
   cleanupStaleSupersededItemsJob,
   pruneOldConversationsJob,
@@ -21,8 +22,8 @@ import {
   deleteQdrantVectorsJob,
   rebuildIndexJob,
 } from "./job-handlers/index-maintenance.js";
+import { journalCarryForwardJob } from "./job-handlers/journal-carry-forward.js";
 import { mediaProcessingJob } from "./job-handlers/media-processing.js";
-import { buildConversationSummaryJob } from "./job-handlers/summarization.js";
 import {
   BackendUnavailableError,
   classifyError,
@@ -34,6 +35,7 @@ import {
   completeMemoryJob,
   deferMemoryJob,
   enqueueCleanupStaleSupersededItemsJob,
+  enqueueMemoryJob,
   enqueuePruneOldConversationsJob,
   failMemoryJob,
   failStalledJobs,
@@ -58,6 +60,31 @@ export function startMemoryJobsWorker(): MemoryJobsWorker {
     log.info({ recovered }, "Recovered stale running memory jobs");
   }
 
+  // Startup recovery: enqueue batch_extract for conversations with pending
+  // unextracted messages (e.g. after a crash mid-conversation).
+  try {
+    const pendingRows = rawAll<{ key: string; value: string }>(
+      `SELECT key, value FROM memory_checkpoints WHERE key LIKE 'batch_extract:%:pending_count' AND CAST(value AS INTEGER) > 0`,
+    );
+    for (const row of pendingRows) {
+      // Extract conversationId from key: "batch_extract:<conversationId>:pending_count"
+      const parts = row.key.split(":");
+      if (parts.length >= 3) {
+        const conversationId = parts.slice(1, -1).join(":");
+        enqueueMemoryJob("batch_extract", { conversationId });
+        log.info(
+          { conversationId, pendingCount: row.value },
+          "Recovered pending batch extraction on startup",
+        );
+      }
+    }
+  } catch (err) {
+    log.warn(
+      { err: err instanceof Error ? err.message : String(err) },
+      "Failed to recover pending batch extractions on startup",
+    );
+  }
+
   let stopped = false;
   let tickRunning = false;
   let timer: ReturnType<typeof setTimeout>;
@@ -137,20 +164,29 @@ export async function runMemoryJobsOnce(
     return 0;
   }
 
-  // Group jobs by type so same-type jobs run sequentially (preventing
-  // checkpoint races for backfill, etc.), while different types run concurrently.
-  const jobsByType = new Map<string, MemoryJob[]>();
+  // Group jobs so they can run concurrently across independent work units.
+  // Jobs targeting different conversations (via payload.conversationId) are
+  // placed in separate groups and can run in parallel. Jobs targeting the
+  // same conversation, or global jobs without a conversationId (backfill,
+  // cleanup, rebuild_index), are grouped together and run sequentially to
+  // prevent checkpoint races.
+  const jobGroups = new Map<string, MemoryJob[]>();
   for (const job of jobs) {
-    let group = jobsByType.get(job.type);
+    const convId =
+      typeof job.payload.conversationId === "string"
+        ? job.payload.conversationId
+        : null;
+    const groupKey = convId ? `${job.type}:${convId}` : job.type;
+    let group = jobGroups.get(groupKey);
     if (!group) {
       group = [];
-      jobsByType.set(job.type, group);
+      jobGroups.set(groupKey, group);
     }
     group.push(job);
   }
 
   let processed = 0;
-  const typeGroups = [...jobsByType.values()];
+  const typeGroups = [...jobGroups.values()];
 
   // Run type groups concurrently using a task pool (up to workerConcurrency
   // active at a time). Unlike the old wave approach, a new group starts as
@@ -294,6 +330,9 @@ async function processJob(
     case "extract_items":
       await extractItemsJob(job);
       return;
+    case "batch_extract":
+      await batchExtractJob(job);
+      return;
     case "extract_entities":
       // Entity extraction has been removed — silently drop legacy jobs
       return;
@@ -304,7 +343,12 @@ async function processJob(
       pruneOldConversationsJob(job, config);
       return;
     case "build_conversation_summary":
-      await buildConversationSummaryJob(job, config);
+      // Deprecated: conversation summaries are now produced as a side-effect
+      // of batch extraction. Silently skip legacy jobs.
+      log.debug(
+        { jobId: job.id },
+        "Skipping deprecated build_conversation_summary job — handled by batch extraction",
+      );
       return;
     case "backfill":
       await backfillJob(job, config);
@@ -331,6 +375,9 @@ async function processJob(
     case "embed_attachment":
       await embedAttachmentJob(job, config);
       return;
+    case "journal_carry_forward":
+      await journalCarryForwardJob(job);
+      return;
     case "generate_conversation_starters":
       await generateConversationStartersJob(job);
       return;

package/src/memory/lifecycle-events-store.ts

@@ -1,6 +1,7 @@
 import { and, asc, eq, gt, or } from "drizzle-orm";
 import { v4 as uuid } from "uuid";
 
+import { getConfig } from "../config/loader.js";
 import { getDb } from "./db.js";
 import { lifecycleEvents } from "./schema.js";
 
@@ -10,8 +11,9 @@ export interface LifecycleEvent {
   createdAt: number;
 }
 
-/** Record a lifecycle event (e.g. app_open, hatch). */
-export function recordLifecycleEvent(eventName: string): LifecycleEvent {
+/** Record a lifecycle event (e.g. app_open, hatch). Returns null when usage data collection is disabled. */
+export function recordLifecycleEvent(eventName: string): LifecycleEvent | null {
+  if (!getConfig().collectUsageData) return null;
   const db = getDb();
   const event: LifecycleEvent = {
     id: uuid(),

package/src/memory/llm-request-log-store.ts

@@ -26,11 +26,12 @@ export function recordRequestLog(
   responsePayload: string,
   messageId?: string,
   provider?: string,
-): void {
+): string {
   const db = getDb();
+  const id = uuid();
   db.insert(llmRequestLogs)
     .values({
-      id: uuid(),
+      id,
       conversationId,
       messageId: messageId ?? null,
       provider: provider ?? null,
@@ -39,6 +40,7 @@ export function recordRequestLog(
       createdAt: Date.now(),
     })
     .run();
+  return id;
 }
 
 export function queryRequestLogs(
@@ -83,6 +85,42 @@ export function backfillMessageIdOnLogs(
     .run();
 }
 
+/**
+ * Set `messageId` on specific log rows identified by their IDs.
+ * Unlike `backfillMessageIdOnLogs` (which updates all null-messageId rows
+ * for a conversation), this targets only the given log rows — safe for
+ * concurrent watch/assistant turns.
+ */
+export function setMessageIdOnLogs(
+  logIds: string[],
+  messageId: string,
+): void {
+  if (logIds.length === 0) return;
+  const db = getDb();
+  db.update(llmRequestLogs)
+    .set({ messageId })
+    .where(inArray(llmRequestLogs.id, logIds))
+    .run();
+}
+
+/**
+ * Re-link LLM request logs from a set of source message IDs to a target
+ * message. Used during message consolidation so logs from deleted
+ * intermediate messages survive and remain queryable via the consolidated
+ * message.
+ */
+export function relinkLlmRequestLogs(
+  fromMessageIds: string[],
+  toMessageId: string,
+): void {
+  if (fromMessageIds.length === 0) return;
+  const db = getDb();
+  db.update(llmRequestLogs)
+    .set({ messageId: toMessageId })
+    .where(inArray(llmRequestLogs.messageId, fromMessageIds))
+    .run();
+}
+
 /**
  * Internal helper: query `llm_request_logs` for rows matching any of the
  * given message IDs, ordered by `createdAt ASC`. Uses the existing

package/src/memory/llm-usage-store.ts

@@ -42,6 +42,7 @@ export function recordUsageEvent(
       cacheReadInputTokens: event.cacheReadInputTokens,
       estimatedCostUsd: event.estimatedCostUsd,
       pricingStatus: event.pricingStatus,
+      llmCallCount: event.llmCallCount ?? 1,
       metadataJson: null,
     })
     .run();
@@ -213,7 +214,7 @@ export function getUsageTotals(range: UsageTimeRange): UsageTotals {
       COALESCE(SUM(cache_creation_input_tokens), 0)               AS total_cache_creation_tokens,
       COALESCE(SUM(cache_read_input_tokens), 0)                   AS total_cache_read_tokens,
       COALESCE(SUM(estimated_cost_usd), 0)                        AS total_estimated_cost_usd,
-      COUNT(*)                                                     AS event_count,
+      COALESCE(SUM(COALESCE(llm_call_count, 1)), 0)               AS event_count,
       COUNT(CASE WHEN pricing_status = 'priced' THEN 1 END)       AS priced_event_count,
       COUNT(CASE WHEN pricing_status = 'unpriced' THEN 1 END)     AS unpriced_event_count
     FROM llm_usage_events
@@ -249,7 +250,7 @@ export function getUsageDayBuckets(range: UsageTimeRange): UsageDayBucket[] {
       COALESCE(SUM(input_tokens), 0)                         AS total_input_tokens,
       COALESCE(SUM(output_tokens), 0)                        AS total_output_tokens,
       COALESCE(SUM(estimated_cost_usd), 0)                   AS total_estimated_cost_usd,
-      COUNT(*)                                                AS event_count
+      COALESCE(SUM(COALESCE(llm_call_count, 1)), 0)          AS event_count
     FROM llm_usage_events
     WHERE created_at >= ?1 AND created_at <= ?2
     GROUP BY date
@@ -292,7 +293,7 @@ export function getUsageGroupBreakdown(
       COALESCE(SUM(cache_creation_input_tokens), 0)  AS total_cache_creation_tokens,
       COALESCE(SUM(cache_read_input_tokens), 0)      AS total_cache_read_tokens,
       COALESCE(SUM(estimated_cost_usd), 0)           AS total_estimated_cost_usd,
-      COUNT(*)                                        AS event_count
+      COALESCE(SUM(COALESCE(llm_call_count, 1)), 0)  AS event_count
     FROM llm_usage_events
     WHERE created_at >= ?1 AND created_at <= ?2
     GROUP BY ${column}

package/src/memory/migrations/199-guardian-request-enrichment-columns.ts

@@ -0,0 +1,71 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { getSqliteFrom } from "../db-connection.js";
+import { tableHasColumn } from "./schema-introspection.js";
+import { withCrashRecovery } from "./validate-migration-state.js";
+
+/**
+ * Add enrichment columns to canonical_guardian_requests for guardian
+ * approval UX:
+ *
+ * - command_preview: truncated command/input preview
+ * - risk_level: "low", "medium", "high"
+ * - activity_text: LLM's explanation of why it's calling the tool
+ * - execution_target: "sandbox" or "host"
+ *
+ * All columns are nullable TEXT — existing rows default to NULL.
+ */
+export function migrateGuardianRequestEnrichmentColumns(
+  database: DrizzleDb,
+): void {
+  withCrashRecovery(
+    database,
+    "migration_guardian_request_enrichment_columns_v1",
+    () => {
+      const raw = getSqliteFrom(database);
+
+      if (
+        !tableHasColumn(
+          database,
+          "canonical_guardian_requests",
+          "command_preview",
+        )
+      ) {
+        raw.exec(
+          /*sql*/ `ALTER TABLE canonical_guardian_requests ADD COLUMN command_preview TEXT`,
+        );
+      }
+
+      if (
+        !tableHasColumn(database, "canonical_guardian_requests", "risk_level")
+      ) {
+        raw.exec(
+          /*sql*/ `ALTER TABLE canonical_guardian_requests ADD COLUMN risk_level TEXT`,
+        );
+      }
+
+      if (
+        !tableHasColumn(
+          database,
+          "canonical_guardian_requests",
+          "activity_text",
+        )
+      ) {
+        raw.exec(
+          /*sql*/ `ALTER TABLE canonical_guardian_requests ADD COLUMN activity_text TEXT`,
+        );
+      }
+
+      if (
+        !tableHasColumn(
+          database,
+          "canonical_guardian_requests",
+          "execution_target",
+        )
+      ) {
+        raw.exec(
+          /*sql*/ `ALTER TABLE canonical_guardian_requests ADD COLUMN execution_target TEXT`,
+        );
+      }
+    },
+  );
+}

package/src/memory/migrations/200-usage-llm-call-count.ts

@@ -0,0 +1,20 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { getSqliteFrom } from "../db-connection.js";
+import { tableHasColumn } from "./schema-introspection.js";
+
+/**
+ * Add llm_call_count column to llm_usage_events so each row records
+ * how many actual LLM API calls it represents (an exchange/turn may
+ * contain multiple tool-use iterations, each making a separate API call).
+ *
+ * Nullable INTEGER — existing rows default to NULL and are treated as 1
+ * by the aggregation queries via COALESCE.
+ */
+export function migrateUsageLlmCallCount(database: DrizzleDb): void {
+  const raw = getSqliteFrom(database);
+  if (!tableHasColumn(database, "llm_usage_events", "llm_call_count")) {
+    raw.exec(
+      /*sql*/ `ALTER TABLE llm_usage_events ADD COLUMN llm_call_count INTEGER`,
+    );
+  }
+}

package/src/memory/migrations/index.ts

@@ -138,6 +138,8 @@ export { migrateMessagesConversationCreatedAtIndex } from "./196-messages-conver
 export { migrateStripIntegrationPrefixFromProviderKeys } from "./196-strip-integration-prefix-from-provider-keys.js";
 export { migrateOAuthProvidersBehaviorColumns } from "./197-oauth-providers-behavior-columns.js";
 export { migrateDropSetupSkillIdColumn } from "./198-drop-setup-skill-id-column.js";
+export { migrateGuardianRequestEnrichmentColumns } from "./199-guardian-request-enrichment-columns.js";
+export { migrateUsageLlmCallCount } from "./200-usage-llm-call-count.js";
 export {
   MIGRATION_REGISTRY,
   type MigrationRegistryEntry,

package/src/memory/query-expansion.ts

@@ -0,0 +1,83 @@
+/**
+ * HyDE (Hypothetical Document Embeddings) query expansion for memory retrieval.
+ *
+ * Generates hypothetical memory documents that bridge the semantic gap between
+ * how users query ("moments that changed everything") and how memories are
+ * actually stored ("Sidd gave Velissa a collar on March 24"). The expanded
+ * queries are embedded alongside the original query to improve recall.
+ */
+
+import type { AssistantConfig } from "../config/types.js";
+import {
+  extractText,
+  getConfiguredProvider,
+  userMessage,
+} from "../providers/provider-send-message.js";
+import { getLogger } from "../util/logger.js";
+
+const log = getLogger("memory-query-expansion");
+
+const SYSTEM_PROMPT = `Generate 3 short hypothetical memory entries that would match this search query. Each should describe what a stored memory about this topic would contain — specific details, emotional context, relationship dynamics. Write from the perspective of stored memory items, not the query itself. Keep each under 80 words. Separate entries with ---`;
+
+/**
+ * Generate hypothetical memory documents for a query using HyDE.
+ *
+ * Returns 1-3 hypothetical document strings that can be embedded alongside
+ * the original query to improve semantic recall. Returns `[]` on any error
+ * (provider unavailable, LLM failure, empty response) — the caller should
+ * fall back to the raw query only.
+ *
+ * The raw query is NOT included in the returned array; the caller handles
+ * that separately.
+ */
+export async function expandQueryWithHyDE(
+  query: string,
+  _config: AssistantConfig,
+  signal?: AbortSignal,
+): Promise<string[]> {
+  try {
+    const provider = await getConfiguredProvider();
+    if (!provider) {
+      log.warn("No provider available for HyDE query expansion");
+      return [];
+    }
+
+    const response = await provider.sendMessage(
+      [userMessage(query)],
+      undefined,
+      SYSTEM_PROMPT,
+      {
+        config: {
+          modelIntent: "latency-optimized" as const,
+        },
+        signal,
+      },
+    );
+
+    const text = extractText(response);
+    if (!text) {
+      log.warn("Empty response from HyDE query expansion");
+      return [];
+    }
+
+    const entries = text
+      .split("---")
+      .map((entry) => entry.trim())
+      .filter((entry) => entry.length > 0)
+      .slice(0, 3);
+
+    if (entries.length === 0) {
+      log.warn("No entries parsed from HyDE query expansion response");
+      return [];
+    }
+
+    return entries;
+  } catch (err) {
+    if (err instanceof DOMException && err.name === "AbortError") throw err;
+    log.warn(
+      { err: err instanceof Error ? err.message : String(err) },
+      "HyDE query expansion failed",
+    );
+    return [];
+  }
+}

package/src/memory/retriever.test.ts

@@ -1468,4 +1468,123 @@ describe("Memory Retriever Pipeline", () => {
       expect(result.mergedCount).toBe(0);
     });
   });
+
+  // -----------------------------------------------------------------------
+  // Serendipity layer
+  // -----------------------------------------------------------------------
+
+  describe("serendipity sampling", () => {
+    test("samples random active items and renders them in <echoes>", async () => {
+      const db = getDb();
+      const now = Date.now();
+      const convId = "conv-serendipity";
+
+      insertConversation(db, convId, now - 60_000);
+      insertMessage(db, "msg-s-1", convId, "user", "hello", now - 50_000);
+
+      // Items sourced from a different conversation so in-context filtering
+      // doesn't remove them (serendipity is cross-conversation recall).
+      const otherConvId = "conv-serendipity-other";
+      insertConversation(db, otherConvId, now - 120_000);
+      insertMessage(db, "msg-s-other", otherConvId, "user", "other", now - 110_000);
+
+      // Insert several active items that are NOT returned by Qdrant
+      for (let i = 1; i <= 5; i++) {
+        insertItem(db, {
+          id: `serendipity-item-${i}`,
+          kind: "fact",
+          subject: `topic ${i}`,
+          statement: `Serendipity fact number ${i}`,
+          importance: i * 0.15, // 0.15..0.75
+          firstSeenAt: now - i * 10_000,
+        });
+        insertItemSource(db, `serendipity-item-${i}`, "msg-s-other", now - i * 10_000);
+      }
+
+      // Qdrant returns nothing — no recalled candidates
+      mockQdrantResults.length = 0;
+
+      const result = await buildMemoryRecall(
+        "unrelated query",
+        convId,
+        TEST_CONFIG,
+      );
+
+      expect(result.enabled).toBe(true);
+      // No semantic hits, so no recalled candidates
+      expect(result.mergedCount).toBe(0);
+      // But serendipity items should appear in the injection
+      expect(result.injectedText).toContain("<echoes>");
+      expect(result.injectedText).toContain("</echoes>");
+      // At most 3 serendipity items
+      const itemMatches = result.injectedText.match(/<item /g);
+      expect(itemMatches).toBeTruthy();
+      expect(itemMatches!.length).toBeLessThanOrEqual(3);
+      expect(itemMatches!.length).toBeGreaterThanOrEqual(1);
+      // selectedCount includes serendipity items
+      expect(result.selectedCount).toBeGreaterThan(0);
+    });
+
+    test("excludes items already in the candidate pool from serendipity", async () => {
+      const db = getDb();
+      const now = Date.now();
+      const convId = "conv-serendipity-excl";
+
+      insertConversation(db, convId, now - 60_000);
+      insertMessage(db, "msg-se-1", convId, "user", "query about X", now - 50_000);
+
+      // This item will be returned by Qdrant as a recalled candidate
+      insertItem(db, {
+        id: "recalled-item",
+        kind: "fact",
+        subject: "X",
+        statement: "Recalled fact about X",
+        importance: 0.9,
+        firstSeenAt: now - 30_000,
+      });
+      insertItemSource(db, "recalled-item", "msg-se-1", now - 30_000);
+
+      // Qdrant returns the recalled item
+      mockQdrantResults.push({
+        id: "qdrant-recalled",
+        score: 0.9,
+        payload: {
+          target_type: "item",
+          target_id: "recalled-item",
+          text: "X: Recalled fact about X",
+          created_at: now - 30_000,
+        },
+      });
+
+      const result = await buildMemoryRecall(
+        "query about X",
+        convId,
+        TEST_CONFIG,
+      );
+
+      expect(result.enabled).toBe(true);
+      // The recalled item is in <recalled>, not in <echoes>
+      if (result.injectedText.includes("<echoes>")) {
+        // If echoes exists, the recalled item should NOT be duplicated there
+        const echoesMatch = result.injectedText.match(
+          /<echoes>([\s\S]*?)<\/echoes>/,
+        );
+        if (echoesMatch) {
+          expect(echoesMatch[1]).not.toContain("recalled-item");
+        }
+      }
+    });
+
+    test("no <echoes> section when no active items exist", async () => {
+      // No items seeded at all
+      const result = await buildMemoryRecall(
+        "anything",
+        "conv-empty-seren",
+        TEST_CONFIG,
+      );
+
+      expect(result.enabled).toBe(true);
+      expect(result.injectedText).not.toContain("<echoes>");
+    });
+  });
 });