@vellumai/assistant 0.6.3 → 0.6.5

package/src/memory/job-handlers/conversation-starters.ts

@@ -60,7 +60,7 @@ export function buildMemoryRollup(scopeId: string): string {
         and(
           sql`${memoryGraphNodes.fidelity} != 'gone'`,
           eq(memoryGraphNodes.scopeId, scopeId),
-        )
+        ),
       )
       .orderBy(desc(memoryGraphNodes.significance))
       .limit(60)
@@ -111,19 +111,21 @@ function buildNewItemsDiff(scopeId: string): string {
      WHERE fidelity != 'gone' AND scope_id = ? AND created > ?
      ORDER BY created DESC LIMIT 20`,
     scopeId,
-    lastGenAt
+    lastGenAt,
   );
 
   if (newItems.length === 0) return "";
 
   return (
     "## New since last generation\n" +
-    newItems.map((i) => {
-      const nl = i.content.indexOf("\n");
-      const subject = nl >= 0 ? i.content.slice(0, nl) : i.content;
-      const statement = nl >= 0 ? i.content.slice(nl + 1) : i.content;
-      return `- (${i.kind}) ${subject}: ${statement}`;
-    }).join("\n")
+    newItems
+      .map((i) => {
+        const nl = i.content.indexOf("\n");
+        const subject = nl >= 0 ? i.content.slice(0, nl) : i.content;
+        const statement = nl >= 0 ? i.content.slice(nl + 1) : i.content;
+        return `- (${i.kind}) ${subject}: ${statement}`;
+      })
+      .join("\n")
   );
 }
 
@@ -162,7 +164,8 @@ export const CONVERSATION_STARTER_CATEGORIES = [
   "integration",
 ] as const;
 
-export type ConversationStarterCategory = typeof CONVERSATION_STARTER_CATEGORIES[number];
+export type ConversationStarterCategory =
+  (typeof CONVERSATION_STARTER_CATEGORIES)[number];
 
 interface GeneratedStarter {
   label: string;
@@ -171,7 +174,7 @@ interface GeneratedStarter {
 }
 
 async function generateStarters(scopeId: string): Promise<GeneratedStarter[]> {
-  const provider = await getConfiguredProvider();
+  const provider = await getConfiguredProvider("conversationStarters");
   if (!provider) {
     log.info("No configured provider for conversation starters generation");
     return [];
@@ -197,7 +200,7 @@ async function generateStarters(scopeId: string): Promise<GeneratedStarter[]> {
   })}`;
 
   // Truncate identity context to prevent oversized prompts when SOUL.md /
-  // IDENTITY.md / USER.md are large.
+  // IDENTITY.md / users/<slug>.md are large.
   const rawIdentityContext = buildCoreIdentityContext({
     userPersona: resolveGuardianPersona(),
   });
@@ -205,11 +208,11 @@ async function generateStarters(scopeId: string): Promise<GeneratedStarter[]> {
     ? truncate(rawIdentityContext, 2000, "\n…[truncated]")
     : null;
 
-  const systemPrompt = `You are generating 4 conversation starters for a personal assistant app. These appear as clickable chips on the empty conversation page — the first thing the user sees when they open the app. Clicking a chip sends its prompt as a message from the user.
+  const systemPrompt = `You are generating conversation starters for a personal assistant app. These appear as clickable chips on the empty conversation page — the first thing the user sees when they open the app. Clicking a chip sends its prompt as a message from the user.
 
 ${timeContext}
 
-Your goal: suggest the 4 most useful things this person could ask you to do right now.
+Your goal: suggest the most useful things this person could ask you to do right now. Produce 8 candidates, ranked best-first; only the top 4 will be shown.
 
 ${
   identityContext
@@ -223,7 +226,7 @@ ${skills}
 
 ## Selection
 
-Generate exactly 4 starters, ranked #1 (best) to #4.
+Generate exactly 8 starters, ranked #1 (best) to #8. The top 4 will be shown; the rest are fallbacks in case any fail downstream validation (e.g. label too long). Put real effort into every slot — any of them may end up displayed.
 
 Start from the user's situation, not from the skill list. Ask yourself:
 - What is this person likely dealing with right now (given the day/time and their context)?
@@ -250,7 +253,7 @@ Favor what is live over what is merely true. Recent changes matter more than old
 ## Output format
 
 Each starter has:
-- label: 3-6 words, max 40 chars, starts with a verb. Written in the user's voice — something they'd want to do, not something the assistant is offering.
+- label: 3-6 words, max 40 chars, starts with a verb. Written in the user's voice — something they'd want to do, not something the assistant is offering. MUST be a grammatically complete phrase: if it uses an adjective ("quarterly", "weekly"), include the noun it modifies ("quarterly review", "weekly sync"). Never end on a dangling modifier, preposition, or trailing "the/my/a". Prefer completeness over tightness when you have room under 40 chars.
 - prompt: 1-2 natural sentences, as the user would actually say them.
 - category: one of ${CONVERSATION_STARTER_CATEGORIES.join(", ")}
 
@@ -258,9 +261,9 @@ Each starter has:
 
 **Voice**: The user clicks these chips to send a message. Every label must read as something the user is asking to do, never something the assistant is saying to the user.
 
-**Coherence**: The 4 starters should feel like one set — similar abstraction level, no jarring mix of mundane chores and life strategy.
+**Coherence**: The top 4 starters should feel like one set — similar abstraction level, no jarring mix of mundane chores and life strategy. The remaining 4 fallbacks may branch into adjacent topics.
 
-**Diversity**: Each chip covers a distinct topic. Never two chips about the same tool, project, or theme. Four topics, four chips.
+**Diversity**: Each chip covers a distinct topic. Never two chips about the same tool, project, or theme. Across all 8 starters, avoid repeating topics.
 
 **No setup chips**: Never include a chip whose primary meaning is configuration or "set up X for Y" unless it solves an urgent pain the user is actively feeling. Prefer the outcome over the mechanism.
 
@@ -276,14 +279,19 @@ Bad → Good (ticket-speak → natural):
 
 Bad → Good (assistant voice → user voice):
 - "You've got a busy week ahead" → "Plan my week ahead"
-- "Let me check your calendar" → "Check my Thursday schedule"`;
+- "Let me check your calendar" → "Check my Thursday schedule"
+
+Bad → Good (incomplete phrase → complete):
+- "Prep for Friday's quarterly" → "Prep for Friday's quarterly review"
+- "Finish the onboarding" → "Finish the onboarding guide"
+- "Draft the release" → "Draft the release notes"`;
 
   const { signal, cleanup } = createTimeout(20000);
   try {
     const response = await provider.sendMessage(
       [
         userMessage(
-          "Generate personalized conversation starters based on my context."
+          "Generate personalized conversation starters based on my context.",
         ),
       ],
       [
@@ -325,22 +333,22 @@ Bad → Good (assistant voice → user voice):
       systemPrompt,
       {
         config: {
-          modelIntent: "quality-optimized",
-          max_tokens: 1024,
+          callSite: "conversationStarters" as const,
+          max_tokens: 2048,
           tool_choice: {
             type: "tool" as const,
             name: "store_conversation_starters",
           },
         },
         signal,
-      }
+      },
     );
     cleanup();
 
     const toolBlock = extractToolUse(response);
     if (!toolBlock) {
       log.warn(
-        "No tool_use block in conversation starters generation response"
+        "No tool_use block in conversation starters generation response",
       );
       return [];
     }
@@ -356,17 +364,18 @@ Bad → Good (assistant voice → user voice):
         (s) =>
           typeof s.label === "string" &&
           s.label.length > 0 &&
+          s.label.length <= 40 &&
           typeof s.prompt === "string" &&
-          s.prompt.length > 0
+          s.prompt.length > 0,
       )
       .slice(0, 4)
       .map((s) => ({
-        label: truncate(s.label, 40, ""),
+        label: s.label,
         prompt: truncate(s.prompt, 500, ""),
         category:
           typeof s.category === "string" &&
           (CONVERSATION_STARTER_CATEGORIES as readonly string[]).includes(
-            s.category
+            s.category,
           )
             ? s.category
             : "productivity",
@@ -380,7 +389,7 @@ Bad → Good (assistant voice → user voice):
 // ── Job handler ───────────────────────────────────────────────────
 
 export async function generateConversationStartersJob(
-  job: MemoryJob
+  job: MemoryJob,
 ): Promise<void> {
   const scopeId = asString(job.payload.scopeId) ?? "default";
 
@@ -413,7 +422,7 @@ export async function generateConversationStartersJob(
         and(
           sql`${memoryGraphNodes.fidelity} != 'gone'`,
           eq(memoryGraphNodes.scopeId, scopeId),
-        )
+        ),
       )
       .groupBy(memoryGraphNodes.type)
       .all();
@@ -447,7 +456,7 @@ export async function generateConversationStartersJob(
   // Count active items for checkpoint
   const countRow = rawGet<{ c: number }>(
     `SELECT COUNT(*) AS c FROM memory_graph_nodes WHERE fidelity != 'gone' AND scope_id = ?`,
-    scopeId
+    scopeId,
   );
   const totalActive = countRow?.c ?? 0;
 
@@ -468,6 +477,6 @@ export async function generateConversationStartersJob(
 
   log.info(
     { scopeId, batch: nextBatch, count: starters.length },
-    "Generated conversation starters"
+    "Generated conversation starters",
   );
 }

package/src/memory/job-handlers/summarization.ts

@@ -161,7 +161,7 @@ async function summarizeWithLLM(
     return buildFallbackSummary(existingSummary, newContent, label);
   }
 
-  const provider = await getConfiguredProvider();
+  const provider = await getConfiguredProvider("conversationSummarization");
   if (!provider) {
     log.debug(
       { label },
@@ -189,7 +189,7 @@ async function summarizeWithLLM(
         systemPrompt,
         {
           config: {
-            modelIntent: summarizationConfig.modelIntent,
+            callSite: "conversationSummarization" as const,
             max_tokens: SUMMARY_MAX_TOKENS,
           },
           signal,

package/src/memory/job-utils.ts

@@ -147,7 +147,13 @@ export function truncate(text: string, max: number): string {
 
 export async function embedAndUpsert(
   config: AssistantConfig,
-  targetType: "segment" | "item" | "summary" | "media" | "graph_node",
+  targetType:
+    | "segment"
+    | "item"
+    | "summary"
+    | "media"
+    | "graph_node"
+    | "pkb_file",
   targetId: string,
   input: EmbeddingInput,
   extraPayload?: Record<string, unknown>,

package/src/memory/jobs/embed-pkb-file.test.ts

@@ -0,0 +1,168 @@
+import { beforeAll, beforeEach, describe, expect, mock, test } from "bun:test";
+
+mock.module("../../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+}));
+
+// Track calls to indexPkbFile so we can assert the handler forwards payload
+// fields correctly.
+const indexPkbFileCalls: Array<{
+  pkbRoot: string;
+  absPath: string;
+  memoryScopeId: string;
+}> = [];
+
+mock.module("../pkb/pkb-index.js", () => ({
+  indexPkbFile: async (
+    pkbRoot: string,
+    absPath: string,
+    memoryScopeId: string,
+  ) => {
+    indexPkbFileCalls.push({ pkbRoot, absPath, memoryScopeId });
+  },
+}));
+
+mock.module("../../config/loader.js", () => ({
+  loadConfig: () => ({}),
+  getConfig: () => ({}),
+  invalidateConfigCache: () => {},
+}));
+
+import { DEFAULT_CONFIG } from "../../config/defaults.js";
+import type { AssistantConfig } from "../../config/types.js";
+import { getDb, initializeDb } from "../db.js";
+import {
+  claimMemoryJobs,
+  type MemoryJob,
+  type MemoryJobType,
+} from "../jobs-store.js";
+import { memoryJobs } from "../schema.js";
+import { embedPkbFileJob, enqueuePkbIndexJob } from "./embed-pkb-file.js";
+
+const TEST_CONFIG: AssistantConfig = DEFAULT_CONFIG;
+
+function makeJob(payload: Record<string, unknown>): MemoryJob {
+  return {
+    id: "job-1",
+    type: "embed_pkb_file",
+    payload,
+    status: "running",
+    attempts: 0,
+    deferrals: 0,
+    runAfter: 0,
+    lastError: null,
+    startedAt: Date.now(),
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+  };
+}
+
+describe("embedPkbFileJob", () => {
+  beforeAll(() => {
+    initializeDb();
+  });
+
+  beforeEach(() => {
+    indexPkbFileCalls.length = 0;
+    const db = getDb();
+    db.delete(memoryJobs).run();
+  });
+
+  test("calls indexPkbFile with payload fields", async () => {
+    await embedPkbFileJob(
+      makeJob({
+        pkbRoot: "/pkb/root",
+        absPath: "/pkb/root/note.md",
+        memoryScopeId: "scope-123",
+      }),
+      TEST_CONFIG,
+    );
+
+    expect(indexPkbFileCalls).toHaveLength(1);
+    expect(indexPkbFileCalls[0]).toEqual({
+      pkbRoot: "/pkb/root",
+      absPath: "/pkb/root/note.md",
+      memoryScopeId: "scope-123",
+    });
+  });
+
+  test("skips when pkbRoot is missing", async () => {
+    await embedPkbFileJob(
+      makeJob({ absPath: "/pkb/root/note.md", memoryScopeId: "scope-123" }),
+      TEST_CONFIG,
+    );
+    expect(indexPkbFileCalls).toHaveLength(0);
+  });
+
+  test("skips when absPath is missing", async () => {
+    await embedPkbFileJob(
+      makeJob({ pkbRoot: "/pkb/root", memoryScopeId: "scope-123" }),
+      TEST_CONFIG,
+    );
+    expect(indexPkbFileCalls).toHaveLength(0);
+  });
+
+  test("skips when memoryScopeId is missing", async () => {
+    await embedPkbFileJob(
+      makeJob({ pkbRoot: "/pkb/root", absPath: "/pkb/root/note.md" }),
+      TEST_CONFIG,
+    );
+    expect(indexPkbFileCalls).toHaveLength(0);
+  });
+});
+
+describe("enqueuePkbIndexJob", () => {
+  beforeAll(() => {
+    initializeDb();
+  });
+
+  beforeEach(() => {
+    indexPkbFileCalls.length = 0;
+    const db = getDb();
+    db.delete(memoryJobs).run();
+  });
+
+  test("enqueues a pending embed_pkb_file job with payload", () => {
+    const id = enqueuePkbIndexJob({
+      pkbRoot: "/pkb/root",
+      absPath: "/pkb/root/note.md",
+      memoryScopeId: "scope-abc",
+    });
+    expect(id).toBeTruthy();
+
+    const claimed = claimMemoryJobs(10);
+    expect(claimed).toHaveLength(1);
+    const [job] = claimed;
+    const expectedType: MemoryJobType = "embed_pkb_file";
+    expect(job.type).toBe(expectedType);
+    expect(job.payload).toEqual({
+      pkbRoot: "/pkb/root",
+      absPath: "/pkb/root/note.md",
+      memoryScopeId: "scope-abc",
+    });
+  });
+
+  test("round-trip: enqueued job dispatched to handler invokes indexPkbFile", async () => {
+    enqueuePkbIndexJob({
+      pkbRoot: "/pkb/root",
+      absPath: "/pkb/root/note.md",
+      memoryScopeId: "scope-rt",
+    });
+
+    const claimed = claimMemoryJobs(10);
+    expect(claimed).toHaveLength(1);
+    const [job] = claimed;
+    expect(job.type).toBe("embed_pkb_file");
+
+    await embedPkbFileJob(job, TEST_CONFIG);
+    expect(indexPkbFileCalls).toHaveLength(1);
+    expect(indexPkbFileCalls[0]).toEqual({
+      pkbRoot: "/pkb/root",
+      absPath: "/pkb/root/note.md",
+      memoryScopeId: "scope-rt",
+    });
+  });
+});

package/src/memory/jobs/embed-pkb-file.ts

@@ -0,0 +1,54 @@
+import type { AssistantConfig } from "../../config/types.js";
+import { asString } from "../job-utils.js";
+import { enqueueMemoryJob, type MemoryJob } from "../jobs-store.js";
+import { indexPkbFile } from "../pkb/pkb-index.js";
+
+/**
+ * Input shape for the `embed_pkb_file` background job.
+ */
+export interface EmbedPkbFileJobInput {
+  pkbRoot: string;
+  absPath: string;
+  memoryScopeId: string;
+}
+
+/**
+ * Job handler: read a PKB markdown file, chunk it, and upsert each chunk to
+ * Qdrant via the shared embedding pipeline. Thin wrapper around
+ * {@link indexPkbFile} so write hooks and startup reconciliation can
+ * fire-and-forget into the async job queue.
+ */
+export async function embedPkbFileJob(
+  job: MemoryJob,
+  _config: AssistantConfig,
+): Promise<void> {
+  const pkbRoot = asString(job.payload.pkbRoot);
+  const absPath = asString(job.payload.absPath);
+  const memoryScopeId = asString(job.payload.memoryScopeId);
+  if (!pkbRoot || !absPath || !memoryScopeId) return;
+
+  try {
+    await indexPkbFile(pkbRoot, absPath, memoryScopeId);
+  } catch (error) {
+    if (
+      error !== null &&
+      typeof error === "object" &&
+      "code" in error &&
+      (error as { code?: unknown }).code === "ENOENT"
+    ) {
+      return;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Enqueue an `embed_pkb_file` job (async, fire-and-forget).
+ */
+export function enqueuePkbIndexJob(input: EmbedPkbFileJobInput): string {
+  return enqueueMemoryJob("embed_pkb_file", {
+    pkbRoot: input.pkbRoot,
+    absPath: input.absPath,
+    memoryScopeId: input.memoryScopeId,
+  });
+}

package/src/memory/jobs-store.ts

@@ -1,4 +1,4 @@
-import { and, asc, eq, inArray, lte, notInArray, sql } from "drizzle-orm";
+import { and, asc, eq, inArray, lte, notInArray, or, sql } from "drizzle-orm";
 import { v4 as uuid } from "uuid";
 
 import { getLogger } from "../util/logger.js";
@@ -18,6 +18,7 @@ export type MemoryJobType =
   | "prune_old_conversations"
   | "prune_old_llm_request_logs"
   | "build_conversation_summary"
+  | "conversation_analyze"
   | "backfill"
   | "rebuild_index"
   | "delete_qdrant_vectors"
@@ -26,6 +27,7 @@ export type MemoryJobType =
   | "embed_attachment"
   | "generate_conversation_starters"
   | "embed_graph_node"
+  | "embed_pkb_file"
   | "graph_extract"
   | "graph_decay"
   | "graph_consolidate"
@@ -40,6 +42,7 @@ const EMBED_JOB_TYPES: MemoryJobType[] = [
   "embed_media",
   "embed_attachment",
   "embed_graph_node",
+  "embed_pkb_file",
   "graph_trigger_embed",
 ];
 
@@ -89,15 +92,19 @@ export function enqueueMemoryJob(
 
 /**
  * Upsert a debounced job: if a pending job of the same type and conversation
- * already exists, push its `runAfter` forward instead of creating a duplicate.
- * This prevents rapid message indexing from spawning redundant jobs.
+ * already exists, merge the new payload into the existing row and update
+ * `runAfter` instead of creating a duplicate. This prevents rapid message
+ * indexing from spawning redundant jobs while ensuring the latest payload
+ * keys (e.g. `scopeId`) reach the handler — including on upgraded instances
+ * where the existing pending row was enqueued by an older build that did
+ * not write those keys.
  *
  * Pass a `dbOverride` (transaction handle) to make this call atomic with
  * surrounding writes.
  */
 export function upsertDebouncedJob(
   type: MemoryJobType,
-  payload: { conversationId: string },
+  payload: { conversationId: string } & Record<string, unknown>,
   runAfter: number,
   dbOverride?: Parameters<ReturnType<typeof getDb>["transaction"]>[0] extends (
     tx: infer T,
@@ -118,8 +125,19 @@ export function upsertDebouncedJob(
     )
     .get();
   if (existing) {
+    let existingPayload: Record<string, unknown> = {};
+    try {
+      existingPayload = JSON.parse(existing.payload) as Record<string, unknown>;
+    } catch {
+      existingPayload = {};
+    }
+    const mergedPayload = { ...existingPayload, ...payload };
     db.update(memoryJobs)
-      .set({ runAfter, updatedAt: Date.now() })
+      .set({
+        payload: JSON.stringify(mergedPayload),
+        runAfter,
+        updatedAt: Date.now(),
+      })
       .where(eq(memoryJobs.id, existing.id))
       .run();
   } else {
@@ -127,6 +145,89 @@ export function upsertDebouncedJob(
   }
 }
 
+/**
+ * Upsert a pending `conversation_analyze` job keyed by both
+ * `conversationId` and `triggerGroup`. Immediate triggers (batch,
+ * compaction) and debounced triggers (idle, lifecycle) live in separate
+ * rows so an idle enqueue cannot push an already-scheduled immediate
+ * row's `runAfter` into the future (and vice versa). Each group still
+ * coalesces within itself: two batch crossings, or two idle triggers,
+ * collapse to a single pending row.
+ */
+export function upsertAutoAnalysisJob(
+  payload: {
+    conversationId: string;
+    triggerGroup: "immediate" | "debounced";
+  },
+  runAfter: number,
+  dbOverride?: Parameters<ReturnType<typeof getDb>["transaction"]>[0] extends (
+    tx: infer T,
+  ) => unknown
+    ? T
+    : never,
+): void {
+  const db = dbOverride ?? getDb();
+  // Match rows with the same triggerGroup OR legacy rows without triggerGroup
+  // (from older builds that used upsertDebouncedJob before triggerGroup was
+  // introduced). Without the IS NULL fallback, the next enqueue would insert
+  // a duplicate pending row for the same conversation.
+  const existing = db
+    .select()
+    .from(memoryJobs)
+    .where(
+      and(
+        eq(memoryJobs.type, "conversation_analyze"),
+        eq(memoryJobs.status, "pending"),
+        sql`json_extract(${memoryJobs.payload}, '$.conversationId') = ${payload.conversationId}`,
+        or(
+          sql`json_extract(${memoryJobs.payload}, '$.triggerGroup') = ${payload.triggerGroup}`,
+          sql`json_extract(${memoryJobs.payload}, '$.triggerGroup') IS NULL`,
+        ),
+      ),
+    )
+    .get();
+  if (existing) {
+    // Merge triggerGroup into legacy rows so subsequent lookups use the new key.
+    const existingPayload = JSON.parse(existing.payload) as Record<
+      string,
+      unknown
+    >;
+    const needsPayloadUpdate = !existingPayload.triggerGroup;
+    db.update(memoryJobs)
+      .set({
+        runAfter,
+        updatedAt: Date.now(),
+        ...(needsPayloadUpdate
+          ? {
+              payload: JSON.stringify({ ...existingPayload, ...payload }),
+            }
+          : {}),
+      })
+      .where(eq(memoryJobs.id, existing.id))
+      .run();
+  } else {
+    enqueueMemoryJob("conversation_analyze", payload, runAfter, dbOverride);
+  }
+
+  // When an immediate trigger fires (batch/compaction), cancel any pending
+  // debounced row for the same conversation — the immediate analysis covers
+  // those messages, making the debounced pass redundant. Without this, both
+  // rows fire independently and double the LLM cost per batch crossing.
+  if (payload.triggerGroup === "immediate") {
+    db.update(memoryJobs)
+      .set({ status: "completed", updatedAt: Date.now() })
+      .where(
+        and(
+          eq(memoryJobs.type, "conversation_analyze"),
+          eq(memoryJobs.status, "pending"),
+          sql`json_extract(${memoryJobs.payload}, '$.conversationId') = ${payload.conversationId}`,
+          sql`json_extract(${memoryJobs.payload}, '$.triggerGroup') = 'debounced'`,
+        ),
+      )
+      .run();
+  }
+}
+
 /**
  * Check whether a pending or running job of the given type already exists.
  * Used to prevent duplicate enqueues for long-running maintenance jobs.