@vellumai/assistant 0.10.9 → 0.10.10-dev.202607162206.d08e98e

package/src/telemetry/telemetry-events-outbox.test.ts

@@ -10,6 +10,7 @@ import {
 } from "./__tests__/outbox-test-harness.js";
 import {
   deleteTelemetryOutboxEvents,
+  deleteTelemetryOutboxEventsBefore,
   discardPendingTelemetryOutboxEvents,
   insertTelemetryOutboxEvent,
   insertTelemetryOutboxEvents,
@@ -290,7 +291,7 @@ describe("telemetry-events-outbox", () => {
     );
   });
 
-  test("recordTelemetryEvent honors the share_analytics opt-out", () => {
+  test("recordTelemetryEvent honors a confirmed share_analytics opt-out", () => {
     setShareAnalytics(false);
     expect(
       recordTelemetryEvent("watchdog", {
@@ -302,6 +303,19 @@ describe("telemetry-events-outbox", () => {
     expect(queryTelemetryOutboxBatch("watchdog", 10)).toEqual([]);
   });
 
+  test("recordTelemetryEvent records while consent is unknown (cold cache)", () => {
+    setShareAnalytics("unknown");
+    const recorded = recordTelemetryEvent("watchdog", {
+      check_name: "c",
+      value: null,
+      detail: null,
+    });
+    expect(recorded).not.toBeNull();
+    expect(queryTelemetryOutboxBatch("watchdog", 10).map((r) => r.id)).toEqual([
+      recorded!.id,
+    ]);
+  });
+
   test("recordTelemetryEvent returns null when the telemetry DB is unavailable", () => {
     withTelemetryDbUnavailable(() => {
       expect(
@@ -315,6 +329,37 @@ describe("telemetry-events-outbox", () => {
     expect(queryTelemetryOutboxBatch("watchdog", 10)).toEqual([]);
   });
 
+  test("prune deletes rows strictly older than the cutoff across every name and returns the count", () => {
+    insert("evt-old-life", 1000, "lifecycle");
+    insert("evt-old-watch", 1500, "watchdog");
+    insert("evt-at-cutoff", 2000, "lifecycle");
+    insert("evt-fresh", 3000, "lifecycle");
+
+    expect(deleteTelemetryOutboxEventsBefore(2000)).toBe(2);
+
+    // Strictly-before semantics: the row AT the cutoff is retained.
+    expect(allIds()).toEqual(["evt-at-cutoff", "evt-fresh"]);
+    expect(queryTelemetryOutboxBatch("watchdog", 10)).toEqual([]);
+  });
+
+  test("prune with nothing expired deletes nothing and returns 0", () => {
+    insert("evt-1", 5000);
+
+    expect(deleteTelemetryOutboxEventsBefore(5000)).toBe(0);
+
+    expect(allIds()).toEqual(["evt-1"]);
+  });
+
+  test("prune returns 0 when the telemetry DB is unavailable", () => {
+    insert("evt-1", 1000);
+
+    withTelemetryDbUnavailable(() => {
+      expect(deleteTelemetryOutboxEventsBefore(2000)).toBe(0);
+    });
+
+    expect(allIds()).toEqual(["evt-1"]);
+  });
+
   test("discards all pending rows for one name only", () => {
     insert("evt-1", 1000, "lifecycle");
     insert("evt-2", 2000, "lifecycle");

package/src/telemetry/telemetry-events-outbox.ts

@@ -9,9 +9,9 @@
 import { asc, eq, inArray } from "drizzle-orm";
 import { v4 as uuid } from "uuid";
 
-import { getTelemetryDb } from "../persistence/db-connection.js";
+import { getSqliteFrom, getTelemetryDb } from "../persistence/db-connection.js";
 import { telemetryEvents } from "../persistence/schema/index.js";
-import { getCachedShareAnalytics } from "../platform/consent-cache.js";
+import { getRawShareAnalytics } from "../platform/consent-cache.js";
 import { APP_VERSION } from "../version.js";
 import type {
   OutboxTelemetryEventName,
@@ -23,6 +23,14 @@ import type {
 /** Ids per DELETE chunk — stays under SQLite's bound-variable limit. */
 const DELETE_CHUNK_SIZE = 500;
 
+/**
+ * Max age of a pending outbox row. The reporter prunes older rows at the
+ * start of every flush cycle, in every consent state — this is what bounds
+ * the unknown-consent buffering (a permanently-unknown state never resolves,
+ * and a row this stale is worthless telemetry anyway).
+ */
+export const OUTBOX_MAX_ROW_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+
 /** One pending outbox row; `payload` is the wire `TelemetryEvent` JSON. */
 export interface TelemetryOutboxRow {
   id: string;
@@ -82,19 +90,25 @@ export function insertTelemetryOutboxEvent(
 /**
  * Lower-level record escape hatch: for payloads that need the record-time
  * `(id, createdAt)` inside type-specific fields (onboarding's activation
- * `daemon_event_id` override and `completed_at`). Gates on usage-data
- * consent, generates the outbox row identity, builds the wire payload via
- * `buildEvent` (which owns all stamping), and inserts. Returns the generated
- * row identity, or null when usage data collection is disabled (the event is
- * dropped to honor the opt-out) or the telemetry DB is unavailable (degraded
- * mode). Prefer `recordTelemetryEvent` when the payload doesn't need them.
+ * `daemon_event_id` override and `completed_at`). Drops only on a confirmed
+ * `share_analytics` opt-out — the record-time drop is a privacy courtesy for
+ * known opt-outs. While consent is unknown (cold cache, no platform session)
+ * the event is recorded: dropping on an unresolved state would permanently
+ * destroy data, and consent is enforced again at flush time. Unknown-state
+ * buffering is bounded — the reporter prunes rows older than
+ * {@link OUTBOX_MAX_ROW_AGE_MS} each flush cycle. Generates the
+ * outbox row identity, builds the wire payload via `buildEvent` (which owns
+ * all stamping), and inserts. Returns the generated row identity, or null
+ * when dropped for the opt-out or when the telemetry DB is unavailable
+ * (degraded mode). Prefer `recordTelemetryEvent` when the payload doesn't
+ * need them.
  */
 export function recordTelemetryOutboxEvent(
   name: string,
   buildEvent: (id: string, createdAt: number) => TelemetryEvent,
   opts?: { conversationId?: string | null },
 ): { id: string; createdAt: number } | null {
-  if (!getCachedShareAnalytics()) {
+  if (getRawShareAnalytics() === false) {
     return null;
   }
   const id = uuid();
@@ -176,6 +190,25 @@ export function deleteTelemetryOutboxEvents(ids: string[]): void {
   }
 }
 
+/**
+ * Delete rows recorded before `cutoffCreatedAt`, across every event name
+ * (age-bound prune). Returns the deleted row count; 0 when the telemetry DB
+ * is unavailable.
+ */
+export function deleteTelemetryOutboxEventsBefore(
+  cutoffCreatedAt: number,
+): number {
+  const db = getTelemetryDb();
+  if (!db) {
+    return 0;
+  }
+  // Raw statement: drizzle's bun-sqlite `.run()` is typed void, and the
+  // prune's only output is the changed-row count.
+  return getSqliteFrom(db)
+    .prepare("DELETE FROM telemetry_events WHERE created_at < ?")
+    .run(cutoffCreatedAt).changes;
+}
+
 /** Drop all pending rows for one event name (telemetry opt-out). */
 export function discardPendingTelemetryOutboxEvents(name: string): void {
   const db = getTelemetryDb();
@@ -184,3 +217,21 @@ export function discardPendingTelemetryOutboxEvents(name: string): void {
   }
   db.delete(telemetryEvents).where(eq(telemetryEvents.name, name)).run();
 }
+
+/**
+ * Distinct event names with at least one pending row in the outbox. Used by the
+ * orphan-drain source to find rows whose type is no longer in the wire contract
+ * (e.g. recorded before the platform removed/renamed a type) so they can be
+ * flushed instead of stranded. Empty when the telemetry DB is unavailable.
+ */
+export function queryDistinctOutboxEventNames(): string[] {
+  const db = getTelemetryDb();
+  if (!db) {
+    return [];
+  }
+  return db
+    .selectDistinct({ name: telemetryEvents.name })
+    .from(telemetryEvents)
+    .all()
+    .map((row) => row.name);
+}

package/src/telemetry/telemetry-wire-source.json

@@ -1,4 +1,4 @@
 {
   "sourceRepo": "vellum-ai/vellum-assistant-platform",
-  "sourceSha": "701c9110672aa6448798b972c93f1b7d34f56dd6"
+  "sourceSha": "d14fd61263565016fa675fb99bfa2371d78f8ff4"
 }

package/src/telemetry/telemetry-wire-validation.ts

@@ -14,7 +14,7 @@
  * events.
  */
 
-import type { z } from "zod";
+import { z } from "zod";
 
 import type { getLogger } from "../util/logger.js";
 import { telemetryEventSchema } from "./telemetry-wire.generated.js";
@@ -26,13 +26,24 @@ type Logger = ReturnType<typeof getLogger>;
  * discriminated union (`.options` + each member's `type` literal), so a new
  * generated event type is validated with zero hand edits here.
  */
-const wireSchemaByType: ReadonlyMap<string, z.ZodType> = new Map(
+const wireSchemaByType: ReadonlyMap<string, z.ZodObject> = new Map(
   telemetryEventSchema.options.map((option) => [
     option.shape.type.value,
     option,
   ]),
 );
 
+/**
+ * Base fields stamped by the daemon at record time, never supplied by a client.
+ * Stripped when deriving the client-facing `fields` schema for a wire type.
+ */
+const TELEMETRY_BASE_FIELD_KEYS = {
+  type: true,
+  daemon_event_id: true,
+  recorded_at: true,
+  assistant_version: true,
+} as const;
+
 /**
  * Event types already warned about as absent from the wire contract.
  * Unknown-type warnings are rate-limited to once per process per type —
@@ -46,6 +57,32 @@ export function resetUnknownTypeWarningsForTests(): void {
   warnedUnknownTypes.clear();
 }
 
+/**
+ * Per-event-type wire schema for one `type` discriminant, or undefined when the
+ * platform contract has no serializer for it. Lets the client-ingest boundary
+ * (`POST /v1/telemetry/ingest`) reject a malformed payload up front with the
+ * same schema pre-flush validation would have logged a silent drop for.
+ */
+export function getWireSchemaForType(type: string): z.ZodObject | undefined {
+  return wireSchemaByType.get(type);
+}
+
+/**
+ * Client-facing `fields` schema for a wire type: the wire object minus the
+ * daemon-stamped base fields. Rebuilt from `.shape` because `.omit()` rejects
+ * the refined wire schemas; this drops the claims/suggestions byte-bound
+ * superRefines, which aren't expressible in the request type anyway — the
+ * handler still validates the assembled event against the full wire schema
+ * ({@link getWireSchemaForType}) for those bounds. Undefined when the platform
+ * contract has no serializer for `type`.
+ */
+export function getWireFieldsSchema(type: string): z.ZodObject | undefined {
+  const schema = wireSchemaByType.get(type);
+  return schema
+    ? z.object(schema.shape).omit(TELEMETRY_BASE_FIELD_KEYS)
+    : undefined;
+}
+
 /**
  * Render a zod issue path for logging without leaking dynamic record keys.
  *

package/src/telemetry/telemetry-wire.generated.ts

@@ -332,6 +332,12 @@ export const onboardingResearchTelemetryEventSchema = z
     assistant_version: z.string().trim().min(1).max(64).nullable().optional(),
     conversation_id: z.string().trim().min(1).max(64).nullable().optional(),
     status: z.string().trim().min(1).max(32),
+    self_reported_occupation: z.string().max(256).nullable().optional(),
+    self_reported_hobbies: z
+      .array(z.string().trim().min(1).max(128))
+      .max(32)
+      .optional(),
+    self_reported_timezone: z.string().max(64).nullable().optional(),
     claims: z.array(jsonValueSchema).max(20),
     claim_count: z.number().int().min(0),
     claims_confident: z.number().int().min(0),
@@ -427,6 +433,8 @@ export type TelemetryIngestRequest = z.infer<
 
 export const telemetryIngestResponseSchema = z.object({
   accepted: z.number().int(),
+  persisted: z.number().int(),
+  dropped: z.record(z.string(), jsonValueSchema),
 });
 export type TelemetryIngestResponse = z.infer<
   typeof telemetryIngestResponseSchema

package/src/telemetry/tool-audit.ts

@@ -14,16 +14,19 @@
  *   - `logToolFailure` emits the operator-facing failure log.
  *
  * The telemetry-only columns (payload sizes + model attribution) are the
- * single write-time privacy gate for `tool_executed` telemetry: when usage
- * data collection is disabled they persist as NULL, which the projection's
- * `arg_bytes IS NOT NULL` filter excludes permanently. The audit fields
+ * single write-time privacy gate for `tool_executed` telemetry: on a confirmed
+ * `share_analytics` opt-out they persist as NULL, which the projection's
+ * `arg_bytes IS NOT NULL` filter excludes permanently. An unknown consent
+ * state (cold cache) populates the columns — NULLing them would destroy the
+ * data irreversibly, and consent is enforced again at flush time and platform
+ * ingest, so opted-out rows never leave the device. The audit fields
  * themselves (tool name, decision, redacted input/result previews, duration)
  * are unaffected — `tool_invocations` is a local always-on audit log.
  */
 
 import { isAllowDecision, type UserDecision } from "../permissions/types.js";
 import { recordLifecycleEvent } from "../persistence/lifecycle-events-store.js";
-import { getCachedShareAnalytics } from "../platform/consent-cache.js";
+import { getRawShareAnalytics } from "../platform/consent-cache.js";
 import { redactJsonStringLeaves } from "../security/redact-json.js";
 import { redactSensitiveFields } from "../security/redaction.js";
 import { redactSecrets } from "../security/secret-scanner.js";
@@ -257,17 +260,20 @@ const NULL_TELEMETRY_COLUMNS: TelemetryColumns = {
 };
 
 /**
- * Telemetry-only columns (payload sizes + model attribution). When usage data
- * collection is disabled the columns persist as NULL, which the projection's
- * `arg_bytes IS NOT NULL` filter excludes permanently — the same mechanism
- * that excludes legacy pre-migration rows (see tool-executed-events-store.ts).
+ * Telemetry-only columns (payload sizes + model attribution). NULLed only on a
+ * confirmed `share_analytics` opt-out — the projection's `arg_bytes IS NOT
+ * NULL` filter excludes NULL rows permanently (the same mechanism that
+ * excludes legacy pre-migration rows, see tool-executed-events-store.ts), so
+ * an unknown consent state (cold cache) must populate the columns rather than
+ * destroy them. Consent is enforced again at flush time and platform ingest,
+ * so opted-out rows never ship.
  */
 function telemetryColumns(
   attribution: UsageAttributionSnapshot | null,
   rawInput: string,
   resultBytes: number,
 ): TelemetryColumns {
-  if (!getCachedShareAnalytics()) {
+  if (getRawShareAnalytics() === false) {
     return NULL_TELEMETRY_COLUMNS;
   }
   return {

package/src/telemetry/tool-executed-events-store.test.ts

@@ -5,7 +5,7 @@ import { beforeEach, describe, expect, mock, test } from "bun:test";
 let shareAnalytics = true;
 
 mock.module("../platform/consent-cache.js", () => ({
-  getCachedShareAnalytics: () => shareAnalytics,
+  getRawShareAnalytics: () => shareAnalytics,
 }));
 
 import {

package/src/telemetry/turn-events-store.ts

@@ -55,6 +55,21 @@ export interface TurnEvent {
    * and should never appear on a user-message row.
    */
   channelId: string | null;
+  /**
+   * Send-source tag for messages the UI sent on the user's behalf
+   * (`"nav_redirect"` — a navigation shortcut redirected the user into
+   * chat with a pre-filled message). Sourced from
+   * `messages.metadata.userMessageSource`, stamped by `handleSendMessage`
+   * when the request body carries `source`. Null for hand-typed messages
+   * and rows predating the field. Lets activation-funnel analytics
+   * separate UI-initiated turns from organic ones.
+   *
+   * Daemon-side projection only for now: the platform's turn serializer
+   * does not yet accept a `source` wire field, so `turnSource` must not
+   * emit it until the platform serializer lands and the wire sync PR
+   * updates `telemetry-wire.generated.ts` (see `src/telemetry/AGENTS.md`).
+   */
+  source: string | null;
   /**
    * Flexible client metadata stashed under `messages.metadata.client` by
    * the HTTP header middleware. Carries optional `browserFamily`,
@@ -160,6 +175,11 @@ export function queryUnreportedTurnEvents(
       >`json_extract(${messages.metadata}, '$.userMessageChannel')`.as(
         "channel_id",
       ),
+      source: sql<
+        string | null
+      >`json_extract(${messages.metadata}, '$.userMessageSource')`.as(
+        "source",
+      ),
       clientMetadata: sql<
         string | null
       >`json_extract(${messages.metadata}, '$.client')`.as("client_metadata"),

package/src/telemetry/types.ts

@@ -1,6 +1,7 @@
 import type { LLMCallSite } from "../config/schemas/llm.js";
 import type { UsageAttributionProfileSource } from "../usage/types.js";
 import type * as wire from "./telemetry-wire.generated.js";
+import { telemetryEventSchema } from "./telemetry-wire.generated.js";
 import type { TurnOutcome } from "./turn-outcome.js";
 
 /** Base fields present on every telemetry event. */
@@ -464,8 +465,8 @@ export interface OnboardingResearchSuggestion {
  * settled result during onboarding. Client-orchestrated: the web client
  * knows exactly when the turn completes and what it produced (claims,
  * suggestions, plugin picks), and reports it once via
- * `POST /v1/telemetry/onboarding-research` — the daemon never detects this
- * turn on its own.
+ * `POST /v1/telemetry/ingest` (as a client-reportable type) — the daemon
+ * never detects this turn on its own.
  *
  * Carries both the raw claim/suggestion text (+ source URLs) and structural
  * counts by confidence tier, so downstream consumers can aggregate cheaply
@@ -475,6 +476,14 @@ export interface OnboardingResearchTelemetryEvent extends TelemetryEventBase {
   type: "onboarding_research";
   conversation_id: string | null;
   status: "done" | "error";
+  /**
+   * The onboarding-form values the turn was run ON (its INPUT), as distinct
+   * from the inferred `claims` below (its OUTPUT). Excludes the user's name by
+   * design. Optional — an older web client omits them.
+   */
+  self_reported_occupation?: string;
+  self_reported_hobbies?: string[];
+  self_reported_timezone?: string;
   claims: OnboardingResearchClaim[];
   claim_count: number;
   claims_confident: number;
@@ -664,18 +673,42 @@ type _extensionsDontCollide = AssertNoWireCollision<
  * change once shipped. The watermark-flushed types (`llm_usage`, `turn`,
  * `tool_executed`) live on their own tables and are deliberately excluded.
  */
-export const OUTBOX_TELEMETRY_EVENT_NAMES = [
-  "lifecycle",
-  "onboarding",
-  "auth_fallback",
-  "skill_loaded",
-  "watchdog",
-  "config_setting",
-  "onboarding_research",
+/**
+ * Types NOT on the generic `telemetry_events` outbox — the high-volume events
+ * flushed from their own SQLite tables by a watermark source
+ * (`telemetry-event-sources.ts`). This is the ONLY hand-maintained partition
+ * fact; every other wire event type is outbox-backed by default. Add a name
+ * here only when a new type gets its own dedicated table.
+ */
+export const WATERMARK_TELEMETRY_EVENT_NAMES = [
+  "llm_usage",
+  "turn",
+  "tool_executed",
 ] as const;
 
-export type OutboxTelemetryEventName =
-  (typeof OUTBOX_TELEMETRY_EVENT_NAMES)[number];
+export type WatermarkTelemetryEventName =
+  (typeof WATERMARK_TELEMETRY_EVENT_NAMES)[number];
+
+/**
+ * Event names backed by the `telemetry_events` outbox: every wire event type
+ * that is not watermark-flushed. Derived from the generated wire contract, so a
+ * new event type added on the platform side flows onto the outbox — and gets a
+ * flush source (`telemetry-event-sources.ts`) and a fully-typed
+ * `recordTelemetryEvent` call — with NO edit here. Each name doubles as the
+ * wire `type` discriminant and the flush-group key.
+ */
+export type OutboxTelemetryEventName = Exclude<
+  keyof wire.WireEventMap,
+  WatermarkTelemetryEventName
+>;
+
+export const OUTBOX_TELEMETRY_EVENT_NAMES: readonly OutboxTelemetryEventName[] =
+  telemetryEventSchema.options
+    .map((option) => option.shape.type.value)
+    .filter(
+      (name): name is OutboxTelemetryEventName =>
+        !(WATERMARK_TELEMETRY_EVENT_NAMES as readonly string[]).includes(name),
+    );
 
 /** Wire event type for one outbox event name. */
 export type OutboxTelemetryEventOf<N extends OutboxTelemetryEventName> =