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

package/src/telemetry/activation-funnel.ts

@@ -0,0 +1,167 @@
+/**
+ * Activation funnel vocabulary — the single source of truth for the
+ * activation-rail telemetry funnel.
+ *
+ * The activation rail emits milestone ("funnel") events into the existing
+ * onboarding telemetry substrate (`type: "onboarding"`). This module defines
+ * the step vocabulary (step_name → step_index), the funnel version, the
+ * cohort arm tag, and the deterministic `daemon_event_id` used for dbt-side
+ * dedup. Downstream PRs (store, reporter, emit handler, turn hook) import
+ * from here so the vocabulary is never duplicated.
+ */
+
+/** Funnel version stamped on every activation event (per JARVIS-1033). */
+export const ACTIVATION_FUNNEL_VERSION = "activation_v1_2026_06";
+
+/**
+ * Filename of the bootstrap template that drives the activation rail. The web
+ * prechat-context sets this as `onboardingContext.bootstrapTemplate` (mirrored
+ * there as `ACTIVATION_RAIL_BOOTSTRAP_TEMPLATE`); the daemon recognizes it to
+ * mark the conversation as an activation session. Single source of truth on the
+ * daemon side so the literal isn't duplicated across modules.
+ */
+export const ACTIVATION_RAIL_BOOTSTRAP_TEMPLATE =
+  "BOOTSTRAP-ACTIVATION-RAIL.md";
+
+/**
+ * Cohort arm tag for Stream-A emission. The daemon only runs the rail for
+ * treatment users, so activation events are tagged with the treatment arm
+ * name ("variant-a"), mirroring `pre-chat-onboarding-experiment-2026-06-06`.
+ * Stream B later threads the assigned arm in place of this constant.
+ */
+export const ACTIVATION_AB_VARIANT = "variant-a";
+
+/**
+ * Activation funnel steps keyed by short id. `stepName` is the wire value
+ * sent to telemetry; `stepIndex` is the 1-based ordinal position. This is
+ * the single source of truth for the step vocabulary.
+ */
+export const ACTIVATION_STEPS = {
+  moment1: { stepName: "activation_moment_1_complete", stepIndex: 1 },
+  moment2: { stepName: "activation_moment_2_complete", stepIndex: 2 },
+  moment3: { stepName: "activation_moment_3_complete", stepIndex: 3 },
+  firstWowExecuted: { stepName: "activation_first_wow_executed", stepIndex: 4 },
+  firstWowInteracted: {
+    stepName: "activation_first_wow_interacted",
+    stepIndex: 5,
+  },
+} as const;
+
+/** Union of valid activation step names. */
+export type ActivationStepName =
+  (typeof ACTIVATION_STEPS)[keyof typeof ACTIVATION_STEPS]["stepName"];
+
+/** step_name → step_index, derived once from the vocabulary. */
+const STEP_INDEX_BY_NAME = new Map<ActivationStepName, number>(
+  Object.values(ACTIVATION_STEPS).map((step) => [
+    step.stepName,
+    step.stepIndex,
+  ]),
+);
+
+/** Type guard: is `value` one of the known activation step names? */
+export function isActivationStepName(
+  value: string,
+): value is ActivationStepName {
+  return STEP_INDEX_BY_NAME.has(value as ActivationStepName);
+}
+
+/**
+ * Model-facing activation-moment tokens. These are the values the model passes
+ * as the optional `ui_show` `activation_moment` tag; the daemon maps each token
+ * to its `ACTIVATION_STEPS[...].stepName` and records the milestone when the
+ * tagged surface is committed. Kept short/stable so the schema enum is friendly
+ * for the model — the canonical wire vocabulary stays `ActivationStepName`.
+ */
+export type ActivationMomentParam =
+  | "moment_1"
+  | "moment_2"
+  | "moment_3"
+  | "first_wow_executed"
+  | "first_wow_interacted";
+
+/**
+ * `ActivationMomentParam` token → canonical `ActivationStepName`, derived from
+ * `ACTIVATION_STEPS` so the vocabulary stays single-sourced. The token order
+ * mirrors `ACTIVATION_STEPS` (indices 1–5).
+ */
+const STEP_NAME_BY_MOMENT_PARAM = {
+  moment_1: ACTIVATION_STEPS.moment1.stepName,
+  moment_2: ACTIVATION_STEPS.moment2.stepName,
+  moment_3: ACTIVATION_STEPS.moment3.stepName,
+  first_wow_executed: ACTIVATION_STEPS.firstWowExecuted.stepName,
+  first_wow_interacted: ACTIVATION_STEPS.firstWowInteracted.stepName,
+} as const satisfies Record<ActivationMomentParam, ActivationStepName>;
+
+/** The five valid model-facing moment tokens (e.g. for a schema enum). */
+export const ACTIVATION_MOMENT_PARAMS = Object.keys(
+  STEP_NAME_BY_MOMENT_PARAM,
+) as ActivationMomentParam[];
+
+/** Type guard: is `value` one of the model-facing activation-moment tokens? */
+export function isActivationMomentParam(
+  value: string,
+): value is ActivationMomentParam {
+  return Object.prototype.hasOwnProperty.call(STEP_NAME_BY_MOMENT_PARAM, value);
+}
+
+/** Map a model-facing moment token to its canonical activation step name. */
+export function activationStepNameForMomentParam(
+  param: ActivationMomentParam,
+): ActivationStepName {
+  return STEP_NAME_BY_MOMENT_PARAM[param];
+}
+
+/**
+ * When each tagged moment is emitted relative to its `ui_show` surface:
+ * - `"show"` — at surface render time. `first_wow_executed` is an *execution*
+ *   signal: the rail's result/`work_result` surface is display-only and may
+ *   receive no user commit, so a commit-time emit would never fire (and if the
+ *   card has an action, deferring to the click would conflate "executed" with
+ *   "interacted" and corrupt funnel timing).
+ * - `"commit"` — on user commit/interaction. The other four moments represent
+ *   resolving an intake, picking an offer/task, or clicking a result action —
+ *   all genuine commit events.
+ */
+export const ACTIVATION_MOMENT_EMIT_AT = {
+  moment_1: "commit",
+  moment_2: "commit",
+  moment_3: "commit",
+  first_wow_executed: "show",
+  first_wow_interacted: "commit",
+} as const satisfies Record<ActivationMomentParam, "show" | "commit">;
+
+/** True when the moment records at surface-render time rather than on commit. */
+export function activationMomentEmitsAtShow(
+  param: ActivationMomentParam,
+): boolean {
+  return ACTIVATION_MOMENT_EMIT_AT[param] === "show";
+}
+
+/** Look up the 1-based funnel index for a step name. */
+export function activationStepIndex(stepName: ActivationStepName): number {
+  // Non-null: ActivationStepName is derived from ACTIVATION_STEPS, so the map
+  // always contains the key.
+  return STEP_INDEX_BY_NAME.get(stepName)!;
+}
+
+/**
+ * Deterministic `daemon_event_id` for an activation event. Keying on
+ * `${funnel_version}:${sessionId}:${stepName}` lets the existing dbt
+ * dedup (keyed on `daemon_event_id`, earliest-wins) collapse a moment that
+ * fires more than once into a single row.
+ *
+ * `funnelVersion` defaults to the current `ACTIVATION_FUNNEL_VERSION` but
+ * callers that have a per-row stored version (e.g. the telemetry reporter
+ * flushing rows recorded under an older version) MUST pass the row's own
+ * `funnel_version` so the id stays stable across a version bump — otherwise
+ * queued/offline v1 rows would be keyed with the new binary's version and
+ * stop collapsing with already-ingested v1 rows from the same session.
+ */
+export function buildActivationDaemonEventId(
+  sessionId: string,
+  stepName: ActivationStepName,
+  funnelVersion: string = ACTIVATION_FUNNEL_VERSION,
+): string {
+  return `${funnelVersion}:${sessionId}:${stepName}`;
+}

