@vellumai/assistant 0.10.4 → 0.10.5-dev.202607022329.d89bf2f

package/src/tools/tool-approval-handler.ts

@@ -5,11 +5,15 @@ import {
   getCanonicalGuardianRequest,
   updateCanonicalGuardianRequest,
 } from "../contacts/canonical-guardian-store.js";
+import type { AutoApproveThreshold } from "../permissions/approval-policy.js";
 import {
   isUnparseableToolArgs,
   unparseableToolArgsMessage,
 } from "../providers/unparseable-tool-args.js";
-import { resolveCapabilities } from "../runtime/capabilities.js";
+import {
+  resolveCapabilities,
+  type SensitiveToolApproval,
+} from "../runtime/capabilities.js";
 import { createOrReuseToolGrantRequest } from "../runtime/tool-grant-request-helper.js";
 import { redactSecrets } from "../security/secret-scanner.js";
 import { computeToolApprovalDigest } from "../security/tool-approval-digest.js";
@@ -29,20 +33,27 @@ import { enforceVerificationControlPlanePolicy } from "./verification-control-pl
 
 const log = getLogger("tool-approval-handler");
 
+/**
+ * Compose the guardian-facing approval question. The question is about the
+ * tool — phrased with the same `Approve tool:` pattern the
+ * confirmation-request bridge uses — and the requester appears only as
+ * parenthetical context, never as the subject of the decision.
+ */
 function buildToolGrantQuestionText(
   toolName: string,
   input: Record<string, unknown>,
   context: ToolContext,
 ): string {
-  const senderLabel =
+  const requesterLabel =
     context.requesterDisplayName ||
     context.requesterIdentifier ||
-    context.requesterExternalUserId ||
-    "A trusted contact";
+    context.requesterExternalUserId;
+  const requesterNote = requesterLabel
+    ? ` (requested by ${requesterLabel})`
+    : "";
   const inputSummary = redactSecrets(summarizeToolInput(toolName, input));
-  return inputSummary
-    ? `${senderLabel} wants to use "${toolName}": ${inputSummary}`
-    : `${senderLabel} is requesting permission to use "${toolName}"`;
+  const summaryPart = inputSummary ? ` — ${inputSummary}` : "";
+  return `Approve tool: ${toolName}${summaryPart}${requesterNote}`;
 }
 
 /** Default polling interval for inline grant wait (ms). */
