@vellumai/assistant 0.11.6 → 0.11.7-staging.2

package/src/cli/commands/mcp.ts

@@ -195,7 +195,7 @@ export function registerMcpCommand(program: Command): void {
               url?: string;
               command?: string;
               args?: string[];
-              risk: string;
+              risk?: string;
               header: string[];
               disabled?: boolean;
             },

package/src/cli/commands/memory/memory-retrospective.ts

@@ -169,6 +169,7 @@ function renderOutcome(outcome: MemoryRetrospectiveOutcome): void {
     case "invoked":
       log.info(
         `Retrospective invoked.\n` +
+          `  outcome:           ${outcome.noFindings ? "reviewed, nothing new to save" : "saved to memory"}\n` +
           `  fork conversation: ${outcome.backgroundConversationId}\n` +
           `  cutoff message:    ${outcome.cutoffMessageId}\n` +
           `  new messages:      ${outcome.newMessageCount}` +

package/src/cli/commands/stt.help.ts

@@ -12,7 +12,7 @@
 // `import()` has nothing to defer.
 // eslint-disable-next-line cli/no-daemon-internals
 import {
-  listProviderIds,
+  listSelectableProviderIds,
   supportsBoundary,
 } from "../../providers/speech-to-text/provider-catalog.js";
 import type { CliCommandHelp } from "../lib/cli-command-help.js";
@@ -22,7 +22,7 @@ import type { CliCommandHelp } from "../lib/cli-command-help.js";
  * providers are omitted: naming one would advertise a configuration that
  * fails on every file.
  */
-const batchProviders = listProviderIds()
+const batchProviders = listSelectableProviderIds()
   .filter((id) => supportsBoundary(id, "daemon-batch"))
   .join(", ");
 

package/src/config/__tests__/backup-schema.test.ts

@@ -7,7 +7,7 @@ import {
 } from "../schemas/backup.js";
 
 describe("BackupConfigSchema", () => {
-  test("empty object parses to full defaults (disabled, sensible intervals, iCloud default)", () => {
+  test("empty object parses to full platform-neutral defaults", () => {
     const parsed = BackupConfigSchema.parse({});
     expect(parsed).toEqual({
       enabled: false,

package/src/config/__tests__/default-profile-catalog.test.ts

@@ -8,10 +8,12 @@ import {
   getEffectiveProfile,
   getEffectiveProfiles,
   getEffectiveProfilesForProvider,
+  getUserSelectableProfilesForProvider,
   PROFILE_IMPLS,
   resolveDefaultProfileForProvider,
 } from "../default-profile-catalog.js";
 import {
+  BACKUP_PROFILE_KEYS,
   DEFAULT_PROFILE_KEYS,
   DEFAULT_PROFILE_PROVIDERS,
   OS_BETA_PROFILE_KEY,
@@ -78,7 +80,7 @@ describe("getEffectiveProfiles", () => {
   test("defaults absent from the workspace resolve from the catalog; os-beta stays flag-gated", () => {
     const effective = getEffectiveProfiles(undefined);
     expect(Object.keys(effective).sort()).toEqual(
-      [...DEFAULT_PROFILE_KEYS].sort(),
+      [...DEFAULT_PROFILE_KEYS, ...BACKUP_PROFILE_KEYS].sort(),
     );
     expect(getEffectiveProfile({}, "balanced")?.model).toBe(
       CODE_DEFAULT_PROFILE_ENTRIES.balanced.model as string,
@@ -155,6 +157,25 @@ describe("getEffectiveProfiles", () => {
   });
 });
 
+describe("user-selectable profile view", () => {
+  test("hides managed backups while retaining them in the fallback catalog", () => {
+    const effective = getEffectiveProfilesForProvider(undefined, {
+      provider: "vellum",
+    });
+    const selectable = getUserSelectableProfilesForProvider(undefined, {
+      provider: "vellum",
+    });
+
+    for (const key of DEFAULT_PROFILE_KEYS) {
+      expect(selectable[key]).toBeDefined();
+    }
+    for (const key of BACKUP_PROFILE_KEYS) {
+      expect(effective[key]).toBeDefined();
+      expect(selectable[key]).toBeUndefined();
+    }
+  });
+});
+
 describe("resolver integration", () => {
   test("resolution serves default-profile content from the code catalog, not the workspace body", () => {
     // The headline milestone test: with only thin managed stubs on disk,
@@ -267,6 +288,40 @@ describe("resolver integration", () => {
       }),
     ).not.toThrow();
   });
+
+  test("a user profile cannot shadow a managed backup profile", () => {
+    // Every backup is code-owned for the same reason `latency-optimized` is:
+    // a backup earns its place by pinning a different upstream than the
+    // primary it backs, and a user shadow can repoint it at the primary's
+    // own provider, so the fallback re-sends into the outage it exists to
+    // route around. `latency-optimized-backup` additionally serves the
+    // live-voice path whenever that primary falls back.
+    for (const key of BACKUP_PROFILE_KEYS) {
+      const llm = LLMSchema.parse({
+        profiles: {
+          [key]: {
+            source: "user",
+            provider: "anthropic",
+            model: "claude-opus-4-6",
+            provider_connection: "anthropic-personal",
+            maxTokens: 32000,
+            effort: "high",
+          },
+        },
+      });
+      const body = CODE_DEFAULT_PROFILE_ENTRIES[key]!;
+      const effective = getEffectiveProfiles(llm.profiles)[key];
+      expect(effective?.model).toBe(body.model);
+      expect(effective?.model).not.toBe("claude-opus-4-6");
+      expect(String(effective?.provider)).toBe("vellum");
+      expect(effective?.provider_connection).toBeUndefined();
+      // Resolution through the managed column agrees with the listing.
+      const resolved = resolveDefaultProfileForProvider(llm.profiles, key, {
+        provider: "vellum",
+      });
+      expect(resolved?.model).toBe(body.model);
+    }
+  });
 });
 
 describe("schema validation", () => {
@@ -301,6 +356,27 @@ describe("schema validation", () => {
     ).toThrow();
   });
 
+  test("managed backup names are valid references without being materialized", () => {
+    // Backups are listed in the effective catalog and are selectable, but
+    // selecting one persists only the reference: nothing lands in
+    // `llm.profiles`. Unless the schema treats the keys as always-available,
+    // the next load strips the selection and silently reverts it.
+    for (const key of BACKUP_PROFILE_KEYS) {
+      expect(() => LLMSchema.parse({ activeProfile: key })).not.toThrow();
+      expect(() => LLMSchema.parse({ advisorProfile: key })).not.toThrow();
+      expect(() =>
+        LLMSchema.parse({ callSites: { mainAgent: { profile: key } } }),
+      ).not.toThrow();
+    }
+    // The keys stay out of `DEFAULT_PROFILE_KEYS`: that array drives picker
+    // order and the intent x provider matrix.
+    expect(
+      BACKUP_PROFILE_KEYS.some((key) =>
+        (DEFAULT_PROFILE_KEYS as readonly string[]).includes(key),
+      ),
+    ).toBe(false);
+  });
+
   test("defaultProvider accepts any default-capable API-key provider and drops the rest", () => {
     expect(
       LLMSchema.parse({ defaultProvider: { provider: "together" } })
@@ -308,7 +384,12 @@ describe("schema validation", () => {
     ).toEqual({ provider: "together" });
     // Endpoint-supplied and keyless providers have no code-resolvable
     // default profile implementation; the catch drops them atomically.
-    for (const provider of ["litellm", "openai-compatible", "ollama"]) {
+    for (const provider of [
+      "litellm",
+      "opencode",
+      "openai-compatible",
+      "ollama",
+    ]) {
       expect(
         LLMSchema.parse({ defaultProvider: { provider } }).defaultProvider,
       ).toBeUndefined();

package/src/config/__tests__/loader-sparse-array-cleanup.test.ts

@@ -99,7 +99,7 @@ describe("config recovery compacts arrays after stripping invalid elements", ()
 
   test("emptied-by-compaction array reverts to a non-empty schema default (backup.offsite.destinations)", () => {
     // `backup.offsite.destinations` defaults to `null`, where `null` means "use
-    // the iCloud default destination" and `[]` means "no offsite destinations".
+    // the platform default" and `[]` means "no offsite destinations".
     // Stripping the sole invalid element must NOT leave an explicit `[]` that
     // overrides the default — it must fall back to the schema default `null`.
     writeConfig({

package/src/config/__tests__/memory-retrospective-schema.test.ts

@@ -1,10 +1,10 @@
 /**
  * Guards over the `memory.retrospective` switches that decide whether the
- * retrospective pass runs at all, and how its fork is materialized.
+ * retrospective pass runs at all.
  *
- * The defaults are the contract: a workspace that says nothing must behave
- * exactly as it did before the fields existed: retrospectives on, forks
- * cloned.
+ * The defaults are the contract: a workspace that says nothing must leave
+ * retrospectives on. A leftover `forkStrategy` key is ignored; retrospective
+ * forks are always referential.
  */
 
 import { describe, expect, test } from "bun:test";
@@ -12,10 +12,10 @@ import { describe, expect, test } from "bun:test";
 import { MemoryRetrospectiveConfigSchema } from "../schemas/memory-retrospective.js";
 
 describe("memory.retrospective config schema", () => {
-  test("an empty block leaves retrospectives on and forks cloning", () => {
+  test("an empty block leaves retrospectives on", () => {
     const parsed = MemoryRetrospectiveConfigSchema.parse({});
     expect(parsed.enabled).toBe(true);
-    expect(parsed.forkStrategy).toBe("cloning");
+    expect(parsed).not.toHaveProperty("forkStrategy");
   });
 
   test("enabled is a boolean-only kill switch", () => {
@@ -27,14 +27,11 @@ describe("memory.retrospective config schema", () => {
     ).toBe(false);
   });
 
-  test("forkStrategy accepts only cloning and reference", () => {
-    expect(
-      MemoryRetrospectiveConfigSchema.parse({ forkStrategy: "reference" })
-        .forkStrategy,
-    ).toBe("reference");
-    expect(
-      MemoryRetrospectiveConfigSchema.safeParse({ forkStrategy: "referential" })
-        .success,
-    ).toBe(false);
+  test("a leftover forkStrategy key is ignored", () => {
+    const parsed = MemoryRetrospectiveConfigSchema.parse({
+      forkStrategy: "cloning",
+    });
+    expect(parsed).not.toHaveProperty("forkStrategy");
+    expect(parsed.enabled).toBe(true);
   });
 });

package/src/config/bundled-skills/computer-use/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: computer-use
-description: Control the macOS desktop
+description: Control a connected desktop
 compatibility: "Designed for Vellum personal assistants"
 metadata:
   emoji: "🖥️"
@@ -8,17 +8,17 @@ metadata:
     display-name: "Computer Use"
     category: "system"
     activation-hints:
-      - "User asks the assistant to click, type, drag, or interact with the macOS GUI directly"
+      - "User asks the assistant to click, type, or interact with the desktop GUI directly"
       - "User wants control of a desktop app with no CLI or API alternative (games, design tools, visual workflows)"
       - "User wants screenshots or visual inspection of what is currently on screen"
     avoid-when:
       - "Task can be done via a more specific skill (gmail, calendar, contacts, terminal-sessions) or a CLI / API call"
 ---
 
-This skill provides the computer_use_* action tools for controlling
-the macOS desktop. CU tools run through the main agent loop via HostCuProxy.
+This skill provides the computer_use_* action tools for controlling a
+connected desktop. CU tools run through the main agent loop via HostCuProxy.
 
 The skill is internally preactivated for conversations with a connected desktop client.
 
-Tools in this skill are proxy tools - execution is forwarded to the connected
-macOS client, never handled locally by the assistant.
+Tools in this skill are proxy tools. Execution is forwarded to a connected
+desktop client and is never handled locally by the assistant.

package/src/config/bundled-skills/computer-use/TOOLS.json

@@ -86,7 +86,7 @@
     },
     {
       "name": "computer_use_key",
-      "description": "Press a key or keyboard shortcut. Supported: enter, tab, escape, backspace, delete, up, down, left, right, space, cmd+a, cmd+c, cmd+v, cmd+z, cmd+tab, cmd+w, shift+tab, option+tab",
+      "description": "Press a key or keyboard shortcut. Supported: enter, tab, escape, backspace, delete, up, down, left, right, space, cmd+a, cmd+c, cmd+v, cmd+z, cmd+tab, cmd+w, shift+tab, option+tab. On Windows use ctrl/alt in place of cmd/option.",
       "category": "computer-use",
       "risk": "medium",
       "input_schema": {
@@ -94,7 +94,7 @@
         "properties": {
           "key": {
             "type": "string",
-            "description": "Key or shortcut to press (e.g. enter, tab, cmd+c, cmd+v)"
+            "description": "Key or shortcut to press (e.g. enter, tab, ctrl+c, cmd+c)"
           },
           "reasoning": {
             "type": "string",
@@ -197,7 +197,8 @@
         "required": ["reasoning"]
       },
       "executor": "tools/computer-use-drag.ts",
-      "execution_target": "host"
+      "execution_target": "host",
+      "supported_client_os": ["macos", "windows"]
     },
     {
       "name": "computer_use_wait",
@@ -227,7 +228,7 @@
     },
     {
       "name": "computer_use_open_app",
-      "description": "Open or switch to a macOS application by name. Preferred over cmd+tab for switching apps - more reliable and explicit.",
+      "description": "Open or switch to a desktop application by name. Preferred over cmd+tab / alt+tab for switching apps - more reliable and explicit.",
       "category": "computer-use",
       "risk": "medium",
       "input_schema": {
@@ -249,7 +250,8 @@
         "required": ["app_name", "reasoning"]
       },
       "executor": "tools/computer-use-open-app.ts",
-      "execution_target": "host"
+      "execution_target": "host",
+      "supported_client_os": ["macos", "windows"]
     },
     {
       "name": "computer_use_run_applescript",
@@ -275,7 +277,8 @@
         "required": ["script", "reasoning"]
       },
       "executor": "tools/computer-use-run-applescript.ts",
-      "execution_target": "host"
+      "execution_target": "host",
+      "supported_client_os": ["macos"]
     },
     {
       "name": "computer_use_done",

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

@@ -40,7 +40,9 @@ export async function transcribeSegmentAudio(
     // Use the provided transcriber or resolve on demand.
     // null = "already resolved, no provider"; only re-resolve when undefined (not passed).
     const resolved =
-      transcriber === undefined ? await resolveBatchTranscriber() : transcriber;
+      transcriber === undefined
+        ? await resolveBatchTranscriber({ role: "batch" })
+        : transcriber;
     if (!resolved) {
       return "";
     }

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

@@ -466,7 +466,7 @@ export async function preprocessForAsset(
     let transcriber: BatchTranscriber | null = null;
     if (options.includeAudio) {
       try {
-        transcriber = await resolveBatchTranscriber();
+        transcriber = await resolveBatchTranscriber({ role: "batch" });
       } catch (err) {
         onProgress?.(
           `Audio transcription unavailable: ${(err as Error).message}\n`,

package/src/config/bundled-skills/phone-calls/SKILL.md

@@ -26,7 +26,7 @@ When speaking on behalf of your user during calls, refer to yourself as an "assi
 
 # Overview
 
-The calling system connects both **outbound** and **inbound** voice calls over Twilio Media Streams: the assistant transcribes and synthesizes call audio itself using the configured STT provider (`services.stt.provider`) and TTS provider (`services.tts.provider`, default: ElevenLabs), so working API keys for both are required before calls can connect. After Twilio setup, the assistant prompts the user to choose a voice from a curated list of supported options.
+The calling system connects both **outbound** and **inbound** voice calls over Twilio Media Streams: the assistant transcribes and synthesizes call audio itself using the STT provider telephony selects (`services.stt.roles.telephony` when set, otherwise `services.stt.provider`) and the TTS provider (`services.tts.provider`, default: ElevenLabs), so working API keys for both are required before calls can connect. After Twilio setup, the assistant prompts the user to choose a voice from a curated list of supported options.
 
 # Initial Setup
 

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

@@ -2,21 +2,22 @@
 
 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)_                                                                                                |
-| `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)_                                                                                |
+| 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`                     | Global STT provider, used by telephony when `services.stt.roles.telephony` is unset. 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 whichever provider telephony resolves to. | `deepgram`                                                                                               |
+| `services.stt.roles.telephony`              | STT provider (and optional `model` family) used for calls, overriding `services.stt.provider` for this consumer only. Calls require a working API key for this provider when it is set. A provider that cannot transcribe calls is rejected when the config is read, not at dial time.                     | _(unset, falls back to `services.stt.provider`)_                                                         |
+| `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/phone-calls/references/TROUBLESHOOTING.md

@@ -94,4 +94,5 @@ Load `twilio-setup` and follow its Channel Trust Floors section. Change **Who ca
 ## Call answers with a spoken "setup required" message and hangs up
 
 - The credential preflight found a missing STT or TTS provider credential — the spoken message names what is missing
-- Store the required API key for the configured `services.stt.provider` / `services.tts.provider` and retry
+- Store the required API key for the provider telephony actually resolves to (`services.stt.roles.telephony` when set, otherwise `services.stt.provider`) and for `services.tts.provider`, then retry
+- A key stored for the global provider does not satisfy a `services.stt.roles.telephony` override: the preflight judges the provider the call will dial

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, 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.",
+      "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 stt_model to pick a provider's model family where it has more than one: deepgram and vellum offer nova-3 (the default, and the only family that transcribes audio files or voice messages) and flux (conversational, streaming-only, with model-native turn detection). Do not select flux 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 and 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, whichever model family is selected. Changes persist to services.stt / services.tts config and take effect immediately.",
       "category": "system",
       "risk": "low",
       "input_schema": {
@@ -16,14 +16,15 @@
               "conversation_timeout",
               "fish_audio_reference_id",
               "stt_language",
+              "stt_model",
               "stt_provider",
               "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-flux is English-only and ignores it). Deepgram shares one API key across TTS and STT, and deepgram-flux uses that same key."
+            "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_model selects a provider's model family where it has more than one (deepgram and vellum: nova-3 or flux). 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."
           },
           "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, 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."
+            "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 stt_model: nova-3 or flux, applied to whichever STT provider is currently active; 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."
           }
         }
       },
@@ -32,7 +33,7 @@
     },
     {
       "name": "open_system_settings",
-      "description": "Open a specific macOS System Settings pane (e.g. Microphone or Speech Recognition privacy). Use this to guide the user through granting permissions that can only be toggled in System Settings.",
+      "description": "Open a specific macOS or Windows system settings pane (e.g. Microphone or Speech Recognition privacy). Use this to guide the user through granting permissions that can only be toggled in system settings. Set platform from the current client_os context.",
       "category": "system",
       "risk": "low",
       "input_schema": {
@@ -42,9 +43,14 @@
             "type": "string",
             "enum": ["microphone", "speech_recognition"],
             "description": "The System Settings pane to open"
+          },
+          "platform": {
+            "type": "string",
+            "enum": ["macos", "windows"],
+            "description": "The desktop platform from the current client_os context"
           }
         },
-        "required": ["pane"]
+        "required": ["pane", "platform"]
       },
       "executor": "tools/open-system-settings.ts",
       "execution_target": "host"

package/src/config/bundled-skills/settings/tools/open-system-settings.test.ts

@@ -0,0 +1,85 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type { ToolContext } from "../../../../tools/types.js";
+
+let windowsHost = true;
+
+mock.module("../../../../util/platform.js", () => ({
+  isWindows: () => windowsHost,
+}));
+
+const { run } = await import("./open-system-settings.js");
+
+let sentMessages: Array<{ type: string; [key: string]: unknown }> = [];
+
+function makeContext(): ToolContext {
+  return {
+    workingDir: "/tmp",
+    conversationId: "conv-xyz",
+    trustClass: "guardian",
+    sendToClient: (message) => {
+      sentMessages.push(message);
+    },
+  };
+}
+
+describe("open_system_settings tool", () => {
+  beforeEach(() => {
+    sentMessages = [];
+    windowsHost = true;
+  });
+
+  test("opens Windows microphone privacy settings", async () => {
+    const result = await run(
+      { pane: "microphone", platform: "windows" },
+      makeContext(),
+    );
+
+    expect(result).toEqual({
+      content:
+        "Opened Windows Settings to Microphone privacy. Please enable Vellum Assistant.",
+      isError: false,
+    });
+    expect(sentMessages).toEqual([
+      {
+        type: "open_url",
+        url: "ms-settings:privacy-microphone",
+        conversationId: "conv-xyz",
+      },
+    ]);
+  });
+
+  test("opens macOS speech recognition settings", async () => {
+    const result = await run(
+      { pane: "speech_recognition", platform: "macos" },
+      makeContext(),
+    );
+
+    expect(result.isError).toBe(false);
+    expect(sentMessages).toEqual([
+      {
+        type: "open_url",
+        url: "x-apple.systempreferences:com.apple.preference.security?Privacy_SpeechRecognition",
+        conversationId: "conv-xyz",
+      },
+    ]);
+  });
+
+  test("uses the host platform when the client platform is absent", async () => {
+    const result = await run({ pane: "microphone" }, makeContext());
+
+    expect(result.isError).toBe(false);
+    expect(sentMessages[0]?.url).toBe("ms-settings:privacy-microphone");
+  });
+
+  test("rejects an unsupported platform", async () => {
+    const result = await run(
+      { pane: "microphone", platform: "linux" },
+      makeContext(),
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain('unknown platform "linux"');
+    expect(sentMessages).toEqual([]);
+  });
+});