verbalcoding 0.2.11 → 0.2.12

package/app-node/stream_sentencer.mjs

@@ -0,0 +1,61 @@
+import { EventEmitter } from 'node:events';
+
+const ANSI_RE = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
+const BOX_RE = /[╭╮╰╯│┊─]/g;
+const PROGRESS_LINE_RE = /^VERBALCODING_PROGRESS\s*:.*$/i;
+const TERMINAL_RE = /[.!?。！？…]+(?=[\s"'\)\]\}]|$)/;
+
+function clean(text) {
+  return String(text || '')
+    .replace(ANSI_RE, '')
+    .split(/\r?\n/)
+    .filter(line => !PROGRESS_LINE_RE.test(line.trim()))
+    .join('\n')
+    .replace(BOX_RE, '')
+    .replace(/[ \t]+/g, ' ');
+}
+
+export function createSentencer({ minChars = 40, maxLatencyMs = 800 } = {}) {
+  const ee = new EventEmitter();
+  let buffer = '';
+  let lastEmit = Date.now();
+
+  function emit(text) {
+    const trimmed = String(text || '').trim();
+    if (!trimmed) return;
+    ee.emit('sentence', trimmed);
+    lastEmit = Date.now();
+  }
+
+  function scan() {
+    while (true) {
+      const match = buffer.match(TERMINAL_RE);
+      if (!match) break;
+      const end = match.index + match[0].length;
+      const sentence = buffer.slice(0, end);
+      buffer = buffer.slice(end).replace(/^\s+/, '');
+      emit(sentence);
+    }
+    if (buffer.length >= minChars && Date.now() - lastEmit >= maxLatencyMs) {
+      const cut = buffer.lastIndexOf(' ');
+      if (cut > Math.floor(minChars / 2)) {
+        emit(buffer.slice(0, cut));
+        buffer = buffer.slice(cut).trim();
+      }
+    }
+  }
+
+  return {
+    on: (event, fn) => ee.on(event, fn),
+    push(text) {
+      const cleaned = clean(text);
+      if (!cleaned) return;
+      buffer += cleaned;
+      scan();
+    },
+    flush() {
+      emit(buffer);
+      buffer = '';
+    },
+  };
+}

package/app-node/stream_sentencer.test.mjs

@@ -0,0 +1,64 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createSentencer } from './stream_sentencer.mjs';
+
+test('emits a sentence on terminal punctuation', () => {
+  const out = [];
+  const s = createSentencer({ minChars: 1, maxLatencyMs: 999999 });
+  s.on('sentence', t => out.push(t));
+  s.push('Hello world. ');
+  assert.deepEqual(out, ['Hello world.']);
+});
+
+test('does not emit on partial sentence', () => {
+  const out = [];
+  const s = createSentencer({ minChars: 1, maxLatencyMs: 999999 });
+  s.on('sentence', t => out.push(t));
+  s.push('Reading file');
+  assert.deepEqual(out, []);
+  s.push(' main.mjs.');
+  assert.deepEqual(out, ['Reading file main.mjs.']);
+});
+
+test('strips ANSI before emitting', () => {
+  const out = [];
+  const s = createSentencer({ minChars: 1, maxLatencyMs: 999999 });
+  s.on('sentence', t => out.push(t));
+  s.push('\x1b[32mDone.\x1b[0m ');
+  assert.deepEqual(out, ['Done.']);
+});
+
+test('filters VERBALCODING_PROGRESS lines', () => {
+  const out = [];
+  const s = createSentencer({ minChars: 1, maxLatencyMs: 999999 });
+  s.on('sentence', t => out.push(t));
+  s.push('VERBALCODING_PROGRESS: reading files main.mjs\nAll set.');
+  s.flush();
+  assert.deepEqual(out, ['All set.']);
+});
+
+test('flush emits residual on close', () => {
+  const out = [];
+  const s = createSentencer({ minChars: 1, maxLatencyMs: 999999 });
+  s.on('sentence', t => out.push(t));
+  s.push('No terminator here');
+  s.flush();
+  assert.deepEqual(out, ['No terminator here']);
+});
+
+test('strips Hermes box characters', () => {
+  const out = [];
+  const s = createSentencer({ minChars: 1, maxLatencyMs: 999999 });
+  s.on('sentence', t => out.push(t));
+  s.push('│ Done.');
+  s.flush();
+  assert.deepEqual(out, ['Done.']);
+});
+
+test('emits multiple sentences in one push', () => {
+  const out = [];
+  const s = createSentencer({ minChars: 1, maxLatencyMs: 999999 });
+  s.on('sentence', t => out.push(t));
+  s.push('First. Second. Third.');
+  assert.deepEqual(out, ['First.', 'Second.', 'Third.']);
+});

package/app-node/streaming_tts_queue.mjs

@@ -0,0 +1,48 @@
+export function createStreamingTTSQueue({ synth, play, signal, cleanup, log = () => {} } = {}) {
+  if (typeof synth !== 'function') throw new Error('synth is required');
+  if (typeof play !== 'function') throw new Error('play is required');
+
+  const queue = [];
+  let pumping = null;
+
+  async function pump() {
+    while (queue.length && !signal?.aborted) {
+      const text = queue.shift();
+      let file;
+      try {
+        file = await synth(text);
+      } catch (e) {
+        log('streaming tts synth failed', e?.message || e);
+        continue;
+      }
+      if (!file) continue;
+      if (signal?.aborted) {
+        try { await cleanup?.(file); } catch {}
+        return;
+      }
+      try {
+        await play(file);
+      } catch (e) {
+        if (signal?.aborted) {
+          try { await cleanup?.(file); } catch {}
+          return;
+        }
+        log('streaming tts play failed', e?.message || e);
+      }
+      try { await cleanup?.(file); } catch {}
+    }
+  }
+
+  return {
+    enqueue(text) {
+      const trimmed = String(text || '').trim();
+      if (!trimmed || signal?.aborted) return;
+      queue.push(trimmed);
+      if (!pumping) pumping = pump().finally(() => { pumping = null; });
+    },
+    async drain() {
+      while (pumping) await pumping;
+    },
+    get size() { return queue.length; },
+  };
+}

package/app-node/streaming_tts_queue.test.mjs

@@ -0,0 +1,58 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createStreamingTTSQueue } from './streaming_tts_queue.mjs';
+
+test('synths and plays in enqueue order', async () => {
+  const order = [];
+  const q = createStreamingTTSQueue({
+    synth: async (t) => { order.push(`synth:${t}`); return `f-${t}`; },
+    play: async (f) => { order.push(`play:${f}`); },
+  });
+  q.enqueue('A.');
+  q.enqueue('B.');
+  await q.drain();
+  assert.deepEqual(order, ['synth:A.', 'play:f-A.', 'synth:B.', 'play:f-B.']);
+});
+
+test('abort stops further playback', async () => {
+  const ctrl = new AbortController();
+  const order = [];
+  const q = createStreamingTTSQueue({
+    synth: async (t) => `f-${t}`,
+    play: async (f) => { order.push(`play:${f}`); if (f === 'f-A.') ctrl.abort(); },
+    signal: ctrl.signal,
+  });
+  q.enqueue('A.');
+  q.enqueue('B.');
+  await q.drain();
+  assert.deepEqual(order, ['play:f-A.']);
+});
+
+test('cleanup runs after play', async () => {
+  const cleaned = [];
+  const q = createStreamingTTSQueue({
+    synth: async (t) => `f-${t}`,
+    play: async () => {},
+    cleanup: async (f) => { cleaned.push(f); },
+  });
+  q.enqueue('A.');
+  await q.drain();
+  assert.deepEqual(cleaned, ['f-A.']);
+});
+
+test('synth error skips that sentence but continues', async () => {
+  const played = [];
+  const q = createStreamingTTSQueue({
+    synth: async (t) => { if (t === 'A.') throw new Error('boom'); return `f-${t}`; },
+    play: async (f) => { played.push(f); },
+  });
+  q.enqueue('A.');
+  q.enqueue('B.');
+  await q.drain();
+  assert.deepEqual(played, ['f-B.']);
+});
+
+test('throws when synth or play missing', () => {
+  assert.throws(() => createStreamingTTSQueue({ play: async () => {} }), /synth is required/);
+  assert.throws(() => createStreamingTTSQueue({ synth: async () => {} }), /play is required/);
+});

