@vellumai/assistant 0.3.19 → 0.3.21

package/src/config/bundled-skills/voice-setup/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: "Voice Setup"
+description: "Complete voice configuration in chat — PTT key, wake word, microphone permissions, ElevenLabs TTS, and troubleshooting"
+user-invocable: true
+metadata: {"vellum": {"emoji": "🎙️", "os": ["darwin"]}}
+---
+
+You are helping the user set up and troubleshoot voice features (push-to-talk, wake word, text-to-speech) entirely within this conversation. Do NOT direct the user to the Settings page for initial setup — handle everything in-chat using the tools below.
+
+## Available Tools
+
+- `voice_config_update` — Change any voice setting (PTT key, wake word enabled/keyword/timeout)
+- `open_system_settings` — Open macOS System Settings to a specific privacy pane
+- `navigate_settings_tab` — Open the Vellum settings panel to the Voice tab
+- `credential_store` — Collect API keys securely (for ElevenLabs TTS)
+
+## Setup Flow
+
+Walk the user through each section in order. Skip sections they don't need. Ask before proceeding to the next section.
+
+### 1. Microphone Permission
+
+Check `<channel_capabilities>` for `microphone_permission_granted`.
+
+**If `false` or missing:**
+1. Explain that macOS requires microphone permission for voice features.
+2. Use `open_system_settings` with `pane: "microphone"` to open the right System Settings pane.
+3. Tell the user: "I've opened System Settings to the Microphone section. Please toggle **Vellum Assistant** on, then come back here."
+4. After they confirm, verify by checking capabilities on the next turn.
+
+**If `true`:** Tell them microphone is already granted and move on.
+
+### 2. Push-to-Talk Activation Key
+
+Present common PTT key options:
+- **Right Option (⌥)** — Default, good general choice
+- **Fn** — Dedicated key on most Mac keyboards
+- **Right Command (⌘)** — Easy to reach
+- **Right Control (⌃)** — Familiar from gaming
+
+Ask which key they prefer, then use `voice_config_update` with `setting: "activation_key"` and the chosen value.
+
+**Common issues to mention:**
+- If they pick a key that conflicts with their emoji picker (Fn or Globe on newer Macs), warn them and suggest an alternative.
+- If they use a terminal app heavily, warn that some keys may be captured by the terminal.
+
+### 3. Wake Word (Optional)
+
+Ask if they want to enable wake word detection (hands-free activation by saying a keyword).
+
+**If yes:**
+1. Use `voice_config_update` with `setting: "wake_word_enabled"`, `value: true`.
+2. Ask what wake word they want. Common choices: "Hey Vellum", "Computer", "Jarvis", their assistant's name.
+3. Use `voice_config_update` with `setting: "wake_word_keyword"` and their chosen word.
+4. Ask about timeout (how long the mic stays active after wake word). Options: 5s, 10s (default), 15s, 30s, 60s.
+5. Use `voice_config_update` with `setting: "wake_word_timeout"` and their chosen value.
+
+**Speech Recognition permission:** Wake word requires Speech Recognition access. Check capabilities — if not granted, use `open_system_settings` with `pane: "speech_recognition"`.
+
+### 4. Text-to-Speech / ElevenLabs (Optional)
+
+Ask if they want high-quality text-to-speech voices via ElevenLabs (optional — standard TTS works without it).
+
+**If yes:**
+1. Tell them they need an ElevenLabs API key. They can get one at https://elevenlabs.io (free tier available).
+2. Use `credential_store` with `action: "prompt"`, `service: "elevenlabs"`, `field: "api_key"` to show a secure input dialog.
+3. After the key is stored, confirm success.
+
+### 5. Verification
+
+After setup is complete:
+1. Summarize what was configured.
+2. Suggest they test by pressing their PTT key (or saying their wake word) and speaking.
+3. Offer to open the Voice settings tab if they want to review: use `navigate_settings_tab` with `tab: "Voice"`.
+
+## Troubleshooting Decision Trees
+
+When the user reports a problem, follow the appropriate decision tree:
+
+### "PTT isn't working" / "Can't record"
+1. **Microphone permission** — Check `microphone_permission_granted` in capabilities. If false, guide through granting it.
+2. **Key check** — Ask what key they're using. Confirm it matches their configured PTT key.
+3. **Emoji picker conflict** — On newer Macs, Fn/Globe opens the emoji picker. If they're using Fn, suggest switching to Right Option or Right Command.
+4. **Speech Recognition permission** — Some voice features need this. Use `open_system_settings` with `pane: "speech_recognition"`.
+5. **App focus** — PTT may not work when Vellum is not the frontmost app or if another app has captured the key.
+
+### "Recording but no text" / "Transcription not working"
+1. **Speech Recognition permission** — Must be granted for transcription.
+2. **Microphone input** — Ask if they see the recording indicator. If yes, the mic works but transcription is failing.
+3. **Locale/language** — Speech recognition works best with the system language. Ask if they're speaking in a different language.
+4. **Background noise** — Excessive noise can prevent transcription. Suggest a quieter environment or a closer microphone.
+
+### "Wake word not detecting"
+1. **Enabled check** — Confirm wake word is enabled in their settings.
+2. **Keyword** — Confirm what keyword they're using. Shorter or common words may have lower accuracy.
+3. **Ambient noise** — Wake word detection is sensitive to background noise.
+4. **Permissions** — Both Microphone and Speech Recognition permissions are required.
+5. **Timeout** — If wake word activates but cuts off too quickly, increase the timeout.
+
+### "Changed a setting but it didn't work"
+1. **IPC broadcast** — The setting should take effect immediately. If it didn't, suggest restarting the assistant.
+2. **Verify** — Open the Voice settings tab with `navigate_settings_tab` to confirm the setting was persisted.
+
+## Deep Debugging
+
+For persistent issues, suggest checking system logs:
+
+```bash
+log stream --predicate 'subsystem == "com.vellum.assistant"' --level debug
+```
+
+Key log categories:
+- `voice` — PTT activation, recording state
+- `wake-word` — Wake word detection events
+- `speech` — Speech recognition results
+
+## Rules
+
+- Always handle setup conversationally in-chat. Do NOT tell the user to go to Settings for initial configuration.
+- Use `navigate_settings_tab` only for review/verification after in-chat setup, not as the primary setup method.
+- Be concise. Don't explain every option exhaustively — present the most common choices and let the user ask for more.
+- If a permission is denied, acknowledge it gracefully and explain what features won't work without it.

