handmux 0.26.0 → 0.27.2

package/dist/src/cli/codexManaged.js

@@ -3,6 +3,15 @@ import path from 'node:path';
 import os from 'node:os';
 import { spawn as spawnChild } from 'node:child_process';
 const PANE_RE = /^%\d+$/;
+function hasExplicitCwd(args) {
+    const optionsEnd = args.indexOf('--');
+    const options = optionsEnd === -1 ? args : args.slice(0, optionsEnd);
+    return options.some((arg) => arg === '-C' || arg === '--cd'
+        || arg.startsWith('--cd=') || (arg.startsWith('-C') && arg.length > 2));
+}
+export function managedCodexArgs(args, cwd) {
+    return hasExplicitCwd(args) ? [...args] : ['--cd', cwd, ...args];
+}
 const errorCode = (error) => {
     if (typeof error !== 'object' || error === null || !('code' in error))
         return null;
@@ -41,7 +50,7 @@ function finish(child) {
 }
 // One App Server belongs to one tmux pane. The TUI and Handmux connect to that pane-owned Unix socket,
 // so thread identity, messages, approvals, settings, interrupts and inbox state share one runtime.
-export async function runManagedCodexProcess(args = [], { home = os.homedir(), env = process.env, spawn = spawnChild, mkdir = (dir) => fs.mkdirSync(dir, { recursive: true, mode: 0o700 }), unlink = (file) => { try {
+export async function runManagedCodexProcess(args = [], { home = os.homedir(), cwd = process.cwd(), env = process.env, spawn = spawnChild, mkdir = (dir) => fs.mkdirSync(dir, { recursive: true, mode: 0o700 }), unlink = (file) => { try {
     fs.unlinkSync(file);
 }
 catch (error) {
@@ -60,7 +69,9 @@ catch (error) {
     let tui = null;
     try {
         await waitForSocket(socketPath, appServer, waitOptions);
-        tui = spawn('codex', ['--remote', `unix://${socketPath}`, ...args], {
+        tui = spawn('codex', [
+            '--remote', `unix://${socketPath}`, ...managedCodexArgs(args, cwd),
+        ], {
             env: managedEnv,
             stdio: 'inherit',
         });

package/dist/src/cli/i18n/en.js

@@ -273,11 +273,26 @@ export default {
     'setup.pushOff': 'Turn off push',
     'setup.voiceOff': 'Turn off voice',
     'setup.voiceKeep': 'keep voice input configured?',
-    'setup.voiceSetup': 'Turn on voice input? (talk to your phone → text; needs an iFlytek/xfyun account)',
+    'setup.voiceSetup': 'Turn on voice input? (live dictation or whole-sentence recognition)',
+    'setup.voiceProvider': 'Voice provider',
+    'setup.voiceTencent': 'Tencent Cloud real-time ASR',
+    'setup.voiceTencentHint': 'WebSocket 2.0 · live partials',
+    'setup.voiceTencentSentence': 'Tencent Cloud sentence ASR',
+    'setup.voiceTencentSentenceHint': 'Tap to record · returns after stopping',
+    'setup.voiceXfyun': 'iFlytek voice dictation',
+    'setup.voiceXfyunHint': 'live partials',
     'setup.voiceAppId': 'xfyun appId',
     'setup.voiceApiKey': 'xfyun apiKey',
     'setup.voiceApiSecret': 'xfyun apiSecret',
+    'setup.voiceTencentAppId': 'Tencent Cloud appId',
+    'setup.voiceTencentSecretId': 'Tencent Cloud secretId',
+    'setup.voiceTencentSecretKey': 'Tencent Cloud secretKey',
+    'setup.voiceTencentEngine': 'engineModelType (16k PCM; default: 16k_zh)',
     'setup.voiceSkipped': '  (skipped — missing fields)',
+    'setup.voiceVerifying': '→ Verifying {profile} with the provider…',
+    'setup.voiceVerified': '✓ Voice configuration verified',
+    'setup.voiceVerifyFailed': '✗ Voice verification failed: {msg}. Check the values or network, then edit a field to retry.',
+    'setup.voiceVerifyUnavailable': '⚠ This voice provider does not support automatic verification yet.',
     'setup.cfLogin': '→ logging in to Cloudflare (a browser will open) …',
     'setup.cfReuse': '✓ reusing existing tunnel {name} ({id})',
     'setup.cfCredMissing1': '⚠ credentials file {file} not found on this machine — the tunnel was likely',

package/dist/src/cli/i18n/zh.js

@@ -272,11 +272,26 @@ export default {
     'setup.pushOff': '关闭推送',
     'setup.voiceOff': '关闭语音',
     'setup.voiceKeep': '保留已配置的语音输入吗?',
-    'setup.voiceSetup': '开启语音输入吗?(对着手机说话转文字;需讯飞账号)',
+    'setup.voiceSetup': '开启语音输入吗?(支持实时听写或整句识别)',
+    'setup.voiceProvider': '语音服务',
+    'setup.voiceTencent': '腾讯云实时语音识别',
+    'setup.voiceTencentHint': 'WebSocket 2.0 · 实时返回',
+    'setup.voiceTencentSentence': '腾讯云一句话识别',
+    'setup.voiceTencentSentenceHint': '点击录音 · 停止后整句返回',
+    'setup.voiceXfyun': '讯飞语音听写',
+    'setup.voiceXfyunHint': '实时返回',
     'setup.voiceAppId': 'xfyun appId',
     'setup.voiceApiKey': 'xfyun apiKey',
     'setup.voiceApiSecret': 'xfyun apiSecret',
+    'setup.voiceTencentAppId': 'Tencent Cloud appId',
+    'setup.voiceTencentSecretId': 'Tencent Cloud secretId',
+    'setup.voiceTencentSecretKey': 'Tencent Cloud secretKey',
+    'setup.voiceTencentEngine': 'engineModelType（16k PCM，默认 16k_zh）',
     'setup.voiceSkipped': '  (已跳过 —— 字段缺失)',
+    'setup.voiceVerifying': '→ 正在向服务商验证 {profile}…',
+    'setup.voiceVerified': '✓ 语音配置验证通过',
+    'setup.voiceVerifyFailed': '✗ 语音配置验证失败：{msg}。请检查填写内容或网络，修改任一字段后会重新验证。',
+    'setup.voiceVerifyUnavailable': '⚠ 当前语音服务商暂不支持自动验证。',
     'setup.cfLogin': '→ 正在登录 Cloudflare(会打开一个浏览器)…',
     'setup.cfReuse': '✓ 复用已有隧道 {name}({id})',
     'setup.cfCredMissing1': '⚠ 本机找不到凭据文件 {file} —— 该隧道很可能是',

package/dist/src/cli/options.js

@@ -2,6 +2,7 @@
 // Resolution order is flags > config file > env > built-in default. The token is ALWAYS materialised
 // (generated when unset) so a public tunnel can never come up token-less.
 import crypto from 'node:crypto';
+import { providerMode, voiceProviderRegistry } from '../asr/providerRegistry.js';
 import { normalizeShortcuts } from '../shortcutConfig.js';
 export const TUNNELS = ['none', 'cloudflare', 'cloudflare-named', 'ssh', 'natapp', 'cpolar'];
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -90,7 +91,8 @@ export function resolveConfig(flags = {}, fileCfg = {}, env = process.env, gen =
         uploadExts: optionalString(pick('uploadExts', env.HANDMUX_UPLOAD_EXTS), 'upload-exts'),
         previewDomain: optionalString(pick('previewDomain', env.HANDMUX_PREVIEW_DOMAIN), 'preview-domain'),
         vapid: parseVapid(fileCfg.vapid), // { public, private, subject } — push notifications
-        xfyun: parseXfyun(fileCfg.xfyun), // { appId, apiKey, apiSecret } — voice input
+        voice: parseVoice(fileCfg.voice, fileCfg.xfyun),
+        xfyun: parseXfyun(fileCfg.xfyun), // legacy voice input; parseVoice migrates it at runtime
         shortcuts: normalizeShortcuts(fileCfg.shortcuts),
         // An explicit public URL is honoured for ANY tunnel mode — including 'none', so someone who runs their
         // own tunnel/reverse-proxy can still have handmux advertise (print + QR) their real domain. The
@@ -162,6 +164,25 @@ function parseVapid(value) {
 function parseXfyun(value) {
     return stringFields(value, ['appId', 'apiKey', 'apiSecret']);
 }
+function parseVoice(value, legacyXfyun) {
+    if (isRecord(value)) {
+        const adapter = voiceProviderRegistry.get(value.provider);
+        const providers = isRecord(value.providers) ? value.providers : {};
+        if (adapter) {
+            if (value.enabled === false)
+                return null;
+            const parsed = {};
+            for (const candidate of voiceProviderRegistry.adapters) {
+                const config = stringFields(providers[candidate.id], candidate.fields.map((field) => field.key));
+                if (config)
+                    parsed[candidate.id] = config;
+            }
+            return { provider: adapter.id, mode: providerMode(adapter, value.mode), providers: parsed };
+        }
+    }
+    const xfyun = parseXfyun(legacyXfyun);
+    return xfyun ? { provider: 'xfyun', mode: 'streaming', providers: { xfyun } } : null;
+}
 function resolvePublicUrl(flags, fileCfg, env, tunnel) {
     if (flags.publicUrl != null)
         return flags.publicUrl;
@@ -240,6 +261,12 @@ export function explainConfig(flags = {}, fileCfg = {}, cfgPath = null, env = pr
     }
     // Integrations live only in the file (secrets); show presence, never the keys.
     rows.push({ key: 'push (vapid)', origin: fileCfg.vapid ? (cfgPath || 'file') : 'default', display: fileCfg.vapid ? 'on' : 'off' });
-    rows.push({ key: 'voice (xfyun)', origin: fileCfg.xfyun ? (cfgPath || 'file') : 'default', display: fileCfg.xfyun ? 'on' : 'off' });
+    const voice = parseVoice(fileCfg.voice, fileCfg.xfyun);
+    const voiceExplicitlyDisabled = isRecord(fileCfg.voice) && fileCfg.voice.enabled === false;
+    rows.push({
+        key: 'voice',
+        origin: voice || voiceExplicitlyDisabled ? (cfgPath || 'file') : 'default',
+        display: voice ? voice.provider : 'off',
+    });
     return rows;
 }

package/dist/src/cli/setupModel.js

@@ -3,6 +3,7 @@
 // interactive shell (setupWizard.ts) so the tested, side-effect-free logic stands on its own. Depends only
 // on i18n (t/getLocale) for user-facing strings — otherwise deterministic given its inputs.
 import { t, getLocale } from './i18n/index.js';
+import { providerMode, voiceProviderRegistry } from '../asr/providerRegistry.js';
 import { TUNNELS } from './options.js';
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 const isTunnel = (value) => typeof value === 'string' && TUNNELS.includes(value);
@@ -16,6 +17,25 @@ const stringObject = (value, keys) => {
             result[key] = value[key];
     return result;
 };
+// Voice credentials and identifiers are copied from provider consoles, where an unnoticed leading or
+// trailing space makes an otherwise valid signature fail. Normalize at the persistence boundary as well as
+// in the interactive editor so every setup caller gets the same behavior.
+export function normalizeVoiceConfig(voice) {
+    const providers = {};
+    for (const [provider, value] of Object.entries(voice.providers)) {
+        if (!value) {
+            providers[provider] = value;
+            continue;
+        }
+        const normalized = {};
+        for (const [key, fieldValue] of Object.entries(value)) {
+            if (typeof fieldValue === 'string')
+                normalized[key] = fieldValue.trim();
+        }
+        providers[provider] = normalized;
+    }
+    return { ...voice, providers };
+}
 // ~/.cloudflared/config.yml for a named tunnel: route the hostname to the local handmux port.
 export function cfConfigYaml({ tunnelName, credentialsFile, hostname, port, }) {
     return [
@@ -61,7 +81,7 @@ const WIZARD_KEYS = [
     'lang', 'name', 'port', 'tunnel', 'token', 'previewDomain',
     'sshHost', 'remotePort', 'sshJump', 'cfHostname', 'cfTunnelName', 'publicUrl',
     'authtoken', 'cpolarRegion',
-    'vapid', 'xfyun',
+    'vapid', 'voice', 'xfyun',
 ];
 // The tunnel-specific keys, cleared whenever the tunnel changes so a switch never carries a stale field.
 export const TUNNEL_KEYS = ['sshHost', 'remotePort', 'sshJump', 'cfHostname', 'cfTunnelName', 'publicUrl', 'authtoken', 'cpolarRegion'];
@@ -98,8 +118,8 @@ export function configFromAnswers(a) {
     }
     if (a.vapid)
         cfg.vapid = a.vapid;
-    if (a.xfyun)
-        cfg.xfyun = a.xfyun;
+    if (a.voice)
+        cfg.voice = normalizeVoiceConfig(a.voice);
     return cfg;
 }
 // Fold this run's answers into an existing config: preserve every non-wizard field, replace the wizard's
@@ -132,13 +152,37 @@ export function answersFromConfig(config = {}) {
     if (typeof cfg.remotePort === 'number' && Number.isFinite(cfg.remotePort))
         a.remotePort = cfg.remotePort;
     const vapid = stringObject(cfg.vapid, ['public', 'private', 'subject']);
+    const voice = voiceFromConfig(cfg.voice);
     const xfyun = stringObject(cfg.xfyun, ['appId', 'apiKey', 'apiSecret']);
     if (vapid)
         a.vapid = vapid;
-    if (xfyun)
-        a.xfyun = xfyun;
+    if (voice)
+        a.voice = voice;
+    else if (xfyun)
+        a.voice = normalizeVoiceConfig({
+            provider: 'xfyun', mode: 'streaming', providers: { xfyun },
+        });
     return a;
 }
+function voiceFromConfig(value) {
+    if (!isRecord(value) || !isRecord(value.providers))
+        return undefined;
+    const adapter = voiceProviderRegistry.get(value.provider);
+    if (!adapter)
+        return undefined;
+    const providers = {};
+    for (const candidate of voiceProviderRegistry.adapters) {
+        const config = stringObject(value.providers[candidate.id], candidate.fields.map((field) => field.key));
+        if (config)
+            providers[candidate.id] = config;
+    }
+    return normalizeVoiceConfig({
+        ...(value.enabled === false ? { enabled: false } : {}),
+        provider: adapter.id,
+        mode: providerMode(adapter, value.mode),
+        providers,
+    });
+}
 // The dim one-line summary shown next to the Connection row (and reused nowhere else). Pure.
 export function summarizeConnection(a) {
     const bare = (url) => String(url || '').replace(/^https?:\/\//, '');

package/dist/src/cli/setupWizard.js

@@ -8,6 +8,7 @@ import path from 'node:path';
 import { homedir } from 'node:os';
 import { spawnSync } from 'node:child_process';
 import webpush from 'web-push';
+import { providerMode, voiceProviderRegistry } from '../asr/providerRegistry.js';
 import { configPath } from './state.js';
 import { defaultGen as genToken, TUNNELS } from './options.js';
 import { resolveCloudflared } from './cloudflared.js';
@@ -28,8 +29,8 @@ const isTunnel = (value) => (typeof value === 'string' && TUNNELS.includes(value
 // The pure answer↔config model + validators + cloudflared text helpers live in setupModel.js. Imported for
 // the interactive shell below; re-exported so their historical import path (this module) stays valid for
 // callers and tests.
-import { cfConfigYaml, parseTunnelCreate, findTunnelId, mergeConfig, answersFromConfig, summarizeConnection, validatePort, validateHost, validatePreviewDomain, validateNonEmpty, validateContact, validateToken, TUNNEL_KEYS, } from './setupModel.js';
-export { cfConfigYaml, parseTunnelCreate, findTunnelId, configFromAnswers, mergeConfig, answersFromConfig, summarizeConnection, validatePort, validateHost, validatePreviewDomain, validateNonEmpty, validateContact, validateToken, } from './setupModel.js';
+import { cfConfigYaml, parseTunnelCreate, findTunnelId, mergeConfig, answersFromConfig, summarizeConnection, normalizeVoiceConfig, validatePort, validateHost, validatePreviewDomain, validateNonEmpty, validateContact, validateToken, TUNNEL_KEYS, } from './setupModel.js';
+export { cfConfigYaml, parseTunnelCreate, findTunnelId, configFromAnswers, mergeConfig, answersFromConfig, summarizeConnection, normalizeVoiceConfig, validatePort, validateHost, validatePreviewDomain, validateNonEmpty, validateContact, validateToken, } from './setupModel.js';
 function readExisting(file) {
     try {
         return new PrivateStateStore(file).readStrict() || {};
@@ -83,7 +84,12 @@ export async function runSetup({ home = homedir(), target = configPath(home), lo
                     { value: 'token', label: t('setup.secToken'), hint: a.token ? maskSecret(a.token) : t('setup.tokenAuto') },
                     { value: 'browser', label: t('setup.secBrowser'), hint: a.previewDomain || t('setup.browserOff') },
                     { value: 'push', label: t('setup.secPush'), hint: a.vapid ? (a.vapid.subject || t('setup.on')) : t('setup.off') },
-                    { value: 'voice', label: t('setup.secVoice'), hint: a.xfyun ? (a.xfyun.appId || t('setup.on')) : t('setup.off') },
+                    {
+                        value: 'voice', label: t('setup.secVoice'),
+                        hint: a.voice && a.voice.enabled !== false
+                            ? `${voiceProfileLabel(a.voice)} · ${a.voice.providers[a.voice.provider]?.appId || t('setup.on')}`
+                            : t('setup.off'),
+                    },
                     // A CLI-tool preference (language of handmux's own terminal output), not an app setting — so it
                     // sits at the bottom of the settings, just above the actions.
                     { value: 'language', label: t('setup.secLanguage'), hint: a.lang === 'zh' ? '中文' : 'English' },
@@ -128,11 +134,11 @@ export async function runSetup({ home = homedir(), target = configPath(home), lo
                         delete a.vapid;
                 }
                 else if (choice === 'voice') {
-                    const xfyun = await editVoice(a);
-                    if (xfyun)
-                        a.xfyun = xfyun;
+                    const voice = await editVoice(a);
+                    if (voice)
+                        a.voice = voice;
                     else
-                        delete a.xfyun;
+                        delete a.voice;
                 }
             }
             catch (e) {
@@ -507,55 +513,84 @@ async function editPush(a) {
         } // Esc in a sub-edit → back to the mini-hub
     }
 }
-// Voice input (iFlytek/xfyun) — three credentials; appId is shown/edited in the clear, the two secrets show
-// only a masked preview and are replaced (never revealed) when edited.
+// Voice input provider hub. Credentials for multiple providers may coexist, but only the explicitly selected
+// provider is injected into the server process. Secrets are masked and replaced, never revealed.
 async function editVoice(a) {
-    let x = a.xfyun;
-    if (!x) {
+    let voice = a.voice;
+    if (!voice || voice.enabled === false) {
         let on;
         try {
             on = await ask(confirm({ message: withBack(t('setup.voiceSetup')), initialValue: false, ...yesno() }));
         }
         catch (e) {
             if (e === CANCELLED)
-                return undefined;
+                return voice;
             throw e;
         }
         if (!on)
-            return undefined;
-        const appId = await ask(text({ message: t('setup.voiceAppId'), validate: validateNonEmpty('appId') }));
-        const apiKey = await ask(password({ message: t('setup.voiceApiKey'), validate: validateNonEmpty('apiKey') }));
-        const apiSecret = await ask(password({ message: t('setup.voiceApiSecret'), validate: validateNonEmpty('apiSecret') }));
-        x = { appId, apiKey, apiSecret };
+            return voice;
+        if (voice) {
+            voice = await ensureVoiceProvider({ ...voice, enabled: true });
+        }
+        else {
+            const profile = await chooseVoiceProfile({ provider: 'tencent', mode: 'streaming' });
+            voice = await ensureVoiceProvider({ ...profile, enabled: true, providers: {} });
+        }
+        await verifyVoiceConfiguration(voice);
     }
     for (;;) {
+        const provider = voice.provider;
+        const adapter = voiceProviderRegistry.get(provider);
+        if (!adapter)
+            throw new Error(`unknown voice provider: ${provider}`);
+        const current = voice.providers[provider] || {};
         let pick;
         try {
             pick = await ask(select({
                 message: withBack(t('setup.secVoice')),
                 options: [
-                    { value: 'appId', label: 'appId', hint: x.appId || '' },
-                    { value: 'apiKey', label: 'apiKey', hint: maskSecret(x.apiKey) },
-                    { value: 'apiSecret', label: 'apiSecret', hint: maskSecret(x.apiSecret) },
+                    { value: 'provider', label: t('setup.voiceProvider'), hint: voiceProfileLabel(voice) },
+                    ...adapter.fields.map((field) => ({
+                        value: field.key,
+                        label: field.key,
+                        hint: field.secret ? maskSecret(current[field.key])
+                            : current[field.key] || field.defaultValue || '',
+                    })),
                     { value: 'off', label: t('setup.voiceOff') },
                 ],
-                initialValue: 'appId',
+                initialValue: 'provider',
             }));
         }
         catch (e) {
             if (e === CANCELLED)
-                return x;
+                return voice;
             throw e;
         }
         if (pick === 'off')
-            return undefined;
+            return { ...voice, enabled: false };
         try {
-            if (pick === 'appId')
-                x = { ...x, appId: await ask(text({ message: t('setup.voiceAppId'), initialValue: x.appId || '', validate: validateNonEmpty('appId') })) };
-            else if (pick === 'apiKey')
-                x = { ...x, apiKey: await ask(password({ message: t('setup.voiceApiKey'), validate: validateNonEmpty('apiKey') })) };
-            else if (pick === 'apiSecret')
-                x = { ...x, apiSecret: await ask(password({ message: t('setup.voiceApiSecret'), validate: validateNonEmpty('apiSecret') })) };
+            if (pick === 'provider') {
+                const selected = await chooseVoiceProfile(voice);
+                voice = await ensureVoiceProvider({ ...voice, ...selected });
+                await verifyVoiceConfiguration(voice);
+            }
+            else {
+                const field = adapter.fields.find((candidate) => candidate.key === pick);
+                if (!field)
+                    continue;
+                const config = { ...current };
+                config[field.key] = String(field.secret
+                    ? await ask(password({ message: t(field.promptKey), validate: validateNonEmpty(field.key) }))
+                    : await ask(text({
+                        message: t(field.promptKey),
+                        initialValue: config[field.key] || field.defaultValue || '',
+                        validate: validateNonEmpty(field.key),
+                    }))).trim();
+                voice = normalizeVoiceConfig({
+                    ...voice, providers: { ...voice.providers, [provider]: config },
+                });
+                await verifyVoiceConfiguration(voice);
+            }
         }
         catch (e) {
             if (e !== CANCELLED)
@@ -563,6 +598,91 @@ async function editVoice(a) {
         }
     }
 }
+function voiceProfileLabel(voice) {
+    const adapter = voiceProviderRegistry.get(voice.provider);
+    const profile = adapter?.profiles.find((candidate) => candidate.mode === voice.mode)
+        ?? adapter?.profiles.find((candidate) => candidate.mode === adapter.defaultMode);
+    return profile ? t(profile.labelKey) : voice.provider;
+}
+async function chooseVoiceProfile(initial) {
+    const profiles = voiceProviderRegistry.adapters.flatMap((adapter) => (adapter.profiles.map((profile) => ({ adapter, profile, value: `${adapter.id}:${profile.mode}` }))));
+    const initialAdapter = voiceProviderRegistry.get(initial.provider) ?? voiceProviderRegistry.adapters[0];
+    if (!initialAdapter)
+        throw new Error('no voice providers registered');
+    const initialValue = `${initialAdapter.id}:${providerMode(initialAdapter, initial.mode)}`;
+    const selected = await ask(select({
+        message: t('setup.voiceProvider'),
+        options: profiles.map(({ profile, value }) => ({
+            value, label: t(profile.labelKey), hint: t(profile.hintKey),
+        })),
+        initialValue,
+    }));
+    const match = profiles.find((candidate) => candidate.value === selected);
+    return match ? { provider: match.adapter.id, mode: match.profile.mode }
+        : { provider: initialAdapter.id, mode: providerMode(initialAdapter, initial.mode) };
+}
+async function ensureVoiceProvider(voice) {
+    const adapter = voiceProviderRegistry.get(voice.provider);
+    if (!adapter)
+        throw new Error(`unknown voice provider: ${voice.provider}`);
+    const config = { ...voice.providers[adapter.id] };
+    for (const field of adapter.fields) {
+        const existing = config[field.key]?.trim();
+        if (existing) {
+            config[field.key] = existing;
+            continue;
+        }
+        if (field.defaultValue) {
+            config[field.key] = field.defaultValue;
+            continue;
+        }
+        config[field.key] = String(field.secret
+            ? await ask(password({ message: t(field.promptKey), validate: validateNonEmpty(field.key) }))
+            : await ask(text({
+                message: t(field.promptKey), initialValue: field.defaultValue || '',
+                validate: validateNonEmpty(field.key),
+            }))).trim();
+    }
+    return normalizeVoiceConfig({
+        ...voice, providers: { ...voice.providers, [adapter.id]: config },
+    });
+}
+async function verifyVoiceConfiguration(voice) {
+    const adapter = voiceProviderRegistry.get(voice.provider);
+    if (!adapter)
+        throw new Error(`unknown voice provider: ${voice.provider}`);
+    if (!adapter.verify) {
+        note(t('setup.voiceVerifyUnavailable'));
+        return false;
+    }
+    const providerConfig = voice.providers[adapter.id] || {};
+    const env = {};
+    for (const field of adapter.fields)
+        env[field.env] = providerConfig[field.key] || '';
+    const config = adapter.readConfig(env, providerMode(adapter, voice.mode));
+    if (!adapter.isConfigured(config)) {
+        note(t('setup.voiceVerifyFailed', { msg: t('setup.voiceSkipped') }));
+        return false;
+    }
+    note(t('setup.voiceVerifying', { profile: voiceProfileLabel(voice) }));
+    try {
+        await adapter.verify(config);
+        note(t('setup.voiceVerified'));
+        return true;
+    }
+    catch (error) {
+        let message = errorMessage(error);
+        for (const field of adapter.fields) {
+            if (!field.secret)
+                continue;
+            const secret = providerConfig[field.key];
+            if (secret)
+                message = message.split(secret).join('••••');
+        }
+        note(t('setup.voiceVerifyFailed', { msg: message }));
+        return false;
+    }
+}
 // login (browser) → create → route dns → write config.yml. The only human step is the browser login.
 async function provisionCloudflareNamed({ home, hostname, tunnelName, port, log, }) {
     const bin = await resolveCloudflared(home);

package/dist/src/cli/supervisor.js

@@ -7,6 +7,7 @@ import path from 'node:path';
 import os from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
+import { providerMode, voiceProviderRegistry } from '../asr/providerRegistry.js';
 import { getDriver } from './drivers.js';
 import { writeState, clearState, claudeStatePath, pushStorePath, previewStorePath, notificationsDirPath } from './state.js';
 import { initialSupervisorComponentState, reduceSupervisorComponent, } from './supervisorState.js';
@@ -114,7 +115,7 @@ export function supervise(cfg, { home, log = console, spawnChild = defaultSpawnC
     const startServer = () => {
         // The server reads only process.env (no .env files) — the CLI resolved the one config file and we
         // hand the server everything it needs here. This is the single injection point: config.json fields →
-        // the env names the server already reads (HANDMUX_* / VAPID_* / XFYUN_*).
+        // the env names the server reads. Voice injects only the selected provider's credentials.
         const env = {
             ...processRef.env,
             NODE_ENV: 'handmux',
@@ -142,13 +143,28 @@ export function supervise(cfg, { home, log = console, spawnChild = defaultSpawnC
             if (cfg.vapid.subject)
                 env.VAPID_SUBJECT = cfg.vapid.subject;
         }
-        if (cfg.xfyun) {
-            if (cfg.xfyun.appId)
-                env.XFYUN_APPID = cfg.xfyun.appId;
-            if (cfg.xfyun.apiKey)
-                env.XFYUN_APIKEY = cfg.xfyun.apiKey;
-            if (cfg.xfyun.apiSecret)
-                env.XFYUN_APISECRET = cfg.xfyun.apiSecret;
+        // Config is authoritative for voice. Always remove inherited ASR state first, including when setup
+        // explicitly disabled voice; otherwise stale shell/service credentials silently re-enable XFYUN.
+        for (const key of [
+            'HANDMUX_ASR_PROVIDER',
+            'HANDMUX_ASR_MODE',
+            ...voiceProviderRegistry.adapters.flatMap((candidate) => (candidate.fields.map((field) => field.env))),
+        ])
+            delete env[key];
+        const voice = cfg.voice === null || cfg.voice?.enabled === false ? null
+            : cfg.voice ?? (cfg.xfyun ? { provider: 'xfyun', providers: { xfyun: cfg.xfyun } } : null);
+        if (voice) {
+            const adapter = voiceProviderRegistry.get(voice.provider);
+            if (adapter) {
+                env.HANDMUX_ASR_PROVIDER = adapter.id;
+                env.HANDMUX_ASR_MODE = providerMode(adapter, voice.mode);
+                const provider = voice.providers[adapter.id];
+                for (const field of adapter.fields) {
+                    const value = provider?.[field.key] || field.defaultValue;
+                    if (value)
+                        env[field.env] = value;
+                }
+            }
         }
         const c = spawnChild(processRef.execPath, [SERVER], { env, stdio: ['ignore', 'inherit', 'inherit'] });
         children.server = c;

package/dist/src/cli/supervisorLaunch.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import { readSupervisorConfig, supervisorConfigPath, writeSupervisorConfig, } from './state.js';
+import { providerMode, voiceProviderRegistry } from '../asr/providerRegistry.js';
 import { TUNNELS } from './options.js';
 import { normalizeShortcuts } from '../shortcutConfig.js';
 const recordOf = (value) => typeof value === 'object' && value !== null && !Array.isArray(value)
@@ -43,6 +44,28 @@ const stringFields = (value, keys, key) => {
     }
     return result;
 };
+const voiceConfig = (value) => {
+    if (value === undefined || value === null)
+        return value;
+    const record = recordOf(value);
+    const providers = recordOf(record?.providers);
+    const adapter = voiceProviderRegistry.get(record?.provider);
+    if (!record || !adapter || !providers) {
+        throw new Error('invalid supervisor config: voice must select a known provider');
+    }
+    const parsed = {};
+    for (const candidate of voiceProviderRegistry.adapters) {
+        const config = stringFields(providers[candidate.id], candidate.fields.map((field) => field.key), `voice.providers.${candidate.id}`);
+        if (config)
+            parsed[candidate.id] = config;
+    }
+    return {
+        ...(record.enabled === false ? { enabled: false } : {}),
+        provider: adapter.id,
+        mode: providerMode(adapter, record.mode),
+        providers: parsed,
+    };
+};
 // The persisted file and the legacy base64 argv are untrusted process boundaries. Parse them before the
 // supervisor starts so malformed or stale data fails as one explicit configuration error instead of being
 // used as partially-typed process arguments.
@@ -87,6 +110,7 @@ export function parseSupervisorConfig(value) {
     const cpolarBin = optionalString(record.cpolarBin, 'cpolarBin');
     const cpolarRegion = optionalString(record.cpolarRegion, 'cpolarRegion');
     const vapid = stringFields(record.vapid, ['public', 'private', 'subject'], 'vapid');
+    const voice = voiceConfig(record.voice);
     const xfyun = stringFields(record.xfyun, ['appId', 'apiKey', 'apiSecret'], 'xfyun');
     if (name !== undefined)
         config.name = name;
@@ -120,6 +144,8 @@ export function parseSupervisorConfig(value) {
         config.cpolarRegion = cpolarRegion;
     if (vapid !== undefined)
         config.vapid = vapid;
+    if (voice !== undefined)
+        config.voice = voice;
     if (xfyun !== undefined)
         config.xfyun = xfyun;
     return config;