verbalcoding 0.2.12 → 0.2.13

package/app-node/voice_turn_runner.test.mjs

@@ -0,0 +1,289 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createVoiceTurnRunner } from './voice_turn_runner.mjs';
+import { createUtteranceRouter } from './utterance_router.mjs';
+import { createPlanDispatcher } from './plan_dispatcher.mjs';
+import { createBridge } from './bridge_context.mjs';
+import { createAgentTurnLifecycle } from './agent_turn.mjs';
+
+function noop() {}
+async function noopAsync() {}
+
+// Build a complete dep set for voiceTurnRunner by first constructing a
+// real utterance_router with stubbed pure-function deps, then threading
+// its outputs into the runner alongside the rest. This mirrors main.mjs's
+// real construction order so the tests catch any inter-module wiring drift.
+function makeDeps(overrides = {}) {
+  const bridge = createBridge();
+  bridge.bridgeState = {
+    deferredSize: () => 0,
+    currentEpoch: () => 1,
+    discardQueues: () => 0,
+  };
+  const agentTurnLifecycle = createAgentTurnLifecycle({ bridge, warn: noop });
+
+  const agentAdapter = {
+    label: 'default-agent', backend: 'hermes',
+    readSessionId: () => null,
+    ask: async () => 'mock agent answer',
+  };
+
+  // Construct the router (post-Phase 7b: dispatch + adapter selection only).
+  const router = createUtteranceRouter({
+    bridge,
+    log: noop, warn: noop, path: { join: (...a) => a.join('/') },
+    ROOT: '/tmp/vc', TTS_VOICE_CONFIG_PATH: '/tmp/voices.json',
+    agentAdapter,
+    settings: { voiceLanguage: 'ko', transcriptChannelId: 'tx-ch', agent: { backend: 'hermes', label: 'hermes' }, tts: {} },
+    projectSessionContextText: () => '',
+    createBridgeAgentAdapter: s => ({ label: s?.label || 'fake', backend: s?.backend || 'hermes', ask: async () => '' }),
+    buildAgentSettings: () => ({ backend: 'hermes', label: 'hermes' }),
+    commandIsInstalled: async () => true,
+    shellSplit: s => String(s).split(' '),
+    sendText: noopAsync, speakText: noopAsync,
+    ensureTtsVoiceConfig: () => ({ backends: {} }),
+    updateTtsVoiceConfig: c => c,
+    writeTtsVoiceConfig: noop,
+    applyVoiceConfigToProcessEnv: () => ({ selection: { backend: 'edge', voiceType: 'female', voice: { language: 'ko', voice: 'x' } } }),
+    ensureSelectedTtsBackendInstalled: noopAsync,
+    rebuildTtsRuntimeSettings: noop,
+    voiceCommandFromTranscript: () => null,
+    voiceChangedText: () => '',
+    voiceLanguageCommandFromTranscript: () => null,
+    voiceCloneCommandFromText: () => null,
+    voiceCloneCapture: { arm: () => ({ targetPath: '' }), cancel: () => false, current: () => null },
+    notifyVoiceCloneSampleGapIfNeeded: noopAsync,
+    languageChangedText: () => '',
+    applyRuntimeLanguage: noop,
+    persistEnvValues: noop,
+    discardVoiceInputQueues: () => 0,
+  });
+
+  // Construct the plan dispatcher (Phase 7b) consuming router outputs.
+  const planDispatcher = createPlanDispatcher({
+    bridge,
+    settings: { voiceLanguage: 'ko', transcriptChannelId: 'tx-ch', agent: { backend: 'hermes', label: 'hermes' } },
+    sendText: noopAsync,
+    speakText: noopAsync,
+    routingStateFor: router.routingStateFor,
+    adapterForBackend: router.adapterForBackend,
+    adapterForProjectSession: router.adapterForProjectSession,
+    resolveProjectSessionForChannel: () => null,
+    isAgentRoutingDecision: () => false,
+    parseDecisionAnswer: () => ({ type: 'unknown' }),
+    parsePlanVoiceCommand: () => ({ type: 'unknown' }),
+    applyPlanCommand: s => s,
+    parsePlanOutput: () => ({ steps: [], decisions: [] }),
+    renderDecisionPrompt: d => d?.text || '',
+    renderResolvedDecisions: () => '',
+    renderFinalPlan: () => '',
+    planModePreamble: () => '',
+    planExecutionPreamble: () => '',
+    isPlanEntryUtterance: () => false,
+  });
+
+  const settings = { voiceLanguage: 'ko', transcriptChannelId: 'tx-ch', agent: { backend: 'hermes', label: 'hermes' }, tts: {} };
+
+  return {
+    bridge,
+    agentTurnLifecycle,
+    settings,
+    client: { channels: { cache: new Map() } },
+    log: noop, warn: noop, fs: { rm: (_p, _o, cb) => cb && cb() },
+    // voice_io
+    transcribe: async () => 'hey hermes do a thing',
+    // tts_player
+    beginStreamingTurn: () => false,
+    endStreamingTurn: noopAsync,
+    speakText: noopAsync,
+    // progress_handler
+    queueProgressSpeechText: noop,
+    stopProgressSpeech: noop,
+    speakImmediateNotice: noopAsync,
+    // notification_handler
+    maybeNotifyTaskComplete: noopAsync,
+    // utterance_router outputs (real router instance built above)
+    handleLanguageCommand: router.handleLanguageCommand,
+    handleTtsVoiceCommand: router.handleTtsVoiceCommand,
+    handleVoiceCloneCommand: router.handleVoiceCloneCommand,
+    dispatchPlanModeUtterance: planDispatcher.dispatchPlanModeUtterance,
+    adapterForBackend: router.adapterForBackend,
+    adapterForProjectSession: router.adapterForProjectSession,
+    planChannelKey: planDispatcher.planChannelKey,
+    routingStateFor: router.routingStateFor,
+    recordUtterance: router.recordUtterance,
+    clearTransientRouting: router.clearTransientRouting,
+    // pure helpers
+    isAllowed: () => true,
+    isAbortError: e => e?.name === 'AbortError',
+    sleep: async () => {},
+    sendText: noopAsync,
+    sendEmbed: async () => true,
+    reloadRuntimeLanguageFromEnv: () => ({ changed: false, voiceLanguage: 'ko', whisperLanguage: 'ko' }),
+    drainDeferredProcessingUtterances: noopAsync,
+    resolveProjectSessionForChannel: () => null,
+    projectSessionContextText: () => '',
+    ontologyStateFor: () => ({ nodeCount: 0, serializeForHandoff: () => '' }),
+    captureOntologyFromTurn: noop,
+    formatRecentDiscordContext: () => '',
+    formatSttResultMessage: (_lang, _u, t) => `you said: ${t}`,
+    formatSttStartMessage: () => '🎧',
+    formatVoiceErrorMessage: (_lang, m) => m,
+    formatWakeRejectedMessage: () => 'no wake word',
+    agentAnswerHeader: () => 'agent says:',
+    emptyAgentAnswer: () => '(empty)',
+    spokenResultOnly: (_p, a) => a,
+    stripWake: t => t,
+    acceptsWake: () => true,
+    sensitivityChangedSpeech: () => '',
+    sensitivityModeFromTranscript: () => null,
+    sensitivityStatusText: () => '',
+    setSensitivityMode: () => ({ mode: 'normal' }),
+    isSensitivityOnlyRequest: () => false,
+    verboseChangedSpeech: () => '',
+    verboseModeFromTranscript: () => null,
+    verboseStatusText: () => '',
+    setVerboseProgress: noop,
+    isVerboseOnlyRequest: () => false,
+    isRoutingOnlyUtterance: () => false,
+    parseAgentRoutingCommand: () => ({ type: 'none' }),
+    renderAgentPrefix: () => '',
+    buildCrossAgentPrompt: ({ prompt }) => prompt,
+    buildFallbackDecision: () => ({ slot: 'fallback' }),
+    parseDecisionAnswer: () => ({ type: 'unknown' }),
+    parseResearchCommand: () => ({ type: 'none' }),
+    runResearchTurn: async () => ({ status: 'no_backend' }),
+    PROGRESS_IDLE_CHECK_MS: 5000,
+    PROGRESS_IDLE_NOTICE_INITIAL_MS: 10000,
+    PROGRESS_IDLE_NOTICE_LIMIT: 20,
+    PROGRESS_IDLE_NOTICE_MAX_MS: 30000,
+    PROGRESS_IDLE_NOTICE_MULTIPLIER: 1.8,
+    STT_START_VOICE_NOTICE: false,
+    ...overrides,
+  };
+}
+
+test('createVoiceTurnRunner exposes handleRecording', () => {
+  const runner = createVoiceTurnRunner(makeDeps());
+  assert.equal(typeof runner.handleRecording, 'function');
+});
+
+test('handleRecording happy path: transcribe -> agent -> send + speak + notify, cleanup green', async () => {
+  const calls = { transcribe: 0, askPrompt: '', sendText: [], speakText: [], notify: [] };
+  // Capture the exact prompt the runner sends to the agent and the exact
+  // answer that flows back out.
+  const fakeAdapter = {
+    label: 'hermes', backend: 'hermes', readSessionId: () => null,
+    ask: async (prompt, _signal, plan) => {
+      calls.askPrompt = prompt;
+      assert.equal(plan.label, 'hermes', 'plan label = agent label');
+      assert.equal(plan.task, true, 'plan.task=true for voice turn');
+      return 'twelve apples';
+    },
+  };
+  const deps = makeDeps({
+    transcribe: async wav => { calls.transcribe++; assert.equal(wav, '/tmp/u.wav'); return 'hermes do the thing'; },
+    sendText: async t => { calls.sendText.push(t); return true; },
+    speakText: async t => { calls.speakText.push(t); },
+    maybeNotifyTaskComplete: async ({ answer, label }) => { calls.notify.push({ answer, label }); },
+    // Force the runner's adapter lookup to return our test adapter rather
+    // than the router's auto-created one (the router builds a fresh adapter
+    // per backend via createBridgeAgentAdapter).
+    adapterForBackend: () => fakeAdapter,
+    adapterForProjectSession: () => fakeAdapter,
+  });
+  const { handleRecording } = createVoiceTurnRunner(deps);
+  assert.equal(deps.bridge.processing, false);
+  await handleRecording('user-1', '/tmp/u.wav', 8192, 1, null);
+  assert.equal(calls.transcribe, 1, 'transcribe called once');
+  assert.equal(calls.askPrompt, 'hermes do the thing', 'agent receives the post-wake prompt');
+  assert.deepEqual(calls.speakText.at(-1), 'twelve apples', 'agent answer is spoken');
+  assert.ok(calls.sendText.some(s => /you said: hermes do the thing/.test(s)), 'STT echoed');
+  assert.ok(calls.sendText.some(s => /twelve apples/.test(s)), 'agent answer surfaced as text');
+  assert.equal(calls.notify.length, 1, 'maybeNotifyTaskComplete fired once');
+  assert.equal(calls.notify[0].label, 'hermes', 'notify carries the agent label');
+  assert.equal(deps.bridge.processing, false, 'processing flag cleared in finally');
+  assert.equal(deps.bridge.activeTurnId, 0, 'activeTurnId cleared');
+  assert.equal(deps.bridge.activeProgressAbortController, null, 'progress controller cleared');
+});
+
+test('handleRecording cleans up progress controller even when agent throws', async () => {
+  const fakeAdapter = {
+    label: 'hermes', backend: 'hermes', readSessionId: () => null,
+    ask: async () => { throw new Error('agent boom'); },
+  };
+  const deps = makeDeps({
+    adapterForBackend: () => fakeAdapter,
+    adapterForProjectSession: () => fakeAdapter,
+  });
+  const { handleRecording } = createVoiceTurnRunner(deps);
+  let finishStatus = null;
+  let finishError = null;
+  const metricsTurn = { mark: () => {}, addMeta: () => {}, stage: () => {}, finish: r => { finishStatus = r.status; finishError = r.error; } };
+  await handleRecording('user-1', '/tmp/u.wav', 8192, 1, metricsTurn);
+  assert.equal(finishStatus, 'error');
+  assert.match(finishError || '', /agent boom/);
+  // Cleanup invariants — the bug Codex flagged on the original voice-path
+  // finally is now guarded by agentTurnLifecycle.finish, so we double-check.
+  assert.equal(deps.bridge.processing, false);
+  assert.equal(deps.bridge.activeProgressAbortController, null);
+  assert.equal(deps.bridge.currentAbortController, null);
+});
+
+test('handleRecording drops when bridge.processing is already true', async () => {
+  const deps = makeDeps();
+  deps.bridge.processing = true;
+  const { handleRecording } = createVoiceTurnRunner(deps);
+  let finishStatus = null;
+  const metricsTurn = { mark: () => {}, addMeta: () => {}, stage: () => {}, finish: r => { finishStatus = r.status; } };
+  await handleRecording('user-1', '/tmp/u.wav', 8192, 1, metricsTurn);
+  assert.equal(finishStatus, 'drop_processing');
+  assert.equal(deps.bridge.processing, true, 'processing flag left intact (other turn owns it)');
+});
+
+test('handleRecording rejects unauthorized users', async () => {
+  const deps = makeDeps({ isAllowed: () => false });
+  const { handleRecording } = createVoiceTurnRunner(deps);
+  let finishStatus = null;
+  const metricsTurn = { mark: () => {}, addMeta: () => {}, stage: () => {}, finish: r => { finishStatus = r.status; } };
+  await handleRecording('intruder', '/tmp/u.wav', 8192, 1, metricsTurn);
+  assert.equal(finishStatus, 'unauthorized');
+});
+
+test('handleRecording short-circuits on empty transcript', async () => {
+  const deps = makeDeps({ transcribe: async () => '' });
+  const { handleRecording } = createVoiceTurnRunner(deps);
+  let finishStatus = null;
+  const metricsTurn = { mark: () => {}, addMeta: () => {}, stage: () => {}, finish: r => { finishStatus = r.status; } };
+  await handleRecording('user-1', '/tmp/u.wav', 8192, 1, metricsTurn);
+  assert.equal(finishStatus, 'empty_transcript');
+  assert.equal(deps.bridge.processing, false, 'processing flag still cleaned up');
+});
+
+test('handleRecording short-circuits when wake word missing', async () => {
+  const sent = [];
+  const deps = makeDeps({
+    acceptsWake: () => false,
+    sendText: async t => { sent.push(t); return true; },
+  });
+  const { handleRecording } = createVoiceTurnRunner(deps);
+  let finishStatus = null;
+  const metricsTurn = { mark: () => {}, addMeta: () => {}, stage: () => {}, finish: r => { finishStatus = r.status; } };
+  await handleRecording('user-1', '/tmp/u.wav', 8192, 1, metricsTurn);
+  assert.equal(finishStatus, 'wake_rejected');
+  assert.ok(sent.some(t => /no wake word/.test(t)), 'wake-rejected message sent');
+});
+
+test('handleRecording with stale language reload aborts before transcribe', async () => {
+  let transcribed = false;
+  const deps = makeDeps({
+    reloadRuntimeLanguageFromEnv: () => ({ changed: true, voiceLanguage: 'en', whisperLanguage: 'en' }),
+    transcribe: async () => { transcribed = true; return 'hi'; },
+  });
+  const { handleRecording } = createVoiceTurnRunner(deps);
+  let finishStatus = null;
+  const metricsTurn = { mark: () => {}, addMeta: () => {}, stage: () => {}, finish: r => { finishStatus = r.status; } };
+  await handleRecording('user-1', '/tmp/u.wav', 8192, 1, metricsTurn);
+  assert.equal(transcribed, false, 'transcribe not called when language changed');
+  assert.equal(finishStatus, 'drop_stale_language_change');
+});

