@vellumai/assistant 0.11.2 → 0.11.3-dev.202608080427.92f668a

package/src/config/__tests__/profile-tool-support.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, test } from "bun:test";
+
+import { profileSupportsTools } from "../profile-tool-support.js";
+import type { AssistantConfig } from "../schema.js";
+import { LLMSchema } from "../schemas/llm.js";
+
+/** An `AssistantConfig` carrying nothing the profile lookup does not read. */
+function configWithProfiles(
+  profiles: Record<string, Record<string, unknown>>,
+): AssistantConfig {
+  return { llm: LLMSchema.parse({ profiles }) } as AssistantConfig;
+}
+
+describe("profileSupportsTools", () => {
+  test("reports false only for a model the catalog declares tool-less", () => {
+    const config = configWithProfiles({
+      "no-tools": { provider: "openrouter", model: "minimax/minimax-01" },
+    });
+    expect(profileSupportsTools("no-tools", config)).toBe(false);
+  });
+
+  test("reports true for a catalog model declared tool-capable", () => {
+    const config = configWithProfiles({
+      "with-tools": { provider: "anthropic", model: "claude-fable-5" },
+    });
+    expect(profileSupportsTools("with-tools", config)).toBe(true);
+  });
+
+  test("fails open for a BYOK model the catalog has never seen", () => {
+    const config = configWithProfiles({
+      byok: { provider: "openrouter", model: "acme/private-llm-9" },
+    });
+    expect(profileSupportsTools("byok", config)).toBeUndefined();
+  });
+
+  test("fails open for a profile key that resolves to nothing", () => {
+    expect(profileSupportsTools("not-a-profile", configWithProfiles({}))).toBe(
+      undefined,
+    );
+  });
+
+  test("verdicts a catalog default profile through the code catalog", () => {
+    // `balanced` carries no workspace body, so the answer has to come from the
+    // resolved default-profile catalog rather than `llm.profiles`.
+    expect(profileSupportsTools("balanced", configWithProfiles({}))).toBe(true);
+  });
+
+  test("reports false for a mix whose every arm is catalog-denied", () => {
+    const config = configWithProfiles({
+      "no-tools": { provider: "openrouter", model: "minimax/minimax-01" },
+      "no-tools-too": {
+        provider: "openrouter",
+        model: "minimax/minimax-m2-her",
+      },
+      blend: {
+        mix: [
+          { profile: "no-tools", weight: 1 },
+          { profile: "no-tools-too", weight: 1 },
+        ],
+      },
+    });
+    // Whichever arm the child's seed lands on, it cannot call tools.
+    expect(profileSupportsTools("blend", config)).toBe(false);
+  });
+
+  test("reports true for a mix whose every arm is catalog-capable", () => {
+    const config = configWithProfiles({
+      "tools-a": { provider: "anthropic", model: "claude-fable-5" },
+      "tools-b": {
+        provider: "anthropic",
+        model: "claude-haiku-4-5-20251001",
+      },
+      blend: {
+        mix: [
+          { profile: "tools-a", weight: 3 },
+          { profile: "tools-b", weight: 1 },
+        ],
+      },
+    });
+    expect(profileSupportsTools("blend", config)).toBe(true);
+  });
+
+  test("fails open for a mix of tool-capable and tool-less arms", () => {
+    const config = configWithProfiles({
+      "no-tools": { provider: "openrouter", model: "minimax/minimax-01" },
+      "with-tools": { provider: "anthropic", model: "claude-fable-5" },
+      blend: {
+        mix: [
+          { profile: "no-tools", weight: 1 },
+          { profile: "with-tools", weight: 1 },
+        ],
+      },
+    });
+    // The arm is picked from the child conversation's seed, and no such
+    // conversation exists yet, so neither arm's verdict speaks for the mix.
+    expect(profileSupportsTools("blend", config)).toBeUndefined();
+  });
+
+  test("fails open for a mix with an arm the catalog has never seen", () => {
+    const config = configWithProfiles({
+      "no-tools": { provider: "openrouter", model: "minimax/minimax-01" },
+      byok: { provider: "openrouter", model: "acme/private-llm-9" },
+      blend: {
+        mix: [
+          { profile: "no-tools", weight: 1 },
+          { profile: "byok", weight: 1 },
+        ],
+      },
+    });
+    expect(profileSupportsTools("blend", config)).toBeUndefined();
+  });
+
+  test("answers a mixed-capability mix identically on every call", () => {
+    const config = configWithProfiles({
+      "no-tools": { provider: "openrouter", model: "minimax/minimax-01" },
+      "with-tools": { provider: "anthropic", model: "claude-fable-5" },
+      blend: {
+        mix: [
+          { profile: "no-tools", weight: 1 },
+          { profile: "with-tools", weight: 1 },
+        ],
+      },
+    });
+    // No seed is available at probe time, so the verdict must not ride on a
+    // random arm pick.
+    const verdicts = new Set(
+      Array.from({ length: 50 }, () => profileSupportsTools("blend", config)),
+    );
+    expect([...verdicts]).toEqual([undefined]);
+  });
+});

package/src/config/bundled-skills/AGENTS.md

