@vellumai/assistant 0.8.8 → 0.8.9-dev.202606091926.ebb2d62

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/conversation-crud.ts

@@ -277,6 +277,7 @@ export interface MessageRow {
   content: string;
   createdAt: number;
   metadata: string | null;
+  clientMessageId: string | null;
 }
 
 const parseMessage = createRowMapper<typeof messages.$inferSelect, MessageRow>({
@@ -286,6 +287,7 @@ const parseMessage = createRowMapper<typeof messages.$inferSelect, MessageRow>({
   content: "content",
   createdAt: "createdAt",
   metadata: "metadata",
+  clientMessageId: "clientMessageId",
 });
 
 export type ConversationCreateType = "standard" | "background" | "scheduled";
@@ -1903,21 +1905,30 @@ export function listActiveInferenceProfileSessions(
 }
 
 /**
- * Resolve the per-turn inference-profile override from an already-loaded
- * conversation row. Returns the row's `inferenceProfile` for interactive
- * conversations, `undefined` for automation threads (subagent fan-out,
- * scheduled tasks, update bulletins) so they run on the workspace defaults
- * rather than inheriting an interactive override.
- *
- * Prefer this row-based form when the caller already needs to read the
- * conversation row for other reasons (e.g. the agent loop's title check).
+ * The conversation fields needed to resolve a per-turn inference-profile
+ * override. Satisfied by both the DB {@link ConversationRow} and the live
+ * in-memory `Conversation`, so callers can derive the override from whichever
+ * representation they already hold without a redundant row fetch.
+ */
+export interface OverrideProfileFields {
+  conversationType?: string | null;
+  inferenceProfile?: string | null;
+  inferenceProfileExpiresAt?: number | null;
+}
+
+/**
+ * Resolve the per-turn inference-profile override from a conversation's
+ * fields. Returns the `inferenceProfile` for interactive conversations,
+ * `undefined` for automation threads (subagent fan-out, scheduled tasks,
+ * update bulletins) so they run on the workspace defaults rather than
+ * inheriting an interactive override.
  */
-export function getConversationOverrideProfileFromRow(
-  conv: ConversationRow | null,
+export function resolveOverrideProfile(
+  fields: OverrideProfileFields | null,
 ): string | undefined {
   if (
-    conv?.conversationType === "background" ||
-    conv?.conversationType === "scheduled"
+    fields?.conversationType === "background" ||
+    fields?.conversationType === "scheduled"
   ) {
     return undefined;
   }
@@ -1931,24 +1942,23 @@ export function getConversationOverrideProfileFromRow(
   // Without this, a session at the exact-expiry millisecond would be served
   // for one extra turn here while being cleared by the reaper.
   if (
-    conv?.inferenceProfileExpiresAt != null &&
-    conv.inferenceProfileExpiresAt <= Date.now()
+    fields?.inferenceProfileExpiresAt != null &&
+    fields.inferenceProfileExpiresAt <= Date.now()
   ) {
     return undefined;
   }
-  return conv?.inferenceProfile ?? undefined;
+  return fields?.inferenceProfile ?? undefined;
 }
 
 /**
  * Resolve the per-turn inference-profile override by conversation id.
- * Convenience wrapper around `getConversationOverrideProfileFromRow` for
- * standalone callers (e.g. subagent spawn, opportunity-wake) that don't
- * already have the row in hand.
+ * Convenience wrapper for standalone callers (e.g. subagent spawn,
+ * opportunity-wake) that don't already have the conversation in hand.
  */
 export function getConversationOverrideProfile(
   conversationId: string,
 ): string | undefined {
-  return getConversationOverrideProfileFromRow(getConversation(conversationId));
+  return resolveOverrideProfile(getConversation(conversationId));
 }
 
 export function setLastNotifiedInferenceProfile(

package/src/memory/conversation-starter-checkpoints.ts

@@ -15,6 +15,7 @@ import { memoryCheckpoints } from "./schema.js";
 export const CK_ITEM_COUNT = "conversation_starters:item_count_at_last_gen";
 export const CK_BATCH = "conversation_starters:generation_batch";
 export const CK_LAST_GEN_AT = "conversation_starters:last_gen_at";
+export const CK_LAST_ATTEMPT_AT = "conversation_starters:last_attempt_at";
 
 export function checkpointKey(base: string, scopeId: string): string {
   return `${base}:${scopeId}`;

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,
@@ -41,6 +42,7 @@ import {
   migrate230AcpSessionHistory,
   migrate231RepairMemoryGraphEventDates,
   migrateA2ATasks,
+  migrateAcpSessionHistoryCwd,
   migrateActivationState,
   migrateActivationStateFkCascade,
   migrateAddConversationInferenceProfile,
@@ -160,6 +162,7 @@ import {
   migrateOAuthProvidersScopeSeparator,
   migrateOAuthProvidersTokenAuthMethodDefault,
   migrateOAuthProvidersTokenExchangeBodyFormat,
+  migrateOnboardingEventsFunnelColumns,
   migrateOnboardingEventsPriorAssistants,
   migrateProviderConnectionBaseUrlAndModels,
   migrateProviderConnectionStatusLabel,
@@ -478,6 +481,9 @@ export function initializeDb(): void {
     migrateScheduleSourceConversation,
     migrateMessagesRoleCreatedAtIndex,
     createAuthFallbackEventsTable,
+    migrateAcpSessionHistoryCwd,
+    migrateOnboardingEventsFunnelColumns,
+    createActivationSessionsTable,
   ];
 
   // Run each migration step, catching and logging individual failures so one

package/src/memory/embedding-backend.ts

@@ -1,6 +1,5 @@
 import { createHash } from "node:crypto";
 
-import { isAssistantFeatureFlagEnabled } from "../config/assistant-feature-flags.js";
 import { getOllamaBaseUrlEnv } from "../config/env.js";
 import { resolveCallSiteConfig } from "../config/llm-resolver.js";
 import type { AssistantConfig } from "../config/types.js";
@@ -302,13 +301,10 @@ export async function selectEmbeddingBackend(
     };
   }
 
-  // When the managed-gemini-embeddings-enabled flag is on AND managed proxy
-  // prerequisites are satisfied, insert managed-proxy Gemini at the front of
-  // the auto chain so platform assistants use Vellum-managed Gemini embeddings.
-  if (
-    (requested === "auto" || requested === "gemini") &&
-    isAssistantFeatureFlagEnabled("managed-gemini-embeddings-enabled", config)
-  ) {
+  // When managed proxy prerequisites are satisfied, insert managed-proxy Gemini
+  // at the front of the auto chain so platform assistants use Vellum-managed
+  // Gemini embeddings.
+  if (requested === "auto" || requested === "gemini") {
     const proxyCtx = await resolveManagedProxyContext();
     if (proxyCtx.enabled) {
       const meta = PLATFORM_PROVIDER_META["gemini"];
@@ -677,12 +673,7 @@ async function selectFallbackBackends(
               geminiCacheExtras(config),
             ),
           );
-        } else if (
-          isAssistantFeatureFlagEnabled(
-            "managed-gemini-embeddings-enabled",
-            config,
-          )
-        ) {
+        } else {
           // Try managed proxy Gemini as fallback when no direct key exists.
           const proxyCtx = await resolveManagedProxyContext();
           const meta = PLATFORM_PROVIDER_META["gemini"];
@@ -724,14 +715,6 @@ async function selectFallbackBackends(
               );
             if (cached) backends.push(cached);
           }
-        } else {
-          // Preserve cached backend on transient credential-store failures.
-          const cached = getCached(
-            "gemini",
-            config.memory.embeddings.geminiModel,
-            geminiCacheExtras(config),
-          );
-          if (cached) backends.push(cached);
         }
         break;
       }

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

@@ -22,6 +22,7 @@ import {
   checkpointKey,
   CK_BATCH,
   CK_ITEM_COUNT,
+  CK_LAST_ATTEMPT_AT,
   CK_LAST_GEN_AT,
   countActiveMemoryNodes,
   getCheckpointValue,
@@ -336,6 +337,7 @@ Bad → Good (incomplete phrase → complete):
         config: {
           callSite: "conversationStarters" as const,
           max_tokens: 2048,
+          temperature: 0.7,
           tool_choice: {
             type: "tool" as const,
             name: "store_conversation_starters",
@@ -395,18 +397,27 @@ export async function generateConversationStartersJob(
   const db = getDb();
   const now = Date.now();
 
+  // Record attempt time so the route handler's cooldown prevents rapid retries
+  // even when generation produces 0 valid starters.
+  upsertCheckpoint(
+    checkpointKey(CK_LAST_ATTEMPT_AT, scopeId),
+    String(now),
+    now,
+  );
+
   const starters = await generateStarters(scopeId);
   if (starters.length === 0) {
     log.info({ scopeId }, "No conversation starters generated");
 
-    // Sync checkpoints so both `staleByAge` and `checkpointAhead` clear.
+    // Sync the item count checkpoint so `checkpointAhead` clears, but do NOT
+    // update `CK_LAST_GEN_AT` — the stale TTL should trigger a retry on the
+    // next GET rather than blocking retries for the full TTL window.
     const totalActive = countActiveMemoryNodes(scopeId);
     upsertCheckpoint(
       checkpointKey(CK_ITEM_COUNT, scopeId),
       String(totalActive),
       now,
     );
-    upsertCheckpoint(checkpointKey(CK_LAST_GEN_AT, scopeId), String(now), now);
     return;
   }
 

package/src/memory/jobs/__tests__/embed-concept-page.test.ts

@@ -143,9 +143,8 @@ afterAll(() => {
 // `getWorkspaceDir()` resolves to the tmpdir.
 const { DEFAULT_CONFIG } = await import("../../../config/defaults.js");
 const { getDb } = await import("../../db-connection.js");
-const { resetDbForTesting } = await import(
-  "../../../__tests__/db-test-helpers.js"
-);
+const { resetDbForTesting } =
+  await import("../../../__tests__/db-test-helpers.js");
 const { initializeDb } = await import("../../db-init.js");
 const { memoryEmbeddings, memoryJobs } = await import("../../schema.js");
 const { claimMemoryJobs } = await import("../../jobs-store.js");
@@ -187,12 +186,14 @@ function makeJob(payload: Record<string, unknown>): MemoryJob {
 
 beforeEach(() => {
   resetDbForTesting();
+  // The first run pays the full cold-start migration chain; bump the hook
+  // timeout above bun's 5s default so the leading test doesn't flake in CI.
   initializeDb();
   embedWithBackendCalls.length = 0;
   upsertCalls.length = 0;
   deleteCalls.length = 0;
   _resetQdrantBreaker();
-});
+}, 30_000);
 
 afterEach(() => {
   // Clean up any pages written between tests so each scenario starts fresh.

package/src/memory/jobs-worker.ts

@@ -8,6 +8,7 @@ import {
   diskPressureBackgroundSkipLogFields,
   shouldLogDiskPressureBackgroundSkip,
 } from "../daemon/disk-pressure-background-gate.js";
+import { maintainJob as memoryV3MaintainJob } from "../plugins/defaults/memory-v3-shadow/maintain-job.js";
 import { getLogger } from "../util/logger.js";
 import { getWorkspaceDir } from "../util/platform.js";
 import { getMemoryCheckpoint, setMemoryCheckpoint } from "./checkpoints.js";
@@ -87,7 +88,6 @@ import {
   memoryV2ConsolidateJob,
 } from "./v2/consolidation-job.js";
 import { memoryV2SweepJob } from "./v2/sweep-job.js";
-import { maintainJob as memoryV3MaintainJob } from "./v3/maintain-job.js";
 
 const log = getLogger("memory-jobs-worker");
 
@@ -95,6 +95,16 @@ const AUTOMATIC_CONSOLIDATION_JOB_PAYLOAD = {
   trigger: MEMORY_V2_CONSOLIDATION_JOB_TRIGGERS.automatic,
 } as const;
 
+/**
+ * Minimum buffer entries required for a scheduled consolidation run. The
+ * time-based schedule noops when `memory/buffer.md` has fewer non-empty lines
+ * than this threshold — the LLM cost of a full consolidation pass outweighs
+ * the benefit when the buffer is nearly empty. Mirrors the heartbeat
+ * max-consecutive-runs skip pattern. Manual "Run now" and the size-based
+ * trigger are not affected.
+ */
+export const MIN_BUFFER_LINES_FOR_CONSOLIDATION = 10;
+
 /**
  * V1 job types that read or write the v1 Qdrant collection via
  * `getQdrantClient()`. When `memory.v2.enabled` is true, the v1 client is
@@ -815,6 +825,20 @@ export function maybeEnqueueGraphMaintenanceJobs(
   for (const { key, intervalMs, jobType } of schedule) {
     const lastRun = parseInt(getMemoryCheckpoint(key) ?? "0", 10);
     if (nowMs - lastRun >= intervalMs) {
+      // Noop scheduled consolidation when the buffer has too few entries to
+      // justify an LLM run — mirrors the heartbeat max-consecutive-runs skip.
+      // The checkpoint advances so the next check fires after the regular
+      // interval. Manual "Run now" is unaffected (routes layer, not schedule).
+      if (jobType === consolidateEntry.jobType) {
+        const bufferPath = join(getWorkspaceDir(), "memory", "buffer.md");
+        if (countBufferLines(bufferPath) < MIN_BUFFER_LINES_FOR_CONSOLIDATION) {
+          log.debug(
+            "Scheduled consolidation skipped: buffer under minimum line threshold",
+          );
+          setMemoryCheckpoint(key, String(nowMs));
+          continue;
+        }
+      }
       const payload =
         jobType === consolidateEntry.jobType
           ? AUTOMATIC_CONSOLIDATION_JOB_PAYLOAD

package/src/memory/migrations/272-acp-session-history-cwd.ts

@@ -0,0 +1,36 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { getSqliteFrom } from "../db-connection.js";
+import { withCrashRecovery } from "./validate-migration-state.js";
+
+const CHECKPOINT_KEY = "migration_acp_session_history_cwd_v1";
+
+const TABLE = "acp_session_history";
+const COLUMN = "cwd";
+
+/**
+ * Add a nullable `cwd TEXT` column to `acp_session_history`.
+ *
+ * Records the working directory the ACP agent process was spawned with so
+ * that a persisted session can later be resumed (`session/load` /
+ * `session/resume` both require the original cwd to reconstruct params).
+ *
+ * `NULL` for rows persisted before this migration ran — legacy sessions
+ * simply are not resumable.
+ *
+ * Idempotent — the PRAGMA guard makes re-running a no-op once the column
+ * exists.
+ */
+export function migrateAcpSessionHistoryCwd(database: DrizzleDb): void {
+  withCrashRecovery(database, CHECKPOINT_KEY, () => {
+    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));
+
+    if (!columnNames.has(COLUMN)) {
+      raw.exec(`ALTER TABLE ${TABLE} ADD COLUMN ${COLUMN} TEXT`);
+    }
+  });
+}

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

@@ -259,6 +259,9 @@ export { migrateScheduleScriptTimeout } from "./269-schedule-script-timeout.js";
 export { migrateMessagesRoleCreatedAtIndex } from "./270-messages-role-created-at-index.js";
 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(