verbalcoding 0.2.11 → 0.2.13

package/README.zh.md

@@ -0,0 +1,133 @@
+# VerbalCoding
+
+<p align="center"><strong>像打电话一样，通过 Discord 语音控制 CLI 编程代理。</strong></p>
+
+<p align="center"><a href="./README.md">English</a> · <a href="./README.ko.md">한국어</a> · <a href="./README.ja.md">日本語</a> · <a href="./README.es.md">Español</a> · <a href="./README.fr.md">Français</a> · <a href="./README.ru.md">Русский</a></p>
+
+<p align="center">
+  <img alt="npm" src="https://img.shields.io/npm/v/verbalcoding?color=CB3837&logo=npm&logoColor=white">
+  <img alt="Node.js" src="https://img.shields.io/badge/Node.js-20%2B-339933?logo=node.js&logoColor=white">
+  <img alt="Discord" src="https://img.shields.io/badge/Discord-voice%20bridge-5865F2?logo=discord&logoColor=white">
+  <img alt="STT" src="https://img.shields.io/badge/STT-whisper.cpp-7C3AED">
+  <img alt="TTS" src="https://img.shields.io/badge/TTS-Edge%20%7C%20OpenVoice%20%7C%20SpeechSwift-0EA5E9">
+  <img alt="License" src="https://img.shields.io/github/license/ca1773130n/VerbalCoding">
+</p>
+
+<p align="center">
+  <img src="docs/assets/figures/verbalcoding-flow.svg" alt="VerbalCoding voice-to-agent flow" width="860">
+</p>
+
+## 为什么需要它
+
+VerbalCoding 把 Discord 语音房间变成编码代理的免提驾驶舱。你说出需求，让 CLI 代理工作，并收到简短语音回复和文本记录；diff 和日志不会被 TTS 长篇朗读。
+
+> **已经在用 Hermes Agent？** Hermes 本身已经通过 `/voice join` / `/voice channel` 支持 Discord 语音频道：它可以加入你当前所在的 VC，用 Whisper 做语音转文字，并用 TTS 回答。只需要这个基础闭环时，VerbalCoding 不是必需的。VerbalCoding 是加在上面的工作流层：项目/会话路由、语音+文本共享上下文、插话规则、进度语音、语言预设、延迟指标，以及 Hermes 之外的 CLI 后端切换。
+
+## 体验亮点
+
+| 能力 | 价值 |
+|---|---|
+| 电话式工作流 | 在同一个 Discord 语音频道里说话、收听、打断、继续。 |
+| 面向人的引导设置 | `vc setup` 一次引导 prerequisites、Discord token/client ID、voice channel、transcript target、backend 和 TTS 设置。 |
+| 本地语音闭环 | Discord audio → local `whisper-cli` → selected CLI agent → TTS reply。 |
+| 可选代理 | 支持 Hermes Agent、Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw、Aider、Cursor CLI 或 custom command。`vc setup` 自动检测已安装项。 |
+| 语音切换代理 | `"ask Codex what it thinks"` 单 turn 路由,`"switch to Aider"` 粘性切换,`"back to default"` 回默认。未安装的二进制会被检测并询问是否回退到默认代理。 |
+| 超越 Hermes 内置语音 | 在同一个 VC 语音闭环上增加项目房间、`!ask` 共享上下文、细粒度打断处理、进度/状态语音和多代理后端控制。 |
+| 真实运维支持 | 内置 doctor auto-fix、Docker UDP 指南、latency metrics、multi-instance rooms 和 redacted config checks。 |
+
+## 快速开始
+
+```bash
+npm install -g verbalcoding@latest
+vc setup
+vc doctor
+vc start
+```
+
+普通用户路径是 `vc setup`。运行时请打开 Discord Developer Portal，并按提示输入 bot token、application/client ID、transcript target 和 voice channel names。
+
+自动化场景可以跳过提示，然后再补充 Discord 信息。
+
+```bash
+vc setup --yes
+vc setup token <bot-token> --client-id <discord-client-id>
+vc setup channels "General,Team Voice"
+vc doctor
+```
+
+## 一分钟完成 Discord 设置
+
+1. 在 Discord Developer Portal 创建 application 和 bot。
+2. 启用 Message Content privileged intent。
+3. 运行 `vc setup`，粘贴 bot token 和 application/client ID。
+4. 输入要自动加入的精确 voice channel 名称。
+5. 用下面的命令邀请 bot。
+
+```bash
+vc bot invite <discord-client-id>
+vc bot invite <discord-client-id> --guild <guild-id>
+```
+
+## 迷你命令地图
+
+```bash
+vc setup                                 # 引导式设置: prerequisites, Discord, backend, voice
+vc setup --yes                           # 非交互 bootstrap/starter config
+vc setup token                           # 稍后轮换或添加 Discord bot token/client ID
+vc setup channels "General,Team Voice"   # 更新 auto-join voice channel names
+vc bot invite CLIENT_ID                  # 生成 Discord bot invite URL
+vc status                                # 显示当前设置
+vc language ko|en|auto                   # 切换 language preset
+vc doctor                                # redacted health check 和 auto-fix
+vc start                                 # 启动默认 bridge
+vc instance setup NAME                   # 创建隔离的 project voice bot
+vc instance start NAME                   # 后台运行该 bot
+```
+
+## 了解更多
+
+| 指南 | 内容 |
+|---|---|
+| [文档中心](docs/i18n/README.zh.md) | 本地化指南索引。 |
+| [Fresh Install](docs/i18n/FRESH_INSTALL.zh.md) | npm/global setup、Discord 设置、首次运行。 |
+| [Usage](docs/i18n/USAGE.zh.md) | CLI 命令、Discord 命令、运行模式、latency。 |
+| [Harness 使用](docs/i18n/HARNESSES.zh.md) | Claude Code、Codex、Aider 等各后端的安装、配置与语音路由。 |
+| [Configuration](docs/i18n/CONFIGURATION.zh.md) | .env、agent backends、MCP、TTS、运维。 |
+| [Troubleshooting](docs/i18n/TROUBLESHOOTING.zh.md) | Docker UDP、token/channel 缺失检查。 |
+| [Multi-Instance](docs/i18n/MULTI_INSTANCE.zh.md) | 每个项目一个固定语音房间。 |
+
+## 要求
+
+| 层级 | 默认 |
+|---|---|
+| Runtime | Node.js 20+ 和 npm。 |
+| Audio | `ffmpeg` 和 local `whisper-cli`。 |
+| TTS | 默认 Edge TTS；可选 OpenVoice、SpeechSwift/CosyVoice、Supertonic。 |
+| Discord | Bot token、Message Content intent、voice permissions、匹配的 channel names。 |
+| Agent | 至少一个已认证 CLI harness；默认 Hermes Agent。 |
+
+## Docker / 容器说明
+
+如果日志出现 `Cannot perform IP discovery - socket closed`，说明 Discord voice UDP 被阻断。在 Linux Docker Compose 中使用：
+
+```yaml
+services:
+  verbalcoding:
+    network_mode: "host"
+```
+
+不要同时使用 `network_mode: "host"` 和 `ports:`。
+
+## 贡献
+
+```bash
+node --check app-node/main.mjs
+npm test
+bash -n run.sh scripts/install.sh scripts/bootstrap_prereqs.sh
+npm pack --dry-run
+vc doctor
+```
+
+## 状态
+
+VerbalCoding 面向公开发布，但仍处于早期阶段。演示视频/GIF、更广泛的 Linux 验证、CI 和安全审查仍是 TODO。

