@vellumai/assistant 0.11.6 → 0.11.7-staging.2

package/src/stt/__tests__/roles.test.ts

@@ -0,0 +1,152 @@
+/**
+ * Per-consumer STT role selection.
+ *
+ * These cover the two pure functions every consumer routes through: which
+ * `{provider, model}` pair a role names, and which catalog row that pair
+ * resolves to. The resolvers, the config schema and the capability gate all
+ * read the same pair, so a drift here is a drift everywhere.
+ */
+import { describe, expect, test } from "bun:test";
+
+import {
+  sttCatalogKeyForRole,
+  sttRoleCapabilityGap,
+  sttSelectionForRole,
+} from "../roles.js";
+
+describe("sttSelectionForRole", () => {
+  test("a role's own entry wins over the global provider", () => {
+    expect(
+      sttSelectionForRole(
+        {
+          provider: "openai-whisper",
+          roles: { dictation: { provider: "deepgram" } },
+        },
+        "dictation",
+      ),
+    ).toEqual({ provider: "deepgram" });
+  });
+
+  test("an unset role falls back to the global provider and its family", () => {
+    expect(
+      sttSelectionForRole(
+        {
+          provider: "deepgram",
+          providers: { deepgram: { model: "flux" } },
+          roles: { dictation: { provider: "openai-whisper" } },
+        },
+        "liveVoice",
+      ),
+    ).toEqual({ provider: "deepgram", model: "flux" });
+  });
+
+  test("a roleless caller reads the global provider", () => {
+    expect(
+      sttSelectionForRole(
+        {
+          provider: "openai-whisper",
+          roles: { dictation: { provider: "deepgram" } },
+        },
+        undefined,
+      ),
+    ).toEqual({ provider: "openai-whisper" });
+  });
+
+  test("a role override does not inherit the global provider's family", () => {
+    // The override names the whole pair. Carrying `flux` across from the
+    // global would pin the override to a family it never asked for.
+    expect(
+      sttSelectionForRole(
+        {
+          provider: "deepgram",
+          providers: { deepgram: { model: "flux" } },
+          roles: { batch: { provider: "deepgram" } },
+        },
+        "batch",
+      ),
+    ).toEqual({ provider: "deepgram" });
+  });
+});
+
+describe("sttCatalogKeyForRole", () => {
+  test("a role's family selects the variant row", () => {
+    expect(
+      sttCatalogKeyForRole(
+        {
+          provider: "deepgram",
+          roles: { liveVoice: { provider: "deepgram", model: "flux" } },
+        },
+        "liveVoice",
+      ),
+    ).toBe("deepgram-flux");
+  });
+
+  test("two roles on one provider resolve to different rows", () => {
+    const stt = {
+      provider: "deepgram",
+      roles: {
+        liveVoice: { provider: "deepgram", model: "flux" },
+        batch: { provider: "deepgram" },
+      },
+    };
+
+    expect(sttCatalogKeyForRole(stt, "liveVoice")).toBe("deepgram-flux");
+    expect(sttCatalogKeyForRole(stt, "batch")).toBe("deepgram");
+  });
+});
+
+describe("sttRoleCapabilityGap", () => {
+  test("live voice accepts a streaming-only family", () => {
+    expect(
+      sttRoleCapabilityGap("liveVoice", {
+        provider: "deepgram",
+        model: "flux",
+      }),
+    ).toBeNull();
+  });
+
+  test("batch rejects the same family, which has no batch endpoint", () => {
+    const gap = sttRoleCapabilityGap("batch", {
+      provider: "deepgram",
+      model: "flux",
+    });
+
+    expect(gap).toContain("deepgram-flux");
+    expect(gap).toContain("batch");
+  });
+
+  test("capability is judged on the resolved row, not the bare provider", () => {
+    // The pair is what distinguishes them: base deepgram batches and the
+    // flux family does not, under one provider id.
+    expect(sttRoleCapabilityGap("batch", { provider: "deepgram" })).toBeNull();
+  });
+
+  test("telephony rejects a provider that does not transcribe calls", () => {
+    const gap = sttRoleCapabilityGap("telephony", {
+      provider: "deepgram",
+      model: "flux",
+    });
+
+    expect(gap).not.toBeNull();
+  });
+
+  test("watch accepts a streaming-only family, having no batch leg", () => {
+    // Watch shares dictation's transport but not its batch fallback, so a
+    // family dictation must reject is legal here.
+    expect(
+      sttRoleCapabilityGap("watch", { provider: "deepgram", model: "flux" }),
+    ).toBeNull();
+    expect(
+      sttRoleCapabilityGap("dictation", {
+        provider: "deepgram",
+        model: "flux",
+      }),
+    ).not.toBeNull();
+  });
+
+  test("an unknown provider is named rather than silently accepted", () => {
+    expect(sttRoleCapabilityGap("batch", { provider: "not-a-provider" })).toBe(
+      '"not-a-provider" is not in the STT provider catalog',
+    );
+  });
+});

