@vellumai/assistant 0.11.9-dev.202609041515.59c84dd → 0.11.9-dev.202609041713.aefee3e

package/Dockerfile

@@ -33,16 +33,6 @@ COPY --parents packages/*/package.json ./
 RUN bun install --frozen-lockfile --ignore-scripts \
     --filter='./assistant' --filter='./assistant/src/api'
 
-# The repo-root .dockerignore decides which skills (and files) ship.
-COPY skills ./skills
-RUN set -eu; for pkg in /app/skills/*/package.json; do \
-      [ -e "$pkg" ] || continue; \
-      dir="$(dirname "$pkg")"; \
-      echo "Installing dependencies for $dir"; \
-      (cd "$dir" && (bun install --frozen-lockfile 2>/dev/null || bun install)); \
-    done
-
-
 # Final stage
 FROM debian:trixie-slim@sha256:4ffb3a1511099754cddc70eb1b12e50ffdb67619aa0ab6c13fcd800a78ef7c7a AS runner
 
@@ -131,6 +121,9 @@ COPY packages/twilio-client /app/packages/twilio-client
 
 COPY assistant /app/assistant
 
+# The repo-root .dockerignore decides which skills (and files) ship.
+COPY skills /app/skills
+
 # Materialize the git-ignored offline plugin manifest from its canonical source.
 # `assistant/src/cli/lib/plugin-catalog-local.ts` statically imports this JSON
 # (loaded even when platform features are enabled), so it must exist in the image

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.11.9-dev.202609041515.59c84dd",
+  "version": "0.11.9-dev.202609041713.aefee3e",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/calls/voice-session-bridge.ts

@@ -325,6 +325,8 @@ export interface VoiceTurnOptions {
   voiceTelemetry?: {
     sessionId: string;
     client?: ClientOs;
+    /** The control the session was started from (the start frame's `entry`). */
+    entry?: string;
   };
   /** Per-turn control prompt. Undefined uses the phone prompt; null disables it. */
   voiceControlPrompt?: string | null;
@@ -1116,12 +1118,20 @@ export async function startVoiceTurn(
               // path already fills from the same `detectClientOs()` value, so
               // a voice turn reports its platform in the column existing turn
               // analytics read rather than one only voice knows about.
+              //
+              // `voice_entry` is voice's own: which control started the
+              // session the turn belongs to, so per-turn analytics can split
+              // the companion from the app without a join back to the
+              // session row.
               client: {
                 voice: true,
                 voice_session_id: opts.voiceTelemetry.sessionId,
                 ...(opts.voiceTelemetry.client
                   ? { os: opts.voiceTelemetry.client }
                   : {}),
+                ...(opts.voiceTelemetry.entry
+                  ? { voice_entry: opts.voiceTelemetry.entry }
+                  : {}),
               },
             }
           : {}),

package/src/live-voice/__tests__/live-voice-session-telemetry.test.ts

@@ -121,7 +121,30 @@ describe("live-voice session telemetry", () => {
 
     await session.start();
 
-    expect(recordLiveVoiceSessionStarted).toHaveBeenCalledWith("session-123");
+    expect(recordLiveVoiceSessionStarted).toHaveBeenCalledWith({
+      sessionId: "session-123",
+      screen: "started_unknown:unknown",
+    });
+
+    await session.close("client_end");
+  });
+
+  test("stamps the started row with the client and entry the start frame declared", async () => {
+    // The dimension this row exists to carry: the same `macos` client covers
+    // the chat's voice button, the companion's Talk and the voice key, and
+    // only the entry says which one the user reached for.
+    const session = readySession({
+      ...START_FRAME,
+      client: "macos",
+      entry: "companion",
+    });
+
+    await session.start();
+
+    expect(recordLiveVoiceSessionStarted).toHaveBeenCalledWith({
+      sessionId: "session-123",
+      screen: "started_macos:companion",
+    });
 
     await session.close("client_end");
   });
@@ -138,7 +161,10 @@ describe("live-voice session telemetry", () => {
 
     // The denominator of the failure rate: a session rejected before `ready`
     // is exactly the one that must not go missing from the started count.
-    expect(recordLiveVoiceSessionStarted).toHaveBeenCalledWith("session-123");
+    expect(recordLiveVoiceSessionStarted).toHaveBeenCalledWith({
+      sessionId: "session-123",
+      screen: "started_unknown:unknown",
+    });
   });
 
   test("records the close reason and a completed outcome on a clean end", async () => {
@@ -329,4 +355,18 @@ describe("live-voice turn attribution", () => {
 
     expect(options.voiceTelemetry).toEqual({ sessionId: "session-123" });
   });
+
+  test("carries the entry point onto the turn beside the client", async () => {
+    const options = await captureTurnOptions({
+      ...START_FRAME,
+      client: "macos",
+      entry: "voice_key",
+    });
+
+    expect(options.voiceTelemetry).toEqual({
+      sessionId: "session-123",
+      client: "macos",
+      entry: "voice_key",
+    });
+  });
 });