package/docs/CONFIGURATION.md

@@ -192,6 +192,8 @@ Remove `ports:` from that Compose service. On Docker Desktop for macOS/Windows,
 
 ## Optional TTS Backends
 
+For the full backend matrix, latency notes, aliases, and Mac mini caveats, see [TTS Backends](TTS_BACKENDS.md).
+
 Edge TTS remains the default and fallback. Optional local backends are configured with their own env vars:
 
 | Backend | Settings | Voice choices |
@@ -200,8 +202,16 @@ Edge TTS remains the default and fallback. Optional local backends are configure
 | Supertonic | `SUPERTONIC_VOICE`, `SUPERTONIC_LANGUAGE` | `M1`–`M5`, `F1`–`F5`; language `ko`, `en`, `es`, `pt`, `fr` |
 | OpenVoice | `OPENVOICE_REF_AUDIO`, `OPENVOICE_STYLE`, `OPENVOICE_LANGUAGE` | User-provided permitted reference WAV; style defaults to `default` |
 | SpeechSwift / CosyVoice | `SPEECHSWIFT_REF_AUDIO`, `SPEECHSWIFT_ENGINE`, `SPEECHSWIFT_SPEAKER`, `SPEECHSWIFT_MODEL_ID` | Reference-sample voices for CosyVoice, or backend-supported speaker/model IDs |