package/src/stt/daemon-batch-transcriber.ts

@@ -273,8 +273,11 @@ export function createDaemonBatchTranscriber(
     case "xai":
       return new XAIBatchTranscriber(apiKey, language);
     case "deepgram-flux":
+    case "vellum-flux":
       // Same copy the resolver raises, so a direct factory caller and a
-      // config-driven one report the mismatch identically.
+      // config-driven one report the mismatch identically. Both Flux
+      // variants are streaming-only: the model has no batch endpoint, BYOK
+      // or managed.
       throw new SttError("provider-error", batchBoundaryGapReason(providerId), {
         userFacing: true,
       });

package/src/stt/roles.ts

@@ -0,0 +1,180 @@
+/**
+ * STT consumer roles.
+ *
+ * `services.stt.provider` is one global that every STT caller reads, while the
+ * provider catalog already models capability per boundary. A provider that is
+ * right for one consumer is therefore wrong for another: Flux has no batch
+ * endpoint, so a global set to it breaks file transcription and telephony at
+ * the same moment it makes live voice better.
+ *
+ * A role names the consumer, not the boundary. Telephony is why: a single call
+ * resolves a streaming transcriber and falls back to a batch one within the
+ * same session, so a `{batch, streaming}` split would put one call on two
+ * roles. Each role instead declares the boundaries its call sites actually
+ * use, and a provider must satisfy all of them to be selectable for it.
+ */
+
+import {
+  getProviderEntry,
+  sttCatalogKeyFor,
+} from "../providers/speech-to-text/provider-catalog.js";
+import type { SttBoundaryId, SttProviderId } from "./types.js";
+
+/** The consumers that may select their own STT provider. */
+export const STT_ROLES = [
+  "liveVoice",
+  "telephony",
+  "dictation",
+  "watch",
+  "batch",
+] as const;
+
+export type SttRole = (typeof STT_ROLES)[number];
+
+/** What a provider must support to serve a role. */
+export interface SttRoleRequirements {
+  /** Every boundary the role's call sites resolve a transcriber on. */
+  readonly boundaries: readonly SttBoundaryId[];
+  /** Whether the role additionally requires telephony ingestion. */
+  readonly requiresTelephony: boolean;
+  /** Human-readable name for config errors and resolver logs. */
+  readonly label: string;
+}
+
+export const STT_ROLE_REQUIREMENTS: Record<SttRole, SttRoleRequirements> = {
+  /**
+   * The live-voice transport arms a streaming transcriber per utterance and
+   * has no batch fallback, so streaming alone is the whole requirement.
+   */
+  liveVoice: {
+    boundaries: ["daemon-streaming"],
+    requiresTelephony: false,
+    label: "live voice",
+  },
+  /**
+   * A call starts on streaming ingestion and falls back to per-turn batch
+   * when no streaming transcriber resolves, so both boundaries are load
+   * bearing inside one session. `telephonyMode` is a separate axis from the
+   * boundaries and is checked on top of them.
+   */
+  telephony: {
+    boundaries: ["daemon-streaming", "daemon-batch"],
+    requiresTelephony: true,
+    label: "telephony",
+  },
+  /**
+   * The composer mic reaches the daemon two ways: a streaming WebSocket for
+   * live partials, and a batch POST of the recorded blob where that socket
+   * is unavailable. Both are the same user-facing feature, so a provider
+   * that serves only one would leave dictation half broken.
+   */
+  dictation: {
+    boundaries: ["daemon-streaming", "daemon-batch"],
+    requiresTelephony: false,
+    label: "dictation",
+  },
+  /**
+   * A watch session streams the user's narration continuously while they
+   * work and files each final on the timeline. It shares dictation's
+   * transport but none of its fallback: there is no batch leg to catch a
+   * provider that cannot stream, so streaming alone is the requirement.
+   */
+  watch: {
+    boundaries: ["daemon-streaming"],
+    requiresTelephony: false,
+    label: "watch",
+  },
+  /** File, attachment and skill transcription. Batch only. */
+  batch: {
+    boundaries: ["daemon-batch"],
+    requiresTelephony: false,
+    label: "batch transcription",
+  },
+};
+
+/**
+ * Why a provider cannot serve a role, or null when it can.
+ *
+ * The catalog already knows every provider's boundaries and telephony mode;
+ * this only asks whether they cover what the role needs. Config validation
+ * rejects a pair on this, and the resolver logs it, so the same sentence
+ * explains the failure wherever it surfaces.
+ */
+export function sttRoleCapabilityGap(
+  role: SttRole,
+  selection: SttRoleSelection,
+): string | null {
+  // Capability belongs to the resolved row: "deepgram" batches and
+  // "deepgram" running flux does not, and only the pair distinguishes them.
+  const provider = sttCatalogKeyFor(
+    selection.provider as SttProviderId,
+    selection.model,
+  );
+  const entry = getProviderEntry(provider);
+  if (!entry) {
+    return `"${selection.provider}" is not in the STT provider catalog`;
+  }
+
+  const requirements = STT_ROLE_REQUIREMENTS[role];
+  const missing = requirements.boundaries.filter(
+    (boundary) => !entry.supportedBoundaries.has(boundary),
+  );
+  if (missing.length > 0) {
+    return `"${provider}" supports no ${missing.join(" or ")} transcription, which ${requirements.label} needs`;
+  }
+
+  if (requirements.requiresTelephony && entry.telephonyMode === "none") {
+    return `"${provider}" does not transcribe calls, which ${requirements.label} needs`;
+  }
+
+  return null;
+}
+
+/** What a role names: a provider, and optionally which of its model families. */
+export interface SttRoleSelection {
+  readonly provider: string;
+  readonly model?: string | undefined;
+}
+
+/**
+ * The STT config a consumer reads: its own `services.stt.roles` entry when it
+ * has one, otherwise the global provider and its configured model family.
+ *
+ * A role names the pair rather than a bare provider because the family is
+ * where capability actually differs. A role that could only name a provider
+ * could not say "live voice on flux", which is the whole reason to have one.
+ *
+ * The parameter is structural rather than the config type on purpose. This
+ * module sits under the config schema (which imports it to validate role
+ * entries), so importing the schema back would close a cycle, and the cycle
+ * would only surface as a module-init failure far from here.
+ */
+export function sttSelectionForRole(
+  stt: {
+    readonly provider: string;
+    readonly providers?:
+      | Record<string, { readonly model?: unknown } | undefined>
+      | undefined;
+    readonly roles?: Partial<Record<SttRole, SttRoleSelection>> | undefined;
+  },
+  role: SttRole | undefined,
+): SttRoleSelection {
+  const override = role === undefined ? undefined : stt.roles?.[role];
+  if (override !== undefined) {
+    return override;
+  }
+  const model = stt.providers?.[stt.provider]?.model;
+  return {
+    provider: stt.provider,
+    ...(typeof model === "string" ? { model } : {}),
+  };
+}
+
+/** The catalog row a role resolves to, via the pair it names. */
+export function sttCatalogKeyForRole(
+  stt: Parameters<typeof sttSelectionForRole>[0],
+  role: SttRole | undefined,
+): SttProviderId {
+  const selection = sttSelectionForRole(stt, role);
+  return sttCatalogKeyFor(selection.provider as SttProviderId, selection.model);
+}

package/src/stt/stt-stream-session.ts

@@ -14,8 +14,9 @@
  * Session lifecycle:
  * 1. Client opens a WebSocket to `/v1/stt/stream` with required `mimeType`
  *    query parameter and optional `provider` metadata. The runtime is
- *    config-authoritative — it resolves the transcriber from
- *    `services.stt.provider` regardless of the requested provider.
+ *    config-authoritative: it resolves the transcriber from the dictation
+ *    role (`services.stt.roles.dictation`, else `services.stt.provider`)
+ *    regardless of the requested provider.
  * 2. The orchestrator resolves a {@link StreamingTranscriber} via
  *    `resolveStreamingTranscriber()` and starts the provider session.
  * 3. The client sends `audio` frames (binary or base64-encoded JSON) and

package/src/stt/types.ts

@@ -17,8 +17,31 @@
 // ---------------------------------------------------------------------------
 
 /**
- * Canonical provider identifiers for daemon-hosted STT backends.
- * Extend this union as new providers are integrated.
+ * Model families a provider may be asked for, via
+ * `services.stt.providers.<id>.model`.
+ *
+ * A family is not a provider model string: `"flux"` selects the conversational
+ * endpoint family, and which member runs is decided downstream from the spoken
+ * language. Providers offering a single family ignore the setting.
+ */
+export const VALID_STT_MODELS = ["nova-3", "flux"] as const;
+
+export type SttModelFamily = (typeof VALID_STT_MODELS)[number];
+
+/**
+ * Catalog identity for a daemon-hosted STT backend.
+ *
+ * This is the key capability is stored under, NOT the set of values a user may
+ * put in `services.stt.provider`. A provider that offers more than one model
+ * family with genuinely different capabilities gets a row per family, because
+ * the catalog is a capability matrix and those capabilities differ. Users
+ * select the family with `services.stt.providers.<id>.model`, and
+ * {@link resolveSttCatalogKey} maps that pair onto the row.
+ *
+ * Keeping the two apart bounds the user-facing surface: adding a model family
+ * costs a catalog row and nothing else, while adding a provider id costs an
+ * enum entry, a settings-picker row, and a place in every predicate that
+ * classifies providers.
  */
 export type SttProviderId =
   | "openai-whisper"
@@ -30,7 +53,14 @@ export type SttProviderId =
   | "deepgram-flux"
   | "google-gemini"
   | "xai"
-  | "vellum";
+  | "vellum"
+  /**
+   * Managed Flux: the same conversational model as `deepgram-flux`, reached
+   * through the platform's speech relay instead of a Deepgram key. Dials the
+   * relay's STT v2 endpoint asking for native Flux frames, so it keeps the
+   * turn events the relay's default v1-shaped translation drops.
+   */
+  | "vellum-flux";
 
 /**
  * Telephony-specific STT capability class.

package/src/subagent/manager.ts

@@ -1478,6 +1478,18 @@ export class SubagentManager {
       .filter((s): s is SubagentState => s !== undefined);
   }
 
+  /**
+   * True when this parent still has a child that is not terminal (`pending`,
+   * `running`, or `awaiting_input`). Idle-eviction and config-reload rebuild
+   * skip those parents so an otherwise-idle conversation does not abort
+   * mid-task children.
+   */
+  hasActiveChildren(parentConversationId: string): boolean {
+    return this.getChildrenOf(parentConversationId).some(
+      (child) => !TERMINAL_STATUSES.has(child.status),
+    );
+  }
+
   /** Total number of active (non-terminal) subagents. */
   get activeCount(): number {
     return [...this.subagents.values()].filter(

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

@@ -12,6 +12,7 @@ describe("liveVoiceSilenceReason", () => {
     expect(
       liveVoiceSilenceReason({
         reachedActive: false,
+        audioInput: true,
         receivedAudio: false,
         detectedSpeech: false,
       }),
@@ -25,6 +26,7 @@ describe("liveVoiceSilenceReason", () => {
     expect(
       liveVoiceSilenceReason({
         reachedActive: false,
+        audioInput: true,
         receivedAudio: true,
         detectedSpeech: true,
       }),
@@ -35,6 +37,7 @@ describe("liveVoiceSilenceReason", () => {
     expect(
       liveVoiceSilenceReason({
         reachedActive: true,
+        audioInput: true,
         receivedAudio: false,
         detectedSpeech: false,
       }),
@@ -48,16 +51,47 @@ describe("liveVoiceSilenceReason", () => {
     expect(
       liveVoiceSilenceReason({
         reachedActive: true,
+        audioInput: true,
         receivedAudio: true,
         detectedSpeech: false,
       }),
     ).toBe("no_speech");
   });
 
+  it("does not blame the microphone on a session that never had one", () => {
+    // A text-only session opened because speech-to-text was unavailable and
+    // the client could type. Scoring the absent microphone as `no_audio` would
+    // file it under a failure it does not have, and inflate the very rate this
+    // taxonomy exists to explain.
+    expect(
+      liveVoiceSilenceReason({
+        reachedActive: true,
+        audioInput: false,
+        receivedAudio: false,
+        detectedSpeech: false,
+      }),
+    ).toBe("text_only");
+  });
+
+  it("still reports text_only when a text-only session streamed stray audio", () => {
+    // A client that has not caught up with `audioInput: false` may keep
+    // sending chunks. Nothing transcribes them, so they say nothing about why
+    // the session was silent, and the reason must not flip on their account.
+    expect(
+      liveVoiceSilenceReason({
+        reachedActive: true,
+        audioInput: false,
+        receivedAudio: true,
+        detectedSpeech: true,
+      }),
+    ).toBe("text_only");
+  });
+
   it("reports speech that never became a turn", () => {
     expect(
       liveVoiceSilenceReason({
         reachedActive: true,
+        audioInput: true,
         receivedAudio: true,
         detectedSpeech: true,
       }),

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

@@ -66,11 +66,16 @@ export type LiveVoiceSessionOutcome = "completed" | "failed";
  * microphone from a muted one from someone deliberately backing out. Those have
  * completely different fixes, so the reason is what makes the rate actionable.
  *
- * The four values are ordered by how far the session got, and each one narrows
- * the cause to a different layer:
+ * The values are ordered by how far the session got, and each one narrows the
+ * cause to a different layer:
  *
  * - `no_ready`  never reached `active`: died in the credential preflight or
  *               the transport, before the user could have said anything.
+ * - `text_only` opened without a speech-to-text leg because the client could
+ *               type, and then the user never typed. Ranked ahead of the audio
+ *               signals because they cannot mean anything here: no microphone
+ *               was ever expected, so scoring such a session `no_audio` would
+ *               read as a failure the session does not have.
  * - `no_audio`  reached `active` but not one audio chunk ever arrived, so the
  *               microphone never opened. Permission denial looks like this.
  * - `no_speech` audio arrived but the detector never classified any of it as
@@ -80,6 +85,7 @@ export type LiveVoiceSessionOutcome = "completed" | "failed";
  */
 export type LiveVoiceSilenceReason =
   | "no_ready"
+  | "text_only"
   | "no_audio"
   | "no_speech"
   | "no_turn";
@@ -91,12 +97,16 @@ export type LiveVoiceSilenceReason =
  */
 export function liveVoiceSilenceReason(signals: {
   reachedActive: boolean;
+  audioInput: boolean;
   receivedAudio: boolean;
   detectedSpeech: boolean;
 }): LiveVoiceSilenceReason {
   if (!signals.reachedActive) {
     return "no_ready";
   }
+  if (!signals.audioInput) {
+    return "text_only";
+  }
   if (!signals.receivedAudio) {
     return "no_audio";
   }

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

@@ -97,6 +97,7 @@ export const llmUsageTelemetryEventSchema = z.object({
   parent_turn_index: z.number().int().min(0).nullable().optional(),
   subagent_role: z.string().trim().min(1).max(64).nullable().optional(),
   subagent_spawn_mode: z.string().trim().min(1).max(64).nullable().optional(),
+  cron_run_id: z.string().trim().min(1).max(64).nullable().optional(),
 });
 export type LlmUsageTelemetryEvent = z.infer<
   typeof llmUsageTelemetryEventSchema
@@ -177,6 +178,11 @@ export const lifecycleTelemetryEventSchema = z.object({
   recorded_at: z.number().int(),
   assistant_version: z.string().trim().min(1).max(64).nullable().optional(),
   event_name: z.string().trim().min(1).max(64),
+  tool_name: z.string().trim().min(1).max(255).optional(),
+  risk_level: z.string().trim().min(1).max(32).optional(),
+  risk_threshold: z.string().trim().min(1).max(32).optional(),
+  surface: z.string().trim().min(1).max(64).optional(),
+  conversation_id: z.string().trim().min(1).max(128).optional(),
 });
 export type LifecycleTelemetryEvent = z.infer<
   typeof lifecycleTelemetryEventSchema