@@ -8,7 +8,7 @@ Each executor is a module exporting `run(input, context)` (the `SkillToolScript`
 
 ## Keeping public docs in sync
 
-A bundled skill's `SKILL.md` is its behavioral source of truth. Skills with a public reference page (`https://www.vellum.ai/docs/skills-reference/<slug>`, authored in the **vellum-assistant-platform** repo) are fingerprinted in `scripts/skill-docs-sync.manifest.json` and enforced by `skill-docs-sync-guard.test.ts`.
+A bundled skill's `SKILL.md` is its behavioral source of truth. Skills with a public reference page (`https://www.vellum.ai/docs/skills-reference/<slug>`, authored in this repo at `clients/docs/src/app/docs/_components/skills-reference-<slug>-content.tsx`) are fingerprinted in `scripts/skill-docs-sync.manifest.json` and enforced by `skill-docs-sync-guard.test.ts`.
 
 When you change a documented skill's `SKILL.md`, the guard fails until you reconcile it:
 

package/src/config/bundled-skills/acp/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: acp
-description: Spawn external coding agents via the Agent Client Protocol (ACP)
+description: Set up, authenticate, and run external coding agents (Claude Code, Codex) via the Agent Client Protocol
 compatibility: "Designed for Vellum personal assistants"
 metadata:
   emoji: "🔗"
@@ -8,13 +8,12 @@ metadata:
     display-name: "ACP"
     category: "development"
     activation-hints:
-      - "User asks to use Claude Code or Codex to do something"
-      - "User wants to delegate a coding task to Claude Code, Codex, or another ACP agent"
-      - "User wants to hand a coding task to another agent and check on it later"
-      - "User wants to spawn an external coding agent that runs autonomously and streams results back"
-      - "User mentions ACP, claude-agent-acp, codex-acp, or running multiple coding agents in parallel"
+      - "User wants to set up, install, configure, authenticate, or connect Claude Code or Codex"
+      - "User asks to use Claude Code or Codex, or delegate a coding task to an ACP agent"
+      - "User wants an agent to work autonomously and report back later"
+      - "User mentions ACP, claude-agent-acp, or codex-acp"
     avoid-when:
-      - "Task is small enough to do inline with the assistant's own tools - no need for an external agent"
+      - "The task is small enough to do inline"
 ---
 
 ACP agent orchestration - spawn external coding agents (Claude Code, Codex) to work on tasks via the Agent Client Protocol. Each agent runs as its own subprocess speaking ACP over stdio and streams results back into the conversation.

package/src/config/bundled-skills/app-builder/SKILL.md

@@ -75,7 +75,7 @@ Every app is multi-file TSX (`formatVersion: 2`). Never write a root-level `inde
 
 ## Responsive & design system
 
-Every app works phone (~360px) to desktop (~1400px+). The `<turn_context>` block carries a `client_os:` field (the OS the user is on): `ios`/`android` → mobile-first (design narrow first, body 17px); `macos`/`web` → desktop-first (multi-column, body 14px); absent → desktop-first unless the request implies phone use ("for my iPhone"). (The sibling `interface:` field is the transport surface — always `web` for the apps — so key layout off `client_os`, not `interface`.)
+Every app works phone (~360px) to desktop (~1400px+). The `<turn_context>` block carries a `client_os:` field (the OS the user is on): `ios`/`android` → mobile-first (design narrow first, body 17px); `macos`/`windows`/`web` → desktop-first (multi-column, body 14px); absent → desktop-first unless the request implies phone use ("for my iPhone"). (The sibling `interface:` field is the transport surface, always `web` for the apps, so key layout off `client_os`, not `interface`.)
 
 **Universal baseline — every build, regardless of client_os:**
 - Viewport meta: `width=device-width, initial-scale=1, viewport-fit=cover`. Never `user-scalable=no` (blocks accessibility zoom).

package/src/config/bundled-skills/app-builder/references/RESPONSIVE.md

@@ -4,12 +4,12 @@ Every app must work across phone (~360px) to desktop (~1400px+).
 
 ## Mode selection
 
-The conversation context's `<turn_context>` block carries a `client_os:` field — the OS the user is on. (Key layout off this, not the sibling `interface:` field: `interface:` is the transport surface and is always `web` for the web/iOS/macOS apps.)
+The conversation context's `<turn_context>` block carries a `client_os:` field, the OS the user is on. (Key layout off this, not the sibling `interface:` field: `interface:` is the transport surface and is always `web` for the web/iOS/macOS/Windows apps.)
 
 **If `client_os: ios` or `android`** (any mobile-web surface):
 → Mobile-first build. Design the narrow viewport first, enhance upward.
 
-**If `client_os: macos` or `web`**:
+**If `client_os: macos`, `windows`, or `web`**:
 → Desktop-first build. Design larger composition first; narrow fallback still meets the universal baseline below.
 
 **If field is absent or ambiguous**:
@@ -52,6 +52,6 @@ The conversation context's `<turn_context>` block carries a `client_os:` field
 - Bottom-anchor the primary action: `position: sticky; bottom: env(safe-area-inset-bottom)`.
 - Replace side modals and popovers with bottom sheets.
 
-## Desktop-first priorities (`client_os: macos` / `web`)
+## Desktop-first priorities (`client_os: macos` / `windows` / `web`)
 
 Multi-column composition, hover-rich affordances, denser information, side modals, inline primary actions. The universal baseline above is still the floor — narrow view must still work.

package/src/config/bundled-skills/media-processing/services/preprocess.ts

@@ -19,6 +19,7 @@ import {
   updateProcessingStage,
 } from "../../../../persistence/media-store.js";
 import { resolveBatchTranscriber } from "../../../../providers/speech-to-text/resolve.js";
+import type { BatchTranscriber } from "../../../../stt/types.js";
 import { silentlyWithLog } from "../../../../util/silently.js";
 import {
   FFMPEG_PALETTE_TIMEOUT_MS,
@@ -459,10 +460,19 @@ export async function preprocessForAsset(
     const allFramePaths: string[] = [];
 
     // Resolve the STT transcriber once for all segments to avoid repeated
-    // credential lookups in the per-segment loop.
-    const transcriber = options.includeAudio
-      ? await resolveBatchTranscriber()
-      : null;
+    // credential lookups in the per-segment loop. A resolver failure degrades
+    // to transcript-less segments like an absent provider does, reporting the
+    // reason on the progress stream rather than killing the whole run.
+    let transcriber: BatchTranscriber | null = null;
+    if (options.includeAudio) {
+      try {
+        transcriber = await resolveBatchTranscriber();
+      } catch (err) {
+        onProgress?.(
+          `Audio transcription unavailable: ${(err as Error).message}\n`,
+        );
+      }
+    }
 
     const scaleFilter = `scale='if(gt(iw,ih),-1,${config.shortEdge})':'if(gt(iw,ih),${config.shortEdge},-1)'`;
 

package/src/config/bundled-skills/phone-calls/references/CONFIG.md

@@ -2,21 +2,21 @@
 
 All call-related settings can be managed via `assistant config`:
 
-| Setting                                     | Description                                                                                                                                                                                                                               | Default                                                                                                  |
-| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| `calls.enabled`                             | Master switch for the calling feature                                                                                                                                                                                                     | `true`                                                                                                   |
-| `calls.provider`                            | Voice provider (currently only `twilio`)                                                                                                                                                                                                  | `twilio`                                                                                                 |
-| `calls.maxDurationSeconds`                  | Maximum call length in seconds                                                                                                                                                                                                            | `3600` (1 hour)                                                                                          |
-| `calls.userConsultTimeoutSeconds`           | How long to wait for user answers                                                                                                                                                                                                         | `120` (2 min)                                                                                            |
-| `calls.disclosure.enabled`                  | Whether the AI announces itself at call start                                                                                                                                                                                             | `true`                                                                                                   |
-| `calls.disclosure.text`                     | The disclosure message spoken at call start                                                                                                                                                                                               | `"At the very beginning of the call, introduce yourself as an assistant calling on behalf of my human."` |
-| `llm.callSites.callAgent.model`             | Override LLM model for call orchestration                                                                                                                                                                                                 | _(unset — falls back to the resolved call-site default)_                                                 |
-| `calls.callerIdentity.allowPerCallOverride` | Allow per-call caller identity selection                                                                                                                                                                                                  | `true`                                                                                                   |
-| `calls.callerIdentity.userNumber`           | E.164 phone number for user-number mode                                                                                                                                                                                                   | _(empty)_                                                                                                |
-| `calls.voice.language`                      | Language code for TTS and transcription                                                                                                                                                                                                   | `en-US`                                                                                                  |
-| `services.stt.provider`                     | STT provider for transcription and telephony. The assistant transcribes call audio itself over the Twilio media stream (streaming when the provider supports it, batch otherwise), so calls require a working API key for this provider.  | `deepgram`                                                                                               |
-| `services.tts.provider`                     | Active TTS provider for speech synthesis. Must be a provider ID from the catalog (`elevenlabs`, `fish-audio`, `deepgram`, `xai`). New providers can be added via the catalog without code changes to call routing.                        | `elevenlabs`                                                                                             |
-| `services.tts.providers.<id>.*`             | Provider-specific settings block. Each catalog provider has its own settings namespace under `services.tts.providers.<id>`. See voice settings in the desktop/iOS app or run `assistant config list` for available settings per provider. | _(per-provider defaults)_                                                                                |
+| Setting                                     | Description                                                                                                                                                                                                                                                     | Default                                                                                                  |
+| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `calls.enabled`                             | Master switch for the calling feature                                                                                                                                                                                                                           | `true`                                                                                                   |
+| `calls.provider`                            | Voice provider (currently only `twilio`)                                                                                                                                                                                                                        | `twilio`                                                                                                 |
+| `calls.maxDurationSeconds`                  | Maximum call length in seconds                                                                                                                                                                                                                                  | `3600` (1 hour)                                                                                          |
+| `calls.userConsultTimeoutSeconds`           | How long to wait for user answers                                                                                                                                                                                                                               | `120` (2 min)                                                                                            |
+| `calls.disclosure.enabled`                  | Whether the AI announces itself at call start                                                                                                                                                                                                                   | `true`                                                                                                   |
+| `calls.disclosure.text`                     | The disclosure message spoken at call start                                                                                                                                                                                                                     | `"At the very beginning of the call, introduce yourself as an assistant calling on behalf of my human."` |
+| `llm.callSites.callAgent.model`             | Override LLM model for call orchestration                                                                                                                                                                                                                       | _(unset — falls back to the resolved call-site default)_                                                 |
+| `calls.callerIdentity.allowPerCallOverride` | Allow per-call caller identity selection                                                                                                                                                                                                                        | `true`                                                                                                   |
+| `calls.callerIdentity.userNumber`           | E.164 phone number for user-number mode                                                                                                                                                                                                                         | _(empty)_                                                                                                |
+| `services.stt.language`                     | Spoken language for transcription (BCP-47 code, or unset for the provider's multilingual default). Per-language TTS voices are configured via `services.tts.providers.<id>.languageVoices` (supported on the elevenlabs, deepgram, and vellum provider blocks). | _(unset)_                                                                                                |
+| `services.stt.provider`                     | STT provider for transcription and telephony. The assistant transcribes call audio itself over the Twilio media stream (streaming when the provider supports it, batch otherwise), so calls require a working API key for this provider.                        | `deepgram`                                                                                               |
+| `services.tts.provider`                     | Active TTS provider for speech synthesis. Must be a provider ID from the catalog (`elevenlabs`, `fish-audio`, `deepgram`, `xai`). New providers can be added via the catalog without code changes to call routing.                                              | `elevenlabs`                                                                                             |
+| `services.tts.providers.<id>.*`             | Provider-specific settings block. Each catalog provider has its own settings namespace under `services.tts.providers.<id>`. See voice settings in the desktop/iOS app or run `assistant config list` for available settings per provider.                       | _(per-provider defaults)_                                                                                |
 
 ## TTS provider call-path behavior
 

package/src/config/bundled-skills/schedule/SKILL.md

@@ -121,7 +121,11 @@ assistant conversations wake "$id" --hint "Summarize the new items" --external-c
 
 ## Inference Profile
 
-Execute-mode runs use the default `mainAgent` model selection unless the schedule pins an `inference_profile` (a key from `llm.profiles`). Pin a profile when a recurring task should run on a specific model — e.g. a cost-optimized profile for a high-frequency digest. Pass `inference_profile: null` on update to revert to the default. The pinned profile is shown on the schedule's details page in settings.
+Every schedule carries a pinned `inference_profile` (a key from `llm.profiles`), so a recurring task keeps running on the model (and the price) it was created under even when the user later changes their default profile. Creating a schedule without `inference_profile` pins it to the user's current default; pass one explicitly when a task should run on a specific model, e.g. a cost-optimized profile for a high-frequency digest. Passing `inference_profile: null` on update re-pins the schedule to the user's current default rather than unpinning it. The pinned profile is shown on the schedule's details page in settings.
+
+The pin governs the agent turns a schedule runs: an execute-mode run, a wake-mode run, and the turns a script-mode schedule hands off to the agent loop with `assistant conversations wake`. The schedule id travels in the script's environment, so those handoff turns run on the pinned profile with no flag to pass. Notify-mode schedules run no agent turn at all, so their pin never comes into play.
+
+Workflow-mode schedules are the exception: each step of a workflow resolves its own model, so a workflow schedule's pin does not govern its runs.
 
 ## Conversation Group
 

package/src/config/bundled-skills/schedule/TOOLS.json

@@ -110,7 +110,7 @@
           },
           "inference_profile": {
             "type": "string",
-            "description": "Inference profile (a key from llm.profiles) the schedule's LLM-executed runs should use, e.g. to run a heavy task on a cheaper model. When omitted, runs use the default mainAgent model selection. Must name a configured profile."
+            "description": "Inference profile (a key from llm.profiles) the schedule's LLM-executed runs should use, e.g. to run a heavy task on a cheaper model. When omitted, the schedule is pinned to the user's current default profile so its model does not change later. Must name a configured profile. Workflow-mode schedules resolve a model per workflow step, so the pin does not govern their runs."
           },
           "group": {
             "type": "string",
@@ -233,7 +233,7 @@
           },
           "inference_profile": {
             "type": ["string", "null"],
-            "description": "Inference profile (a key from llm.profiles) the schedule's LLM-executed runs should use. Pass null to clear the override and revert to the default mainAgent model selection. Must name a configured profile."
+            "description": "Inference profile (a key from llm.profiles) the schedule's LLM-executed runs should use. Pass null to re-pin the schedule to the user's current default profile. Must name a configured profile. Workflow-mode schedules resolve a model per workflow step, so the pin does not govern their runs."
           },
           "group": {
             "type": ["string", "null"],

package/src/config/bundled-skills/settings/TOOLS.json

@@ -3,7 +3,7 @@
   "tools": [
     {
       "name": "voice_config_update",
-      "description": "Update a voice configuration setting. Use tts_provider / stt_provider to switch the active TTS / STT provider. Provider \"vellum\" is Vellum-managed speech (billed to your organization; requires a Vellum platform connection via 'assistant platform connect'); any other provider uses the user's own API key. Valid TTS providers come from the provider catalog (vellum, elevenlabs, fish-audio, deepgram, xai); valid STT providers: vellum, deepgram, google-gemini, openai-whisper, xai. Use tts_voice_id to change the voice; it targets whichever TTS provider is currently active. For elevenlabs, pass an ElevenLabs voice ID. For vellum (managed), pass a managed voice model ID: this may be an ElevenLabs voice ID (managed speech serves the same ElevenLabs voices) or a Deepgram Aura model ID (e.g. aura-2-thalia-en); only rate-carded voices synthesize, so prefer models from the managed catalog (daemon route GET tts/managed-voices, also used by the web voice picker). For deepgram, pass a Deepgram Aura model ID. Use fish_audio_reference_id for Fish Audio voice reference. Use stt_language to set the spoken language for speech recognition: one of the 49 base language codes on the verified Deepgram nova-3 monolingual roster (e.g. en, es, hi, ta, zh, ko), or \"multi\" for code-switching mid-sentence across its 10-language roster (English, Spanish, French, German, Hindi, Russian, Portuguese, Japanese, Italian, Dutch; e.g. Hinglish); plain language names like \"tamil\" or \"multilingual\" are accepted and normalized. Accepted values follow the configured STT provider: vellum-managed and deepgram accept the full roster plus \"multi\"; xai accepts only the 10 multilingual-roster codes (en, es, fr, de, hi, ru, pt, ja, it, nl) and rejects \"multi\" and the extended codes (both are verified for Deepgram nova-3 only); google-gemini / openai-whisper auto-detect natively, so the value persists but is ignored while they are active. Deepgram uses the same API key for TTS and STT. Changes persist to services.stt / services.tts config and take effect immediately.",
+      "description": "Update a voice configuration setting. Use tts_provider / stt_provider to switch the active TTS / STT provider. Provider \"vellum\" is Vellum-managed speech (billed to your organization; requires a Vellum platform connection via 'assistant platform connect'); any other provider uses the user's own API key. Valid TTS providers come from the provider catalog (vellum, elevenlabs, fish-audio, deepgram, xai); valid STT providers: vellum, deepgram, deepgram-flux, google-gemini, openai-whisper, xai. deepgram-flux is streaming-only: it serves live speech (voice mode, dictation) but cannot transcribe audio files or voice messages, so do not recommend it when the user wants file transcription. Use tts_voice_id to change the voice; it targets whichever TTS provider is currently active. For elevenlabs, pass an ElevenLabs voice ID. For vellum (managed), pass a managed voice model ID: this may be an ElevenLabs voice ID (managed speech serves the same ElevenLabs voices) or a Deepgram Aura model ID (e.g. aura-2-thalia-en); only rate-carded voices synthesize, so prefer models from the managed catalog (assistant route GET tts/managed-voices, also used by the web voice picker). For deepgram, pass a Deepgram Aura model ID. Use fish_audio_reference_id for Fish Audio voice reference. Use stt_language to set the spoken language for speech recognition: one of the 50 base language codes on the verified Deepgram nova-3 monolingual roster (e.g. en, es, hi, ta, zh, ko), or \"multi\" for code-switching mid-sentence across its 10-language roster (English, Spanish, French, German, Hindi, Russian, Portuguese, Japanese, Italian, Dutch; e.g. Hinglish); plain language names like \"tamil\" or \"multilingual\" are accepted and normalized. Accepted values follow the configured STT provider: vellum-managed and deepgram accept the full roster plus \"multi\"; xai accepts only the 10 multilingual-roster codes (en, es, fr, de, hi, ru, pt, ja, it, nl) and rejects \"multi\" and the extended codes (both are verified for Deepgram nova-3 only); google-gemini / openai-whisper auto-detect natively and deepgram-flux runs an English-only model, so the value persists but is ignored while they are active. Deepgram uses the same API key for TTS and STT, and deepgram-flux shares it too. Changes persist to services.stt / services.tts config and take effect immediately.",
       "category": "system",
       "risk": "low",
       "input_schema": {
@@ -20,10 +20,10 @@
               "tts_provider",
               "tts_voice_id"
             ],
-            "description": "The voice setting to change. tts_provider / stt_provider select the active provider for each service (\"vellum\" = Vellum-managed speech; anything else = the user's own API key). tts_voice_id sets the voice for the currently active TTS provider (ElevenLabs voice ID for elevenlabs; a managed voice model ID for vellum, meaning an ElevenLabs voice ID or a Deepgram Aura model ID like aura-2-thalia-en; a Deepgram Aura model ID for deepgram; voice ID for xai). fish_audio_reference_id sets the Fish Audio voice reference. stt_language sets the spoken language for speech recognition (vellum-managed/deepgram: the full roster plus \"multi\"; xai: only the 10 multilingual-roster codes, with \"multi\" and the extended codes rejected; google-gemini and openai-whisper auto-detect and ignore it). Deepgram shares one API key across TTS and STT."
+            "description": "The voice setting to change. tts_provider / stt_provider select the active provider for each service (\"vellum\" = Vellum-managed speech; anything else = the user's own API key). tts_voice_id sets the voice for the currently active TTS provider (ElevenLabs voice ID for elevenlabs; a managed voice model ID for vellum, meaning an ElevenLabs voice ID or a Deepgram Aura model ID like aura-2-thalia-en; a Deepgram Aura model ID for deepgram; voice ID for xai). fish_audio_reference_id sets the Fish Audio voice reference. stt_language sets the spoken language for speech recognition (vellum-managed/deepgram: the full roster plus \"multi\"; xai: only the 10 multilingual-roster codes, with \"multi\" and the extended codes rejected; google-gemini and openai-whisper auto-detect and ignore it; deepgram-flux is English-only and ignores it). Deepgram shares one API key across TTS and STT, and deepgram-flux uses that same key."
           },
           "value": {
-            "description": "The new value for the setting. For tts_provider: one of vellum, elevenlabs, fish-audio, deepgram, xai. For stt_provider: one of vellum, deepgram, google-gemini, openai-whisper, xai. For tts_voice_id: a voice ID for the active TTS provider: an alphanumeric ElevenLabs voice ID (elevenlabs), a managed voice model ID which may be an ElevenLabs voice ID or a Deepgram Aura model ID like aura-2-thalia-en (vellum), or a Deepgram Aura model ID (deepgram). For fish_audio_reference_id: a Fish Audio voice reference ID. For stt_language: one of the 49 base codes on the nova-3 monolingual roster (e.g. en, es, hi, ta, zh, ko), or multi (code-switching across its 10-language roster); language names like \"hindi\", \"tamil\", or \"multilingual\" are also accepted and normalized; when the configured STT provider is xai, only the 10 multilingual-roster codes (en, es, fr, de, hi, ru, pt, ja, it, nl) are accepted. For conversation_timeout: seconds (5, 10, 15, 30, or 60). For activation_key: key identifier string."
+            "description": "The new value for the setting. For tts_provider: one of vellum, elevenlabs, fish-audio, deepgram, xai. For stt_provider: one of vellum, deepgram, deepgram-flux, google-gemini, openai-whisper, xai; deepgram-flux serves live speech only and cannot transcribe files. For tts_voice_id: a voice ID for the active TTS provider: an alphanumeric ElevenLabs voice ID (elevenlabs), a managed voice model ID which may be an ElevenLabs voice ID or a Deepgram Aura model ID like aura-2-thalia-en (vellum), or a Deepgram Aura model ID (deepgram). For fish_audio_reference_id: a Fish Audio voice reference ID. For stt_language: one of the 50 base codes on the nova-3 monolingual roster (e.g. en, es, hi, ta, zh, ko), or multi (code-switching across its 10-language roster); language names like \"hindi\", \"tamil\", or \"multilingual\" are also accepted and normalized; when the configured STT provider is xai, only the 10 multilingual-roster codes (en, es, fr, de, hi, ru, pt, ja, it, nl) are accepted. For conversation_timeout: seconds (5, 10, 15, 30, or 60). For activation_key: key identifier string."
           }
         }
       },

package/src/config/bundled-skills/settings/tools/voice-config-update.ts

@@ -179,6 +179,7 @@ const STT_LANGUAGE_ALIASES: Record<
   thai: "th",
   turkish: "tr",
   ukrainian: "uk",
+  urdu: "ur",
   vietnamese: "vi",
   multilingual: "multi",
   auto: "multi",

package/src/config/bundled-skills/subagent/SKILL.md

@@ -22,33 +22,50 @@ Subagent orchestration -- spawn background agents to work on tasks in parallel.
 
 Subagents follow this status flow: `pending` -> `running` -> `completed` / `failed` / `aborted`
 
-- **Spawn**: Use `subagent_spawn` with a label, objective, and role. The subagent runs autonomously.
+- **Spawn**: Use `subagent_spawn` with a label, objective, and type. The subagent runs autonomously.
 - **Mid-run communication**: Subagents can send notifications to the parent via `notify_parent` while still running -- useful for sharing interim findings or signaling that they are blocked.
 - **Auto-notification**: The parent conversation is automatically notified when a subagent reaches a terminal status (completed/failed/aborted). Do NOT poll `subagent_status`.
 - **Read output**: Use `subagent_read` after the subagent reaches a terminal status to retrieve its full output.
 
-## Roles
+## Types
 
-Each subagent is spawned with a role that determines its tool access. Choose the most restrictive role that can accomplish the task.
+There are three subagent types. Pick one with two questions: **does it need to change anything**, and **do you need its answer before you can continue?**
 
 `recall` is local information search across memory, the personal knowledge base, past conversations, and workspace files. Use it when a subagent needs prior context that is not already in the prompt.
 
-| Role | Tools | When to use |
-|---|---|---|
-| `general` | Full tool access | Task genuinely needs unrestricted capabilities (rare -- prefer a specialized role) |
-| `researcher` | `web_search`, `web_fetch`, `file_read`, `file_list`, `recall`, `notify_parent` | Information gathering, web research, codebase exploration, reading documentation |
-| `coder` | `bash`, `file_read`, `file_write`, `file_edit`, `web_search`, `recall`, `notify_parent` | Code changes, file editing, running commands, build/test tasks |
-| `planner` | `file_read`, `file_list`, `web_search`, `web_fetch`, `recall`, `notify_parent` | Analysis, planning, synthesizing information, reviewing approaches |
-| `investigator` | `code_search`, `file_read`, `file_list`, `web_search`, `web_fetch`, `recall`, `notify_parent` | Root-cause analysis: debugging, log forensics, tracing behavior across many files. Read-only search/read tools only (no shell): use `code_search` to grep file contents across directories, `file_list` to enumerate paths, `file_read` to read whole files and logs; returns a compact root-cause report |
-| `advisor` | None (tool-less) | Read-only senior-advisor consult. Runs on a stronger model, inherits full parent context, and BLOCKS until it returns guidance |
+| Type | Changes things? | You wait? | Tools | When to use |
+|---|---|---|---|---|
+| `researcher` | No | No | `web_search`, `web_fetch`, `file_read`, `file_list`, `code_search`, `recall`, `skill_execute`, `notify_parent` | Web research, codebase exploration, reading documentation, root-cause investigation, reviewing an approach against the code |
+| `builder` | Yes | No | Your whole tool surface, unrestricted: shell, file writes and edits, and every connector, MCP, and browser tool you can reach | Code changes, file output, build/test runs, anything that must run a command or act on an outside system |
+| `advisor` | No | Yes | Read-only fact checking in the workspace: `file_read`, `file_list`, `code_search` | Read-only senior-advisor consult. Runs on a stronger model, inherits full parent context, and BLOCKS until it returns guidance |
 
-All specialized roles (`researcher`, `coder`, `planner`) include `notify_parent` for mid-run communication with the parent.
+Both background types can call `notify_parent` for mid-run communication with the parent.
 
-Read-only roles (`researcher`, `planner`, `investigator`, `advisor`) cannot write or edit files, run commands, or otherwise persist output. If the task must **produce a file, save results, or run a command**, use `coder` (or `general`) — a read-only role finishes without producing anything, and the delegated write silently no-ops.
+A `researcher` is scoped to the fixed read-only list above: it cannot write or edit files, run commands, reach a connector, or otherwise persist output. If the task must **produce a file, save results, run a command, or act on an outside system**, spawn a `builder`: a researcher finishes without producing anything, and the delegated write silently no-ops.
+
+**Model tier is a separate knob.** Use `inference_profile` to run any type on a stronger or cheaper model. **A persona is not a type**: see the fallback below.
+
+### Legacy names and unknown roles
+
+The older role names still work: `planner` and `investigator` run as a `researcher`, `coder` and `general` run as a `builder`. The spawn result names the type that actually ran.
+
+Any other `role` text is treated as a persona, not a type. The subagent runs as a **`researcher`** (read-only) with that text framing how it approaches the task, and the spawn result says so. That is deliberate least privilege: an invented or misspelled role must never silently hand out write access. If the task genuinely needed to write, the subagent reports that it cannot, and you re-spawn it with `role: "builder"`.
+
+Omitting `role` entirely runs a `builder`, so a spawn that names no type keeps your full tool surface.
+
+### Verification
+
+Checking that something is actually done is not a fourth type. It is a `researcher` with `output_contract: "verdict"`.
+
+A verdict subagent returns, for each criterion in the objective, `PASS` or `FAIL` plus the exact evidence (file path, line, value, or quote), `CANNOT VERIFY` where the evidence is missing, and nothing else. Give it the criteria explicitly in the objective; a vague "check the work" gets you a vague list.
+
+It runs on a cheaper model by default, because checking a claim against evidence that already exists is mechanical work, not investigation. An explicit `inference_profile` still wins if a check genuinely needs a stronger model, and so does a profile pinned on the `subagentSpawn` call site in config (see Inference Profile below).
+
+The other contracts: `output_contract: "artifact"` tells a `builder` that the deliverable is the thing produced and to end by listing the exact files it created or modified. `"report"` is the default and asks for nothing extra. A contract that does not match the type is rejected rather than quietly changed, and the `advisor` takes no contract (it has its own framing).
 
 ## Consulting the Advisor
 
-The `advisor` role is the one role you spawn on your own judgment, unprompted — you do NOT wait for the user to ask for a subagent. The other roles (`researcher`, `coder`, `planner`, `investigator`, `general`) stay delegation-driven: reach for them to offload work, typically when the user's request calls for it. The advisor is different: proactively consult it whenever the conditions below are met.
+The `advisor` is the one type you spawn on your own judgment, unprompted: you do NOT wait for the user to ask for a subagent. The background types (`researcher`, `builder`) stay delegation-driven: reach for them to offload work, typically when the user's request calls for it. The advisor is different: proactively consult it whenever the conditions below are met.
 
 Orient yourself first (read the relevant files, understand the task), then consult the advisor:
 
@@ -58,7 +75,7 @@ Orient yourself first (read the relevant files, understand the task), then consu
 
 The consult is synchronous and read-only: spawning an `advisor` subagent BLOCKS until it returns guidance. It runs on a stronger model and inherits your full context, so it sees the task, your tool calls, and their results without you re-explaining. It also receives a snapshot of your environment (the tools available to you this turn, the full skill catalog, and your workspace) so its guidance can point you at existing platform capabilities by name. Give its guidance serious weight; only override it when primary-source evidence contradicts a specific claim, and say so when you do.
 
-Beyond that snapshot, the advisor sees only what is in this conversation. It cannot read files, other conversations, or external systems on its own. If you want it to weigh specific evidence (a file's contents, a command's output, results gathered elsewhere), surface that evidence in the conversation or the spawn objective before consulting.
+The advisor has read-only workspace tools (`file_read`, `file_list`, `code_search`) so it can open a file or search the code when a decisive fact would change its advice. It uses them sparingly, for verification rather than exploration, and it cannot change anything or persist output. It has no memory search and cannot see other conversations or external systems, and every lookup it has to make delays your answer, so surface the evidence you already have (a file's contents, a command's output, results gathered elsewhere) in the conversation or the spawn objective before consulting.
 
 Spawn the advisor **alone** — do NOT batch the consult in the same turn as other tool calls (especially file edits, shell commands, or anything destructive or expensive). Tool calls you issue in the same turn run concurrently with the consult, so they would execute before you see its guidance. Consult the advisor by itself, read its guidance, then act.
 
@@ -90,15 +107,29 @@ Only the parent conversation that spawned a subagent can interact with it (check
 
 Set `send_result_to_user: false` when spawning a subagent whose result is for internal processing only. The parent will still be notified on completion, but the notification will instruct it to read the result without presenting it to the user.
 
+## Repeat Spawns
+
+Spawning an objective that several near-identical subagents have already completed in the last day can come back as a message about those earlier runs instead of a new subagent. Read what the earlier run produced with `subagent_read`, or narrow the objective to what is actually still missing.
+
+A second message covers the other shape: near-identical copies that are still running and have returned nothing yet. There is nothing to read in that case, so wait for the running ones to report back, or narrow the objective to the part they are not covering.
+
+Either way it is advisory, not a block: pass `confirm_repeat: true` to spawn anyway. An `advisor` consult is never held this way.
+
 ## Inference Profile
 
-Set `inference_profile` to an `llm.profiles` key when a subagent should run under a specific model profile. When omitted, the subagent inherits the parent turn's active profile if one exists; otherwise it uses the `subagentSpawn` call site's default model selection.
+Set `inference_profile` to an `llm.profiles` key when a subagent should run under a specific model profile.
+
+When it is omitted, the subagent takes the `subagentSpawn` call site's default model selection. It does not pick up the profile the spawning turn is running on: a profile pinned on a conversation is a choice about that conversation, and it does not follow the work that conversation delegates.
+
+An `inference_profile` you name explicitly wins, unless the model catalog does not report it as tool-capable, in which case it is replaced by the `subagentSpawn` default with a note on the spawn result. An `advisor` consult applies that same fallback, with the note alongside its guidance.
+
+`output_contract: "verdict"` takes a cheaper profile, so a verdict runs cheap unless you name an `inference_profile` yourself. A profile pinned on the `subagentSpawn` call site in config also beats the cheap preset, so an operator can decide what checks run on.
 
 ## Fork Mode
 
 Forks are sub-agents that inherit the parent's full context -- messages, system prompt, and memory -- sharing the KV cache for near-free context inheritance. Use forks when the task benefits from knowing what you've been discussing; use a regular sub-agent when the task is self-contained.
 
-**Key behaviors:** Forks default to `general` role (the `role` parameter is ignored for forks), except the special `advisor` role, which is honored even as a fork. `send_result_to_user` defaults to `false`. Read fork output with `last_n: 1` to get only the final synthesis.
+**Key behaviors:** A fork honors the type you name, so `role: "researcher"` gives a read-only fork. A fork that names no type runs as a `builder` and so keeps your full tool surface, which is what the system prompt it inherits describes. A persona reaches a fork through its task framing rather than its prompt, since the prompt is yours verbatim. `send_result_to_user` defaults to `false`. Read fork output with `last_n: 1` to get only the final synthesis.
 
 **When to fork vs regular sub-agent:**
 
@@ -110,17 +141,17 @@ Forks are sub-agents that inherit the parent's full context -- messages, system
 | Comparing multiple sources against what was discussed | Parallel forks |
 | Self-contained task with a clear objective | Regular sub-agent |
 
-Rule of thumb: "Does this task need to know what we've been talking about?" If yes, fork. If the objective is fully self-describing, use a regular sub-agent with a scoped role.
+Rule of thumb: "Does this task need to know what we've been talking about?" If yes, fork. If the objective is fully self-describing, use a regular sub-agent with a scoped type.
 
 ## Tips
 
 - Do NOT poll `subagent_status` in a loop. You will be notified automatically when a subagent completes.
-- Use roles to scope tool access and minimize blast radius. Default to the most restrictive role that works.
-- Spawn a `researcher` and `coder` in parallel for research-then-implement workflows -- the researcher gathers context while the coder starts on the known parts.
+- Prefer `researcher` unless the task has to change something. Read-only is the smaller blast radius, and most delegated work is reading.
+- Spawn a `researcher` and a `builder` in parallel for research-then-implement workflows -- the researcher gathers context while the builder starts on the known parts.
 - Use `notify_parent` for interim findings instead of waiting for completion. This lets the parent act on partial results early.
 - Use `subagent_message` to send follow-up instructions to a running subagent.
 - Use `subagent_abort` to cancel a subagent that is no longer needed.
 - Default to spawning subagents for any task that involves web research, multi-file exploration, or independent coding work. Serial execution should be the exception, not the rule.
-- Delegate root-cause investigations ("why is X happening?", debugging, log forensics) to an `investigator` instead of grepping inline. A long investigation done inline floods your own context with file slices and grep output, crowding out the conversation; the investigator does the digging in its own context and returns a compact root-cause report.
+- Delegate root-cause investigations ("why is X happening?", debugging, log forensics) to a `researcher` instead of grepping inline. A long investigation done inline floods your own context with file slices and grep output, crowding out the conversation; the researcher does the digging in its own context and returns a compact root-cause report.
 - When a user request has both an information-gathering component and an action component, spawn a researcher immediately rather than doing the research inline yourself.
-- Prefer spawning 2-3 focused subagents over one large general-purpose subagent. Smaller scopes finish faster and fail more gracefully.
+- Prefer spawning 2-3 focused subagents over one broad one. Smaller scopes finish faster and fail more gracefully.

package/src/config/bundled-skills/subagent/TOOLS.json

@@ -3,7 +3,7 @@
   "tools": [
     {
       "name": "subagent_spawn",
-      "description": "Spawn an independent subagent to work on a task in parallel. The subagent runs autonomously and its results are reported back when complete.\n\nTwo modes:\n- **Regular sub-agent** (fork: false or omitted): Gets only the objective + context fields. Use for self-contained tasks with clear objectives. Can use scoped roles (researcher, coder, planner).\n- **Fork** (fork: true): Inherits full parent context (messages, system prompt, memory). Shares KV cache for near-free context inheritance. Use when the task benefits from knowing what you've been discussing. Defaults to general role (the 'advisor' role is the exception: it is honored as a fork). Results are internal by default (send_result_to_user: false). Read with last_n: 1 to get only the final synthesis.\n\nDecision heuristic: Does the task need to know what we've been talking about? Fork. Is it self-contained? Regular sub-agent.\n\nThe 'advisor' role is a synchronous, read-only \"consult a stronger advisor\" mode: it inherits your full context plus a snapshot of your environment (available tools, skill catalog, workspace), has no tools of its own, and BLOCKS until it returns focused strategic guidance in a single response.",
+      "description": "Spawn an independent subagent to work on a task in parallel. The subagent runs autonomously and its results are reported back when complete.\n\nTwo modes:\n- **Regular sub-agent** (fork: false or omitted): Gets only the objective + context fields. Use for self-contained tasks with clear objectives. Pick its type with role: 'researcher' (read-only, fixed tool list) or 'builder' (write-capable, your whole tool surface).\n- **Fork** (fork: true): Inherits full parent context (messages, system prompt, memory). Shares KV cache for near-free context inheritance. Use when the task benefits from knowing what you've been discussing. A fork that names a role runs scoped to it; a fork that names none keeps your full tool surface. Results are internal by default (send_result_to_user: false). Read with last_n: 1 to get only the final synthesis.\n\nDecision heuristic: Does the task need to know what we've been talking about? Fork. Is it self-contained? Regular sub-agent.\n\nThe 'advisor' role is a synchronous, read-only \"consult a stronger advisor\" mode: it inherits your full context plus a snapshot of your environment (available tools, skill catalog, workspace), has read-only workspace tools for checking a decisive fact (file_read, file_list, code_search), and BLOCKS until it returns focused strategic guidance in a single response. It cannot change anything, persist output, or see other conversations.",
       "category": "orchestration",
       "risk": "low",
       "input_schema": {
@@ -23,7 +23,7 @@
           },
           "fork": {
             "type": "boolean",
-            "description": "When true, the subagent inherits the parent's full context (messages, system prompt, memory) instead of receiving only the objective + context fields. Fork mode defaults to 'general' role (the role parameter is ignored for forks), except the special 'advisor' role which is honored even as a fork, and defaults send_result_to_user to false. Use for tasks that benefit from the full conversational context."
+            "description": "When true, the subagent inherits the parent's full context (messages, system prompt, memory) instead of receiving only the objective + context fields. A fork honors the role you name; naming none keeps this conversation's full tool surface, since the inherited system prompt describes those tools. Forks default send_result_to_user to false. Use for tasks that benefit from the full conversational context."
           },
           "send_result_to_user": {
             "type": "boolean",
@@ -31,19 +31,20 @@
           },
           "role": {
             "type": "string",
-            "enum": [
-              "general",
-              "researcher",
-              "coder",
-              "planner",
-              "investigator",
-              "advisor"
-            ],
-            "description": "Agent specialization that controls tool access. 'researcher': read-only (web, files, memory). 'coder': file and bash access. 'planner': read-only analysis. 'investigator': root-cause analysis: debugging, log forensics, tracing behavior across many files; uses read-only search/read tools (code_search, file_read, file_list) with no shell access and returns a compact root-cause report. 'advisor': synchronous, read-only \"consult a stronger advisor\": inherits full context plus a snapshot of your environment (available tools, skill catalog, workspace), has no tools of its own, and blocks until it returns focused strategic guidance. 'general': full access (default). The read-only roles (researcher, planner, investigator, advisor) cannot persist output; use 'coder' or 'general' for any objective that must write files or run commands, or a read-only subagent will finish without producing anything. Non-advisor roles are ignored when fork: true (forks default to general); the advisor role is honored even as a fork."
+            "description": "Which of the three subagent types to run, chosen by two questions: does it need to change anything, and do you need the answer before you can continue? 'researcher': changes nothing, runs in the background, scoped to a fixed read-only list (web_search, web_fetch, file_read, file_list, code_search, recall, skill_execute) for research, exploration, root-cause investigation, and review. 'builder': changes things, runs in the background on this conversation's whole tool surface (shell, file writes and edits, plus every connector, MCP, and browser tool you can reach) for code changes, file output, and anything that must run a command or act on an outside system. 'advisor': changes nothing and BLOCKS your turn until it answers; inherits your full context plus a snapshot of your environment (available tools, skill catalog, workspace), can read files and search code (file_read, file_list, code_search) to check a decisive fact, and returns focused strategic guidance. Default when omitted: 'builder', so a spawn that names no type keeps the full tool surface. The older names are still accepted as aliases ('planner' and 'investigator' run as researcher, 'coder' and 'general' run as builder). Any other text is not a type: the subagent runs as a researcher with that text as its persona, so if the task must write files or run commands, name 'builder' explicitly. A read-only subagent asked to produce a file finishes without producing anything. Roles apply to forks too; a fork that names no role runs as a builder and keeps this conversation's full tool surface, and a fork's persona reaches it through its task framing."
           },
           "inference_profile": {
             "type": "string",
-            "description": "Optional llm.profiles key this subagent should run under. When omitted, the subagent inherits the parent turn's profile when one is active; otherwise it uses the subagentSpawn call site's default model selection."
+            "description": "Optional llm.profiles key this subagent should run under. When omitted, the subagent takes the subagentSpawn call site's default model selection, never the profile your own turn is running on: a profile pinned on this conversation is a choice about this conversation and does not follow the work you delegate. A profile you name here that the model catalog does not report as tool-capable is replaced by that same default, with a note on the result. An output_contract of 'verdict' takes a cheaper profile unless you name a profile here, or unless the subagentSpawn call site has its own profile pinned in config, which also beats the cheaper preset."
+          },
+          "confirm_repeat": {
+            "type": "boolean",
+            "description": "Set true to spawn anyway when the repeat-spawn guard reports that this objective already completed several times in the last day, or that near-identical copies of it are still running with nothing returned yet."
+          },
+          "output_contract": {
+            "type": "string",
+            "enum": ["report", "verdict", "artifact"],
+            "description": "What the subagent owes back. 'report' (default): prose answering the objective. 'verdict': per-criterion PASS or FAIL with the exact evidence (file path, line, value, or quote), CANNOT VERIFY where evidence is missing, and no prose beyond that list; researcher-only, and it defaults to a cheaper model because checking is mechanical. Use it for completion checks and audits instead of spawning a premium investigator. 'artifact': the deliverable is the thing produced, ending with the exact files created or modified; builder-only. A contract that does not match the role is rejected rather than coerced, and the advisor takes no contract at all."
           }
         },
         "required": ["label", "objective"]
@@ -123,7 +124,7 @@
     },
     {
       "name": "subagent_read",
-      "description": "Read the full conversation output from a subagent. Use this after a subagent completes to retrieve its full work product.",
+      "description": "NOT a file reader: this returns a subagent's conversation output, addressed by subagent_id or label. To read a file from disk use file_read instead. Use this after a subagent completes to retrieve its full work product; while it is still running you will be notified automatically when it finishes, so there is no need to poll.",
       "category": "orchestration",
       "risk": "low",
       "input_schema": {