-
-Only clone voices you own or have permission to use. If a local backend fails or times out, VerbalCoding falls back to Edge TTS.
+| OmniVoice | `OMNIVOICE_PYTHON`, `OMNIVOICE_MODEL`, `OMNIVOICE_REF_AUDIO`, `OMNIVOICE_REF_TEXT`, `OMNIVOICE_LANGUAGE`, `OMNIVOICE_SPEAKER` | k2-fsa/OmniVoice reference-sample cloning or optional voice-design attributes |
+| Qwen3 TTS | `QWEN3TTS_COMMAND`, `QWEN3TTS_MODE`, `QWEN3TTS_MODEL`, `QWEN3TTS_SPEAKER` | Preset speaker such as `sohee`, reference mode, or designed speaker text |
+| MLX Audio | `MLXAUDIO_PYTHON`, `MLXAUDIO_MODEL`, `MLXAUDIO_VOICE`, `MLXAUDIO_LANG_CODE` | MLX Qwen3 voice/speaker IDs such as `Chelsie` |
+| NeuTTS Air | `NEUTTSAIR_PYTHON`, `NEUTTSAIR_BACKBONE_REPO`, `NEUTTSAIR_CODEC_REPO`, `NEUTTSAIR_REF_AUDIO`, `NEUTTSAIR_REF_TEXT` | English NeuTTS Air reference-sample cloning; use Q4 GGUF for lower latency |
+| FireRedTTS-2 | `FIREREDTTS2_COMMAND`, `FIREREDTTS2_PRETRAINED_DIR`, `FIREREDTTS2_PROMPT_AUDIO`, `FIREREDTTS2_PROMPT_TEXT` | Prompt-reference voice or random speaker |
+| FireRedTTS-2 MLX helper | `integrations/fireredtts2/synth_mlx.py` | Experimental Apple Silicon LLM-port helper; not a canonical `TTS_BACKEND` yet |
+| MOSS-TTS-Nano | `MOSSTTSNANO_COMMAND`, `MOSSTTSNANO_SCRIPT`, `MOSSTTSNANO_CHECKPOINT`, `MOSSTTSNANO_PROMPT_AUDIO` | OpenMOSS prompt reference or continuation mode |
+| MOSS-TTS-Nano MLX | `MOSSTTSNANO_MLX_PYTHON`, `MOSSTTSNANO_MLX_SCRIPT`, `MOSSTTSNANO_MLX_WORKER`, `MOSSTTSNANO_PROMPT_AUDIO` | Experimental MLX hybrid prompt reference or continuation mode |
+
+Only clone voices you own or have permission to use. For OmniVoice, install it in a separate Python environment such as `.venv-omnivoice` (`pip install torch torchaudio soundfile omnivoice`) and set `TTS_BACKEND=omnivoice`. For NeuTTS Air, install the local `neutts` package in `.venv-neuttsair`, set `TTS_BACKEND=neuttsair`, and keep progress prompts on Edge unless explicitly testing local progress TTS. If a local backend fails or times out, VerbalCoding falls back to Edge TTS.
 
 ## Operational Notes
 

