@vellumai/assistant 0.9.1-staging.1 → 0.10.0-staging.2

package/docs/activation-funnel-telemetry.md

@@ -50,8 +50,9 @@ Flow, end to end:
      `assistant/src/telemetry/activation-funnel.ts`;
    - emission is best-effort (wrapped in try/catch) and never blocks or alters
      the surface-action flow;
-   - `recordActivationEvent` respects the `getConfig().collectUsageData` opt-out
-     gate (returns `null` / no row when disabled).
+   - `recordActivationEvent` respects the platform `share_analytics` consent gate
+     via `getCachedShareAnalytics()` (returns `null` / no row when the platform
+     user has not consented; default-off when there is no platform session).
 2. **Reporter flushes** every ~5 min: `usage-telemetry-reporter.ts`
    (`REPORT_INTERVAL_MS = 5 * 60 * 1000`, with a one-time
    `INITIAL_FLUSH_DELAY_MS = 30_000` after startup) POSTs unreported onboarding
@@ -172,22 +173,27 @@ When the flag is ON, the web prechat context selects
 `BOOTSTRAP-ACTIVATION-RAIL.md` as the bootstrap template, and the daemon marks
 the conversation in `activation_sessions` on first build of the system prompt.
 
-### 5.2 Confirm usage-data collection is enabled — and do NOT run in dev mode
-
-Two gates must both be satisfied or no rows reach BigQuery:
-
-1. `recordActivationEvent` no-ops when `config.collectUsageData` is false, so the
-   dev build/config must have usage-data collection enabled, or no rows are
-   written to SQLite.
-2. **Dev mode disables the flush entirely.** `assistant/src/daemon/lifecycle.ts`
-   computes the effective setting as `collectUsageData = !isDevMode &&
-config.collectUsageData`, so when the daemon runs in dev mode (`VELLUM_DEV=1`)
-   the `UsageTelemetryReporter` is never started — rows accumulate in SQLite but
-   are never POSTed, and the "wait/restart for flush" steps below will never
-   reach BigQuery. For an end-to-end smoke test, run the daemon **outside dev
-   mode** (so the reporter starts), or explicitly invoke the reporter's
-   `flush()` via a dev hook. The SQLite rows can still be inspected directly in
-   dev mode, but the BigQuery verification (§6) requires a real flush.
+### 5.2 Confirm share_analytics consent is on — and pick the right daemon mode
+
+Two distinct concerns: whether record-time rows reach SQLite (consent gate), and
+whether those rows reach BigQuery (flush gate, dev-disabled).
+
+1. `recordActivationEvent` no-ops when the platform `share_analytics` consent is
+   off (it reads `getCachedShareAnalytics()`), and the consent is **default-off
+   when there is no platform session**. So the dev session must be signed in to
+   the platform with `share_analytics` consent enabled, or no rows are written to
+   SQLite. The consent cache is refreshed by `startConsentRefresh()` in
+   `assistant/src/daemon/lifecycle.ts`, which runs **regardless of dev mode** — so
+   a dev session signed in with `share_analytics` consent enabled writes
+   record-time rows to SQLite, where they can be inspected directly.
+2. **Dev mode disables the flush entirely.** When the daemon runs in dev mode
+   (`VELLUM_DEV=1`), `assistant/src/daemon/lifecycle.ts` never starts the
+   `UsageTelemetryReporter` — rows accumulate in SQLite (consent permitting) but
+   are never POSTed, and the "wait/restart for flush" steps below will never reach
+   BigQuery. For an end-to-end smoke test, run the daemon **outside dev mode** (so
+   the reporter starts), or explicitly invoke the reporter's `flush()` via a dev
+   hook. The SQLite rows can be inspected directly in dev mode, but the BigQuery
+   verification (§6) requires a real flush.
 
 ### 5.3 Start a fresh activation conversation and capture its id
 

package/node_modules/@vellumai/gateway-client/src/admission-policy-contract.ts