package/app-node/text_routing.mjs

@@ -6,3 +6,23 @@ export function shouldRouteDiscordTextToAgent({ content = '', channelId = '', tr
   if (!target) return true;
   return String(channelId || '') === target;
 }
+
+export function appendRecentDiscordText(state, { channelId = '', authorLabel = 'user', content = '', now = Date.now(), maxEntries = 12 } = {}) {
+  const id = String(channelId || '').trim();
+  const text = String(content || '').trim();
+  if (!id || !text || text.startsWith('!')) return;
+  const entries = state.get(id) || [];
+  entries.push({ at: Number(now) || Date.now(), authorLabel: String(authorLabel || 'user'), content: text.slice(0, 500) });
+  state.set(id, entries.slice(-maxEntries));
+}
+
+export function formatRecentDiscordContext(state, { channelId = '', now = Date.now(), maxAgeMs = 10 * 60 * 1000, maxEntries = 6 } = {}) {
+  const id = String(channelId || '').trim();
+  if (!id) return '';
+  const cutoff = (Number(now) || Date.now()) - maxAgeMs;
+  const entries = (state.get(id) || [])
+    .filter(entry => Number(entry.at) >= cutoff)
+    .slice(-maxEntries);
+  if (!entries.length) return '';
+  return ['최근 텍스트 채널 메시지:', ...entries.map(entry => `- ${entry.authorLabel}: ${entry.content}`)].join('\n');
+}

package/app-node/text_routing.test.mjs

@@ -1,7 +1,11 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 
-import { shouldRouteDiscordTextToAgent } from './text_routing.mjs';
+import {
+  appendRecentDiscordText,
+  formatRecentDiscordContext,
+  shouldRouteDiscordTextToAgent,
+} from './text_routing.mjs';
 
 test('routes normal transcript-channel text to the shared agent session', () => {
   assert.equal(shouldRouteDiscordTextToAgent({
@@ -16,3 +20,21 @@ test('does not route commands or other channels to the shared agent session', ()
   assert.equal(shouldRouteDiscordTextToAgent({ content: '다른 채널 말', channelId: 'other', transcriptChannelId: 'transcript' }), false);
   assert.equal(shouldRouteDiscordTextToAgent({ content: '   ', channelId: 'transcript', transcriptChannelId: 'transcript' }), false);
 });
+
+test('formats recent Discord text context for voice turns without commands', () => {
+  const state = new Map();
+  appendRecentDiscordText(state, { channelId: 'thread', authorLabel: 'user', content: '음성채널에서만 나가줘', now: 1000 });
+  appendRecentDiscordText(state, { channelId: 'thread', authorLabel: 'user', content: '!ping', now: 1100 });
+  appendRecentDiscordText(state, { channelId: 'thread', authorLabel: 'assistant', content: '알겠어', now: 1200 });
+
+  const context = formatRecentDiscordContext(state, {
+    channelId: 'thread',
+    now: 2000,
+    maxAgeMs: 5000,
+  });
+
+  assert.match(context, /최근 텍스트 채널 메시지/);
+  assert.match(context, /user: 음성채널에서만 나가줘/);
+  assert.doesNotMatch(context, /!ping/);
+  assert.match(context, /assistant: 알겠어/);
+});

package/docs/CONFIGURATION.md

@@ -1,32 +1,70 @@
 # VerbalCoding Configuration
 
-## Setup Wizard
+<!-- readme-glow-up:intro -->
+<p align="center">
+  <a href="../README.md">README</a> ·
+  <a href="README.md">Docs hub</a> ·
+  <a href="FRESH_INSTALL.md">Fresh Install</a> ·
+  <a href="USAGE.md">Usage</a> ·
+  <a href="CONFIGURATION.md">Configuration</a> ·
+  <a href="TROUBLESHOOTING.md">Troubleshooting</a> ·
+  <a href="MULTI_INSTANCE.md">Multi-Instance</a>
+</p>
+
+> Settings reference for Discord, agents, TTS, MCP, and runtime behavior.
+>
+> Fast path: `vc setup handles normal config; edit .env only for advanced overrides`
+<!-- /readme-glow-up:intro -->
+
+## Setup Command Map
+
+For npm/global installs, use `vc` commands instead of manually editing `.env`:
 
-Discord bot/application setup is intentionally not re-explained from scratch here. Use these upstream guides for the Discord-side steps, then return to VerbalCoding setup:
+```bash
+vc setup                               # guided setup: prerequisites, Discord token, voice channels
+vc setup --yes                         # non-interactive bootstrap/starter config
+vc setup token                         # later update Discord bot token
+vc setup channels "General,Team Voice" # later update auto-join voice channel names
+vc setup channel "General"             # alias
+vc setup voice "General"               # alias
+vc doctor                               # redacted health check and supported auto-fixes
+vc start                                # run the default bridge
+```
 
-- Hermes Agent Discord messaging guide: <https://hermes-agent.nousresearch.com/docs/user-guide/messaging/discord>
-- Discord official bot overview: <https://docs.discord.com/developers/bots/overview>
-- Discord official quick start: <https://docs.discord.com/developers/quick-start/getting-started>
+Clone-only setup remains available:
 
 ```bash
-./scripts/install.sh
+./scripts/install.sh --yes
 ```
 
-The installer asks for Discord token, allowed users, auto-join voice channel names, transcript channel/thread, CLI harness backend, default voice language, TTS settings, and wake-word behavior. It writes `.env` with mode `0600`; `.env` is ignored by git. It also links the short shell command `vc`.
+`vc setup token` updates `DISCORD_BOT_TOKEN` and optional `DISCORD_CLIENT_ID`. `vc setup channels` updates `AUTO_JOIN_VOICE_CHANNELS`. Both preserve unrelated `.env` values, write the file with mode `0600`, and avoid printing token values.
+
+## Discord Bot/Application Setup
+
+Use these upstream guides for the Discord-side steps, then return to VerbalCoding setup:
 
-If you only need the shell command after manual install:
+- Hermes Agent Discord messaging guide: <https://hermes-agent.nousresearch.com/docs/user-guide/messaging/discord>
+- Discord official bot overview: <https://docs.discord.com/developers/bots/overview>
+- Discord official quick start: <https://docs.discord.com/developers/quick-start/getting-started>
+
+Minimum flow:
 
 ```bash
-npm link
+vc bot invite <discord-client-id>
+vc setup token <bot-token> --client-id <discord-client-id>
+vc setup channels "VerbalCoding,General"
+vc doctor
 ```
 
+The bot needs Message Content privileged intent plus text/voice permissions for the target channels.
+
 ## Supported Agent Backends
 
 Set `AGENT_BACKEND` in `.env`.
 
 | Backend | Default command | Notes |
 |---|---|---|
-| `hermes` | `hermes chat -Q -q` | Default. Preserves `.verbalcoding-session` resume behavior. |
+| `hermes` | `hermes chat -Q -q` | Default. Preserves `.verbalcoding-session` resume behavior. `vc doctor` can auto-install the Hermes CLI on supported macOS/Linux installs. |
 | `claude-code` / `claude` | `claude -p` | Override with `CLAUDE_COMMAND` or `AGENT_COMMAND`. |
 | `codex` | `codex exec` | Override with `CODEX_COMMAND` or `AGENT_COMMAND`. |
 | `gemini` | `gemini -p` | Override with `GEMINI_COMMAND` or `AGENT_COMMAND`. |
@@ -62,8 +100,9 @@ New backends should implement the same contract and keep voice/STT/TTS behavior
 
 ```bash
 DISCORD_BOT_TOKEN="***"
+DISCORD_CLIENT_ID="123456789012345678"
 DISCORD_ALLOWED_USERS="123456789012345678"
-AUTO_JOIN_VOICE_CHANNELS="일반,General,general"
+AUTO_JOIN_VOICE_CHANNELS="VerbalCoding,General"
 TRANSCRIPT_CHANNEL_ID="123456789012345678"
 
 AGENT_BACKEND="hermes"
@@ -95,9 +134,7 @@ Language presets and voice selection are separate:
 - Live voice commands such as “남자 한국어 목소리로 바꿔”, “여자 한국어 목소리로 바꿔”, `change voice to Korean female`, and `switch speaker to English` change only the speaker/voice type.
 - `!voice-test <text>` plays a quick sample with the currently selected backend and voice.
 
-Voice selection is stored in `config/tts-voices.json` by default. Override the path with `TTS_VOICE_CONFIG`. The running bridge re-reads/applies voice selection before synthesis, so voice commands take effect without a full restart.
-
-Default Edge catalog:
+Voice selection is stored in `config/tts-voices.json` by default. Override the path with `TTS_VOICE_CONFIG`.
 
 | `TTS_VOICE_TYPE` | `TTS_VOICE` | Language |
 |---|---|---|
@@ -107,29 +144,9 @@ Default Edge catalog:
 | `english_male` | `en-US-GuyNeural` | English |
 | `english_female` | `en-US-AriaNeural` | English |
 
-Manual persistent override:
-
-```bash
-TTS_BACKEND="edge"
-TTS_VOICE_TYPE="korean_male"
-TTS_VOICE="ko-KR-InJoonNeural"
-TTS_VOICE_CONFIG="config/tts-voices.json"
-```
-
-For OpenVoice, SpeechSwift, or Supertonic, keep the backend-specific voice/reference settings in the sections below; the same voice catalog file can still track the active voice type.
-
-Backend-specific voice options:
-
-| Backend | Settings | Voice choices |
-|---|---|---|
-| Edge | `TTS_VOICE_TYPE`, `TTS_VOICE` | Built-in types above, plus any voice returned by `edge-tts --list-voices` |
-| 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 |
-
 ## Utterance Segmentation
 
-`UTTERANCE_IDLE_MS` controls how long the bridge waits after a speech segment before it decides the user is done and starts STT. The default is `4500` ms to preserve longer spoken instructions with natural pauses. Lower values feel faster for short commands but can split long dictation; higher values are safer for thoughtful speech.
+`UTTERANCE_IDLE_MS` controls how long the bridge waits after a speech segment before it decides the user is done and starts STT.
 
 ```bash
 UTTERANCE_IDLE_MS="4500"  # balanced default
@@ -138,7 +155,7 @@ UTTERANCE_IDLE_MS="6000"  # safer for long dictation with pauses
 
 ## MCP Server
 
-VerbalCoding ships a stdio MCP server so Hermes Agent or any MCP client can control the bridge through tools instead of relying on skills or free-form shell commands.
+VerbalCoding ships a stdio MCP server so Hermes Agent or any MCP client can control the bridge through tools.
 
 Hermes config example:
 
@@ -161,74 +178,30 @@ Exposed MCP tools:
 | `set_language` | Update STT/progress/TTS language together |
 | `start`, `stop`, `restart` | Control the Discord voice bridge |
 
-## Optional OpenVoice TTS
+## Docker / Container Networking
 
-Edge TTS remains the default and fallback. To try local voice cloning with OpenVoice V2:
+Discord voice needs outbound UDP. If Docker logs show `Cannot perform IP discovery - socket closed`, try Linux host networking:
 
-```bash
-./scripts/setup_openvoice.sh
-# Download checkpoints_v2_0417.zip from OpenVoice docs and extract under vendor/OpenVoice/checkpoints_v2/
-mkdir -p voice-samples
-# Put a permitted reference sample at voice-samples/user-reference.wav,
-# or capture one from Discord with !voice-clone capture.
-python3 integrations/openvoice/synth.py --openvoice-dir vendor/OpenVoice --ref-audio voice-samples/user-reference.wav --text '안녕하세요. 버벌코딩 목소리 복제 테스트입니다.' --output /tmp/verbalcoding-openvoice-smoke.wav
-```
-
-Then set:
-
-```bash
-TTS_BACKEND="openvoice"
-OPENVOICE_REF_AUDIO="./voice-samples/user-reference.wav"
-OPENVOICE_PROGRESS="0"
-```
-
-Only clone voices you own or have permission to use. If OpenVoice fails or times out, VerbalCoding falls back to Edge TTS.
-
-## Optional Supertonic TTS
-
-```bash
-./scripts/setup_supertonic.sh
-supertonic tts '안녕하세요. 수퍼토닉 테스트입니다.' --lang ko --voice M1 --steps 2 --speed 1.0 -o /tmp/verbalcoding-supertonic.wav
-```
-
-Then set:
-
-```bash
-TTS_BACKEND="supertonic"
-SUPERTONIC_COMMAND="./.venv-supertonic/bin/supertonic"
-SUPERTONIC_VOICE="M1"
-SUPERTONIC_LANGUAGE="ko"
-SUPERTONIC_STEPS="2"
-SUPERTONIC_SPEED="1.0"
-SUPERTONIC_PROGRESS="0"
+```yaml
+services:
+  verbalcoding:
+    network_mode: "host"
 ```
 
-If Supertonic is missing, fails, or times out, VerbalCoding falls back to Edge TTS.
-
-## Optional SpeechSwift / CosyVoice TTS
+Remove `ports:` from that Compose service. On Docker Desktop for macOS/Windows, host networking may not expose UDP the same way; run on the host or a Linux VM if voice still fails.
 
-On Apple Silicon, `speech-swift` is a local backend for Korean voice cloning with MLX-native CosyVoice/Qwen3-TTS.
+## Optional TTS Backends
 
-```bash
-brew tap soniqo/speech https://github.com/soniqo/speech-swift
-brew install speech
-```
+Edge TTS remains the default and fallback. Optional local backends are configured with their own env vars:
 
-Recommended env:
-
-```bash
-TTS_BACKEND="speechswift"
-SPEECHSWIFT_MODE="server"
-SPEECHSWIFT_ENGINE="cosyvoice"
-SPEECHSWIFT_LANGUAGE="korean"
-SPEECHSWIFT_REF_AUDIO="./voice-samples/user-reference.wav"
-SPEECHSWIFT_SERVER_HOST="127.0.0.1"
-SPEECHSWIFT_SERVER_PORT="18080"
-SPEECHSWIFT_SERVER_URL="http://127.0.0.1:18080"
-SPEECHSWIFT_PROGRESS="0"
-```
+| Backend | Settings | Voice choices |
+|---|---|---|
+| Edge | `TTS_VOICE_TYPE`, `TTS_VOICE` | Built-in types above, plus any voice returned by `edge-tts --list-voices` |
+| 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 |
 
-Keep Edge for quick progress/backchannel prompts.
+Only clone voices you own or have permission to use. If a local backend fails or times out, VerbalCoding falls back to Edge TTS.
 
 ## Operational Notes