package/docs/HARNESSES.md

@@ -0,0 +1,58 @@
+# Coding Agent Harnesses
+
+<p align="center">
+  <a href="../README.md">README</a> ·
+  <a href="README.md">Docs hub</a> ·
+  <a href="USAGE.md">Usage</a> ·
+  <a href="CONFIGURATION.md">Configuration</a> ·
+  <a href="TROUBLESHOOTING.md">Troubleshooting</a>
+</p>
+
+VerbalCoding is agent-agnostic. It drives whichever CLI coding agent you have installed by spawning it once per voice turn, feeding the transcript as a prompt, and speaking the response back. Pick **one** as your default; the cross-agent voice routing lets you reach the others mid-session.
+
+| Harness | Default command | Session resume | Per-harness doc |
+|---|---|---|---|
+| Hermes Agent | `hermes chat -Q -q` | ✅ (`--resume <id>`) | [HERMES_VOICE.md](./HERMES_VOICE.md) (positioning) + [HARNESS_HERMES.md](./HARNESS_HERMES.md) |
+| Claude Code | `claude -p` | ❌ | [HARNESS_CLAUDE.md](./HARNESS_CLAUDE.md) |
+| Codex | `codex exec` | ❌ (output-last-message capture) | [HARNESS_CODEX.md](./HARNESS_CODEX.md) |
+| Gemini CLI | `gemini -p` | ❌ | [HARNESS_GEMINI.md](./HARNESS_GEMINI.md) |
+| OpenCode | `opencode run` | ❌ | [HARNESS_OPENCODE.md](./HARNESS_OPENCODE.md) |
+| OpenClaw | `openclaw run` | ❌ | [HARNESS_OPENCLAW.md](./HARNESS_OPENCLAW.md) |
+| Aider | `aider --no-pretty --yes-always --message` | ❌ | [HARNESS_AIDER.md](./HARNESS_AIDER.md) |
+| Cursor CLI | `cursor-agent --print --prompt` | ❌ | [HARNESS_CURSOR.md](./HARNESS_CURSOR.md) |
+
+## Pick your default
+
+`vc setup` auto-detects installed binaries and lets you pick. Non-interactive override:
+
+```bash
+# .env or instance .env
+AGENT_BACKEND=claude              # hermes | claude | codex | gemini | opencode | openclaw | aider | cursor | custom
+```
+
+Each harness picks up its own command from a matching env var (`HERMES_COMMAND`, `CLAUDE_COMMAND`, etc.). The shared envs `AGENT_LABEL`, `AGENT_COMMAND`, `AGENT_SESSION_FILE`, `AGENT_WORKDIR`, `AGENT_PROJECT_CONTEXT`, `AGENT_TASK_TIMEOUT_MS`, `AGENT_CHAT_TIMEOUT_MS`, `AGENT_VERBOSE_PROGRESS` override per-harness defaults when set.
+
+## Routing between harnesses by voice
+
+Once configured, you can reach any **installed** harness from a voice channel without restarting:
+
+- `"ask Codex what it thinks"` — single-turn route, next utterance returns to the default.
+- `"switch to Aider"` — sticky route until you say `"back to default"`.
+- Plan-mode `which_agent` slot — the agent itself proposes which backend runs the next plan.
+
+The routing layer detects whether the binary is on `PATH` (resolving relative commands against the active project session's workdir). If not installed, the bridge asks `"Want me to use the default agent instead?"` — answer `"yes"` to fall back or `"no"` to cancel.
+
+Aliases recognized by the parser: `claude` / `claude code`, `codex` / `코덱스`, `gemini` / `gemini cli` / `제미나이`, `opencode`, `openclaw`, `aider` / `에이더`, `cursor` / `cursor cli`, `hermes` / `헤르메스`.
+
+## Shared semantics
+
+Things every harness adapter respects:
+
+- **Voice plan mode** — `"plan it first"` → narrate a plan; edit by voice; `"approve"` to execute against the chosen harness.
+- **Barge-in** — interrupting cuts the current TTS and aborts the agent task. Sticky routing survives interrupts; only single-turn routes are cleared.
+- **Verbose progress** — `AGENT_VERBOSE_PROGRESS=1` (or `"상세 진행 켜"`) prints structured progress events the harness emits (file reads, web search, tool use). Smart-progress, if `SMART_PROGRESS_API_KEY` is set, summarizes these into one sentence per batch.
+- **Push handoff** — `NOTIFY_PROVIDER=ntfy|pushover` plus `NOTIFY_MIN_TASK_MS` fires a push notification when a long task completes and the voice channel is empty. Debounced by body + `NOTIFY_DEBOUNCE_MS`.
+- **Per-channel state** — each Discord voice channel keeps its own routing, plan-mode, and recent-utterance ring buffer.
+- **Project sessions** — `!session new <name> <workdir>` binds a Discord channel to a project; per-(harness, session) adapters are cached and invalidated on rebind.
+
+See per-harness docs for install paths, auth, and gotchas. `docs/CONFIGURATION.md` is the canonical env-var reference.

package/docs/HARNESS_AIDER.md

@@ -0,0 +1,50 @@
+# Aider — Harness Notes
+
+<p align="center">
+  <a href="../README.md">README</a> ·
+  <a href="HARNESSES.md">Harnesses</a> ·
+  <a href="USAGE.md">Usage</a> ·
+  <a href="CONFIGURATION.md">Configuration</a>
+</p>
+
+Aider is a pair-programming AI CLI focused on direct edits. VerbalCoding drives it through `aider --no-pretty --yes-always --message` — the prompt is passed as the `--message` value so each voice turn becomes one non-interactive Aider run that may modify files in `AGENT_WORKDIR`.
+
+## Install
+
+```bash
+pip install aider-chat
+aider --version
+# Confirm a single-message run works:
+aider --no-pretty --yes-always --message "list the top-level files"
+```
+
+Aider needs an API key for the model you point it at (OpenAI / Anthropic / a local server). See <https://aider.chat>.
+
+## Configure VerbalCoding
+
+```bash
+# .env
+AGENT_BACKEND=aider
+# optional
+AIDER_COMMAND="aider --no-pretty --yes-always --message"   # default
+AGENT_WORKDIR=/Users/you/code/your-project                 # where Aider should edit
+AGENT_PROJECT_CONTEXT="..."
+AGENT_CHAT_TIMEOUT_MS=120000                               # Aider can take longer
+AGENT_TASK_TIMEOUT_MS=0
+```
+
+`--no-pretty` strips Rich-formatting box characters so the stream sentencer doesn't choke on them. `--yes-always` keeps the run non-interactive (Aider won't pause for "apply this diff?" prompts).
+
+## Voice phrases to switch TO Aider
+
+- en: `"switch to Aider"`, `"ask Aider to ..."`
+- ko: `"aider로 전환해줘"`, `"에이더로 전환"`
+
+The matcher accepts `aider` and `에이더`.
+
+## Gotchas
+
+- **Aider edits files.** Unlike Claude / Codex / Gemini under `-p`, Aider directly modifies the working tree as part of answering. Be deliberate about `AGENT_WORKDIR` — usually a project session's `workdir`.
+- **Diffs in output.** Aider often emits diff-shaped text. If a turn is interrupted, the bridge speaks an "interrupted" notice and skips reading the diff aloud — check the text channel and `git status`.
+- **Auth.** `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` need to be in Aider's environment; instance-isolated installs typically use `instances/<project>.env`.
+- **Per-channel state.** Cross-agent routing is per Discord channel; switching to Aider in one project room does not affect another.