@@ -155,31 +166,94 @@ export async function waitForInlineGrant(
 
 const UI_SURFACE_TOOLS = new Set(["ui_show", "ui_update", "ui_dismiss"]);
 
-function requiresGuardianApprovalForActor(
+/**
+ * Tool-sensitivity predicate: does invoking this tool require an approval
+ * decision at all? This is purely about the tool and where it executes —
+ * actor identity never feeds in here (it enters the decision only through
+ * the `CapabilitySet` floor, see {@link resolveSensitiveToolDecision}).
+ */
+export function isSensitiveTool(
   toolName: string,
   executionTarget: ExecutionTarget,
 ): boolean {
   // UI surface tools are passive, user-visible operations (cards, forms,
-  // tables). User input is voluntary and user-controlled — skip the guardian
-  // gate so they work during fresh onboarding before trust is established.
+  // tables). User input is voluntary and user-controlled — they are not
+  // sensitive, so they work during fresh onboarding before trust is
+  // established.
   if (UI_SURFACE_TOOLS.has(toolName)) {
     return false;
   }
 
-  // Side-effect tools always require guardian approval for untrusted actors.
-  // Read-only host execution is also blocked because it can leak sensitive
-  // local information (e.g. shell/file reads).
+  // Side-effect tools are sensitive. Read-only host execution is too,
+  // because it can leak sensitive local information (e.g. shell/file reads).
   return isSideEffectTool(toolName) || executionTarget === "host";
 }
 
-function guardianApprovalDeniedMessage(
-  trustClass: ToolContext["trustClass"],
+/**
+ * Threshold for the approval cell governing an invocation — the matrix axis
+ * of the sensitive-tool composition. Shares the auto-approve threshold
+ * vocabulary defined in `permissions/approval-policy.ts`.
+ */
+export type ApprovalCellThreshold = AutoApproveThreshold;
+
+/**
+ * Outcome of the sensitive-tool composition:
+ * - `proceed`: no scoped grant needed (tool not sensitive, or the actor's
+ *   capability set self-approves; lane-B risk/threshold policy in
+ *   `permissions/approval-policy.ts` still applies downstream).
+ * - `escalate-and-wait`: a scoped grant is required; on a grant miss,
+ *   escalate to the guardian and wait inline.
+ * - `deny`: a scoped grant is required; on a grant miss, fail closed.
+ */
+export type SensitiveToolDecision = "proceed" | "escalate-and-wait" | "deny";
+
+/**
+ * Single composition point for the sensitive-tool approval decision:
+ * approval-cell threshold × tool risk level × `CapabilitySet` floor.
+ *
+ * The decision is about the tool; actor identity feeds in only through the
+ * already-resolved `sensitiveToolApproval` capability. That floor is
+ * deterministic and cannot be lifted by the other axes: when the capability
+ * is not `"self"`, a sensitive invocation without a grant always escalates
+ * or denies. `cellThreshold` and `riskLevel` are composition axes the
+ * decision does not consult — no threshold/risk combination may lift the
+ * outcome above the floor.
+ */
+export function resolveSensitiveToolDecision(input: {
+  sensitive: boolean;
+  /**
+   * Approval-matrix cell axis. The decision does not consult it — the floor
+   * alone resolves the outcome — so callers pass `undefined` rather than
+   * paying a threshold lookup to populate it.
+   */
+  cellThreshold: ApprovalCellThreshold | undefined;
+  /**
+   * Risk level as known at gate time. The full risk classification runs
+   * after this gate (in the permission checker), so callers may only have
+   * the pre-classification level here — composing decisions on this axis
+   * requires moving classification ahead of the gate first.
+   */
+  riskLevel: string;
+  sensitiveToolApproval: SensitiveToolApproval;
+}): SensitiveToolDecision {
+  if (!input.sensitive || input.sensitiveToolApproval === "self") {
+    return "proceed";
+  }
+  return input.sensitiveToolApproval;
+}
+
+/**
+ * Denial copy is about the tool (an action requiring guardian approval),
+ * never about who the requester is.
+ */
+function sensitiveToolDeniedMessage(
+  decision: SensitiveToolDecision,
   toolName: string,
 ): string {
-  if (resolveCapabilities(trustClass).sensitiveToolApproval === "deny") {
+  if (decision === "deny") {
     return `Permission denied for "${toolName}": this action requires guardian approval from a verified channel identity.`;
   }
-  return `Permission denied for "${toolName}": this action requires guardian approval and the current actor is not the guardian.`;
+  return `Permission denied for "${toolName}": this action requires guardian approval before it can run.`;
 }
 
 export type PreExecutionGateResult =
@@ -317,16 +391,20 @@ export class ToolApprovalHandler {
       | Parameters<typeof consumeGrantForInvocation>[0]
       | null = null;
 
-    const guardianApprovalRequired = requiresGuardianApprovalForActor(
-      name,
-      executionTarget,
-    );
+    const sensitive = isSensitiveTool(name, executionTarget);
+    const { sensitiveToolApproval } = resolveCapabilities(context.trustClass);
+    // cellThreshold stays unresolved: the decision does not consult it
+    // (the floor is deterministic), and resolving a live threshold here
+    // would block grant consumption — including already-approved calls and
+    // voice abort handling — on a gateway IPC read.
+    const sensitiveDecision = resolveSensitiveToolDecision({
+      sensitive,
+      cellThreshold: undefined,
+      riskLevel,
+      sensitiveToolApproval,
+    });
 
-    if (
-      resolveCapabilities(context.trustClass).sensitiveToolApproval !==
-        "self" &&
-      guardianApprovalRequired
-    ) {
+    if (sensitiveDecision !== "proceed") {
       const inputDigest = computeToolApprovalDigest(name, input);
       needsGrantConsumption = true;
       deferredConsumeParams = {
@@ -544,8 +622,7 @@ export class ToolApprovalHandler {
       // Actors with no identity (unknown) remain fail-closed with no
       // escalation or wait.
       if (
-        resolveCapabilities(context.trustClass).sensitiveToolApproval ===
-          "escalate-and-wait" &&
+        sensitiveDecision === "escalate-and-wait" &&
         context.assistantId &&
         context.executionChannel &&
         context.requesterExternalUserId
@@ -692,7 +769,7 @@ export class ToolApprovalHandler {
       }
 
       // Unknown/unverified actors or escalation failures - generic denial.
-      const reason = guardianApprovalDeniedMessage(context.trustClass, name);
+      const reason = sensitiveToolDeniedMessage(sensitiveDecision, name);
       log.warn(
         {
           toolName: name,

package/{node_modules/@vellumai/skill-host-contracts/src → src/tools}/tool-types.ts

@@ -1,25 +1,24 @@
 /**
- * Tool-related type declarations shared between the daemon and any
- * skill-side package that needs to describe tools, permission risk, or tool
- * execution results on the wire.
+ * Tool-related type declarations: the neutral leaf module describing
+ * tools, permission risk, and tool execution results.
  *
- * Pure type-level declarations only (+ the `RiskLevel` enum, which is a value
- * but is safely cross-package). No runtime helpers live here — the assistant
- * keeps all behavior functions in `assistant/src/tools/` and re-exports the
- * types from this file.
+ * Pure type-level declarations only (+ the `RiskLevel` enum, which is a
+ * value). No runtime helpers live here — the assistant keeps all behavior
+ * functions in `assistant/src/tools/` and re-exports the types from this
+ * file. This module imports nothing, so it can sit at the bottom of the
+ * import graph and be consumed by `tools/types.ts`, `providers/types.ts`,
+ * and `permissions/types.ts` without creating cycles.
  *
  * Heavy daemon-internal references (CES client, host-proxy classes, trust
  * classifications, interface IDs, content blocks, CES `ApprovalRequired`)
- * are held as opaque `unknown` / broadened-`string` placeholders on this
- * side so the contracts package never reaches into the assistant or the
- * service-contracts runtime. The assistant redeclares `Tool`, `ToolContext`,
- * `ToolExecutionResult`, `ToolExecutedEvent`, `ToolLifecycleEvent`,
- * `ToolLifecycleEventHandler`, and `ProxyToolResolver` in
- * `assistant/src/tools/types.ts` with the concrete types in place, so
- * existing call sites keep their full type information. The two sides are
- * structurally independent — no inheritance, no intersection — which
- * avoids TypeScript's contravariance mismatches on lifecycle-event
- * handlers.
+ * are held as opaque `unknown` / broadened-`string` placeholders here. The
+ * assistant redeclares `Tool`, `ToolContext`, `ToolExecutionResult`,
+ * `ToolExecutedEvent`, `ToolLifecycleEvent`, `ToolLifecycleEventHandler`,
+ * and `ProxyToolResolver` in `assistant/src/tools/types.ts` with the
+ * concrete types in place, so existing call sites keep their full type
+ * information. The two sides are structurally independent — no inheritance,
+ * no intersection — which avoids TypeScript's contravariance mismatches on
+ * lifecycle-event handlers.
  */
 
 // ---------------------------------------------------------------------------

package/src/tools/types.ts

@@ -1,15 +1,4 @@
 import type { ApprovalRequired } from "@vellumai/service-contracts/credential-rpc";
-import type {
-  DiffInfo,
-  ExecutionTarget,
-  ProxyApprovalCallback,
-  SensitiveOutputBinding,
-  ToolExecutionErrorEvent as ContractsToolExecutionErrorEvent,
-  ToolExecutionStartEvent,
-  ToolPermissionDeniedEvent,
-  ToolPermissionPromptEvent,
-} from "@vellumai/skill-host-contracts";
-import { RiskLevel } from "@vellumai/skill-host-contracts";
 import { z } from "zod";
 
 import type { InterfaceId } from "../channels/types.js";
@@ -19,6 +8,17 @@ import type { SecretPromptResult } from "../permissions/secret-prompter.js";
 import type { ContentBlock } from "../providers/types.js";
 import type { TrustClass } from "../runtime/actor-trust-resolver.js";
 import type { UsageAttributionSnapshot } from "../usage/attribution.js";
+import type {
+  DiffInfo,
+  ExecutionTarget,
+  ProxyApprovalCallback,
+  SensitiveOutputBinding,
+  ToolExecutionErrorEvent as ContractsToolExecutionErrorEvent,
+  ToolExecutionStartEvent,
+  ToolPermissionDeniedEvent,
+  ToolPermissionPromptEvent,
+} from "./tool-types.js";
+import { RiskLevel } from "./tool-types.js";
 
 export const DISK_PRESSURE_CLEANUP_TOOL_NAMES: ReadonlySet<string> = new Set([
   "bash",
@@ -37,11 +37,11 @@ export function isDiskPressureCleanupToolName(name: string): boolean {
 
 // ---------------------------------------------------------------------------
 // Re-exports + concrete overlays for types that live in
-// @vellumai/skill-host-contracts.
+// ./tool-types.js.
 //
-// The canonical declarations moved into the neutral contracts package as
-// part of the skill-isolation work. This file preserves existing import
-// paths (`"../tools/types.js"`) so all callers keep resolving.
+// The canonical declarations live in the neutral leaf module
+// `./tool-types.js`. This file preserves existing import paths
+// (`"../tools/types.js"`) so all callers keep resolving.
 //
 // Pure re-exports below cover types the contracts package could declare
 // without any assistant-side references. The remaining interfaces (`Tool`,
@@ -73,8 +73,8 @@ export type {
   ToolExecutionStartEvent,
   ToolPermissionDeniedEvent,
   ToolPermissionPromptEvent,
-} from "@vellumai/skill-host-contracts";
-export { RiskLevel } from "@vellumai/skill-host-contracts";
+} from "./tool-types.js";
+export { RiskLevel } from "./tool-types.js";
 
 // ---------------------------------------------------------------------------
 // Assistant-side concrete overlays
@@ -483,6 +483,18 @@ export interface ToolContext {
    * @legacy
    */
   sourceActorPrincipalId?: string;
+  /**
+   * The conversation's effective per-chat plugin scope, as produced by
+   * `getEffectiveEnabledPluginSet`: `null` means no per-chat restriction;
+   * otherwise a Set of allowed plugin ids (the user's selection unioned with
+   * the always-on first-party defaults). Skill-surface tools that resolve
+   * skills by id outside the per-turn projection — `skill_load` (body load)
+   * and `find_similar_skills` (discovery) — read this to drop skills owned by
+   * plugins outside the conversation's scope. Populated per tool call from the
+   * live conversation state.
+   * @legacy
+   */
+  enabledPluginSet?: Set<string> | null;
 }
 
 /**

package/src/tools/ui-surface/definitions.ts

@@ -243,7 +243,8 @@ export const uiShowTool = {
     "- dynamic_page: { html, width?, height?, preview?: { title, subtitle?, description?, icon?, metrics?: [{ label, value }] } }\n" +
     "- file_upload: { prompt, acceptedTypes?, maxFiles? }\n" +
     "- task_preferences: {} (no data needed — categories are rendered client-side)\n" +
-    '- work_result: { eyebrow?, status?: "completed"|"partial"|"failed"|"in_progress", summary?, metrics?: [{ label, value, detail?, tone?: "neutral"|"positive"|"warning"|"negative" }], sections?: [{ id?, title, description?, type?: "items"|"timeline"|"diff"|"artifacts"|"warnings", items?: [{ id?, title, description?, status?, tone?, metadata?: [{ label, value }], href? }], diffs?: [{ label?, before?, after? }] }] }. Shows a structured receipt after real work: what changed, what was skipped, proof points, and next actions. Keep display-only unless explicit follow-up buttons are needed.\n\n' +
+    '- work_result: { eyebrow?, status?: "completed"|"partial"|"failed"|"in_progress", summary?, metrics?: [{ label, value, detail?, tone?: "neutral"|"positive"|"warning"|"negative" }], sections?: [{ id?, title, description?, type?: "items"|"timeline"|"diff"|"artifacts"|"warnings", items?: [{ id?, title, description?, status?, tone?, metadata?: [{ label, value }], href? }], diffs?: [{ label?, before?, after? }] }] }. Shows a structured receipt after real work: what changed, what was skipped, proof points, and next actions. Keep display-only unless explicit follow-up buttons are needed.\n' +
+    '- channel_setup: { channel: "slack" | "telegram" | "phone" }. Opens the channel setup panel in a side drawer. Returns success only after a connected client confirms the panel rendered (an error means the user does NOT see the panel — never claim it is open after an error). The user then completes credential entry at their own pace. Slack shows a full setup wizard; Telegram and Phone show credential forms (the assistant handles remaining setup steps like webhooks in chat after the user saves credentials).\n\n' +
     "For multi-step or long-running turns (web searches, file operations, research), show a task_progress card early and keep its steps updated as work progresses. Coarse steps are fine, and you can add or revise them as the work takes shape — a rough card beats no signal.",
   category: "ui-surface",
   defaultRiskLevel: RiskLevel.Low,
@@ -256,6 +257,7 @@ export const uiShowTool = {
         type: "string",
         enum: [
           "card",
+          "channel_setup",
           "choice",
           "copy_block",
           "oauth_connect",

package/src/tts/__tests__/provider-adapters.test.ts

@@ -537,6 +537,43 @@ describe("Fish Audio TTS provider adapter", () => {
     );
   });
 
+  test("pcm output request maps to wav format at 8 kHz", async () => {
+    const provider = createFishAudioProvider();
+    await provider.synthesize(makeRequest({ outputFormat: "pcm" }));
+
+    const [, config, options] = mockSynthesizeWithFishAudio.mock.calls[0]!;
+    expect((config as { format: string }).format).toBe("wav");
+    expect((options as { sampleRate?: number } | undefined)?.sampleRate).toBe(
+      8000,
+    );
+  });
+
+  test("synthesizeStream pcm output request maps to wav format at 8 kHz", async () => {
+    const provider = createFishAudioProvider();
+    await provider.synthesizeStream!(
+      makeRequest({ outputFormat: "pcm" }),
+      () => {},
+    );
+
+    const [, config, options] = mockSynthesizeWithFishAudio.mock.calls[0]!;
+    expect((config as { format: string }).format).toBe("wav");
+    expect((options as { sampleRate?: number } | undefined)?.sampleRate).toBe(
+      8000,
+    );
+  });
+
+  test("explicit format request does not set a sample rate", async () => {
+    mockFishAudioConfig.format = "wav";
+    const provider = createFishAudioProvider();
+    await provider.synthesize(makeRequest());
+
+    const [, config, options] = mockSynthesizeWithFishAudio.mock.calls[0]!;
+    expect((config as { format: string }).format).toBe("wav");
+    expect(
+      (options as { sampleRate?: number } | undefined)?.sampleRate,
+    ).toBeUndefined();
+  });
+
   // -- Streaming -----------------------------------------------------------
 
   test("synthesizeStream passes onChunk callback through", async () => {

package/src/tts/__tests__/provider-catalog.test.ts

@@ -53,6 +53,15 @@ describe("TTS provider catalog", () => {
     }
   });
 
+  test("every entry declares a valid mediaStreamPlayback output format", () => {
+    const validFormats = new Set(["pcm", "wav", "none"]);
+    for (const entry of entries) {
+      expect(validFormats.has(entry.mediaStreamPlayback.outputFormat)).toBe(
+        true,
+      );
+    }
+  });
+
   test("every entry has at least one secret requirement", () => {
     for (const entry of entries) {
       expect(entry.secretRequirements.length).toBeGreaterThan(0);
@@ -120,6 +129,10 @@ describe("ElevenLabs catalog entry", () => {
     expect(entry.capabilities.supportedFormats).toContain("mp3");
   });
 
+  test("plays over media-stream via PCM output", () => {
+    expect(entry.mediaStreamPlayback.outputFormat).toBe("pcm");
+  });
+
   test("requires a credential stored under 'credential/elevenlabs/api_key'", () => {
     const apiKeySecret = entry.secretRequirements.find(
       (s) => s.credentialStoreKey === "credential/elevenlabs/api_key",
@@ -146,6 +159,10 @@ describe("Fish Audio catalog entry", () => {
     expect(entry.capabilities.supportedFormats).toContain("opus");
   });
 
+  test("plays over media-stream via WAV output", () => {
+    expect(entry.mediaStreamPlayback.outputFormat).toBe("wav");
+  });
+
   test("requires an API key stored under 'credential/fish-audio/api_key'", () => {
     const apiKeySecret = entry.secretRequirements.find(
       (s) => s.credentialStoreKey === "credential/fish-audio/api_key",
@@ -172,6 +189,10 @@ describe("Deepgram catalog entry", () => {
     expect(entry.capabilities.supportedFormats).toContain("opus");
   });
 
+  test("plays over media-stream via PCM output", () => {
+    expect(entry.mediaStreamPlayback.outputFormat).toBe("pcm");
+  });
+
   test("requires an API key stored under 'credential/deepgram/api_key'", () => {
     const apiKeySecret = entry.secretRequirements.find(
       (s) => s.credentialStoreKey === "credential/deepgram/api_key",

package/src/tts/provider-catalog.ts

@@ -55,6 +55,27 @@ interface TtsProviderCatalogCapabilities {
   readonly supportedFormats: readonly string[];
 }
 
+/**
+ * Output format the provider's adapter produces when a caller requests
+ * PCM output (`outputFormat: "pcm"`) for media-stream playback.
+ *
+ * The media-stream transport can only transcode raw PCM or WAV
+ * (PCM-in-container) to mu-law — compressed formats (mp3, opus) produce
+ * garbled audio. Providers whose adapter honours the PCM hint declare
+ * `"pcm"`; providers that substitute WAV declare `"wav"`; providers that
+ * can only produce compressed audio declare `"none"` and are not playable
+ * over media-stream transports.
+ */
+export type TtsMediaStreamOutputFormat = "pcm" | "wav" | "none";
+
+/**
+ * How the provider's synthesized audio plays over media-stream transports.
+ */
+export interface TtsMediaStreamPlayback {
+  /** Format the adapter produces for media-stream (PCM-hinted) requests. */
+  readonly outputFormat: TtsMediaStreamOutputFormat;
+}
+
 /**
  * Link to a provider's API-key management page, shown in settings UI.
  */
@@ -71,7 +92,7 @@ interface TtsCredentialsGuide {
  * metadata level — identity, display name, telephony call mode,
  * capabilities, secret requirements, and client-facing display metadata.
  */
-interface TtsProviderCatalogEntry {
+export interface TtsProviderCatalogEntry {
   /** Unique provider identifier matching {@link TtsProviderId}. */
   readonly id: TtsProviderId;
 
@@ -94,22 +115,24 @@ interface TtsProviderCatalogEntry {
   readonly callMode: TtsCallMode;
 
   /**
-   * Whether the call path may fall back to native Twilio token-based
-   * TTS when synthesized audio fails.
+   * Whether the call path may fall back to the text-token path when
+   * synthesized audio fails.
    *
    * Providers with `callMode: "native-twilio"` always set this to `true`.
-   * Synthesized-play providers that also work through Twilio's built-in
-   * TTS (e.g. Fish Audio) set this to `true` so callers still hear
-   * a response if synthesis fails. Providers that have **no** native
-   * Twilio integration (e.g. Deepgram) set this to `false` — a synthesis
-   * failure must propagate so the outer error handler can surface a
-   * user-facing recovery message.
+   * Synthesized-play providers with a usable token fallback (e.g. Fish
+   * Audio) set this to `true` so callers still hear a response if
+   * synthesis fails. Providers without one (e.g. Deepgram) set this to
+   * `false` — a synthesis failure must propagate so the outer error
+   * handler can surface a user-facing recovery message.
    */
   readonly allowNativeFallback: boolean;
 
   /** Static provider-level capabilities. */
   readonly capabilities: Readonly<TtsProviderCatalogCapabilities>;
 
+  /** How the provider's audio plays over media-stream transports. */
+  readonly mediaStreamPlayback: Readonly<TtsMediaStreamPlayback>;
+
   /** Secrets the provider requires to function. */
   readonly secretRequirements: readonly Readonly<TtsProviderSecretRequirement>[];
 }
@@ -143,6 +166,8 @@ const CATALOG: readonly TtsProviderCatalogEntry[] = [
       supportsStreaming: false,
       supportedFormats: ["mp3"],
     },
+    // The adapter honours the PCM hint via `pcm_16000` output.
+    mediaStreamPlayback: { outputFormat: "pcm" },
     secretRequirements: [
       {
         credentialStoreKey: "credential/elevenlabs/api_key",
@@ -171,6 +196,8 @@ const CATALOG: readonly TtsProviderCatalogEntry[] = [
       supportsStreaming: true,
       supportedFormats: ["mp3", "wav", "opus"],
     },
+    // The adapter substitutes WAV for the PCM hint (no raw PCM support).
+    mediaStreamPlayback: { outputFormat: "wav" },
     secretRequirements: [
       {
         credentialStoreKey: "credential/fish-audio/api_key",
@@ -199,6 +226,8 @@ const CATALOG: readonly TtsProviderCatalogEntry[] = [
       supportsStreaming: false,
       supportedFormats: ["mp3", "wav", "opus"],
     },
+    // The adapter honours the PCM hint via `linear16` + `container=none`.
+    mediaStreamPlayback: { outputFormat: "pcm" },
     secretRequirements: [
       {
         credentialStoreKey: "credential/deepgram/api_key",
@@ -226,6 +255,8 @@ const CATALOG: readonly TtsProviderCatalogEntry[] = [
       supportsStreaming: false,
       supportedFormats: ["mp3", "wav"],
     },
+    // The adapter honours the PCM hint via the `pcm` codec.
+    mediaStreamPlayback: { outputFormat: "pcm" },
     secretRequirements: [
       {
         credentialStoreKey: "credential/xai/api_key",

package/src/tts/providers/fish-audio-provider.ts

@@ -23,6 +23,13 @@ import type {
 
 const log = getLogger("tts:fish-audio");
 
+/**
+ * Sample rate requested when the caller wants PCM (the phone path).
+ * Twilio media streams consume 8 kHz; without this Fish defaults WAV
+ * to 44.1 kHz, which the media-stream transcoder would play ~5.5x slow.
+ */
+const TELEPHONY_SAMPLE_RATE_HZ = 8000;
+
 // ---------------------------------------------------------------------------
 // Error types
 // ---------------------------------------------------------------------------
@@ -92,11 +99,12 @@ export function createFishAudioProvider(): TtsProvider {
       const config = getConfig().services.tts.providers["fish-audio"];
       const referenceId = resolveReferenceId(request, config);
 
-      // When PCM output is requested, override to WAV. Fish Audio
-      // doesn't support raw PCM, but WAV gives us PCM in a container
-      // that audioBufferToFrames can extract.
-      const effectiveFormat =
-        request.outputFormat === "pcm" ? "wav" : config.format;
+      // When PCM output is requested, override to WAV at 8 kHz. Fish Audio
+      // doesn't support raw PCM, but WAV gives us PCM in a container that
+      // audioBufferToFrames can extract; the explicit sample rate avoids
+      // Fish's 44.1 kHz WAV default.
+      const pcmRequested = request.outputFormat === "pcm";
+      const effectiveFormat = pcmRequested ? "wav" : config.format;
 
       // Build an effective config with the resolved reference ID
       // and the potentially overridden format.
@@ -119,6 +127,7 @@ export function createFishAudioProvider(): TtsProvider {
       try {
         audio = await synthesizeWithFishAudio(request.text, effectiveConfig, {
           signal: request.signal,
+          sampleRate: pcmRequested ? TELEPHONY_SAMPLE_RATE_HZ : undefined,
         });
       } catch (err) {
         if (err instanceof Error && err.name === "AbortError") throw err;
@@ -140,11 +149,10 @@ export function createFishAudioProvider(): TtsProvider {
       const config = getConfig().services.tts.providers["fish-audio"];
       const referenceId = resolveReferenceId(request, config);
 
-      // When PCM output is requested, override to WAV. Fish Audio
-      // doesn't support raw PCM, but WAV gives us PCM in a container
-      // that audioBufferToFrames can extract.
-      const effectiveFormat =
-        request.outputFormat === "pcm" ? "wav" : config.format;
+      // When PCM output is requested, override to WAV at 8 kHz (see
+      // synthesize above).
+      const pcmRequested = request.outputFormat === "pcm";
+      const effectiveFormat = pcmRequested ? "wav" : config.format;
 
       const effectiveConfig: TtsFishAudioProviderConfig = {
         ...config,
@@ -166,6 +174,7 @@ export function createFishAudioProvider(): TtsProvider {
         audio = await synthesizeWithFishAudio(request.text, effectiveConfig, {
           onChunk,
           signal: request.signal,
+          sampleRate: pcmRequested ? TELEPHONY_SAMPLE_RATE_HZ : undefined,
         });
       } catch (err) {
         if (err instanceof Error && err.name === "AbortError") throw err;

package/src/tts/types.ts

@@ -30,10 +30,9 @@ export type TtsProviderId =
 /**
  * Describes how a TTS provider integrates with the telephony call path.
  *
- * - `native-twilio`    — Twilio handles TTS natively via ConversationRelay;
- *                         text tokens are forwarded to the relay and Twilio
- *                         synthesises audio using the provider's built-in
- *                         integration.
+ * - `native-twilio`    — Twilio handles TTS natively; text tokens are
+ *                         forwarded to Twilio, which synthesises audio
+ *                         using the provider's built-in integration.
  * - `synthesized-play` — The assistant synthesises audio via the provider's
  *                         HTTP API and streams chunks to Twilio via `play`
  *                         messages. Used when the provider is not natively

package/src/util/__tests__/process-tree.test.ts

@@ -39,8 +39,16 @@ describe("deriveName", () => {
     expect(deriveName("bun run /worker.ts")).toBe("worker");
   });
 
-  test("falls back to the interpreter when there is no script arg", () => {
-    expect(deriveName("bun repl")).toBe("bun");
+  test("surfaces the arguments when an interpreter runs no script file", () => {
+    expect(deriveName("bun repl")).toBe("bun repl");
+    expect(deriveName("bun run dev")).toBe("bun run dev");
+    expect(deriveName("bun x prettier --write .")).toBe("bun x prettier .");
+    expect(deriveName("node --inspect server")).toBe("node server");
+  });
+
+  test("falls back to the bare interpreter when only flags follow", () => {
+    expect(deriveName("bun --version")).toBe("bun");
+    expect(deriveName("bun")).toBe("bun");
   });
 
   test("handles empty input", () => {