@@ -0,0 +1,97 @@
+/**
+ * Shared admission policy vocabulary used on the gateway→runtime wire.
+ *
+ * Both the gateway (channel admission policy storage + kill switch) and the
+ * runtime (admission-policy stage) consume these values. Keeping the type
+ * here avoids the runtime importing from `gateway/src` and avoids the
+ * vocabulary drift the plan §2.1 flags for the verification-purpose
+ * `trustClass` enum.
+ */
+
+import { z } from "zod";
+
+/**
+ * Per-channel inbound admission policy — ordered from most-restrictive
+ * (`no_one`, hard kill switch) to most-permissive (`strangers`, admits any
+ * sender). See `unverified-contact-role-plan.md` §2.3.
+ */
+export const ADMISSION_POLICY_VALUES = [
+  "no_one",
+  "guardian_only",
+  "trusted_contacts",
+  "any_contact",
+  "strangers",
+] as const;
+
+export type AdmissionPolicy = (typeof ADMISSION_POLICY_VALUES)[number];
+
+export const AdmissionPolicySchema = z.enum(ADMISSION_POLICY_VALUES);
+
+/**
+ * Read-side default applied when a channel has no row in the DB. Matches
+ * today's effective semantics: guardian + active contacts admitted,
+ * strangers denied. See plan §2.2.
+ */
+export const ADMISSION_POLICY_DEFAULT: AdmissionPolicy = "trusted_contacts";
+
+/**
+ * Minimum trust rank required for each policy. Higher rank = more trusted.
+ * `no_one` is 5 — above the maximum guardian rank (4) — so no class is ever
+ * admitted. See plan §2.4 for the rank table.
+ */
+export const ADMISSION_FLOOR: Record<AdmissionPolicy, number> = {
+  no_one: 5,
+  guardian_only: 4,
+  trusted_contacts: 3,
+  any_contact: 2,
+  strangers: 1,
+};
+
+/**
+ * Hard-exempt internal channels — never subject to PUT policy, omitted from
+ * GET list, runtime admission stage short-circuits without floor check.
+ *
+ * `platform` / `a2a` are peer/internal channels with no human-trust model.
+ *
+ * `phone` is NOT exempt — voice ingress enforces the admission floor.
+ *
+ * `vellum` / `whatsapp` are NOT exempt — their floors are still enforced at
+ * runtime — but they are hidden from the configurable UI; see
+ * {@link ADMISSION_POLICY_HIDDEN_CHANNELS}.
+ */
+export const ADMISSION_POLICY_EXEMPT_CHANNELS: ReadonlySet<string> = new Set([
+  "platform",
+  "a2a",
+]);
+
+export function isAdmissionPolicyExemptChannel(channelType: string): boolean {
+  return ADMISSION_POLICY_EXEMPT_CHANNELS.has(channelType);
+}
+
+/**
+ * Channels omitted from the Channel Trust Floors list (GET) and rejected on
+ * PUT/DELETE — managed automatically at their seed default, not user
+ * configurable. Unlike {@link ADMISSION_POLICY_EXEMPT_CHANNELS} they are still
+ * enforced at runtime, so hiding a real inbound channel like `whatsapp` never
+ * silently disables its admission floor check. The startup seed re-pins any
+ * drifted row so a stale floor (e.g. a legacy `no_one`) can't strand a channel
+ * the user can no longer see.
+ *
+ * `vellum` is the local desktop/web client surface; the guardian is always
+ * max-rank there, so the seed default admits them regardless of the floor.
+ */
+export const ADMISSION_POLICY_HIDDEN_CHANNELS: ReadonlySet<string> = new Set([
+  "vellum",
+  "whatsapp",
+]);
+
+export function isAdmissionPolicyHiddenChannel(channelType: string): boolean {
+  return ADMISSION_POLICY_HIDDEN_CHANNELS.has(channelType);
+}
+
+export function isAdmissionPolicy(value: unknown): value is AdmissionPolicy {
+  return (
+    typeof value === "string" &&
+    (ADMISSION_POLICY_VALUES as readonly string[]).includes(value)
+  );
+}

package/node_modules/@vellumai/gateway-client/src/inbound-contract.ts

@@ -12,6 +12,8 @@
 
 import { z } from "zod";
 
+import { AdmissionPolicySchema } from "./admission-policy-contract.js";
+
 // ---------------------------------------------------------------------------
 // Command intent (channel-initiated commands, e.g. Telegram /start)
 // ---------------------------------------------------------------------------
@@ -67,6 +69,14 @@ export const SourceMetadataSchema = z
     /** Slack workspace/team ID. */
     account: z.string().optional(),
 
+    /**
+     * Per-channel inbound admission policy attached by the gateway. The
+     * runtime admission-policy stage enforces the floor against the
+     * resolved trust class; when absent, the runtime falls back to
+     * `ADMISSION_POLICY_DEFAULT` (`trusted_contacts`).
+     */
+    admissionPolicy: AdmissionPolicySchema.optional(),
+
     // Email-specific fields
     /** Email subject line. */
     emailSubject: z.string().optional(),

package/node_modules/@vellumai/gateway-client/src/index.ts

@@ -55,3 +55,18 @@ export type {
 export type { IpcRequest, IpcResponse, Logger } from "./types.js";
 
 export { noopLogger } from "./types.js";
+
+// Admission policy contract (gateway → daemon) — Zod schemas + derived types + channel sets
+export {
+  ADMISSION_FLOOR,
+  ADMISSION_POLICY_DEFAULT,
+  ADMISSION_POLICY_EXEMPT_CHANNELS,
+  ADMISSION_POLICY_HIDDEN_CHANNELS,
+  ADMISSION_POLICY_VALUES,
+  AdmissionPolicySchema,
+  isAdmissionPolicy,
+  isAdmissionPolicyExemptChannel,
+  isAdmissionPolicyHiddenChannel,
+} from "./admission-policy-contract.js";
+
+export type { AdmissionPolicy } from "./admission-policy-contract.js";