package/docs/HARNESS_CLAUDE.md

@@ -0,0 +1,56 @@
+# Claude Code — Harness Notes
+
+<p align="center">
+  <a href="../README.md">README</a> ·
+  <a href="HARNESSES.md">Harnesses</a> ·
+  <a href="USAGE.md">Usage</a> ·
+  <a href="CONFIGURATION.md">Configuration</a>
+</p>
+
+Claude Code is Anthropic's official terminal-resident coding agent. VerbalCoding drives it through `claude -p`, where each voice turn is one invocation. Claude Code does not expose a stable session-resume contract over `-p`, so each call is a fresh context — use `AGENT_PROJECT_CONTEXT` and the cross-agent handoff block to keep continuity.
+
+## Install
+
+```bash
+npm install -g @anthropic-ai/claude-code
+claude login
+claude -p "hello"     # confirm it answers
+```
+
+## Configure VerbalCoding
+
+```bash
+# .env
+AGENT_BACKEND=claude              # alias 'claude-code' also accepted
+# optional
+CLAUDE_COMMAND="claude -p"        # default; override e.g. to add --model, --debug
+AGENT_PROJECT_CONTEXT="Working on the auth module; previous decisions: oauth=github."
+AGENT_WORKDIR=/Users/you/code/your-project
+AGENT_CHAT_TIMEOUT_MS=45000
+AGENT_TASK_TIMEOUT_MS=0
+AGENT_VERBOSE_PROGRESS=0
+```
+
+`AGENT_SESSION_FILE` defaults to `<repo>/.agent-sessions/claude` but is **unused** by this harness — Claude Code's `-p` is stateless. Leave it set; it just becomes a no-op.
+
+## What Claude sees per turn
+
+Every turn the adapter prepends a Discord-aware preamble (English or Korean depending on `VOICE_LANGUAGE`), the project context, recent Discord text context, and finally the user's transcribed utterance. On cross-agent handoff (e.g. you said `"ask Codex ..."` last turn and just spoke again), the prepended block also includes a "Recent user voice" line of up to the last 4 utterances plus the most recently resolved plan decisions, so Claude doesn't start cold.
+
+## Verbose progress
+
+Claude Code does not emit a standard progress stream over `-p`. `AGENT_VERBOSE_PROGRESS=1` still works — the adapter parses tool/file/web mentions out of stdout/stderr if Claude prints them — but expect coarser progress than Hermes.
+
+## Voice phrases to switch TO Claude Code
+
+- en: `"switch to Claude Code"`, `"ask Claude ..."`, `"let Claude finish this"`
+- ko: `"클로드로 전환"`, `"claude한테 물어봐"`
+
+The matcher accepts both `claude` and `claude code` as aliases; strict mode (used for routing-only utterances) requires an exact alias.
+
+## Gotchas
+
+- **No session resume.** A long-running pair-programming session needs the cross-agent handoff context block to carry decisions forward. The bridge does this automatically on backend changes; within the same backend, set `AGENT_PROJECT_CONTEXT` to a short summary.
+- **Quoted command paths.** If `CLAUDE_COMMAND` uses a quoted absolute path (e.g. `"/Applications/Claude Code/claude" -p`), VerbalCoding's installation probe uses `shellSplit` and honors quotes correctly.
+- **Auth refresh.** `claude login` token expiry surfaces as a non-zero exit; the bridge reports the failure and (if a non-default backend) the fallback prompt will offer to retry on the default.
+- **Patch-like output.** If Claude returns a diff and the turn is interrupted, the bridge says `"the agent was interrupted; check the text channel for files and tests"` rather than reading the diff aloud.

