verbalcoding 0.2.0

package/app-node/mcp_tools.mjs

@@ -0,0 +1,198 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+
+import { parseKeyValueEnv } from './install_config.mjs';
+import { applyLanguagePreset, languageStatus, normalizeLanguageKey } from './language_config.mjs';
+import { AUTO_RESTART_ENV_KEY, autoRestartStatusText, normalizeAutoRestartCommand } from './restart_policy.mjs';
+
+function quoteEnv(value) {
+  return JSON.stringify(String(value ?? ''));
+}
+
+export function readEnvFile(file) {
+  if (!fs.existsSync(file)) return {};
+  return parseKeyValueEnv(fs.readFileSync(file, 'utf8'));
+}
+
+export function upsertEnvFile(file, updates) {
+  const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  const seen = new Set();
+  const lines = existing.split(/\r?\n/).map(raw => {
+    const line = raw.trim();
+    if (!line || line.startsWith('#') || !line.includes('=')) return raw;
+    const idx = line.indexOf('=');
+    const key = line.slice(0, idx).trim().replace(/^export\s+/, '');
+    if (!(key in updates)) return raw;
+    seen.add(key);
+    return `${key}=${quoteEnv(updates[key])}`;
+  });
+  for (const [key, value] of Object.entries(updates)) {
+    if (!seen.has(key)) lines.push(`${key}=${quoteEnv(value)}`);
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${lines.filter((line, index, arr) => line !== '' || index < arr.length - 1).join('\n')}\n`, { mode: 0o600 });
+}
+
+function runCommand(command, args, { root, timeoutMs = 120000, env = process.env } = {}) {
+  const result = spawnSync(command, args, {
+    cwd: root,
+    env,
+    encoding: 'utf8',
+    timeout: timeoutMs,
+    maxBuffer: 2 * 1024 * 1024,
+  });
+  return {
+    ok: result.status === 0,
+    status: result.status,
+    signal: result.signal,
+    stdout: sanitizeOutput(result.stdout || ''),
+    stderr: sanitizeOutput(result.stderr || ''),
+  };
+}
+
+function sanitizeOutput(text) {
+  return String(text || '')
+    .replace(/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+/g, '[REDACTED_EMAIL]')
+    .replace(/(token|api[_-]?key|password|secret|authorization|connection[_-]?string)\s*[:=]\s*\S+/gi, '$1=[REDACTED]')
+    .replace(/[A-Za-z0-9_-]{40,}/g, '[REDACTED]');
+}
+
+function runningPids() {
+  const result = spawnSync('ps', ['-axo', 'pid,command'], { encoding: 'utf8' });
+  if (result.status !== 0) return [];
+  return result.stdout
+    .split(/\r?\n/)
+    .map(line => line.trim())
+    .map(line => /^(\d+)\s+(.+)$/.exec(line))
+    .filter(Boolean)
+    .filter(match => /node\s+app-node\/main\.mjs/.test(match[2]))
+    .map(match => Number(match[1]));
+}
+
+function startBridge({ root, env = process.env } = {}) {
+  const pids = runningPids();
+  if (pids.length) return { ok: true, alreadyRunning: true, pids };
+  fs.mkdirSync(path.join(root, '.cache'), { recursive: true });
+  const child = spawn('./run.sh', {
+    cwd: root,
+    env: {
+      ...env,
+      BRIDGE_LOG_PATH: '/tmp/verbalcoding-node.log',
+      NODE_AUDIO_DEBUG_DIR: '/tmp/verbalcoding-node-debug',
+    },
+    detached: true,
+    stdio: 'ignore',
+  });
+  child.unref();
+  return { ok: true, started: true, pid: child.pid };
+}
+
+function stopBridge() {
+  const pids = runningPids();
+  for (const pid of pids) {
+    try { process.kill(pid, 'SIGTERM'); } catch {}
+  }
+  return { ok: true, stoppedPids: pids };
+}
+
+export function createVerbalCodingMcpTools({ root = process.cwd(), envPath = path.join(root, '.env'), env = process.env } = {}) {
+  const toolDefs = [
+    {
+      name: 'status',
+      description: 'Return VerbalCoding runtime/config status without exposing secrets.',
+      inputSchema: { type: 'object', properties: {} },
+      handler: async () => {
+        const values = readEnvFile(envPath);
+        const lang = languageStatus(values);
+        return {
+          project: root,
+          running: runningPids().length > 0,
+          pids: runningPids(),
+          backend: values.AGENT_BACKEND || 'hermes',
+          ttsBackend: values.TTS_BACKEND || 'edge',
+          sttLanguage: lang.sttLanguage,
+          voiceLanguage: lang.voiceLanguage,
+          ttsVoice: lang.ttsVoice,
+          autoRestartAfterCommit: autoRestartStatusText(values),
+          sessionFile: values.HERMES_SESSION_FILE || path.join(root, '.verbalcoding-session'),
+        };
+      },
+    },
+    {
+      name: 'doctor',
+      description: 'Run VerbalCoding doctor and return redacted output.',
+      inputSchema: { type: 'object', properties: {} },
+      handler: async () => runCommand('npm', ['run', 'doctor'], { root, env }),
+    },
+    {
+      name: 'set_auto_restart',
+      description: 'Enable or disable commit-time voice bot auto-restart. Defaults off unless explicitly enabled.',
+      inputSchema: {
+        type: 'object',
+        properties: { enabled: { type: 'boolean', description: 'true to enable, false to disable' } },
+        required: ['enabled'],
+      },
+      handler: async ({ enabled }) => {
+        upsertEnvFile(envPath, { [AUTO_RESTART_ENV_KEY]: enabled ? '1' : '0' });
+        const values = readEnvFile(envPath);
+        return { ok: true, status: autoRestartStatusText(values), value: values[AUTO_RESTART_ENV_KEY] };
+      },
+    },
+    {
+      name: 'set_language',
+      description: 'Set STT/progress/TTS language preset to ko, en, or auto.',
+      inputSchema: {
+        type: 'object',
+        properties: { language: { type: 'string', enum: ['ko', 'en', 'auto'] } },
+        required: ['language'],
+      },
+      handler: async ({ language }) => {
+        const key = normalizeLanguageKey(language, '');
+        if (!key) throw new Error(`Unknown language: ${language}`);
+        const next = applyLanguagePreset(readEnvFile(envPath), key);
+        upsertEnvFile(envPath, {
+          VOICE_LANGUAGE: next.VOICE_LANGUAGE,
+          WHISPER_CPP_LANGUAGE: next.WHISPER_CPP_LANGUAGE,
+          STT_LANGUAGE: next.STT_LANGUAGE,
+          TTS_BACKEND: next.TTS_BACKEND,
+          TTS_VOICE: next.TTS_VOICE,
+        });
+        return { ok: true, status: languageStatus(next) };
+      },
+    },
+    {
+      name: 'start',
+      description: 'Start the VerbalCoding Discord voice bridge if it is not already running.',
+      inputSchema: { type: 'object', properties: {} },
+      handler: async () => startBridge({ root, env }),
+    },
+    {
+      name: 'stop',
+      description: 'Gracefully stop the VerbalCoding Discord voice bridge.',
+      inputSchema: { type: 'object', properties: {} },
+      handler: async () => stopBridge(),
+    },
+    {
+      name: 'restart',
+      description: 'Restart the VerbalCoding Discord voice bridge with an optional short notice.',
+      inputSchema: {
+        type: 'object',
+        properties: { notice: { type: 'string', description: 'Short user-facing restart notice detail' } },
+      },
+      handler: async ({ notice = 'MCP 요청으로 재시작해' } = {}) => {
+        fs.mkdirSync(path.join(root, '.cache'), { recursive: true });
+        fs.writeFileSync(path.join(root, '.cache', 'restart-notice.txt'), String(notice).replace(/\s+/g, ' ').trim().slice(0, 160));
+        const stopped = stopBridge();
+        const started = startBridge({ root, env });
+        return { ok: Boolean(started.ok), stopped, started };
+      },
+    },
+  ];
+  const tools = new Map(toolDefs.map(tool => [tool.name, tool]));
+  return { toolDefs, tools };
+}
+
+export function toolResultContent(value) {
+  return [{ type: 'text', text: JSON.stringify(value, null, 2) }];
+}

package/app-node/mcp_tools.test.mjs

@@ -0,0 +1,39 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { createVerbalCodingMcpTools, readEnvFile } from './mcp_tools.mjs';
+import { AUTO_RESTART_ENV_KEY } from './restart_policy.mjs';
+
+test('MCP tool definitions expose VerbalCoding control surface', () => {
+  const { toolDefs, tools } = createVerbalCodingMcpTools({ root: process.cwd() });
+  const names = toolDefs.map(tool => tool.name).sort();
+  assert.deepEqual(names, ['doctor', 'restart', 'set_auto_restart', 'set_language', 'start', 'status', 'stop']);
+  assert.equal(tools.get('set_auto_restart').inputSchema.required[0], 'enabled');
+});
+
+test('set_auto_restart MCP tool writes the default-off restart flag', async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'vc-mcp-'));
+  const envPath = path.join(dir, '.env');
+  const { tools } = createVerbalCodingMcpTools({ root: dir, envPath });
+  const off = await tools.get('set_auto_restart').handler({ enabled: false });
+  assert.equal(off.value, '0');
+  assert.equal(readEnvFile(envPath)[AUTO_RESTART_ENV_KEY], '0');
+  const on = await tools.get('set_auto_restart').handler({ enabled: true });
+  assert.equal(on.value, '1');
+  assert.equal(readEnvFile(envPath)[AUTO_RESTART_ENV_KEY], '1');
+});
+
+test('set_language MCP tool updates STT, progress, and TTS language together', async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'vc-mcp-lang-'));
+  const envPath = path.join(dir, '.env');
+  const { tools } = createVerbalCodingMcpTools({ root: dir, envPath });
+  const result = await tools.get('set_language').handler({ language: 'en' });
+  assert.equal(result.ok, true);
+  const values = readEnvFile(envPath);
+  assert.equal(values.VOICE_LANGUAGE, 'en');
+  assert.equal(values.WHISPER_CPP_LANGUAGE, 'en');
+  assert.match(values.TTS_VOICE, /^en-/);
+});

package/app-node/progress_cache.mjs

@@ -0,0 +1,7 @@
+import { createHash } from 'node:crypto';
+
+export function progressTtsCacheFileName({ backendKeyParts, text, ext }) {
+  const key = `${(backendKeyParts || []).join('\n')}\n${String(text || '')}`;
+  const digest = createHash('sha256').update(key, 'utf8').digest('hex');
+  return `${digest}.${ext || 'mp3'}`;
+}

package/app-node/progress_cache.test.mjs

@@ -0,0 +1,23 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { progressTtsCacheFileName } from './progress_cache.mjs';
+
+test('progressTtsCacheFileName includes full text even when backend key prefix is long', () => {
+  const longBackendKey = [
+    'speechswift',
+    'server',
+    'http://127.0.0.1:18080',
+    'cosyvoice',
+    '/path/to/VerbalCoding/voice-samples/user-reference.wav',
+    'korean',
+    'aufklarer/CosyVoice3-0.5B-MLX-4bit',
+  ];
+
+  const first = progressTtsCacheFileName({ backendKeyParts: longBackendKey, text: 'Hermes Agent 호출 시작', ext: 'wav' });
+  const second = progressTtsCacheFileName({ backendKeyParts: longBackendKey, text: '터미널 명령 실행', ext: 'wav' });
+
+  assert.notEqual(first, second);
+  assert.match(first, /^[a-f0-9]{64}\.wav$/);
+  assert.match(second, /^[a-f0-9]{64}\.wav$/);
+});

package/app-node/progress_speech.mjs

@@ -0,0 +1,102 @@
+const CATEGORY_LABELS = {
+  ko: {
+    test: '테스트 실행', edit: '파일 수정', read: '파일 읽기', search: '검색', terminal: '터미널 실행',
+    skill: '스킬 사용', browser: '브라우저 확인', tool: '툴 사용', agent: '에이전트 처리', work: '작업 처리',
+  },
+  en: {
+    test: 'running tests', edit: 'editing files', read: 'reading files', search: 'searching', terminal: 'running terminal commands',
+    skill: 'loading skills', browser: 'checking the browser', tool: 'using tools', agent: 'calling the agent', work: 'working',
+  },
+};
+
+const CATEGORY_RULES = [
+  { key: 'test', pattern: /(테스트|test|pytest|npm test|node --test)/i },
+  { key: 'edit', pattern: /(파일\s*수정|수정|patch|write_file|쓰기|변경|edit)/i },
+  { key: 'read', pattern: /(파일\s*읽기|read_file|읽기|열람)/i },
+  { key: 'search', pattern: /(웹\s*검색|검색|web_search|search_files|찾기)/i },
+  { key: 'terminal', pattern: /(터미널|명령|terminal|shell|실행)/i },
+  { key: 'skill', pattern: /(스킬|skill)/i },
+  { key: 'browser', pattern: /(브라우저|browser)/i },
+  { key: 'tool', pattern: /(툴|도구|tool)/i },
+  { key: 'agent', pattern: /(에이전트|agent|hermes)/i },
+];
+
+function labelsFor(language = 'ko') {
+  return /^en/i.test(String(language || '')) ? CATEGORY_LABELS.en : CATEGORY_LABELS.ko;
+}
+
+export function progressCategory(event, { language = 'ko' } = {}) {
+  const text = String(event || '').replace(/\s+/g, ' ').trim();
+  if (!text) return null;
+  const labels = labelsFor(language);
+  const found = CATEGORY_RULES.find(rule => rule.pattern.test(text));
+  return found ? { key: found.key, label: labels[found.key] } : { key: 'work', label: labels.work };
+}
+
+export function progressDetail(event, { language = 'ko' } = {}) {
+  const text = String(event || '').replace(/\s+/g, ' ').trim();
+  if (!text) return '';
+  const category = progressCategory(text, { language });
+  let detail = text
+    .replace(/^VERBALCODING_PROGRESS:\s*/i, '')
+    .replace(/^(파일\s*읽기|파일\s*수정|웹\s*검색|터미널\s*(명령\s*)?실행|테스트\s*실행|스킬\s*사용|툴\s*사용|브라우저\s*확인|에이전트\s*(호출|처리|응답\s*수신)?|Hermes Agent\s*(호출\s*시작|응답\s*수신)?)\s*/i, '')
+    .replace(/^(read_file|write_file|patch|web_search|search_files|terminal|skill_view|tool)\s*/i, '')
+    .replace(/[`*_#>\[\](){}]/g, '')
+    .replace(/\b[a-zA-Z0-9_.\/-]+\.(mjs|js|py|md|json|txt|sh|yaml|yml)\b/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (!detail || detail.length < 2) return category?.label || '';
+  if (detail.length > 28) detail = detail.slice(0, 27).replace(/[\s,.;:，。]+$/u, '');
+  return `${category?.label || labelsFor(language).work} ${detail}`.trim();
+}
+
+export function formatProgressMessage(event, { language = 'ko' } = {}) {
+  const text = String(event || '').replace(/\s+/g, ' ').trim();
+  if (!text) return '';
+  const category = progressCategory(text, { language });
+  const detail = progressDetail(text, { language });
+  const english = /^en/i.test(String(language || ''));
+  const safeDetail = english && /\p{Script=Hangul}/u.test(detail) ? '' : detail;
+  const body = english ? (safeDetail || category?.label || 'working') : (safeDetail || category?.label || '작업 처리');
+  const emoji = {
+    test: '🧪',
+    edit: '✏️',
+    read: '📖',
+    search: '🔎',
+    terminal: '💻',
+    skill: '📚',
+    browser: '🌐',
+    agent: '🤖',
+    tool: '🛠️',
+    work: '⚙️',
+  }[category?.key || 'work'] || '⚙️';
+  return `${emoji} ${body}`.trim();
+}
+
+export function summarizeProgressEvents(events, { maxCategories = 3, language = 'ko' } = {}) {
+  const seenDetails = new Set();
+  const details = [];
+  const seenCategories = new Set();
+  const labels = [];
+  for (const event of events || []) {
+    const category = progressCategory(event, { language });
+    if (category && !seenCategories.has(category.key)) {
+      seenCategories.add(category.key);
+      labels.push(category.label);
+    }
+    const detail = progressDetail(event, { language });
+    if (detail && !seenDetails.has(detail)) {
+      seenDetails.add(detail);
+      details.push(detail);
+    }
+  }
+  const items = details.length ? details : labels;
+  if (!items.length) return '';
+  const english = /^en/i.test(String(language || ''));
+  if (items.length === 1) return english ? `${items[0]}.` : `${items[0]} 중이야.`;
+  const shown = items.slice(0, Math.max(1, maxCategories));
+  if (items.length > shown.length) {
+    return english ? `${shown.join(', ')}, and ${items.length - shown.length} more.` : `${shown.join(', ')} 외 ${items.length - shown.length}개 작업 중이야.`;
+  }
+  return english ? `${shown.join(', ')}.` : `${shown.join(', ')} 중이야.`;
+}

package/app-node/progress_speech.test.mjs

@@ -0,0 +1,48 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { progressCategory, progressDetail, summarizeProgressEvents, formatProgressMessage } from './progress_speech.mjs';
+
+test('progressCategory maps raw verbose events to stable cache-friendly buckets', () => {
+  assert.equal(progressCategory('파일 읽기 app-node/main.mjs').key, 'read');
+  assert.equal(progressCategory('터미널 명령 실행 npm test').key, 'test');
+  assert.equal(progressCategory('웹 검색 VerbalCoding setup').key, 'search');
+  assert.equal(progressCategory('스킬 사용 discord-voice-hermes-bridge').key, 'skill');
+});
+
+test('progressDetail preserves the meaningful task name after the generic prefix', () => {
+  assert.equal(progressDetail('파일 수정 재시작 안내 문구 개선'), '파일 수정 재시작 안내 문구 개선');
+  assert.equal(progressDetail('터미널 실행 음성봇 재시작 적용'), '터미널 실행 음성봇 재시작 적용');
+});
+
+test('formatProgressMessage renders intermediate text in the selected English language', () => {
+  assert.equal(formatProgressMessage('파일 읽기 app-node/main.mjs', { language: 'en' }), '📖 reading files');
+  assert.equal(formatProgressMessage('터미널 명령 실행 npm test', { language: 'en' }), '🧪 running tests npm test');
+  assert.equal(formatProgressMessage('파일 수정 재시작 안내 문구 개선', { language: 'en' }), '✏️ editing files');
+});
+
+test('agent progress events format as visible and speakable status', () => {
+  assert.equal(formatProgressMessage('Hermes Agent 호출 시작'), '🤖 에이전트 처리');
+  assert.equal(summarizeProgressEvents(['Hermes Agent 호출 시작']), '에이전트 처리 중이야.');
+});
+
+test('summarizeProgressEvents batches many raw events with meaningful details', () => {
+  const text = summarizeProgressEvents([
+    '파일 읽기 app-node/main.mjs',
+    '파일 수정 재시작 안내 문구 개선',
+    '웹 검색 VerbalCoding setup',
+    '터미널 명령 실행 npm test',
+  ]);
+  assert.equal(text, '파일 읽기, 파일 수정 재시작 안내 문구 개선, 검색 VerbalCoding setup 외 1개 작업 중이야.');
+});
+
+test('summarizeProgressEvents caps spoken details to keep latency low', () => {
+  const text = summarizeProgressEvents([
+    '파일 읽기 app-node/main.mjs',
+    '웹 검색 VerbalCoding setup',
+    '테스트 실행 npm test',
+    '스킬 사용 discord-voice-hermes-bridge',
+    '브라우저 확인 settings page',
+  ], { maxCategories: 3 });
+  assert.equal(text, '파일 읽기, 검색 VerbalCoding setup, 테스트 실행 npm test 외 2개 작업 중이야.');
+});

package/app-node/project_sessions.mjs

@@ -0,0 +1,148 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function slugifySessionName(name) {
+  const slug = String(name || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}_.-]+/gu, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 64);
+  return slug || 'default';
+}
+
+export function loadProjectSessions(configPath) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    return {
+      version: 1,
+      sessions: parsed.sessions && typeof parsed.sessions === 'object' ? parsed.sessions : {},
+      channelSessions: parsed.channelSessions && typeof parsed.channelSessions === 'object' ? parsed.channelSessions : {},
+    };
+  } catch {
+    return { version: 1, sessions: {}, channelSessions: {} };
+  }
+}
+
+export function saveProjectSessions(configPath, state) {
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, `${JSON.stringify({
+    version: 1,
+    sessions: state.sessions || {},
+    channelSessions: state.channelSessions || {},
+  }, null, 2)}\n`, { mode: 0o600 });
+}
+
+export function createProjectSession({ root, state, name, workdir, channelId, voiceChannelId = '', transcriptChannelId = '', mcpContext = '' }) {
+  const sessionName = String(name || '').trim();
+  if (!sessionName) throw new Error('session name is required');
+  const slug = slugifySessionName(sessionName);
+  const resolvedWorkdir = path.resolve(String(workdir || root));
+  const session = {
+    name: sessionName,
+    slug,
+    workdir: resolvedWorkdir,
+    sessionFile: path.join(root, '.agent-sessions', 'hermes', `${slug}.session`),
+    transcriptChannelId: String(transcriptChannelId || channelId || '').trim(),
+    voiceChannelId: String(voiceChannelId || '').trim(),
+    mcpContext: String(mcpContext || '').trim(),
+    createdAt: new Date().toISOString(),
+  };
+  state.sessions[slug] = session;
+  if (channelId) state.channelSessions[String(channelId)] = slug;
+  if (voiceChannelId) state.channelSessions[String(voiceChannelId)] = slug;
+  return session;
+}
+
+export function bindProjectSessionToChannel({ state, nameOrSlug, channelId }) {
+  const slug = findProjectSessionSlug(state, nameOrSlug);
+  if (!slug) throw new Error(`unknown project session: ${nameOrSlug}`);
+  state.channelSessions[String(channelId)] = slug;
+  return state.sessions[slug];
+}
+
+export function findProjectSessionSlug(state, nameOrSlug) {
+  const key = slugifySessionName(nameOrSlug);
+  if (state.sessions[key]) return key;
+  const wanted = String(nameOrSlug || '').trim().toLowerCase();
+  return Object.entries(state.sessions || {}).find(([, session]) => String(session.name || '').toLowerCase() === wanted)?.[0] || null;
+}
+
+export function projectSessionForChannel(state, channelId) {
+  const slug = state.channelSessions?.[String(channelId || '')];
+  return slug ? state.sessions?.[slug] || null : null;
+}
+
+export function listProjectSessions(state) {
+  return Object.values(state.sessions || {}).sort((a, b) => String(a.name).localeCompare(String(b.name)));
+}
+
+export function projectSessionContextText(session) {
+  if (!session) return '';
+  const parts = [`Project session: ${session.name}`, `Working directory: ${session.workdir}`];
+  if (session.mcpContext) parts.push(`MCP/project context: ${session.mcpContext}`);
+  return parts.join('\n');
+}
+
+function tokenParts(rest) {
+  return rest.match(/(?:"([^"]+)"|'([^']+)'|(\S+))/g)?.map(part => part.replace(/^['"]|['"]$/g, '')) || [];
+}
+
+function parseVoiceOption(parts) {
+  const out = [];
+  let voice = '';
+  for (let i = 0; i < parts.length; i += 1) {
+    const part = parts[i];
+    if (part === '--voice' || part === '--voice-channel' || part === '--vc') {
+      voice = parts[i + 1] || '';
+      i += 1;
+      continue;
+    }
+    if (part.startsWith('--voice=')) {
+      voice = part.slice('--voice='.length);
+      continue;
+    }
+    if (part.startsWith('--voice-channel=')) {
+      voice = part.slice('--voice-channel='.length);
+      continue;
+    }
+    out.push(part);
+  }
+  return { parts: out, voice };
+}
+
+export function parseProjectSessionCommand(content) {
+  const text = String(content || '').trim();
+  const match = /^!(?:project-session|session)\s+(new|create|use|bind|attach-voice|voice|status|list|reset)\b\s*(.*)$/i.exec(text);
+  if (!match) return parseNaturalVoiceAttachCommand(text);
+  const action = match[1].toLowerCase();
+  const rest = match[2].trim();
+  if (action === 'status' || action === 'list' || action === 'reset') return { action, rest };
+  const parsed = parseVoiceOption(tokenParts(rest));
+  if (action === 'use' || action === 'bind') return { action: 'use', name: parsed.parts.join(' '), voice: parsed.voice };
+  if (action === 'attach-voice' || action === 'voice') {
+    return {
+      action: 'attach-voice',
+      name: parsed.voice ? parsed.parts.join(' ') : '',
+      voice: parsed.voice || parsed.parts.join(' '),
+    };
+  }
+  return {
+    action: 'new',
+    name: parsed.parts[0] || '',
+    workdir: parsed.parts[1] || '',
+    mcpContext: parsed.parts.slice(2).join(' '),
+    voice: parsed.voice,
+  };
+}
+
+export function parseNaturalVoiceAttachCommand(content) {
+  const text = String(content || '').trim();
+  if (!text || text.startsWith('!')) return null;
+  const compact = text.replace(/\s+/g, ' ');
+  const hasVoiceTarget = /(음성|보이스)\s*(채널|세션)|voice\s*(channel|session)|vc\b/i.test(compact);
+  const asksAttach = /(붙여\s*(줘|줘라|달라|주세요|주라)|연결\s*(해|해줘|해줘라|해주세요|시켜|시켜줘)|attach|connect)/i.test(compact);
+  if (!hasVoiceTarget || !asksAttach) return null;
+  const explicit = /(?:--voice(?:-channel)?|--vc)\s+(["']?)([^"'\s][^"']*?)\1(?:\s|$)/i.exec(compact);
+  return { action: 'attach-voice', voice: explicit?.[2]?.trim() || '' };
+}