package/src/telemetry/types.ts

@@ -183,6 +183,19 @@ export interface OnboardingTelemetryEvent extends TelemetryEventBase {
   google_connected?: boolean;
   google_scopes?: string[];
   ab_variant?: string;
+  /**
+   * Activation-funnel fields (mirror the web funnel shape and the platform
+   * serializer). The platform accepts an onboarding event via either the
+   * legacy `screen` path or the all-funnel-fields path (`session_id` +
+   * `step_name` + `step_index` + `completed_at` + `funnel_version` +
+   * `ab_variant`).
+   */
+  session_id?: string;
+  step_name?: string;
+  step_index?: number;
+  completed_at?: string;
+  funnel_version?: string;
+  user_id?: string;
 }
 
 /**

package/src/telemetry/usage-telemetry-reporter.test.ts

@@ -131,6 +131,11 @@ const mockQueryUnreportedOnboardingEvents = mock(
       googleScopesJson: string | null;
       priorAssistantsJson: string | null;
       abVariant: string | null;
+      sessionId: string | null;
+      stepName: string | null;
+      stepIndex: number | null;
+      completedAt: string | null;
+      funnelVersion: string | null;
     }[],
 );
 
@@ -152,6 +157,10 @@ import { getDb } from "../memory/db-connection.js";
 import { initializeDb } from "../memory/db-init.js";
 import { authFallbackEvents } from "../memory/schema.js";
 import type { UsageEvent } from "../usage/types.js";
+import {
+  ACTIVATION_FUNNEL_VERSION,
+  buildActivationDaemonEventId,
+} from "./activation-funnel.js";
 import { UsageTelemetryReporter } from "./usage-telemetry-reporter.js";
 
 initializeDb();
@@ -201,6 +210,34 @@ function makeUsageEvent(
   };
 }
 
+type OnboardingEventFixture = ReturnType<
+  typeof mockQueryUnreportedOnboardingEvents
+>[number];
+
+function makeOnboardingEvent(
+  overrides: Partial<OnboardingEventFixture> = {},
+): OnboardingEventFixture {
+  eventIdCounter += 1;
+  return {
+    id: `onb-${eventIdCounter}`,
+    createdAt: 1700000000000 + eventIdCounter * 1000,
+    screen: "tools",
+    toolsJson: null,
+    tasksJson: null,
+    tone: null,
+    googleConnected: null,
+    googleScopesJson: null,
+    priorAssistantsJson: null,
+    abVariant: null,
+    sessionId: null,
+    stepName: null,
+    stepIndex: null,
+    completedAt: null,
+    funnelVersion: null,
+    ...overrides,
+  };
+}
+
 const originalFetch = globalThis.fetch;
 let mockFetch: ReturnType<typeof mock>;
 
@@ -1184,4 +1221,121 @@ describe("UsageTelemetryReporter", () => {
     expect(idCalls.length).toBeGreaterThanOrEqual(1);
     expect(idCalls[idCalls.length - 1][1]).toBe(lastRow.id);
   });
+
+  // -------------------------------------------------------------------------
+  // Onboarding / activation funnel events
+  // -------------------------------------------------------------------------
+
+  test("activation onboarding row serializes funnel fields + deterministic daemon_event_id", async () => {
+    mockQueryUnreportedUsageEvents.mockReturnValue([]);
+    const sessionId = "sess-activation-1";
+    const stepName = "activation_moment_1_complete";
+    mockQueryUnreportedOnboardingEvents.mockReturnValue([
+      makeOnboardingEvent({
+        id: "onb-activation-1",
+        screen: stepName,
+        abVariant: "variant-a",
+        sessionId,
+        stepName,
+        stepIndex: 1,
+        completedAt: "2026-06-06T00:00:00.000Z",
+        funnelVersion: ACTIVATION_FUNNEL_VERSION,
+      }),
+    ]);
+    mockFetch.mockImplementation(() =>
+      Promise.resolve(new Response('{"accepted":1}', { status: 200 })),
+    );
+
+    const reporter = new UsageTelemetryReporter();
+    await reporter.flush();
+
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+    const body = JSON.parse(
+      (mockFetch.mock.calls[0] as [string, RequestInit])[1].body as string,
+    );
+    expect(body.events.length).toBe(1);
+    expect(body.events[0]).toMatchObject({
+      type: "onboarding",
+      session_id: sessionId,
+      step_name: stepName,
+      step_index: 1,
+      completed_at: "2026-06-06T00:00:00.000Z",
+      funnel_version: "activation_v1_2026_06",
+      daemon_event_id: buildActivationDaemonEventId(sessionId, stepName),
+    });
+  });
+
+  test("activation daemon_event_id is keyed on the row's stored funnel_version, not the binary constant", async () => {
+    mockQueryUnreportedUsageEvents.mockReturnValue([]);
+    const sessionId = "sess-activation-old";
+    const stepName = "activation_moment_1_complete";
+    // A row recorded under an OLDER funnel version, queued across an upgrade.
+    const oldVersion = "activation_v0_2026_05";
+    expect(oldVersion).not.toBe(ACTIVATION_FUNNEL_VERSION);
+    mockQueryUnreportedOnboardingEvents.mockReturnValue([
+      makeOnboardingEvent({
+        id: "onb-activation-old",
+        screen: stepName,
+        abVariant: "variant-a",
+        sessionId,
+        stepName,
+        stepIndex: 1,
+        completedAt: "2026-05-01T00:00:00.000Z",
+        funnelVersion: oldVersion,
+      }),
+    ]);
+    mockFetch.mockImplementation(() =>
+      Promise.resolve(new Response('{"accepted":1}', { status: 200 })),
+    );
+
+    const reporter = new UsageTelemetryReporter();
+    await reporter.flush();
+
+    const body = JSON.parse(
+      (mockFetch.mock.calls[0] as [string, RequestInit])[1].body as string,
+    );
+    expect(body.events[0]).toMatchObject({
+      funnel_version: oldVersion,
+      daemon_event_id: buildActivationDaemonEventId(
+        sessionId,
+        stepName,
+        oldVersion,
+      ),
+    });
+    // Guard: the id must carry the row's version, not the binary constant.
+    expect(body.events[0].daemon_event_id).toBe(
+      `${oldVersion}:${sessionId}:${stepName}`,
+    );
+  });
+
+  test("legacy onboarding row keeps daemon_event_id: e.id and omits funnel fields", async () => {
+    mockQueryUnreportedUsageEvents.mockReturnValue([]);
+    mockQueryUnreportedOnboardingEvents.mockReturnValue([
+      makeOnboardingEvent({
+        id: "onb-legacy-1",
+        screen: "tools",
+        toolsJson: JSON.stringify(["calendar"]),
+      }),
+    ]);
+    mockFetch.mockImplementation(() =>
+      Promise.resolve(new Response('{"accepted":1}', { status: 200 })),
+    );
+
+    const reporter = new UsageTelemetryReporter();
+    await reporter.flush();
+
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+    const body = JSON.parse(
+      (mockFetch.mock.calls[0] as [string, RequestInit])[1].body as string,
+    );
+    expect(body.events.length).toBe(1);
+    const e = body.events[0];
+    expect(e.type).toBe("onboarding");
+    expect(e.daemon_event_id).toBe("onb-legacy-1");
+    expect(e.session_id).toBeUndefined();
+    expect(e.step_name).toBeUndefined();
+    expect(e.step_index).toBeUndefined();
+    expect(e.completed_at).toBeUndefined();
+    expect(e.funnel_version).toBeUndefined();
+  });
 });

package/src/telemetry/usage-telemetry-reporter.ts

@@ -28,6 +28,10 @@ import { VellumPlatformClient } from "../platform/client.js";
 import { getDeviceId } from "../util/device-id.js";
 import { getLogger } from "../util/logger.js";
 import { APP_VERSION } from "../version.js";
+import {
+  type ActivationStepName,
+  buildActivationDaemonEventId,
+} from "./activation-funnel.js";
 import type { TelemetryEvent, TurnTelemetryClientInfo } from "./types.js";
 
 const log = getLogger("usage-telemetry");
@@ -337,7 +341,22 @@ export class UsageTelemetryReporter {
         ...onboardingEvents.map(
           (e): TelemetryEvent => ({
             type: "onboarding",
-            daemon_event_id: e.id,
+            // Wire-only override for activation rows: a deterministic id keyed
+            // on funnel_version/session/step lets dbt collapse a moment that
+            // fires more than once. Key on the ROW's stored `funnelVersion`
+            // (not the binary's current constant) so rows recorded under an
+            // older version — flushed offline or after an upgrade — keep a
+            // stable id and still collapse with already-ingested rows. The
+            // SQLite watermark cursor still uses `e.id`/`e.createdAt`, so this
+            // override is checkpoint-safe.
+            daemon_event_id:
+              e.sessionId && e.stepName && e.funnelVersion
+                ? buildActivationDaemonEventId(
+                    e.sessionId,
+                    e.stepName as ActivationStepName,
+                    e.funnelVersion,
+                  )
+                : e.id,
             recorded_at: e.createdAt,
             screen: e.screen,
             ...(e.toolsJson ? { tools: JSON.parse(e.toolsJson) } : {}),
@@ -350,6 +369,12 @@ export class UsageTelemetryReporter {
               ? { google_scopes: JSON.parse(e.googleScopesJson) }
               : {}),
             ...(e.abVariant ? { ab_variant: e.abVariant } : {}),
+            // Activation funnel fields — only present on activation rows.
+            ...(e.sessionId ? { session_id: e.sessionId } : {}),
+            ...(e.stepName ? { step_name: e.stepName } : {}),
+            ...(e.stepIndex != null ? { step_index: e.stepIndex } : {}),
+            ...(e.completedAt ? { completed_at: e.completedAt } : {}),
+            ...(e.funnelVersion ? { funnel_version: e.funnelVersion } : {}),
             // Onboarding events fall back to the envelope `assistant_version`
             // — same upload-time attribution risk as before this PR. Adding
             // the record-time column to `onboarding_events` (#30733) is a

package/src/tools/acp/context.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared ToolContext accessors for the ACP tools.
+ */
+
+import type { ServerMessage } from "../../daemon/message-protocol.js";
+import type { ToolContext } from "../types.js";
+
+/**
+ * Narrows `ToolContext.sendToClient` to the `ServerMessage` sender the ACP
+ * session manager expects. ToolContext types the callback against an
+ * index-signature message shape (`{ type: string; [key: string]: unknown }`)
+ * that ServerMessage's union members don't structurally satisfy, so the
+ * cast lives here once instead of being duplicated at every ACP tool call
+ * site.
+ */
+export function getSendToClient(
+  context: ToolContext,
+): ((msg: ServerMessage) => void) | undefined {
+  return context.sendToClient as ((msg: ServerMessage) => void) | undefined;
+}