package/docs/HARNESS_CODEX.md

@@ -0,0 +1,56 @@
+# Codex — Harness Notes
+
+<p align="center">
+  <a href="../README.md">README</a> ·
+  <a href="HARNESSES.md">Harnesses</a> ·
+  <a href="USAGE.md">Usage</a> ·
+  <a href="CONFIGURATION.md">Configuration</a>
+</p>
+
+Codex CLI is OpenAI's terminal coding agent. VerbalCoding drives it through `codex exec`. Because `codex exec` writes its final assistant text to a temp file when `--output-last-message <path>` is passed, the adapter inserts that flag automatically and reads the file back even if stdout is noisy.
+
+## Install
+
+```bash
+npm install -g @openai/codex
+codex login              # or set OPENAI_API_KEY for headless use
+codex exec "hello"
+```
+
+## Configure VerbalCoding
+
+```bash
+# .env
+AGENT_BACKEND=codex
+# optional
+CODEX_COMMAND="codex exec"                      # default
+AGENT_PROJECT_CONTEXT="What we're working on, what's already decided."
+AGENT_WORKDIR=/Users/you/code/your-project
+AGENT_CHAT_TIMEOUT_MS=45000
+AGENT_TASK_TIMEOUT_MS=0
+```
+
+`AGENT_SESSION_FILE` is unused (Codex `exec` is stateless across calls).
+
+## Output capture
+
+For Codex, the adapter:
+
+1. Generates a temp path under `os.tmpdir()` like `verbalcoding-codex-last-<pid>-<ts>.txt`.
+2. Inserts `--output-last-message <path>` immediately before the final positional prompt arg.
+3. After the run, reads that file as the authoritative answer (preferred over `stdout`).
+4. Deletes the temp file.
+
+This is robust to Codex emitting tool-use chatter on stdout; the spoken answer always comes from the captured file.
+
+## Voice phrases to switch TO Codex
+
+- en: `"switch to Codex"`, `"ask Codex what it thinks"`
+- ko: `"코덱스로 전환"`, `"코덱스한테 물어봐"`
+
+## Gotchas
+
+- **Long tasks.** Set `AGENT_TASK_TIMEOUT_MS=0` for codegen runs that may take minutes. The adapter respects `signal.aborted` so barge-in still cuts cleanly.
+- **No session resume.** Pass context via `AGENT_PROJECT_CONTEXT` and rely on the cross-agent handoff block for continuity after a route change.
+- **Patch-like output safety.** If a turn is interrupted and Codex was mid-diff, the bridge does **not** read the diff aloud — it speaks an "interrupted" notice and asks you to check the text channel.
+- **Auth.** A 401 from the OpenAI backend surfaces as a non-zero exit; the bridge reports the failure and the cross-agent fallback prompt offers the default agent.