package/app-node/project_sessions.test.mjs

@@ -0,0 +1,77 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  bindProjectSessionToChannel,
+  createProjectSession,
+  loadProjectSessions,
+  parseNaturalVoiceAttachCommand,
+  parseProjectSessionCommand,
+  projectSessionContextText,
+  projectSessionForChannel,
+  saveProjectSessions,
+  slugifySessionName,
+} from './project_sessions.mjs';
+
+test('project sessions map Discord text and voice channel ids to isolated Hermes session files', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'vc-sessions-'));
+  const state = loadProjectSessions(path.join(root, 'sessions.json'));
+  const session = createProjectSession({ root, state, name: 'LLM Wiki', workdir: '/tmp/llm-wiki', channelId: 'text-1', voiceChannelId: 'voice-1', mcpContext: 'llm-wiki graph' });
+  assert.equal(session.slug, 'llm-wiki');
+  assert.equal(session.voiceChannelId, 'voice-1');
+  assert.equal(session.sessionFile, path.join(root, '.agent-sessions', 'hermes', 'llm-wiki.session'));
+  assert.equal(projectSessionForChannel(state, 'text-1').name, 'LLM Wiki');
+  assert.equal(projectSessionForChannel(state, 'voice-1').name, 'LLM Wiki');
+  assert.match(projectSessionContextText(session), /Working directory: \/tmp\/llm-wiki/);
+});
+
+test('project sessions persist and can be rebound to another channel', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'vc-sessions-persist-'));
+  const configPath = path.join(root, 'sessions.json');
+  const state = loadProjectSessions(configPath);
+  createProjectSession({ root, state, name: 'Other Project', workdir: root, channelId: 'a' });
+  saveProjectSessions(configPath, state);
+  const loaded = loadProjectSessions(configPath);
+  bindProjectSessionToChannel({ state: loaded, nameOrSlug: 'other-project', channelId: 'b' });
+  assert.equal(projectSessionForChannel(loaded, 'b').name, 'Other Project');
+});
+
+test('project session command parser supports new/use/status/list/reset', () => {
+  assert.deepEqual(parseProjectSessionCommand('!session new wiki /tmp/wiki graph'), {
+    action: 'new', name: 'wiki', workdir: '/tmp/wiki', mcpContext: 'graph', voice: '',
+  });
+  assert.deepEqual(parseProjectSessionCommand('!project-session use wiki'), { action: 'use', name: 'wiki', voice: '' });
+  assert.equal(parseProjectSessionCommand('!session status').action, 'status');
+  assert.equal(slugifySessionName('한글 Project!'), '한글-project');
+});
+
+test('project session command parser supports explicit voice channel selection', () => {
+  assert.deepEqual(parseProjectSessionCommand('!session new wiki /tmp/wiki graph --voice "LLM Wiki Voice"'), {
+    action: 'new', name: 'wiki', workdir: '/tmp/wiki', mcpContext: 'graph', voice: 'LLM Wiki Voice',
+  });
+  assert.deepEqual(parseProjectSessionCommand('!session use wiki --voice=LLM-Voice'), {
+    action: 'use', name: 'wiki', voice: 'LLM-Voice',
+  });
+  assert.deepEqual(parseProjectSessionCommand('!session attach-voice --voice "LLM-Wiki"'), {
+    action: 'attach-voice', name: '', voice: 'LLM-Wiki',
+  });
+  assert.deepEqual(parseProjectSessionCommand('!session voice LLM-Wiki'), {
+    action: 'attach-voice', name: '', voice: 'LLM-Wiki',
+  });
+  assert.deepEqual(parseProjectSessionCommand('!session voice llm-wiki --voice "LLM-Wiki"'), {
+    action: 'attach-voice', name: 'llm-wiki', voice: 'LLM-Wiki',
+  });
+});
+
+test('project session parser treats natural voice attach requests as control commands', () => {
+  assert.deepEqual(parseProjectSessionCommand('이 쓰레드에 음성 채널 붙여줘'), {
+    action: 'attach-voice', voice: '',
+  });
+  assert.deepEqual(parseNaturalVoiceAttachCommand('보이스 세션 연결해줘 --voice "LLM Wiki"'), {
+    action: 'attach-voice', voice: 'LLM Wiki',
+  });
+  assert.equal(parseNaturalVoiceAttachCommand('음성 채널 상태가 어때?'), null);
+});