package/src/live-voice/__tests__/protocol.test.ts

@@ -339,6 +339,73 @@ describe("parseLiveVoiceClientTextFrame", () => {
     expect("client" in result.frame).toBe(false);
   });
 
+  test("parses the entry point from the start frame", () => {
+    const result = parseLiveVoiceClientTextFrame(
+      JSON.stringify({
+        type: "start",
+        client: "macos",
+        entry: "companion",
+        audio: { mimeType: "audio/pcm", sampleRate: 24000, channels: 1 },
+      }),
+    );
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+
+    expect(result.frame).toMatchObject({
+      type: "start",
+      client: "macos",
+      entry: "companion",
+    });
+  });
+
+  test("carries an entry token it has never seen, since the clients mint them", () => {
+    // An open set on purpose: a daemon older than the client that sent the
+    // value must carry it through rather than erase it.
+    const result = parseLiveVoiceClientTextFrame(
+      JSON.stringify({
+        type: "start",
+        entry: "some_future_surface",
+        audio: { mimeType: "audio/pcm", sampleRate: 24000, channels: 1 },
+      }),
+    );
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+
+    expect(result.frame).toMatchObject({ entry: "some_future_surface" });
+  });
+
+  test.each([
+    ["not a string", 42],
+    ["empty", ""],
+    ["uppercase", "Companion"],
+    ["punctuation", "companion:talk"],
+    ["over-long", "a".repeat(33)],
+  ])(
+    "drops an off-shape entry (%s) rather than rejecting the session",
+    (_label, entry) => {
+      const result = parseLiveVoiceClientTextFrame(
+        JSON.stringify({
+          type: "start",
+          entry,
+          audio: { mimeType: "audio/pcm", sampleRate: 24000, channels: 1 },
+        }),
+      );
+
+      expect(result.ok).toBe(true);
+      if (!result.ok) {
+        return;
+      }
+
+      expect("entry" in result.frame).toBe(false);
+    },
+  );
+
   test("drops an unrecognized client rather than rejecting the session", () => {
     const result = parseLiveVoiceClientTextFrame(
       JSON.stringify({

package/src/live-voice/live-voice-session.ts

@@ -80,6 +80,7 @@ import { getSubagentManager } from "../subagent/index.js";
 import {
   liveVoiceEndScreen,
   liveVoiceSilenceReason,
+  liveVoiceStartScreen,
 } from "../telemetry/live-voice-funnel.js";
 import { getToolOwner } from "../tools/registry.js";
 import {
@@ -1493,7 +1494,13 @@ export class LiveVoiceSession implements LiveVoiceSessionContract {
     // credentials is precisely the one the failure rate needs to count, and
     // recording the start only once `ready` goes out would hide every such
     // session from both the numerator and the denominator.
-    recordLiveVoiceSessionStarted(this.context.sessionId);
+    recordLiveVoiceSessionStarted({
+      sessionId: this.context.sessionId,
+      screen: liveVoiceStartScreen(
+        this.context.startFrame.client,
+        this.context.startFrame.entry,
+      ),
+    });
 
     if (this.resolveCredentialReadiness) {
       const readiness = await this.resolveCredentialReadiness();
@@ -5262,6 +5269,9 @@ export class LiveVoiceSession implements LiveVoiceSessionContract {
           ...(this.context.startFrame.client
             ? { client: this.context.startFrame.client }
             : {}),
+          ...(this.context.startFrame.entry
+            ? { entry: this.context.startFrame.entry }
+            : {}),
         },
         voiceControlPrompt: buildVoiceControlPrompt(activeTurn, {
           ...(leg.frontDoor !== undefined ? { frontDoor: leg.frontDoor } : {}),

package/src/live-voice/protocol.ts

@@ -135,6 +135,39 @@ export interface LiveVoiceClientStartFrame {
    * load-bearing for what a voice turn may do.
    */
   readonly client?: ClientOs;
+  /**
+   * Which control the session was asked from, as distinct from which client
+   * (`client`) it was asked on. The macOS app alone has three: the chat's
+   * voice button (`composer`), the companion surface's Talk (`companion`),
+   * and the voice key (`voice_key`, or `voice_key_ask` for a hold made over a
+   * selection). `deep_link` is Siri, a widget, the Action Button or a Live
+   * Activity tap, and `cli` the terminal client. Absent from clients that
+   * predate the field.
+   *
+   * Analytics only, exactly like `client`, and unlike `client` an open string
+   * rather than a closed set: the values are minted where the controls are,
+   * in the clients, and a daemon older than the client that sent one must
+   * carry the value through rather than erase it. The parser bounds the shape
+   * instead ({@link parseLiveVoiceEntry}) and drops anything outside it, so a
+   * malformed value costs a chart facet and never the session.
+   */
+  readonly entry?: string;
+}
+
+/**
+ * The shape a start frame's `entry` must have: a short snake_case token.
+ *
+ * The bound is set by where the value lands. The started telemetry row stamps
+ * `started_<client>:<entry>` into a 64-character wire field, and the longest
+ * `ClientOs` is seven characters, so 32 leaves the stamp well inside it.
+ */
+const LIVE_VOICE_ENTRY_PATTERN = /^[a-z][a-z0-9_]{0,31}$/;
+
+/** Parse a start frame's `entry`. Returns `null` for anything off-shape. */
+export function parseLiveVoiceEntry(value: unknown): string | null {
+  return typeof value === "string" && LIVE_VOICE_ENTRY_PATTERN.test(value)
+    ? value
+    : null;
 }
 
 /**
@@ -1088,6 +1121,8 @@ function validateStartFrame(
   // analytics dimension, and failing a session's startup over it would trade a
   // gap in a chart for a user who cannot talk to their assistant.
   const client = parseClientOs(value.client);
+  // Same policy for the same reason: a dimension, not a capability.
+  const entry = parseLiveVoiceEntry(value.entry);
 
   return {
     ok: true,
@@ -1097,6 +1132,7 @@ function validateStartFrame(
         ? { conversationId: value.conversationId }
         : {}),
       ...(client ? { client } : {}),
+      ...(entry ? { entry } : {}),
       audio: audioConfig.frame,
       ...(isLiveVoiceTurnDetectionMode(value.turnDetection)
         ? { turnDetection: value.turnDetection }

package/src/oauth/__tests__/seed-providers-managed.test.ts

@@ -48,6 +48,18 @@ describe("PROVIDER_SEED_DATA managed mode wiring", () => {
     );
     expect(gated).toEqual([]);
 
+    // `selections:read` is documented by Figma but not offered in the app's
+    // OAuth scope list, so requesting it fails the whole authorization. It
+    // stays in availableScopes for BYO apps that do have it.
+    expect(figma.defaultScopes).not.toContain("selections:read");
+    const availableScopes = figma.availableScopes;
+    expect(Array.isArray(availableScopes)).toBe(true);
+    if (Array.isArray(availableScopes)) {
+      expect(availableScopes.map(({ scope }) => scope)).toContain(
+        "selections:read",
+      );
+    }
+
     // GET /v1/me backs both the ping and the identity label.
     expect(figma.defaultScopes).toContain("current_user:read");
   });

package/src/oauth/seed-providers.ts

@@ -980,7 +980,9 @@ export const PROVIDER_SEED_DATA: Record<
     // on it. Enterprise-only and org-admin-only scopes (file_variables:*,
     // library_analytics:read, org:*) are offered but not requested by
     // default, because Figma rejects the whole authorization request if the
-    // app cannot grant a requested scope.
+    // app cannot grant a requested scope. `selections:read` is withheld for
+    // that same reason: it is not offered in the app's OAuth scope list, so
+    // requesting it would fail the entire authorization.
     defaultScopes: [
       "current_user:read",
       "file_content:read",
@@ -995,7 +997,6 @@ export const PROVIDER_SEED_DATA: Record<
       "library_content:read",
       "library_assets:read",
       "team_library_content:read",
-      "selections:read",
     ],
     availableScopes: [
       {

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

@@ -130,9 +130,10 @@ export function recordActivationEvent(params: {
  * `telemetry/live-voice-funnel.ts` for why duration and turn count are derived
  * from that pairing rather than carried as fields.
  *
- * `screen` carries the end reason on the ended event (the started event has no
- * dimension beyond the step itself). Returns null when usage data collection is
- * disabled or the telemetry database is unavailable.
+ * `screen` carries the end reason on the ended event and the originating
+ * client and entry point on the started one (see `liveVoiceStartScreen`).
+ * Returns null when usage data collection is disabled or the telemetry
+ * database is unavailable.
  *
  * **Never throws.** These fire from `LiveVoiceSession.start()` and `.close()`,
  * which are the user's call itself: the outbox insert raises on a telemetry DB
@@ -176,14 +177,19 @@ export function recordLiveVoiceSessionEvent(params: {
   );
 }
 
-/** Record the "a live-voice session was attempted" milestone. */
-export function recordLiveVoiceSessionStarted(
-  sessionId: string,
-): OnboardingEvent | null {
+/**
+ * Record the "a live-voice session was attempted" milestone, with where it
+ * was attempted from.
+ */
+export function recordLiveVoiceSessionStarted(params: {
+  sessionId: string;
+  screen: string;
+}): OnboardingEvent | null {
   return recordLiveVoiceSessionEvent({
     stepName: LIVE_VOICE_STEPS.sessionStarted.stepName,
     stepIndex: LIVE_VOICE_STEPS.sessionStarted.stepIndex,
-    sessionId,
+    sessionId: params.sessionId,
+    screen: params.screen,
   });
 }
 

package/src/telemetry/__tests__/live-voice-funnel.test.ts

@@ -3,8 +3,40 @@ import { describe, expect, it } from "bun:test";
 import {
   liveVoiceEndScreen,
   liveVoiceSilenceReason,
+  liveVoiceStartScreen,
 } from "../live-voice-funnel.js";
 
+describe("liveVoiceStartScreen", () => {
+  it("stamps the client and the entry point", () => {
+    expect(liveVoiceStartScreen("macos", "companion")).toBe(
+      "started_macos:companion",
+    );
+  });
+
+  it("keeps both halves present when a client sends neither", () => {
+    // A query splits the stamp on its colon; a stand-in for a missing half
+    // keeps that split from needing a null branch per side.
+    expect(liveVoiceStartScreen(undefined, undefined)).toBe(
+      "started_unknown:unknown",
+    );
+    expect(liveVoiceStartScreen(null, null)).toBe("started_unknown:unknown");
+  });
+
+  it("stands in for whichever half is missing on its own", () => {
+    expect(liveVoiceStartScreen("ios")).toBe("started_ios:unknown");
+    expect(liveVoiceStartScreen(undefined, "deep_link")).toBe(
+      "started_unknown:deep_link",
+    );
+  });
+
+  it("keeps the longest stamp inside the wire field's 64-char bound", () => {
+    // The parser caps `entry` at 32 characters and the longest `ClientOs` is
+    // `windows`; the stamp built from both must still fit the ingest cap.
+    const longest = liveVoiceStartScreen("windows", "a".repeat(32));
+    expect(longest.length).toBeLessThanOrEqual(64);
+  });
+});
+
 describe("liveVoiceSilenceReason", () => {
   it("blames the transport when the session never went active", () => {
     // Nothing after `ready` can be held against a session that never got

package/src/telemetry/live-voice-funnel.ts

@@ -24,6 +24,7 @@
  * unmatched `started` rows instead of treating them as open-ended sessions.
  */
 
+import type { ClientOs } from "../channels/types.js";
 import type { LiveVoiceSessionCloseReason } from "../live-voice/live-voice-session-manager.js";
 import type { LiveVoiceProtocolErrorCode } from "../live-voice/protocol.js";
 
@@ -116,6 +117,38 @@ export function liveVoiceSilenceReason(signals: {
   return "no_turn";
 }
 
+/**
+ * The half of a start stamp that stands in for a dimension the client did not
+ * send: an older client, or one that sends no identity at all.
+ */
+const LIVE_VOICE_UNATTRIBUTED = "unknown";
+
+/**
+ * The `screen` dimension for a started session: the client it started on and
+ * the control it started from, as `started_<client>:<entry>`.
+ *
+ * Both halves come off the start frame verbatim (`client` is a `ClientOs`;
+ * `entry` is the client's own token, see `protocol.ts`). Both are always
+ * present, with {@link LIVE_VOICE_UNATTRIBUTED} standing in for a missing one,
+ * so a query can split the stamp on its colon without a null branch per half.
+ *
+ * The client rides the started row and not only the turn rows because a
+ * quarter of sessions never produce a turn, and those are the ones the client
+ * dimension is most needed on: "voice did nothing for me" is a per-client
+ * question. Until now those sessions had no client at all (the admin
+ * dashboard's `(no turns)` bucket); this stamp gives every session one.
+ *
+ * The entry is what separates the macOS app's three ways in from each other:
+ * the same `client` covers the chat's voice button, the companion's Talk and
+ * the voice key, and only the entry says which one the user reached for.
+ */
+export function liveVoiceStartScreen(
+  client?: ClientOs | null,
+  entry?: string | null,
+): string {
+  return `started_${client ?? LIVE_VOICE_UNATTRIBUTED}:${entry ?? LIVE_VOICE_UNATTRIBUTED}`;
+}
+
 /**
  * The `screen` dimension for an ended session: how it closed, plus a detail
  * half. That detail is the protocol error code when a failure closed it, or the