package/docs/HARNESS_CURSOR.md

@@ -0,0 +1,45 @@
+# Cursor CLI — Harness Notes
+
+<p align="center">
+  <a href="../README.md">README</a> ·
+  <a href="HARNESSES.md">Harnesses</a> ·
+  <a href="USAGE.md">Usage</a> ·
+  <a href="CONFIGURATION.md">Configuration</a>
+</p>
+
+Cursor CLI (`cursor-agent`) is Cursor's terminal agent. VerbalCoding drives it through `cursor-agent --print --prompt`, passing the user's transcribed utterance as the prompt value. `--print` keeps the run non-interactive.
+
+## Install
+
+Follow the upstream Cursor CLI install. Confirm:
+
+```bash
+cursor-agent --print --prompt "hello"
+```
+
+## Configure VerbalCoding
+
+```bash
+# .env
+AGENT_BACKEND=cursor                                       # alias 'cursor-cli' also accepted
+# optional
+CURSOR_COMMAND="cursor-agent --print --prompt"             # default
+AGENT_PROJECT_CONTEXT="..."
+AGENT_WORKDIR=/Users/you/code/your-project
+AGENT_CHAT_TIMEOUT_MS=45000
+AGENT_TASK_TIMEOUT_MS=0
+```
+
+## Voice phrases to switch TO Cursor
+
+- en: `"switch to Cursor"`, `"ask Cursor ..."`, `"switch to cursor cli"`, `"switch to cursor agent"`
+- ko: `"커서로 전환"`, `"cursor한테 물어봐"`
+
+The matcher accepts `cursor`, `cursor cli`, `cursor-cli`, `cursor agent`, and `cursor-agent`.
+
+## Gotchas
+
+- **Prompt placement.** `--prompt` expects the value to follow; VerbalCoding's shell-aware argv builder places the transcribed utterance as the final positional argument, so `CURSOR_COMMAND` must end with `--prompt`.
+- **Editor side-effects.** Cursor's CLI may touch local cursor-related state files in the working directory; if that's surprising for a voice-only flow, point `AGENT_WORKDIR` at an isolated project dir.
+- **No session resume.** Use `AGENT_PROJECT_CONTEXT` for cross-turn continuity, plus the cross-agent handoff block when routing back from a different harness.
+- **Patch safety.** If Cursor returns a diff and the turn is interrupted, the bridge does not read the diff aloud.