package/src/tools/acp/list-agents.test.ts

@@ -33,31 +33,17 @@ beforeEach(() => {
 // ---------------------------------------------------------------------------
 
 describe("executeAcpListAgents", () => {
-  test("returns disabled hint when ACP is disabled", async () => {
-    config.setConfig({ enabled: false });
-
-    const result = await executeAcpListAgents({}, makeContext());
-
-    expect(result.isError).toBe(false);
-    const parsed = JSON.parse(result.content as string);
-    expect(parsed.enabled).toBe(false);
-    // Pulls from the shared ACP_DISABLED_HINT constant exported by
-    // resolve-agent.ts. The exact wording is checked in resolve-agent.test.ts.
-    expect(parsed.hint).toContain("acp.enabled");
-    expect(parsed.hint).toContain("config.json");
-  });
-
-  test("enabled, no user config: both defaults present with source 'default' and available based on Bun.which", async () => {
+  test("no user config: all defaults present with source 'default' and available based on Bun.which", async () => {
     config.setConfig({ agents: {} });
 
     const result = await executeAcpListAgents({}, makeContext());
 
     expect(result.isError).toBe(false);
     const parsed = JSON.parse(result.content as string);
-    expect(parsed.enabled).toBe(true);
     expect(parsed.agents.map((a: { id: string }) => a.id)).toEqual([
       "claude",
       "codex",
+      "gemini",
     ]);
     for (const entry of parsed.agents) {
       expect(entry.source).toBe("default");
@@ -67,7 +53,7 @@ describe("executeAcpListAgents", () => {
     }
   });
 
-  test("enabled, user overrides claude: claude has source 'config' and the user's command", async () => {
+  test("user overrides claude: claude has source 'config' and the user's command", async () => {
     config.setConfig({
       agents: {
         claude: {
@@ -82,7 +68,6 @@ describe("executeAcpListAgents", () => {
 
     expect(result.isError).toBe(false);
     const parsed = JSON.parse(result.content as string);
-    expect(parsed.enabled).toBe(true);
 
     const claude = parsed.agents.find((a: { id: string }) => a.id === "claude");
     expect(claude.source).toBe("config");
@@ -106,7 +91,12 @@ describe("executeAcpListAgents", () => {
     const codex = parsed.agents.find((a: { id: string }) => a.id === "codex");
     expect(codex.available).toBe(false);
     expect(codex.unavailableReason).toBe("'codex-acp' is not on PATH");
-    expect(codex.setupHint).toBe("npm i -g @zed-industries/codex-acp");
+    expect(codex.setupHint).toBe("bun add -g @zed-industries/codex-acp");
+
+    const gemini = parsed.agents.find((a: { id: string }) => a.id === "gemini");
+    expect(gemini.available).toBe(false);
+    expect(gemini.unavailableReason).toBe("'gemini' is not on PATH");
+    expect(gemini.setupHint).toBe("bun add -g @google/gemini-cli");
 
     const claude = parsed.agents.find((a: { id: string }) => a.id === "claude");
     expect(claude.available).toBe(true);

package/src/tools/acp/list-agents.ts

@@ -1,31 +1,19 @@
-import { ACP_DISABLED_HINT, listAcpAgents } from "../../acp/resolve-agent.js";
+import { listAcpAgents } from "../../acp/resolve-agent.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
 
 /**
  * Lists ACP coding agents available to spawn (configured + bundled defaults),
  * marking each with its source (`config` vs `default`), whether the agent's
  * binary is on PATH, and an install hint when missing.
- *
- * When `acp.enabled: false`, returns a single hint instructing the user to
- * enable ACP — no agent list is surfaced because none can run.
  */
 export async function executeAcpListAgents(
   _input: Record<string, unknown>,
   _context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const { enabled, agents } = listAcpAgents();
-  if (!enabled) {
-    return {
-      content: JSON.stringify({
-        enabled: false,
-        hint: ACP_DISABLED_HINT,
-      }),
-      isError: false,
-    };
-  }
+  const { agents } = listAcpAgents();
 
   return {
-    content: JSON.stringify({ enabled, agents }),
+    content: JSON.stringify({ agents }),
     isError: false,
   };
 }