@vellumai/assistant 0.8.9-staging.2 → 0.8.9-staging.4

package/src/daemon/tool-side-effects.ts

@@ -155,6 +155,21 @@ registerHook("app_refresh", (_name, input, _result, { ctx }) => {
   notifyAppChanged(ctx, appId, { fileChange: true });
 });
 
+// app_update compiles internally (like app_refresh) but emits no events of its
+// own, so without this hook an updated app leaves open surfaces rendering the
+// stale dist and never re-deploys or invalidates the Library. The executor owns
+// the compile; notifyAppChanged only refreshes surfaces and broadcasts.
+registerHook("app_update", (_name, input, _result, { ctx }) => {
+  const appId = input.app_id as string | undefined;
+  if (!appId) return;
+  try {
+    addAppConversationId(appId, ctx.conversationId);
+  } catch (err) {
+    log.warn({ err, appId }, "Failed to track conversation ID on app_update");
+  }
+  notifyAppChanged(ctx, appId, { fileChange: true });
+});
+
 registerHook("voice_config_update", (_name, input) => {
   const setting = input.setting as string | undefined;
   if (!setting) return;

package/src/memory/__tests__/activation-session-store.test.ts

@@ -0,0 +1,41 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+mock.module("../../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+}));
+
+import {
+  isActivationSession,
+  markActivationSession,
+} from "../activation-session-store.js";
+import { getDb } from "../db-connection.js";
+import { initializeDb } from "../db-init.js";
+import { activationSessions } from "../schema.js";
+
+initializeDb();
+
+describe("activation-session-store", () => {
+  beforeEach(() => {
+    getDb().delete(activationSessions).run();
+  });
+
+  test("marks a conversation and reports it as an activation session", () => {
+    markActivationSession("c1");
+    expect(isActivationSession("c1")).toBe(true);
+  });
+
+  test("unmarked conversations are not activation sessions", () => {
+    expect(isActivationSession("nope")).toBe(false);
+  });
+
+  test("marking the same conversation twice is idempotent", () => {
+    markActivationSession("c1");
+    markActivationSession("c1");
+    expect(isActivationSession("c1")).toBe(true);
+    const rows = getDb().select().from(activationSessions).all();
+    expect(rows.length).toBe(1);
+  });
+});

package/src/memory/__tests__/onboarding-events-store.test.ts

@@ -0,0 +1,80 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+// Silence the logger.
+mock.module("../../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+}));
+
+// Mutable usage-data gate, flipped per-test.
+let collectUsageData = true;
+mock.module("../../config/loader.js", () => ({
+  getConfig: () => ({ collectUsageData }),
+}));
+
+import { getDb } from "../db-connection.js";
+import { initializeDb } from "../db-init.js";
+import {
+  queryUnreportedOnboardingEvents,
+  recordActivationEvent,
+} from "../onboarding-events-store.js";
+import { onboardingEvents } from "../schema.js";
+
+initializeDb();
+
+function resetTable(): void {
+  getDb().delete(onboardingEvents).run();
+}
+
+describe("onboarding-events-store: recordActivationEvent", () => {
+  beforeEach(() => {
+    collectUsageData = true;
+    resetTable();
+  });
+
+  test("persists an activation funnel event that round-trips through the query", () => {
+    const event = recordActivationEvent({
+      stepName: "activation_moment_1_complete",
+      sessionId: "conv-1",
+    });
+    expect(event).not.toBeNull();
+
+    const rows = queryUnreportedOnboardingEvents(0, undefined, 10);
+    expect(rows).toHaveLength(1);
+    const row = rows[0]!;
+    expect(row.stepName).toBe("activation_moment_1_complete");
+    expect(row.stepIndex).toBe(1);
+    expect(row.funnelVersion).toBe("activation_v1_2026_06");
+    expect(row.screen).toBe("activation_moment_1_complete");
+    expect(row.abVariant).toBe("variant-a");
+    expect(row.sessionId).toBe("conv-1");
+    expect(row.completedAt).toBe(new Date(row.createdAt).toISOString());
+  });
+
+  test("honors an explicit abVariant override", () => {
+    recordActivationEvent({
+      stepName: "activation_moment_2_complete",
+      sessionId: "conv-2",
+      abVariant: "variant-b",
+    });
+
+    const rows = queryUnreportedOnboardingEvents(0, undefined, 10);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]!.abVariant).toBe("variant-b");
+    expect(rows[0]!.stepIndex).toBe(2);
+  });
+
+  test("returns null and writes no row when collectUsageData is disabled", () => {
+    collectUsageData = false;
+    const event = recordActivationEvent({
+      stepName: "activation_moment_1_complete",
+      sessionId: "conv-3",
+    });
+    expect(event).toBeNull();
+
+    const rows = queryUnreportedOnboardingEvents(0, undefined, 10);
+    expect(rows).toHaveLength(0);
+  });
+});

package/src/memory/activation-session-store.ts

@@ -0,0 +1,43 @@
+import { eq } from "drizzle-orm";
+
+import { getLogger } from "../util/logger.js";
+import { getDb } from "./db-connection.js";
+import { activationSessions } from "./schema.js";
+
+const log = getLogger("activation-session-store");
+
+/**
+ * Mark a conversation as an activation-rail session. Idempotent (the row's
+ * primary key is the conversation id) and best-effort: a write failure is
+ * logged and swallowed so it never blocks the turn that triggered it.
+ */
+export function markActivationSession(conversationId: string): void {
+  try {
+    getDb()
+      .insert(activationSessions)
+      .values({ conversationId, createdAt: Date.now() })
+      .onConflictDoNothing()
+      .run();
+  } catch (err) {
+    log.warn({ err, conversationId }, "Failed to mark activation session");
+  }
+}
+
+/**
+ * Whether the given conversation was started on the activation rail. Best-effort:
+ * a read failure is logged and treated as "not an activation session".
+ */
+export function isActivationSession(conversationId: string): boolean {
+  try {
+    const row = getDb()
+      .select({ conversationId: activationSessions.conversationId })
+      .from(activationSessions)
+      .where(eq(activationSessions.conversationId, conversationId))
+      .limit(1)
+      .get();
+    return row !== undefined;
+  } catch (err) {
+    log.warn({ err, conversationId }, "Failed to read activation session");
+    return false;
+  }
+}

package/src/memory/db-init.ts

@@ -16,6 +16,7 @@ import { getDb, getSqlite } from "./db-connection.js";
 import { migrateToolCreatedItems } from "./graph/bootstrap.js";
 import {
   addCoreColumns,
+  createActivationSessionsTable,
   createApprovalPromptTsTrackerTable,
   createAssistantInboxTables,
   createAuthFallbackEventsTable,
@@ -161,6 +162,7 @@ import {
   migrateOAuthProvidersScopeSeparator,
   migrateOAuthProvidersTokenAuthMethodDefault,
   migrateOAuthProvidersTokenExchangeBodyFormat,
+  migrateOnboardingEventsFunnelColumns,
   migrateOnboardingEventsPriorAssistants,
   migrateProviderConnectionBaseUrlAndModels,
   migrateProviderConnectionStatusLabel,
@@ -480,6 +482,8 @@ export function initializeDb(): void {
     migrateMessagesRoleCreatedAtIndex,
     createAuthFallbackEventsTable,
     migrateAcpSessionHistoryCwd,
+    migrateOnboardingEventsFunnelColumns,
+    createActivationSessionsTable,
   ];
 
   // Run each migration step, catching and logging individual failures so one

package/src/memory/migrations/273-onboarding-events-funnel-columns.ts

@@ -0,0 +1,46 @@
+import { type DrizzleDb, getSqliteFrom } from "../db-connection.js";
+
+const TABLE = "onboarding_events";
+const COLUMNS: Array<{ name: string; type: string }> = [
+  { name: "session_id", type: "TEXT" },
+  { name: "step_name", type: "TEXT" },
+  { name: "step_index", type: "INTEGER" },
+  { name: "completed_at", type: "TEXT" },
+  { name: "funnel_version", type: "TEXT" },
+];
+
+/**
+ * Add nullable funnel-tracking columns to `onboarding_events`.
+ *
+ * The original table (#30733) recorded one row per onboarding screen but had
+ * no way to stitch those rows into an ordered, per-attempt funnel: there was
+ * no session correlator, no step ordering, and no completion timestamp. These
+ * columns let the activation-funnel reporting attribute each event to a single
+ * onboarding attempt (`session_id`), order steps within it (`step_name` /
+ * `step_index`), record when a step finished (`completed_at`), and version the
+ * funnel shape so changes to the step set don't silently corrupt historical
+ * conversion math (`funnel_version`).
+ *
+ * All columns are nullable — `NULL` for rows persisted before this migration
+ * ran.
+ *
+ * Idempotent — re-running is a no-op once the columns exist. Pure DDL with a
+ * PRAGMA guard, no registry entry needed (matches the 252 / 261 / 264 / 265 /
+ * 267 pattern).
+ */
+export function migrateOnboardingEventsFunnelColumns(
+  database: DrizzleDb,
+): void {
+  const raw = getSqliteFrom(database);
+
+  const columns = raw.query(`PRAGMA table_info(${TABLE})`).all() as Array<{
+    name: string;
+  }>;
+  const columnNames = new Set(columns.map((c) => c.name));
+
+  for (const { name, type } of COLUMNS) {
+    if (!columnNames.has(name)) {
+      raw.exec(`ALTER TABLE ${TABLE} ADD COLUMN ${name} ${type}`);
+    }
+  }
+}

package/src/memory/migrations/274-create-activation-sessions.ts

@@ -0,0 +1,15 @@
+import type { DrizzleDb } from "../db-connection.js";
+
+/**
+ * Create the activation_sessions table. One row per conversation that was
+ * started on the activation-rail bootstrap template, used by the activation
+ * funnel telemetry to scope events to activation conversations.
+ */
+export function createActivationSessionsTable(database: DrizzleDb): void {
+  database.run(/*sql*/ `
+    CREATE TABLE IF NOT EXISTS activation_sessions (
+      conversation_id TEXT PRIMARY KEY,
+      created_at INTEGER NOT NULL
+    )
+  `);
+}

package/src/memory/migrations/index.ts

@@ -260,6 +260,8 @@ export { migrateMessagesRoleCreatedAtIndex } from "./270-messages-role-created-a
 export { migrateScheduleSourceConversation } from "./270-schedule-source-conversation.js";
 export { createAuthFallbackEventsTable } from "./271-create-auth-fallback-events.js";
 export { migrateAcpSessionHistoryCwd } from "./272-acp-session-history-cwd.js";
+export { migrateOnboardingEventsFunnelColumns } from "./273-onboarding-events-funnel-columns.js";
+export { createActivationSessionsTable } from "./274-create-activation-sessions.js";
 export {
   MIGRATION_REGISTRY,
   type MigrationRegistryEntry,

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

@@ -2,6 +2,12 @@ import { and, asc, eq, gt, or } from "drizzle-orm";
 import { v4 as uuid } from "uuid";
 
 import { getConfig } from "../config/loader.js";
+import {
+  ACTIVATION_AB_VARIANT,
+  ACTIVATION_FUNNEL_VERSION,
+  activationStepIndex,
+  type ActivationStepName,
+} from "../telemetry/activation-funnel.js";
 import { getDb } from "./db-connection.js";
 import { onboardingEvents } from "./schema.js";
 
@@ -16,6 +22,11 @@ export interface OnboardingEvent {
   googleScopesJson: string | null;
   priorAssistantsJson: string | null;
   abVariant: string | null;
+  sessionId: string | null;
+  stepName: string | null;
+  stepIndex: number | null;
+  completedAt: string | null;
+  funnelVersion: string | null;
 }
 
 export interface RecordOnboardingEventParams {
@@ -27,6 +38,17 @@ export interface RecordOnboardingEventParams {
   googleScopes?: string[];
   priorAssistants?: string[];
   abVariant?: string;
+  sessionId?: string | null;
+  stepName?: string | null;
+  stepIndex?: number | null;
+  completedAt?: string | null;
+  funnelVersion?: string | null;
+}
+
+/** Insert a fully-built event row. Shared by all record* entry points. */
+function insertOnboardingEvent(event: OnboardingEvent): OnboardingEvent {
+  getDb().insert(onboardingEvents).values(event).run();
+  return event;
 }
 
 /**
@@ -37,8 +59,7 @@ export function recordOnboardingEvent(
   params: RecordOnboardingEventParams,
 ): OnboardingEvent | null {
   if (!getConfig().collectUsageData) return null;
-  const db = getDb();
-  const event: OnboardingEvent = {
+  return insertOnboardingEvent({
     id: uuid(),
     createdAt: Date.now(),
     screen: params.screen,
@@ -53,22 +74,44 @@ export function recordOnboardingEvent(
       ? JSON.stringify(params.priorAssistants)
       : null,
     abVariant: params.abVariant ?? null,
-  };
-  db.insert(onboardingEvents)
-    .values({
-      id: event.id,
-      createdAt: event.createdAt,
-      screen: event.screen,
-      toolsJson: event.toolsJson,
-      tasksJson: event.tasksJson,
-      tone: event.tone,
-      googleConnected: event.googleConnected,
-      googleScopesJson: event.googleScopesJson,
-      priorAssistantsJson: event.priorAssistantsJson,
-      abVariant: event.abVariant,
-    })
-    .run();
-  return event;
+    sessionId: params.sessionId ?? null,
+    stepName: params.stepName ?? null,
+    stepIndex: params.stepIndex ?? null,
+    completedAt: params.completedAt ?? null,
+    funnelVersion: params.funnelVersion ?? null,
+  });
+}
+
+/**
+ * Record an activation-funnel milestone event. Reuses the onboarding telemetry
+ * substrate (`screen` carries the step name to satisfy the NOT NULL column).
+ * Returns null when usage data collection is disabled.
+ */
+export function recordActivationEvent(params: {
+  stepName: ActivationStepName;
+  sessionId: string;
+  userId?: string | null;
+  abVariant?: string;
+}): OnboardingEvent | null {
+  if (!getConfig().collectUsageData) return null;
+  const createdAt = Date.now();
+  return insertOnboardingEvent({
+    id: uuid(),
+    createdAt,
+    screen: params.stepName,
+    toolsJson: null,
+    tasksJson: null,
+    tone: null,
+    googleConnected: null,
+    googleScopesJson: null,
+    priorAssistantsJson: null,
+    abVariant: params.abVariant ?? ACTIVATION_AB_VARIANT,
+    sessionId: params.sessionId,
+    stepName: params.stepName,
+    stepIndex: activationStepIndex(params.stepName),
+    completedAt: new Date(createdAt).toISOString(),
+    funnelVersion: ACTIVATION_FUNNEL_VERSION,
+  });
 }
 
 /**
@@ -93,6 +136,11 @@ export function queryUnreportedOnboardingEvents(
       googleScopesJson: onboardingEvents.googleScopesJson,
       priorAssistantsJson: onboardingEvents.priorAssistantsJson,
       abVariant: onboardingEvents.abVariant,
+      sessionId: onboardingEvents.sessionId,
+      stepName: onboardingEvents.stepName,
+      stepIndex: onboardingEvents.stepIndex,
+      completedAt: onboardingEvents.completedAt,
+      funnelVersion: onboardingEvents.funnelVersion,
     })
     .from(onboardingEvents)
     .where(

package/src/memory/schema/infrastructure.ts

@@ -277,6 +277,11 @@ export const onboardingEvents = sqliteTable("onboarding_events", {
   googleScopesJson: text("google_scopes_json"),
   priorAssistantsJson: text("prior_assistants_json"),
   abVariant: text("ab_variant"),
+  sessionId: text("session_id"),
+  stepName: text("step_name"),
+  stepIndex: integer("step_index"),
+  completedAt: text("completed_at"),
+  funnelVersion: text("funnel_version"),
 });
 
 // Aggregated legacy-loopback auth-fallback counts forwarded by the gateway.
@@ -294,6 +299,14 @@ export const authFallbackEvents = sqliteTable("auth_fallback_events", {
   windowEnd: integer("window_end").notNull(),
 });
 
+// One row per conversation started on the activation-rail bootstrap template.
+// Lets the activation funnel telemetry scope its events to activation
+// conversations without inspecting the bootstrap template at emit time.
+export const activationSessions = sqliteTable("activation_sessions", {
+  conversationId: text("conversation_id").primaryKey(),
+  createdAt: integer("created_at").notNull(),
+});
+
 export const traceEvents = sqliteTable(
   "trace_events",
   {

package/src/memory/v2/__tests__/consolidation-job.test.ts

@@ -105,43 +105,15 @@ mock.module("../../jobs-store.js", () => ({
   isMemoryEnabled: () => true,
 }));
 
-// ── v3 health-injection mocks ───────────────────────────────────────
+// ── v3 follow-up flag mock ──────────────────────────────────────────
 //
-// The consolidation handler optionally prepends a v3 health block to the
-// prompt when a v3 flag is on AND the rendered report is non-empty. These
-// mocks let each test (a) toggle the flag, (b) decide what health block the
-// renderer produces, and (c) force the health computation to throw — without
-// materializing a real v3 data dir. The tree/core/page-index loaders are
-// stubbed to inert values; `computeV3Health` is a pass-through whose result is
-// fed to the toggleable `renderV3Health`.
+// A v3 flag being on appends `memory_v3_maintain` to the post-consolidation
+// follow-up fan-out. This mock lets each test toggle the flag.
 let v3FlagOn = false;
 mock.module("../../../config/assistant-feature-flags.js", () => ({
   isAssistantFeatureFlagEnabled: () => v3FlagOn,
 }));
 
-let renderedHealth = "";
-let computeThrows = false;
-mock.module("../../../plugins/defaults/memory-v3-shadow/health.js", () => ({
-  computeV3Health: () => {
-    if (computeThrows) throw new Error("simulated health compute failure");
-    return {};
-  },
-  renderV3Health: () => renderedHealth,
-}));
-
-mock.module("../../../plugins/defaults/memory-v3-shadow/tree.js", () => ({
-  loadLeafTree: async () => ({ leaves: new Map(), byPage: new Map() }),
-  resolveDataDir: () => "/tmp/v3-data-stub",
-}));
-
-mock.module("../../../plugins/defaults/memory-v3-shadow/core.js", () => ({
-  loadCore: async () => new Set<string>(),
-}));
-
-mock.module("../../v2/page-index.js", () => ({
-  getPageIndex: async () => ({ entries: [] }),
-}));
-
 // ── Workspace pin ───────────────────────────────────────────────────
 let tmpWorkspace: string;
 let previousWorkspaceEnv: string | undefined;
@@ -211,10 +183,8 @@ beforeEach(() => {
   enqueuedJobs.length = 0;
   nextJobIdCounter = 0;
 
-  // v3 health injection defaults: flag off, no rendered block, no throw.
+  // v3 follow-up flag default: off.
   v3FlagOn = false;
-  renderedHealth = "";
-  computeThrows = false;
 });
 
 // ---------------------------------------------------------------------------
@@ -409,69 +379,6 @@ describe("memoryV2ConsolidateJob — non-empty buffer", () => {
   });
 });
 
-describe("memoryV2ConsolidateJob — v3 health injection", () => {
-  beforeEach(() => {
-    writeFileSync(
-      bufferPath(),
-      "- [Apr 27, 9:00 AM] Alice prefers VS Code over Vim.\n",
-    );
-  });
-
-  test("prepends the health block when a v3 flag is on and the report is actionable", async () => {
-    v3FlagOn = true;
-    renderedHealth = "memory-v3 health:\n- 2 unassigned slug(s): a, b";
-
-    const result = await memoryV2ConsolidateJob(makeJob(), CONFIG);
-
-    expect(result.kind).toBe("invoked");
-    const prompt = runnerLastArgs?.prompt as string;
-    // The health block is PREPENDED, separated by a blank line, with the
-    // base consolidation prompt still present underneath it.
-    expect(prompt.startsWith(`${renderedHealth}\n\n`)).toBe(true);
-    expect(prompt).toContain("memory consolidation");
-    expect(prompt).not.toContain(CUTOFF_PLACEHOLDER);
-  });
-
-  test("leaves the prompt unchanged when the report is all-green (empty render)", async () => {
-    v3FlagOn = true;
-    renderedHealth = "";
-
-    const result = await memoryV2ConsolidateJob(makeJob(), CONFIG);
-
-    expect(result.kind).toBe("invoked");
-    const prompt = runnerLastArgs?.prompt as string;
-    expect(prompt).not.toContain("memory-v3 health:");
-    // Prompt is exactly the resolved consolidation body.
-    expect(prompt).toContain("memory consolidation");
-  });
-
-  test("leaves the prompt unchanged when v3 flags are off even if a block would render", async () => {
-    v3FlagOn = false;
-    renderedHealth = "memory-v3 health:\n- 1 unassigned slug(s): a";
-
-    const result = await memoryV2ConsolidateJob(makeJob(), CONFIG);
-
-    expect(result.kind).toBe("invoked");
-    const prompt = runnerLastArgs?.prompt as string;
-    expect(prompt).not.toContain("memory-v3 health:");
-    expect(prompt).toContain("memory consolidation");
-  });
-
-  test("falls back to the base prompt when health computation throws", async () => {
-    v3FlagOn = true;
-    computeThrows = true;
-    renderedHealth = "memory-v3 health:\n- should not appear";
-
-    const result = await memoryV2ConsolidateJob(makeJob(), CONFIG);
-
-    // A health-compute failure must NEVER break consolidation.
-    expect(result.kind).toBe("invoked");
-    const prompt = runnerLastArgs?.prompt as string;
-    expect(prompt).not.toContain("memory-v3 health:");
-    expect(prompt).toContain("memory consolidation");
-  });
-});
-
 describe("memoryV2ConsolidateJob — concurrent invocations", () => {
   beforeEach(() => {
     writeFileSync(bufferPath(), "- [Apr 27, 9:00 AM] Alice prefers VS Code.\n");

package/src/memory/v2/__tests__/page-store.test.ts

@@ -186,6 +186,28 @@ describe("writePage + readPage round-trip", () => {
     expect(read!.body).toBe(page.body);
   });
 
+  test("round-trips authored links: frontmatter (memory-v3 edge lane)", async () => {
+    const page = makePage({
+      frontmatter: {
+        edges: [],
+        ref_files: [],
+        ref_urls: [],
+        links: ["bob-handoff — the partner this hands off to"],
+      },
+    });
+    await writePage(workspaceDir, page);
+
+    // A page using the optional `links:` frontmatter must NOT be rejected by the
+    // strict schema (it would otherwise be dropped from memory-v3 entirely), and
+    // the curated links must survive the render → read round-trip so the edge
+    // graph can parse them back from the rendered frontmatter.
+    const read = await readPage(workspaceDir, page.slug);
+    expect(read).not.toBeNull();
+    expect(read!.frontmatter.links).toEqual([
+      "bob-handoff — the partner this hands off to",
+    ]);
+  });
+
   test("renders frontmatter at the top with --- delimiters", async () => {
     const page = makePage();
     await writePage(workspaceDir, page);