package/app-node/agent_adapters.mjs

@@ -23,12 +23,14 @@ export function voiceBridgePrompt(text, options = {}) {
   const english = /^en/i.test(String(options.language || ''));
   const lines = english ? [
     'This is a user utterance from a Discord voice call.',
+    'Consider Discord voice-channel speech and text-channel messages as one shared conversation context when inferring intent.',
     'Answer in English. For simple conversation/status questions, do not use tools; answer directly in 1-3 sentences.',
     'Use tools only for real work requests such as file edits, command execution, log checks, or web/search tasks.',
     'If code changes are made, do not read diffs or full code aloud; summarize outcome and next checks briefly.',
     'Do not include CLI metadata or session_id in the answer.',
   ] : [
     'Discord 음성 대화로 들어온 사용자 발화다.',
+    '의도를 판단할 때 음성 채널 발화와 텍스트 채널 메시지를 같은 대화 맥락으로 함께 고려해라.',
     '단순 대화/상태 질문이면 도구를 쓰지 말고 1~3문장으로 바로 한국어 답변해라.',
     '파일 수정, 실행, 로그 확인, 검색 같은 실제 작업 지시일 때만 필요한 도구를 사용해라.',
     '코드 변경을 수행했다면 음성 답변에는 diff나 코드 전문을 읽지 말고, 작업 결과와 다음 확인 사항만 짧게 말해라.',
@@ -57,6 +59,10 @@ export function voiceBridgePrompt(text, options = {}) {
     lines.push(english ? 'Route this turn through the following project/session context:' : '이 턴은 아래 프로젝트/세션 컨텍스트로 처리해라.');
     lines.push(String(options.projectContext).trim());
   }
+  if (options.recentDiscordContext) {
+    lines.push(english ? 'Recent Discord text-channel context to consider with this voice utterance:' : '이 음성 발화와 함께 고려할 최근 Discord 텍스트 채널 맥락:');
+    lines.push(String(options.recentDiscordContext).trim());
+  }
   return lines.concat(['', text]).join('\n');
 }
 
@@ -251,6 +257,24 @@ export function buildAgentSettings({ ROOT, env = process.env } = {}) {
       sessionFile: env.AGENT_SESSION_FILE || path.join(root, '.agent-sessions', 'openclaw'),
       supportsHermesSession: false,
     },
+    aider: {
+      label: 'Aider',
+      command: env.AIDER_COMMAND || 'aider --no-pretty --yes-always --message',
+      sessionFile: env.AGENT_SESSION_FILE || path.join(root, '.agent-sessions', 'aider'),
+      supportsHermesSession: false,
+    },
+    cursor: {
+      label: 'Cursor CLI',
+      command: env.CURSOR_COMMAND || 'cursor-agent --print --prompt',
+      sessionFile: env.AGENT_SESSION_FILE || path.join(root, '.agent-sessions', 'cursor'),
+      supportsHermesSession: false,
+    },
+    'cursor-cli': {
+      label: 'Cursor CLI',
+      command: env.CURSOR_COMMAND || 'cursor-agent --print --prompt',
+      sessionFile: env.AGENT_SESSION_FILE || path.join(root, '.agent-sessions', 'cursor'),
+      supportsHermesSession: false,
+    },
     custom: {
       label: env.AGENT_LABEL || 'Custom Agent',
       command: env.AGENT_COMMAND || '',
@@ -294,6 +318,7 @@ export function createAgentAdapter(settings, deps = {}) {
   const hermesSessionsDir = deps.hermesSessionsDir || path.join(os.homedir(), '.hermes', 'sessions');
   const spawnProcess = deps.spawn;
   const onProgress = deps.onProgress || (() => {});
+  const onStdoutChunk = deps.onStdoutChunk || null;
   const emittedProgress = new Set();
   let activeProgressLanguage = settings.language;
   const capabilities = agentAdapterCapabilities(settings);
@@ -308,7 +333,7 @@ export function createAgentAdapter(settings, deps = {}) {
   }
 
   function execWithOptionalProgress(cmd, args, options, verbose) {
-    if (!verbose || !spawnProcess) return execFileAsync(cmd, args, options);
+    if ((!verbose && !onStdoutChunk) || !spawnProcess) return execFileAsync(cmd, args, options);
     return new Promise((resolve, reject) => {
       const child = spawnProcess(cmd, args, {
         env: options.env,
@@ -353,7 +378,8 @@ export function createAgentAdapter(settings, deps = {}) {
       child.stdout?.on('data', chunk => {
         const s = chunk.toString();
         stdout += s;
-        emitVerboseProgress(s);
+        if (onStdoutChunk) { try { onStdoutChunk(s); } catch (e) { warn('onStdoutChunk failed', e?.stack || e); } }
+        if (verbose) emitVerboseProgress(s);
         if (stdout.length + stderr.length > options.maxBuffer) {
           const err = new Error('maxBuffer exceeded');
           err.code = 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER';
@@ -364,7 +390,7 @@ export function createAgentAdapter(settings, deps = {}) {
       child.stderr?.on('data', chunk => {
         const s = chunk.toString();
         stderr += s;
-        emitVerboseProgress(s);
+        if (verbose) emitVerboseProgress(s);
         if (stdout.length + stderr.length > options.maxBuffer) {
           const err = new Error('maxBuffer exceeded');
           err.code = 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER';
@@ -467,7 +493,12 @@ export function createAgentAdapter(settings, deps = {}) {
   function buildArgs(text, options = {}) {
     const argv = shellSplit(settings.command);
     const cmd = argv[0];
-    const query = voiceBridgePrompt(text, { verboseProgress: options.verboseProgress, language: options.language, projectContext: options.projectContext });
+    const query = voiceBridgePrompt(text, {
+      verboseProgress: options.verboseProgress,
+      language: options.language,
+      projectContext: options.projectContext,
+      recentDiscordContext: options.recentDiscordContext,
+    });
     let args = argv.slice(1);
     if (settings.backend === 'hermes' && options.verboseProgress) {
       // Hermes quiet mode intentionally suppresses tool previews.  In verbose
@@ -491,8 +522,9 @@ export function createAgentAdapter(settings, deps = {}) {
     const language = plan.language || settings.language;
     activeProgressLanguage = language;
     const projectContext = plan.projectContext || settings.projectContext || '';
+    const recentDiscordContext = plan.recentDiscordContext || '';
     emittedProgress.clear();
-    const { cmd, args, sessionId } = buildArgs(text, { verboseProgress, language, projectContext });
+    const { cmd, args, sessionId } = buildArgs(text, { verboseProgress, language, projectContext, recentDiscordContext });
     const start = Date.now();
     const label = plan.label || settings.label;
     const { args: finalArgs, outputPath } = addCodexOutputCapture(args);

package/app-node/agent_adapters.test.mjs

@@ -288,6 +288,8 @@ test('Claude, Codex, and Gemini adapters use backend-specific default commands w
     { backend: 'gemini', command: ['gemini', '-p'], label: 'Gemini' },
     { backend: 'opencode', command: ['opencode', 'run'], label: 'OpenCode' },
     { backend: 'openclaw', command: ['openclaw', 'run'], label: 'OpenClaw' },
+    { backend: 'aider', command: ['aider', '--no-pretty', '--yes-always', '--message'], label: 'Aider' },
+    { backend: 'cursor', command: ['cursor-agent', '--print', '--prompt'], label: 'Cursor CLI' },
   ];
 
   for (const item of cases) {
@@ -352,10 +354,20 @@ test('voiceBridgePrompt keeps voice-specific operating instructions with user te
   const prompt = voiceBridgePrompt('파일 수정해줘');
 
   assert.match(prompt, /Discord 음성 대화/);
-  assert.match(prompt, /파일 수정, 실행, 로그 확인/);
   assert.match(prompt, /파일 수정해줘/);
 });
 
+test('voiceBridgePrompt includes recent Discord text context when provided', () => {
+  const prompt = voiceBridgePrompt('왜 죽었어?', {
+    recentDiscordContext: '최근 텍스트 채널 메시지:\n- user: 음성채널에서만 나가줘',
+  });
+
+  assert.match(prompt, /음성 채널 발화와 텍스트 채널 메시지를 같은 대화 맥락으로 함께 고려/);
+  assert.match(prompt, /최근 텍스트 채널 메시지/);
+  assert.match(prompt, /음성채널에서만 나가줘/);
+  assert.match(prompt, /왜 죽었어\?/);
+});
+
 test('voiceBridgePrompt adds optional verbose progress instructions only when enabled', () => {
   const normal = voiceBridgePrompt('파일 수정해줘');
   const verbose = voiceBridgePrompt('파일 수정해줘', { verboseProgress: true });
@@ -444,6 +456,20 @@ test('signal failure with patch-like output returns a concise interruption messa
   assert.doesNotMatch(answer, /@@|review diff|old|new/);
 });
 
+test('createAgentAdapter satisfies the agent adapter contract for every known backend', () => {
+  const backends = ['hermes', 'claude', 'codex', 'gemini', 'opencode', 'openclaw', 'aider', 'cursor'];
+  for (const backend of backends) {
+    const settings = buildAgentSettings({ ROOT: '/tmp/vc-test', env: { AGENT_BACKEND: backend } });
+    const adapter = createAgentAdapter(settings, {
+      execFileAsync: async () => ({ stdout: '', stderr: '' }),
+      log: () => {},
+      warn: () => {},
+    });
+    assert.doesNotThrow(() => assertAgentAdapterContract(adapter), `${backend} should satisfy contract`);
+    assert.equal(adapter.backend, backend);
+  }
+});
+
 test('hermes adapter spawn carries HERMES_HOME from instance env into child env', async () => {
   const { buildHermesSpawnOptions } = await import('./agent_adapters.mjs');
   const opts = buildHermesSpawnOptions({

package/app-node/agent_detect.mjs

@@ -0,0 +1,73 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const PROBES = [
+  { backend: 'hermes', bin: 'hermes', defaultCommand: 'hermes chat -Q -q', envCommand: 'HERMES_COMMAND', label: 'Hermes Agent' },
+  { backend: 'claude', bin: 'claude', defaultCommand: 'claude -p', envCommand: 'CLAUDE_COMMAND', label: 'Claude Code' },
+  { backend: 'codex', bin: 'codex', defaultCommand: 'codex exec', envCommand: 'CODEX_COMMAND', label: 'Codex' },
+  { backend: 'gemini', bin: 'gemini', defaultCommand: 'gemini -p', envCommand: 'GEMINI_COMMAND', label: 'Gemini' },
+  { backend: 'opencode', bin: 'opencode', defaultCommand: 'opencode run', envCommand: 'OPENCODE_COMMAND', label: 'OpenCode' },
+  { backend: 'openclaw', bin: 'openclaw', defaultCommand: 'openclaw run', envCommand: 'OPENCLAW_COMMAND', label: 'OpenClaw' },
+  { backend: 'aider', bin: 'aider', defaultCommand: 'aider --no-pretty --yes-always --message', envCommand: 'AIDER_COMMAND', label: 'Aider' },
+  { backend: 'cursor', bin: 'cursor-agent', defaultCommand: 'cursor-agent --print --prompt', envCommand: 'CURSOR_COMMAND', label: 'Cursor CLI' },
+];
+
+function defaultWhich(bin, { env = process.env, accessSync = fs.accessSync } = {}) {
+  const pathVar = env.PATH || '';
+  const sep = process.platform === 'win32' ? ';' : ':';
+  const exts = process.platform === 'win32' ? (env.PATHEXT || '.EXE;.CMD;.BAT').split(';') : [''];
+  for (const dir of pathVar.split(sep)) {
+    if (!dir) continue;
+    for (const ext of exts) {
+      const candidate = path.join(dir, bin + ext);
+      try {
+        accessSync(candidate, fs.constants.X_OK);
+        return candidate;
+      } catch { /* not here */ }
+    }
+  }
+  return null;
+}
+
+export async function detectInstalledAgents(env = process.env, { which } = {}) {
+  const probe = which || ((bin) => defaultWhich(bin, { env }));
+  return Promise.all(PROBES.map(async (p) => {
+    const located = await probe(p.bin);
+    return {
+      backend: p.backend,
+      label: p.label,
+      bin: p.bin,
+      path: located || null,
+      present: Boolean(located),
+      command: env[p.envCommand] || p.defaultCommand,
+    };
+  }));
+}
+
+export function listKnownBackends() {
+  return PROBES.map(p => ({ backend: p.backend, label: p.label, bin: p.bin }));
+}
+
+export function pickDefaultBackend(detection, preferred = '') {
+  const list = Array.isArray(detection) ? detection : [];
+  const pref = String(preferred || '').toLowerCase();
+  if (pref) {
+    const match = list.find(r => r.backend === pref && r.present);
+    if (match) return match.backend;
+  }
+  const firstPresent = list.find(r => r.present);
+  if (firstPresent) return firstPresent.backend;
+  return 'hermes';
+}
+
+export function formatAgentDetectionReport(detection) {
+  const list = Array.isArray(detection) ? detection : [];
+  if (!list.length) return 'No agent backends probed.';
+  const rows = list.map(r => {
+    const marker = r.present ? '✓' : '·';
+    const pathPart = r.present ? r.path : 'not found';
+    return `  ${marker} ${r.label.padEnd(14)} ${r.bin.padEnd(14)} ${pathPart}`;
+  });
+  const presentCount = list.filter(r => r.present).length;
+  return `Agent backends (${presentCount}/${list.length} present):\n${rows.join('\n')}`;
+}

package/app-node/agent_detect.test.mjs

@@ -0,0 +1,77 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { detectInstalledAgents, listKnownBackends, pickDefaultBackend, formatAgentDetectionReport } from './agent_detect.mjs';
+
+test('detectInstalledAgents marks present when which resolves', async () => {
+  const fakeWhich = async (bin) => (bin === 'hermes' ? '/usr/local/bin/hermes' : null);
+  const result = await detectInstalledAgents({}, { which: fakeWhich });
+  const hermes = result.find(r => r.backend === 'hermes');
+  assert.equal(hermes.present, true);
+  assert.equal(hermes.path, '/usr/local/bin/hermes');
+  const claude = result.find(r => r.backend === 'claude');
+  assert.equal(claude.present, false);
+});
+
+test('detectInstalledAgents includes aider and cursor', async () => {
+  const fakeWhich = async () => null;
+  const result = await detectInstalledAgents({}, { which: fakeWhich });
+  const backends = result.map(r => r.backend);
+  assert.ok(backends.includes('aider'));
+  assert.ok(backends.includes('cursor'));
+});
+
+test('detectInstalledAgents honors env overrides for command', async () => {
+  const fakeWhich = async (bin) => (bin === 'aider' ? '/opt/aider' : null);
+  const result = await detectInstalledAgents({ AIDER_COMMAND: 'aider --foo' }, { which: fakeWhich });
+  const aider = result.find(r => r.backend === 'aider');
+  assert.equal(aider.command, 'aider --foo');
+  assert.equal(aider.present, true);
+});
+
+test('listKnownBackends returns 8 entries', () => {
+  const list = listKnownBackends();
+  assert.equal(list.length, 8);
+  assert.ok(list.some(b => b.backend === 'hermes'));
+  assert.ok(list.some(b => b.backend === 'cursor'));
+});
+
+test('detectInstalledAgents default which uses PATH iteration', async () => {
+  const result = await detectInstalledAgents({ PATH: '/nonexistent/dir' }, {});
+  assert.ok(Array.isArray(result));
+  for (const r of result) assert.equal(r.present, false);
+});
+
+test('pickDefaultBackend respects preferred when present', () => {
+  const detection = [
+    { backend: 'hermes', present: false },
+    { backend: 'claude', present: true },
+    { backend: 'aider', present: true },
+  ];
+  assert.equal(pickDefaultBackend(detection, 'aider'), 'aider');
+});
+
+test('pickDefaultBackend falls back to first present when preferred missing', () => {
+  const detection = [
+    { backend: 'hermes', present: false },
+    { backend: 'claude', present: true },
+    { backend: 'aider', present: true },
+  ];
+  assert.equal(pickDefaultBackend(detection, 'codex'), 'claude');
+});
+
+test('pickDefaultBackend returns hermes when nothing detected', () => {
+  const detection = [{ backend: 'hermes', present: false }, { backend: 'claude', present: false }];
+  assert.equal(pickDefaultBackend(detection, ''), 'hermes');
+});
+
+test('formatAgentDetectionReport marks present and missing', () => {
+  const detection = [
+    { backend: 'hermes', label: 'Hermes Agent', bin: 'hermes', present: true, path: '/usr/local/bin/hermes' },
+    { backend: 'claude', label: 'Claude Code', bin: 'claude', present: false, path: null },
+  ];
+  const out = formatAgentDetectionReport(detection);
+  assert.match(out, /1\/2 present/);
+  assert.match(out, /✓ Hermes Agent/);
+  assert.match(out, /· Claude Code/);
+  assert.match(out, /not found/);
+});

package/app-node/agent_routing.mjs

@@ -0,0 +1,148 @@
+const BACKEND_ALIASES = {
+  hermes: ['hermes', '헤르메스'],
+  claude: ['claude code', 'claude-code', 'claude'],
+  codex: ['codex', '코덱스'],
+  gemini: ['gemini cli', 'gemini-cli', 'gemini', '제미나이'],
+  opencode: ['opencode', 'open code'],
+  openclaw: ['openclaw', 'open claw'],
+  aider: ['aider', '에이더'],
+  cursor: ['cursor cli', 'cursor-cli', 'cursor agent', 'cursor-agent', 'cursor'],
+};
+
+const BACKEND_LOOKUP = (() => {
+  const pairs = [];
+  for (const [backend, aliases] of Object.entries(BACKEND_ALIASES)) {
+    for (const alias of aliases) pairs.push([alias.toLowerCase(), backend]);
+  }
+  pairs.sort((a, b) => b[0].length - a[0].length);
+  return pairs;
+})();
+
+const BACKEND_LABELS = {
+  hermes: { en: 'Hermes', ko: '헤르메스' },
+  claude: { en: 'Claude Code', ko: 'Claude Code' },
+  codex: { en: 'Codex', ko: '코덱스' },
+  gemini: { en: 'Gemini', ko: 'Gemini' },
+  opencode: { en: 'OpenCode', ko: 'OpenCode' },
+  openclaw: { en: 'OpenClaw', ko: 'OpenClaw' },
+  aider: { en: 'Aider', ko: 'Aider' },
+  cursor: { en: 'Cursor CLI', ko: 'Cursor CLI' },
+};
+
+const ROUTING_SLOT_NAMES = new Set(['which_agent', 'agent', 'who_answers', 'router_agent']);
+
+const ASK_EN = /\bask\s+([a-z][a-z0-9 \-]{1,30}?)(?:\s+(?:to|what|if|whether)\b|[?,.]|$)/i;
+const SWITCH_EN = /\bswitch\s+to\s+([a-z][a-z0-9 \-]{1,30}?)(?:[?,.]|$)/i;
+const LET_FINISH_EN = /\blet\s+([a-z][a-z0-9 \-]{1,30}?)\s+(?:finish|handle|do)\b/i;
+const RESTORE_EN = /\b(back\s+to\s+default|use\s+the\s+default\s+agent|default\s+agent)\b/i;
+
+const ASK_KO = /([가-힣A-Za-z][가-힣A-Za-z0-9\-]{1,30})(?:한테|에게|에)\s*(물어|질문)/;
+const SWITCH_KO = /([가-힣A-Za-z][가-힣A-Za-z0-9\-]{1,30})(?:로|으로)\s*(전환|바꿔|바꿔줘)/;
+const RESTORE_KO = /(기본(?:으로)?\s*(?:돌아|복귀)|기본\s*에이전트)/;
+
+export function isRoutingOnlyUtterance(text) {
+  const t = String(text || '').trim();
+  if (!t) return false;
+  const normalized = t.toLowerCase().replace(/[.,!?]+$/u, '').trim();
+  if (/^(?:please\s+)?(?:back\s+to\s+default|use\s+the\s+default\s+agent|default\s+agent)$/i.test(normalized)) return true;
+  if (/^기본(?:으로)?\s*(?:돌아(?:가|가줘)?|복귀)$/.test(normalized)) return true;
+  const en = normalized.match(/^(?:please\s+)?(?:switch\s+to|use)\s+(.+)$/i);
+  if (en) return resolveBackendAlias(en[1], { strict: true }) !== null;
+  const ko = normalized.match(/^(.+?)(?:로|으로)\s*(?:전환|바꿔|바꿔줘)$/);
+  if (ko) return resolveBackendAlias(ko[1], { strict: true }) !== null;
+  return false;
+}
+
+export function resolveBackendAlias(rawName, { strict = false } = {}) {
+  const needle = String(rawName || '').toLowerCase().trim();
+  if (!needle) return null;
+  for (const [alias, backend] of BACKEND_LOOKUP) {
+    if (needle === alias) return backend;
+  }
+  if (strict) return null;
+  for (const [alias, backend] of BACKEND_LOOKUP) {
+    if (needle.includes(alias)) return backend;
+  }
+  return null;
+}
+
+export function parseAgentRoutingCommand(text, language = 'en') {
+  const t = String(text || '').trim();
+  if (!t) return { type: 'none' };
+  if (RESTORE_EN.test(t) || RESTORE_KO.test(t)) return { type: 'restore' };
+  const switchMatch = t.match(SWITCH_EN) || t.match(LET_FINISH_EN);
+  if (switchMatch) {
+    const backend = resolveBackendAlias(switchMatch[1]);
+    if (backend) return { type: 'route', backend, sticky: true };
+  }
+  const switchKo = t.match(SWITCH_KO);
+  if (switchKo) {
+    const backend = resolveBackendAlias(switchKo[1]);
+    if (backend) return { type: 'route', backend, sticky: true };
+  }
+  const askMatch = t.match(ASK_EN);
+  if (askMatch) {
+    const backend = resolveBackendAlias(askMatch[1]);
+    if (backend) return { type: 'route', backend, sticky: false };
+  }
+  const askKo = t.match(ASK_KO);
+  if (askKo) {
+    const backend = resolveBackendAlias(askKo[1]);
+    if (backend) return { type: 'route', backend, sticky: false };
+  }
+  return { type: 'none' };
+}
+
+export function isAgentRoutingDecision(decision) {
+  if (!decision || typeof decision !== 'object') return false;
+  const slot = String(decision.slot || '').toLowerCase();
+  return ROUTING_SLOT_NAMES.has(slot);
+}
+
+export function renderAgentPrefix(backend, language = 'en') {
+  const key = String(backend || '').toLowerCase();
+  if (!BACKEND_LABELS[key]) return '';
+  const en = /^en/i.test(String(language || ''));
+  const label = BACKEND_LABELS[key][en ? 'en' : 'ko'];
+  return en ? `${label} says: ` : `${label}: `;
+}
+
+function labelFor(backend, language) {
+  const key = String(backend || '').toLowerCase();
+  if (!BACKEND_LABELS[key]) return key || 'agent';
+  return BACKEND_LABELS[key][/^en/i.test(String(language || '')) ? 'en' : 'ko'];
+}
+
+export function buildCrossAgentPrompt({
+  prompt, fromBackend, toBackend,
+  resolvedDecisions = {}, priorUtterances = [], language = 'en',
+} = {}) {
+  const en = /^en/i.test(String(language || ''));
+  const fromLabel = labelFor(fromBackend, language);
+  const toLabel = labelFor(toBackend, language);
+  const lines = [];
+  lines.push(en
+    ? `[Cross-agent handoff from ${fromLabel} to ${toLabel}]`
+    : `[에이전트 핸드오프: ${fromLabel} → ${toLabel}]`);
+  const decKeys = Object.keys(resolvedDecisions || {});
+  if (decKeys.length) {
+    const parts = decKeys.map(k => `${k}=${resolvedDecisions[k] === null ? '(agent picks)' : resolvedDecisions[k]}`);
+    lines.push(en ? `Prior decisions: ${parts.join(', ')}` : `이전 결정: ${parts.join(', ')}`);
+  }
+  const utterances = (priorUtterances || []).filter(Boolean).slice(-4);
+  if (utterances.length) {
+    lines.push(en
+      ? `Recent user voice: ${utterances.join(' | ')}`
+      : `최근 사용자 음성: ${utterances.join(' | ')}`);
+  }
+  lines.push(en ? `User request: ${prompt}` : `사용자 요청: ${prompt}`);
+  return lines.join('\n');
+}
+
+export function buildFallbackDecision(missingBackend, fallbackLabel, language = 'en') {
+  const en = /^en/i.test(String(language || ''));
+  const question = en
+    ? `${missingBackend} is not installed. Use ${fallbackLabel} instead?`
+    : `${missingBackend}이(가) 설치되어 있지 않아. ${fallbackLabel}로 대신 진행할까?`;
+  return { slot: 'fallback', question, options: ['yes', 'no'] };
+}