package/docs/HARNESS_GEMINI.md

@@ -0,0 +1,45 @@
+# Gemini CLI — Harness Notes
+
+<p align="center">
+  <a href="../README.md">README</a> ·
+  <a href="HARNESSES.md">Harnesses</a> ·
+  <a href="USAGE.md">Usage</a> ·
+  <a href="CONFIGURATION.md">Configuration</a>
+</p>
+
+Gemini CLI is Google's terminal coding agent. VerbalCoding drives it through `gemini -p`. Each voice turn is one invocation; there is no built-in session-resume across calls.
+
+## Install
+
+Follow the upstream Gemini CLI install guide. Confirm:
+
+```bash
+gemini -p "hello"
+```
+
+## Configure VerbalCoding
+
+```bash
+# .env
+AGENT_BACKEND=gemini
+# optional
+GEMINI_COMMAND="gemini -p"                  # default; add --model, --debug as needed
+AGENT_PROJECT_CONTEXT="..."
+AGENT_WORKDIR=/Users/you/code/your-project
+AGENT_CHAT_TIMEOUT_MS=45000
+AGENT_TASK_TIMEOUT_MS=0
+```
+
+## Voice phrases to switch TO Gemini
+
+- en: `"switch to Gemini"`, `"ask Gemini ..."`, `"switch to Gemini CLI"`
+- ko: `"제미나이로 전환"`, `"gemini한테 물어봐"`
+
+The matcher accepts `gemini`, `gemini cli`, `gemini-cli`, and `제미나이`.
+
+## Gotchas
+
+- **No session resume.** Same continuity story as Claude / Codex: rely on `AGENT_PROJECT_CONTEXT` and the cross-agent handoff block.
+- **Long answers.** Gemini sometimes returns large structured responses; the stream sentencer splits them into TTS-able sentences. Code fences are stripped from speech (the text channel still gets the full answer with code).
+- **API key.** If Gemini exits non-zero with an auth error, the bridge reports the message; the cross-agent fallback prompt offers the default agent if Gemini was a non-default route.
+- **Verbose progress.** Gemini's stdout doesn't follow Hermes' `┊`-style preview format, so verbose progress mostly relies on the smart-progress LLM summarizer.