package/src/config/core-schema.ts

@@ -124,7 +124,7 @@ export const ContextWindowConfigSchema = z.object({
     .number({ error: 'contextWindow.maxInputTokens must be a number' })
     .int('contextWindow.maxInputTokens must be an integer')
     .positive('contextWindow.maxInputTokens must be a positive integer')
-    .default(180000),
+    .default(200000),
   targetInputTokens: z
     .number({ error: 'contextWindow.targetInputTokens must be a number' })
     .int('contextWindow.targetInputTokens must be an integer')

package/src/config/env-registry.ts

@@ -124,6 +124,16 @@ export function getEnableMonitoring(): boolean {
   return flag('VELLUM_ENABLE_MONITORING');
 }
 
+/**
+ * IS_CONTAINERIZED — boolean, default: false
+ * When true, indicates the assistant is running inside a container (e.g. Docker).
+ * Any new data that needs to survive restarts must be written to BASE_DATA_DIR,
+ * which is mapped to a persistent volume.
+ */
+export function getIsContainerized(): boolean {
+  return flag('IS_CONTAINERIZED');
+}
+
 // ── Known env var names ──────────────────────────────────────────────────────
 
 /**

package/src/config/feature-flag-registry.json

@@ -0,0 +1,61 @@
+{
+  "version": 1,
+  "flags": [
+    {
+      "id": "sms",
+      "scope": "assistant",
+      "key": "feature_flags.sms.enabled",
+      "label": "SMS",
+      "description": "Show SMS setup in Settings > Connect and enable the SMS setup skill",
+      "defaultEnabled": true
+    },
+    {
+      "id": "hatch-new-assistant",
+      "scope": "assistant",
+      "key": "feature_flags.hatch-new-assistant.enabled",
+      "label": "Hatch New Assistant",
+      "description": "Show Hatch New Assistant action in Settings > Account",
+      "defaultEnabled": true
+    },
+    {
+      "id": "guardian-verify-setup",
+      "scope": "assistant",
+      "key": "feature_flags.guardian-verify-setup.enabled",
+      "label": "Guardian Verification Setup",
+      "description": "Enable guardian verification routing in the system prompt",
+      "defaultEnabled": true
+    },
+    {
+      "id": "browser",
+      "scope": "assistant",
+      "key": "feature_flags.browser.enabled",
+      "label": "Browser",
+      "description": "Enable browser skill prerequisites section in the system prompt",
+      "defaultEnabled": true
+    },
+    {
+      "id": "twitter",
+      "scope": "assistant",
+      "key": "feature_flags.twitter.enabled",
+      "label": "Twitter",
+      "description": "Enable X (Twitter) skill section in the system prompt",
+      "defaultEnabled": true
+    },
+    {
+      "id": "user-hosted-enabled",
+      "scope": "macos",
+      "key": "user_hosted_enabled",
+      "label": "User Hosted Enabled",
+      "description": "Enable user-hosted onboarding flow",
+      "defaultEnabled": false
+    },
+    {
+      "id": "local-http-enabled",
+      "scope": "macos",
+      "key": "local_http_enabled",
+      "label": "Local HTTP Enabled",
+      "description": "Enable local HTTP transport mode in macOS app",
+      "defaultEnabled": false
+    }
+  ]
+}

package/src/config/loader.ts

@@ -1,4 +1,5 @@
-import { existsSync, readFileSync, statSync,writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
 
 import { deleteSecureKey,getSecureKey, setSecureKey } from '../security/secure-keys.js';
 import { ConfigError } from '../util/errors.js';
@@ -113,6 +114,7 @@ export function loadConfig(): AssistantConfig {
     const configPath = getConfigPath();
 
     let fileConfig: Record<string, unknown> = {};
+    let configFileExisted = true;
     if (existsSync(configPath)) {
       const mode = statSync(configPath).mode;
       if (mode & 0o077) {
@@ -127,6 +129,8 @@ export function loadConfig(): AssistantConfig {
       } catch (err) {
         throw new ConfigError(`Failed to parse config at ${configPath}: ${err}`);
       }
+    } else {
+      configFileExisted = false;
     }
 
     // Pre-validate apiKeys shape before migration (must be a plain object)
@@ -182,6 +186,23 @@ export function loadConfig(): AssistantConfig {
     // Validate and apply defaults via Zod schema
     const config = validateWithSchema(fileConfig);
 
+    // If the config file didn't exist, write the full defaults to disk so
+    // users can discover and edit all available options.
+    if (!configFileExisted) {
+      try {
+        const dir = dirname(configPath);
+        if (!existsSync(dir)) {
+          mkdirSync(dir, { recursive: true });
+        }
+        // Strip apiKeys (managed in secure storage) and dataDir (runtime-derived)
+        const { apiKeys: _, dataDir: _d, ...persistable } = config;
+        writeFileSync(configPath, JSON.stringify(persistable, null, 2) + '\n');
+        log.info('Wrote default config to %s', configPath);
+      } catch (err) {
+        log.warn({ err }, 'Failed to write default config file');
+      }
+    }
+
     // Set cached before secure-key/env overrides so re-entrant calls
     // return the in-flight config instead of bare defaults.
     cached = config;

package/src/config/mcp-schema.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+
+const McpStdioTransportSchema = z.object({
+  type: z.literal('stdio'),
+  command: z.string({ error: 'mcp transport command must be a string' }),
+  args: z.array(z.string()).default([]),
+  env: z.record(z.string(), z.string()).optional(),
+});
+
+const McpSseTransportSchema = z.object({
+  type: z.literal('sse'),
+  url: z.string({ error: 'mcp transport url must be a string' }),
+  headers: z.record(z.string(), z.string()).optional(),
+});
+
+const McpStreamableHttpTransportSchema = z.object({
+  type: z.literal('streamable-http'),
+  url: z.string({ error: 'mcp transport url must be a string' }),
+  headers: z.record(z.string(), z.string()).optional(),
+});
+
+export const McpTransportSchema = z.discriminatedUnion('type', [
+  McpStdioTransportSchema,
+  McpSseTransportSchema,
+  McpStreamableHttpTransportSchema,
+]);
+
+export const McpServerConfigSchema = z.object({
+  transport: McpTransportSchema,
+  enabled: z.boolean({ error: 'mcp server enabled must be a boolean' }).default(true),
+  defaultRiskLevel: z.enum(['low', 'medium', 'high'], {
+    error: 'mcp server defaultRiskLevel must be one of: low, medium, high',
+  }).default('high'),
+  maxTools: z.number({ error: 'mcp server maxTools must be a number' }).int().positive().default(20),
+  allowedTools: z.array(z.string()).optional(),
+  blockedTools: z.array(z.string()).optional(),
+});
+
+export const McpConfigSchema = z.object({
+  servers: z.record(z.string(), McpServerConfigSchema).default({} as any),
+  globalMaxTools: z.number({ error: 'mcp globalMaxTools must be a number' }).int().positive().default(50),
+});
+
+export type McpTransport = z.infer<typeof McpTransportSchema>;
+export type McpServerConfig = z.infer<typeof McpServerConfigSchema>;
+export type McpConfig = z.infer<typeof McpConfigSchema>;

package/src/config/sandbox-schema.ts

@@ -1,48 +1,9 @@
 import { z } from 'zod';
 
-const VALID_SANDBOX_BACKENDS = ['native', 'docker'] as const;
-const VALID_DOCKER_NETWORKS = ['none', 'bridge'] as const;
-
-export const DockerConfigSchema = z.object({
-  image: z
-    .string({ error: 'sandbox.docker.image must be a string' })
-    .default('vellum-sandbox:latest'),
-  shell: z
-    .string({ error: 'sandbox.docker.shell must be a string' })
-    .default('bash'),
-  cpus: z
-    .number({ error: 'sandbox.docker.cpus must be a number' })
-    .finite('sandbox.docker.cpus must be finite')
-    .positive('sandbox.docker.cpus must be a positive number')
-    .default(1),
-  memoryMb: z
-    .number({ error: 'sandbox.docker.memoryMb must be a number' })
-    .int('sandbox.docker.memoryMb must be an integer')
-    .positive('sandbox.docker.memoryMb must be a positive integer')
-    .default(512),
-  pidsLimit: z
-    .number({ error: 'sandbox.docker.pidsLimit must be a number' })
-    .int('sandbox.docker.pidsLimit must be an integer')
-    .positive('sandbox.docker.pidsLimit must be a positive integer')
-    .default(256),
-  network: z
-    .enum(VALID_DOCKER_NETWORKS, {
-      error: `sandbox.docker.network must be one of: ${VALID_DOCKER_NETWORKS.join(', ')}`,
-    })
-    .default('none'),
-});
-
 export const SandboxConfigSchema = z.object({
   enabled: z
     .boolean({ error: 'sandbox.enabled must be a boolean' })
     .default(true),
-  backend: z
-    .enum(VALID_SANDBOX_BACKENDS, {
-      error: `sandbox.backend must be one of: ${VALID_SANDBOX_BACKENDS.join(', ')}`,
-    })
-    .default('docker'),
-  docker: DockerConfigSchema.default({} as any),
 });
 
 export type SandboxConfig = z.infer<typeof SandboxConfigSchema>;
-export type DockerConfig = z.infer<typeof DockerConfigSchema>;

package/src/config/schema.ts

@@ -109,13 +109,21 @@ export {
   NotificationsConfigSchema,
 } from './notifications-schema.js';
 export type {
-  DockerConfig,
   SandboxConfig,
 } from './sandbox-schema.js';
 export {
-  DockerConfigSchema,
   SandboxConfigSchema,
 } from './sandbox-schema.js';
+export type {
+  McpConfig,
+  McpServerConfig,
+  McpTransport,
+} from './mcp-schema.js';
+export {
+  McpConfigSchema,
+  McpServerConfigSchema,
+  McpTransportSchema,
+} from './mcp-schema.js';
 export type {
   RemotePolicyConfig,
   RemoteProviderConfig,
@@ -154,6 +162,7 @@ import {
   TimeoutConfigSchema,
   UiConfigSchema,
 } from './core-schema.js';
+import { McpConfigSchema } from './mcp-schema.js';
 import { MemoryConfigSchema } from './memory-schema.js';
 import { NotificationsConfigSchema } from './notifications-schema.js';
 import { SandboxConfigSchema } from './sandbox-schema.js';
@@ -215,6 +224,7 @@ export const AssistantConfigSchema = z.object({
     .default([]),
   heartbeat: HeartbeatConfigSchema.default({} as any),
   swarm: SwarmConfigSchema.default({} as any),
+  mcp: McpConfigSchema.default({} as any),
   skills: SkillsConfigSchema.default({} as any),
   workspaceGit: WorkspaceGitConfigSchema.default({} as any),
   calls: CallsConfigSchema.default({} as any),
@@ -224,6 +234,12 @@ export const AssistantConfigSchema = z.object({
   daemon: DaemonConfigSchema.default({} as any),
   notifications: NotificationsConfigSchema.default({} as any),
   ui: UiConfigSchema.default({} as any),
+  featureFlags: z
+    .record(z.string(), z.boolean({ error: 'featureFlags values must be booleans' }))
+    .default({} as any),
+  assistantFeatureFlagValues: z
+    .record(z.string(), z.boolean({ error: 'assistantFeatureFlagValues values must be booleans' }))
+    .optional(),
 }).superRefine((config, ctx) => {
   if (config.contextWindow?.targetInputTokens != null && config.contextWindow?.maxInputTokens != null &&
       config.contextWindow.targetInputTokens >= config.contextWindow.maxInputTokens) {

package/src/config/skill-state.ts

@@ -1,3 +1,4 @@
+import { isAssistantFeatureFlagEnabled } from './assistant-feature-flags.js';
 import type { AssistantConfig, SkillEntryConfig } from './schema.js';
 import type { SkillSummary } from './skills.js';
 import { checkSkillRequirements } from './skills.js';
@@ -12,6 +13,34 @@ export interface ResolvedSkill {
   configEntry?: SkillEntryConfig;
 }
 
+// Skill IDs whose feature flag key differs from the default
+// `feature_flags.<skillId>.enabled` derivation. The sms-setup skill is
+// gated by the `sms` flag so that the macOS Settings SMS toggle controls
+// both the channel UI and the setup skill.
+const SKILL_FLAG_KEY_OVERRIDES: Record<string, string> = {
+  'sms-setup': 'feature_flags.sms.enabled',
+};
+
+/**
+ * Derive the feature flag key for a given skill ID, respecting overrides.
+ *
+ * Exported so other modules (system-prompt, session-skill-tools, skill loader)
+ * can perform the same mapping without duplicating the override table.
+ */
+export function skillFlagKey(skillId: string): string {
+  return SKILL_FLAG_KEY_OVERRIDES[skillId] ?? `feature_flags.${skillId}.enabled`;
+}
+
+/**
+ * @deprecated Use `isAssistantFeatureFlagEnabled` from `./assistant-feature-flags.js` instead.
+ *
+ * Thin backward-compatible wrapper that delegates to the canonical resolver.
+ * Kept to avoid breaking existing call sites during migration.
+ */
+export function isSkillFeatureEnabled(skillId: string, config: AssistantConfig): boolean {
+  return isAssistantFeatureFlagEnabled(skillFlagKey(skillId), config);
+}
+
 export function resolveSkillStates(
   catalog: SkillSummary[],
   config: AssistantConfig,
@@ -20,6 +49,11 @@ export function resolveSkillStates(
   const { entries, allowBundled } = config.skills ?? { entries: {}, allowBundled: null };
 
   for (const skill of catalog) {
+    // Assistant feature flag gate: if the flag is explicitly OFF, skip this skill entirely
+    if (!isAssistantFeatureFlagEnabled(skillFlagKey(skill.id), config)) {
+      continue;
+    }
+
     // Filter bundled skills by allowlist
     if (skill.source === 'bundled' && allowBundled != null && !allowBundled.includes(skill.id)) {
       continue;

package/src/config/skills-schema.ts

@@ -28,7 +28,6 @@ export const RemoteProvidersConfigSchema = z.object({
   clawhub: RemoteProviderConfigSchema.default({} as any),
 });
 
-const VALID_SKILLS_SH_RISK_LEVELS = ['safe', 'low', 'medium', 'high', 'critical', 'unknown'] as const;
 // 'unknown' is valid as a risk label on a skill but not as a threshold — setting the threshold
 // to 'unknown' would silently disable fail-closed behavior since nothing can exceed it.
 const VALID_MAX_RISK_LEVELS = ['safe', 'low', 'medium', 'high', 'critical'] as const;

package/src/config/skills.ts

@@ -13,12 +13,21 @@ const log = getLogger('skills');
 
 // ─── New interfaces for extended skill metadata ──────────────────────────────
 
+export interface SkillCliSpec {
+  /** CLI command name (e.g. "doordash"). Used as the launcher script name in ~/.vellum/bin/. */
+  command: string;
+  /** Entry point filename relative to the skill directory (e.g. "doordash-entry.ts"). */
+  entry: string;
+}
+
 export interface VellumMetadata {
   emoji?: string;
   os?: string[];
   requires?: SkillRequirements;
   primaryEnv?: string;
   install?: InstallerSpec[];
+  /** Declares a standalone CLI entry point for this skill. */
+  cli?: SkillCliSpec;
 }
 
 export interface SkillRequirements {