verbalcoding 0.2.0

package/app-node/agent_adapters.test.mjs

@@ -0,0 +1,455 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  buildAgentSettings,
+  createAgentAdapter,
+  extractVerboseProgressEvents,
+  interruptedAgentMessage,
+  isPatchLikeOutput,
+  resolveExecTimeout,
+  sanitizeAgentOutput,
+  voiceBridgePrompt,
+} from './agent_adapters.mjs';
+import { assertAgentAdapterContract } from './agent_contract.mjs';
+
+test('buildAgentSettings defaults to Hermes backend and uses VerbalCoding session file', () => {
+  const settings = buildAgentSettings({ ROOT: '/project', env: {} });
+
+  assert.equal(settings.backend, 'hermes');
+  assert.equal(settings.label, 'Hermes Agent');
+  assert.equal(settings.command, 'hermes chat -Q -q');
+  assert.equal(settings.sessionFile, '/project/.verbalcoding-session');
+  assert.equal(settings.cwd, '/project');
+  assert.equal(settings.taskTimeoutMs, 0);
+});
+
+test('Hermes adapter resumes and saves Hermes CLI session ids', async () => {
+  const calls = [];
+  const files = new Map([['/tmp/hermes-session', 'old-session\n']]);
+  const adapter = createAgentAdapter({
+    backend: 'hermes',
+    label: 'Hermes Agent',
+    command: 'hermes chat -Q -q',
+    sessionFile: '/tmp/hermes-session',
+    taskTimeoutMs: 300000,
+    chatTimeoutMs: 45000,
+  }, {
+    readFileSync: path => files.get(path),
+    writeFileSync: (path, value) => files.set(path, value),
+    execFileAsync: async (cmd, args) => {
+      calls.push({ cmd, args });
+      return { stdout: '좋아, 처리했어.\n', stderr: 'session_id: new-session\n' };
+    },
+    log: () => {},
+    warn: () => {},
+  });
+
+  const answer = await adapter.ask('테스트해줘');
+
+  assert.equal(answer, '좋아, 처리했어.');
+  assert.equal(calls[0].cmd, 'hermes');
+  assert.deepEqual(calls[0].args.slice(0, 5), ['chat', '-Q', '--resume', 'old-session', '-q']);
+  assert.match(calls[0].args.at(-1), /Discord 음성 대화로 들어온 사용자 발화다/);
+  assert.match(calls[0].args.at(-1), /테스트해줘/);
+  assert.equal(files.get('/tmp/hermes-session'), 'new-session\n');
+  assert.equal(assertAgentAdapterContract(adapter), true);
+  assert.equal(adapter.capabilities.supportsSessionResume, true);
+});
+
+test('adapter passes project context prompt and cwd for project sessions', async () => {
+  const calls = [];
+  const adapter = createAgentAdapter({
+    backend: 'hermes',
+    label: 'Hermes Agent · Wiki',
+    command: 'hermes chat -Q -q',
+    sessionFile: '/tmp/wiki-session',
+    cwd: '/tmp/wiki-workdir',
+    taskTimeoutMs: 300000,
+    chatTimeoutMs: 45000,
+  }, {
+    readFileSync: () => '',
+    writeFileSync: () => {},
+    execFileAsync: async (cmd, args, options) => {
+      calls.push({ cmd, args, options });
+      return { stdout: '처리했어.\n', stderr: 'session_id: wiki-session\n' };
+    },
+    log: () => {},
+    warn: () => {},
+  });
+
+  const result = await adapter.run('프로젝트 상태 봐줘', undefined, {
+    language: 'ko',
+    projectContext: 'Project session: Wiki\nWorking directory: /tmp/wiki-workdir\nMCP/project context: wiki graph',
+  });
+
+  assert.equal(result.answer, '처리했어.');
+  assert.equal(calls[0].options.cwd, '/tmp/wiki-workdir');
+  assert.match(calls[0].args.at(-1), /Project session: Wiki/);
+  assert.match(calls[0].args.at(-1), /MCP\/project context: wiki graph/);
+});
+
+test('buildAgentSettings accepts per-instance AGENT_CWD and AGENT_PROJECT_CONTEXT aliases', () => {
+  const settings = buildAgentSettings({ ROOT: '/repo', env: {
+    AGENT_BACKEND: 'hermes',
+    AGENT_CWD: '/repo/llm-wiki',
+    AGENT_PROJECT_CONTEXT: 'Project session: LLM-Wiki',
+  } });
+
+  assert.equal(settings.cwd, '/repo/llm-wiki');
+  assert.equal(settings.projectContext, 'Project session: LLM-Wiki');
+});
+
+test('adapter uses default project context from settings when plan omits it', async () => {
+  const calls = [];
+  const adapter = createAgentAdapter({
+    backend: 'codex',
+    label: 'Codex · Wiki',
+    command: 'codex exec',
+    sessionFile: '/tmp/codex-session',
+    cwd: '/tmp/wiki-workdir',
+    projectContext: 'Project session: LLM-Wiki',
+    taskTimeoutMs: 300000,
+    chatTimeoutMs: 45000,
+  }, {
+    execFileAsync: async (cmd, args, options) => {
+      calls.push({ cmd, args, options });
+      return { stdout: 'done\n', stderr: '' };
+    },
+    log: () => {},
+    warn: () => {},
+  });
+
+  await adapter.run('status?', undefined, { language: 'en' });
+  assert.equal(calls[0].options.cwd, '/tmp/wiki-workdir');
+  assert.match(calls[0].args.at(-1), /Project session: LLM-Wiki/);
+});
+
+test('adapter run returns formal result while ask keeps string compatibility', async () => {
+  const adapter = createAgentAdapter({
+    backend: 'hermes',
+    label: 'Hermes Agent',
+    command: 'hermes chat -Q -q',
+    sessionFile: '/tmp/hermes-session',
+    taskTimeoutMs: 300000,
+    chatTimeoutMs: 45000,
+  }, {
+    readFileSync: () => '',
+    writeFileSync: () => {},
+    execFileAsync: async () => ({ stdout: 'Done.\n', stderr: 'session_id: new-session\n' }),
+    log: () => {},
+    warn: () => {},
+  });
+
+  const result = await adapter.run({ text: 'do it' }, undefined, { language: 'en' });
+  assert.equal(result.contractVersion, 1);
+  assert.equal(result.status, 'ok');
+  assert.equal(result.answer, 'Done.');
+  assert.equal(result.backend, 'hermes');
+  assert.equal(result.sessionId, 'new-session');
+  assert.equal(await adapter.ask('do it', undefined, { language: 'en' }), 'Done.');
+});
+
+test('Hermes verbose progress drops quiet flag and parses rich CLI final response', async () => {
+  const calls = [];
+  const progress = [];
+  const files = new Map([['/tmp/hermes-session', 'old-session\n']]);
+  const adapter = createAgentAdapter({
+    backend: 'hermes',
+    label: 'Hermes Agent',
+    command: 'hermes chat -Q -q',
+    sessionFile: '/tmp/hermes-session',
+    taskTimeoutMs: 300000,
+    chatTimeoutMs: 45000,
+  }, {
+    readFileSync: path => files.get(path),
+    writeFileSync: (path, value) => files.set(path, value),
+    spawn: (_cmd, args) => {
+      calls.push({ args });
+      const listeners = {};
+      const child = {
+        stdout: { on: (event, cb) => { listeners[`stdout:${event}`] = cb; } },
+        stderr: { on: (event, cb) => { listeners[`stderr:${event}`] = cb; } },
+        on: (event, cb) => { listeners[event] = cb; },
+        kill: () => {},
+      };
+      queueMicrotask(() => {
+        listeners['stdout:data']?.(Buffer.from('  ┊ 💻 $         terminal  0.8s\n'));
+        listeners['stdout:data']?.(Buffer.from('╭─ ⚕ Hermes ─╮\n    완료했어.\n╰────────────╯\n\nSession: new-session\n'));
+        listeners.close?.(0, null);
+      });
+      return child;
+    },
+    execFileAsync: async () => { throw new Error('spawn should be used for verbose progress'); },
+    onProgress: event => progress.push(event),
+    log: () => {},
+    warn: () => {},
+  });
+
+  const answer = await adapter.ask('테스트해줘', undefined, { verboseProgress: true });
+
+  assert.equal(calls[0].args.includes('-Q'), false);
+  assert.deepEqual(calls[0].args.slice(0, 4), ['chat', '--resume', 'old-session', '-q']);
+  assert.equal(answer, '완료했어.');
+  assert.equal(files.get('/tmp/hermes-session'), 'new-session\n');
+  assert.ok(progress.includes('Hermes Agent 호출 시작'));
+  assert.ok(progress.includes('터미널 도구 사용 terminal'));
+});
+
+test('Hermes verbose progress uses English lifecycle events when language is English', async () => {
+  const progress = [];
+  const adapter = createAgentAdapter({
+    backend: 'hermes',
+    label: 'Hermes Agent',
+    command: 'hermes chat -Q -q',
+    sessionFile: '/tmp/hermes-session',
+    taskTimeoutMs: 300000,
+    chatTimeoutMs: 45000,
+  }, {
+    readFileSync: () => '',
+    writeFileSync: () => {},
+    spawn: () => {
+      const listeners = {};
+      const child = {
+        stdout: { on: (event, cb) => { listeners[`stdout:${event}`] = cb; } },
+        stderr: { on: (event, cb) => { listeners[`stderr:${event}`] = cb; } },
+        on: (event, cb) => { listeners[event] = cb; },
+        kill: () => {},
+      };
+      queueMicrotask(() => {
+        listeners['stdout:data']?.(Buffer.from('╭─ ⚕ Hermes ─╮\n    Done.\n╰────────────╯\n'));
+        listeners.close?.(0, null);
+      });
+      return child;
+    },
+    execFileAsync: async () => { throw new Error('spawn should be used'); },
+    onProgress: event => progress.push(event),
+    log: () => {},
+    warn: () => {},
+  });
+
+  const answer = await adapter.ask('do it', undefined, { verboseProgress: true, language: 'en' });
+
+  assert.equal(answer, 'Done.');
+  assert.ok(progress.includes('calling the agent Hermes Agent'));
+  assert.ok(progress.includes('received agent response Hermes Agent'));
+});
+
+test('Hermes adapter falls back to saved session final answer when verbose CLI output omits it', async () => {
+  const files = new Map([
+    ['/tmp/hermes-session', 'old-session\n'],
+    ['/tmp/hermes-sessions/session_new-session.json', JSON.stringify({
+      messages: [
+        { role: 'user', content: '질문' },
+        { role: 'assistant', content: 'VERBALCODING_PROGRESS: 로그 확인' },
+        { role: 'assistant', content: '실제 최종 답변이야.' },
+      ],
+    })],
+  ]);
+  const adapter = createAgentAdapter({
+    backend: 'hermes',
+    label: 'Hermes Agent',
+    command: 'hermes chat -Q -q',
+    sessionFile: '/tmp/hermes-session',
+    taskTimeoutMs: 300000,
+    chatTimeoutMs: 45000,
+  }, {
+    hermesSessionsDir: '/tmp/hermes-sessions',
+    readFileSync: path => files.get(path),
+    writeFileSync: (path, value) => files.set(path, value),
+    spawn: (_cmd, _args) => {
+      const listeners = {};
+      const child = {
+        stdout: { on: (event, cb) => { listeners[`stdout:${event}`] = cb; } },
+        stderr: { on: (event, cb) => { listeners[`stderr:${event}`] = cb; } },
+        on: (event, cb) => { listeners[event] = cb; },
+        kill: () => {},
+      };
+      queueMicrotask(() => {
+        listeners['stdout:data']?.(Buffer.from('VERBALCODING_PROGRESS: 로그 확인\nSession: new-session\n'));
+        listeners.close?.(0, null);
+      });
+      return child;
+    },
+    execFileAsync: async () => { throw new Error('spawn should be used'); },
+    log: () => {},
+    warn: () => {},
+  });
+
+  const answer = await adapter.ask('분석해줘', undefined, { verboseProgress: true });
+
+  assert.equal(answer, '실제 최종 답변이야.');
+});
+
+test('Claude, Codex, and Gemini adapters use backend-specific default commands without Hermes resume', async () => {
+  const cases = [
+    { backend: 'claude', command: ['claude', '-p'], label: 'Claude Code' },
+    { backend: 'codex', command: ['codex', 'exec'], label: 'Codex' },
+    { backend: 'gemini', command: ['gemini', '-p'], label: 'Gemini' },
+    { backend: 'opencode', command: ['opencode', 'run'], label: 'OpenCode' },
+    { backend: 'openclaw', command: ['openclaw', 'run'], label: 'OpenClaw' },
+  ];
+
+  for (const item of cases) {
+    const calls = [];
+    const settings = buildAgentSettings({ ROOT: '/project', env: { AGENT_BACKEND: item.backend } });
+    assert.equal(settings.label, item.label);
+
+    const adapter = createAgentAdapter(settings, {
+      execFileAsync: async (cmd, args) => {
+        calls.push({ cmd, args });
+        return { stdout: `${item.label} 응답\n`, stderr: '' };
+      },
+      log: () => {},
+      warn: () => {},
+    });
+
+    const answer = await adapter.ask('작업해줘');
+
+    assert.equal(answer, `${item.label} 응답`);
+    assert.equal(calls[0].cmd, item.command[0]);
+    assert.deepEqual(calls[0].args.slice(0, item.command.length - 1), item.command.slice(1));
+    assert.equal(calls[0].args.includes('--resume'), false);
+    assert.match(calls[0].args.at(-1), /작업해줘/);
+  }
+});
+
+test('custom adapter uses AGENT_COMMAND and AGENT_LABEL', async () => {
+  const settings = buildAgentSettings({
+    ROOT: '/project',
+    env: { AGENT_BACKEND: 'custom', AGENT_COMMAND: 'my-agent --ask', AGENT_LABEL: 'My Agent' },
+  });
+  const calls = [];
+  const adapter = createAgentAdapter(settings, {
+    execFileAsync: async (cmd, args) => {
+      calls.push({ cmd, args });
+      return { stdout: '완료\n', stderr: '' };
+    },
+    log: () => {},
+    warn: () => {},
+  });
+
+  const answer = await adapter.ask('해줘');
+
+  assert.equal(settings.label, 'My Agent');
+  assert.equal(answer, '완료');
+  assert.equal(calls[0].cmd, 'my-agent');
+  assert.deepEqual(calls[0].args.slice(0, -1), ['--ask']);
+});
+
+test('sanitizeAgentOutput strips CLI metadata from spoken/text answer', () => {
+  assert.equal(
+    sanitizeAgentOutput('↻ Resumed session abc\nsession_id: xyz\n진짜 답변\n'),
+    '진짜 답변',
+  );
+  assert.equal(
+    sanitizeAgentOutput('╭─ ⚕ Hermes ─╮\n    박스 답변\n╰────────────╯\nSession: abc\n'),
+    '박스 답변',
+  );
+});
+
+test('voiceBridgePrompt keeps voice-specific operating instructions with user text', () => {
+  const prompt = voiceBridgePrompt('파일 수정해줘');
+
+  assert.match(prompt, /Discord 음성 대화/);
+  assert.match(prompt, /파일 수정, 실행, 로그 확인/);
+  assert.match(prompt, /파일 수정해줘/);
+});
+
+test('voiceBridgePrompt adds optional verbose progress instructions only when enabled', () => {
+  const normal = voiceBridgePrompt('파일 수정해줘');
+  const verbose = voiceBridgePrompt('파일 수정해줘', { verboseProgress: true });
+
+  assert.doesNotMatch(normal, /VERBALCODING_PROGRESS/);
+  assert.match(verbose, /VERBALCODING_PROGRESS/);
+  assert.match(verbose, /파일 읽기|웹 검색|터미널 실행|툴 사용/);
+});
+
+test('voiceBridgePrompt uses English instructions and progress language when requested', () => {
+  const prompt = voiceBridgePrompt('test this', { verboseProgress: true, language: 'en' });
+
+  assert.match(prompt, /Answer in English/);
+  assert.match(prompt, /VERBALCODING_PROGRESS: reading files/);
+  assert.doesNotMatch(prompt, /짧은 한국어 단계/);
+});
+
+test('extractVerboseProgressEvents summarizes tool activity without leaking raw logs', () => {
+  const events = extractVerboseProgressEvents([
+    'VERBALCODING_PROGRESS: 파일 읽기 app-node/main.mjs',
+    'Calling tool functions.web_search with query secret token abcdef',
+    'tool_use: terminal command="npm test"',
+    'Calling tool functions.skill_view with name discord-voice-hermes-bridge',
+    '  ┊ 🔎           web_search  1.2s',
+    'unrelated verbose log line that should not be included',
+  ].join('\n'));
+
+  assert.deepEqual(events, [
+    '파일 읽기 app-node/main.mjs',
+    '웹 검색 실행',
+    '터미널 명령 실행',
+    '스킬 사용',
+  ]);
+});
+
+test('extractVerboseProgressEvents localizes implicit tool activity to English', () => {
+  const events = extractVerboseProgressEvents([
+    'Calling tool functions.web_search with query secret token abcdef',
+    'tool_use: terminal command="npm test"',
+    'Calling tool functions.skill_view with name discord-voice-hermes-bridge',
+    '  ┊ 📖           read_file  0.5s',
+    '  ┊ 🔎           web_search  1.2s',
+  ].join('\n'), { language: 'en' });
+
+  assert.deepEqual(events, [
+    'searching web',
+    'running terminal commands',
+    'loading skills',
+    'using file tool read_file',
+  ]);
+});
+
+test('resolveExecTimeout disables timeout for zero or invalid task timeout values', () => {
+  assert.equal(resolveExecTimeout(0), undefined);
+  assert.equal(resolveExecTimeout(-1), undefined);
+  assert.equal(resolveExecTimeout(Infinity), undefined);
+  assert.equal(resolveExecTimeout(45000), 45000);
+});
+
+test('signal failure with patch-like output returns a concise interruption message instead of diff', async () => {
+  const adapter = createAgentAdapter({
+    backend: 'hermes',
+    label: 'Hermes Agent',
+    command: 'hermes chat -Q -q',
+    sessionFile: '/tmp/hermes-session',
+    taskTimeoutMs: 1,
+    chatTimeoutMs: 1,
+  }, {
+    readFileSync: () => '',
+    writeFileSync: () => {},
+    execFileAsync: async () => {
+      const err = new Error('Command failed');
+      err.signal = 'SIGINT';
+      err.stdout = '┊ review diff\na/file → b/file\n@@ -1 +1 @@\n-old\n+new\n+more\n+more\n+more\n+more\n+more\n+more\n+more\n+more\n';
+      err.stderr = '';
+      throw err;
+    },
+    log: () => {},
+    warn: () => {},
+  });
+
+  const answer = await adapter.ask('수정해줘');
+
+  assert.equal(isPatchLikeOutput('┊ review diff\na/file → b/file\n@@ -1 +1 @@\n-old\n+new'), true);
+  assert.equal(answer, interruptedAgentMessage('Hermes Agent', true));
+  assert.doesNotMatch(answer, /@@|review diff|old|new/);
+});
+
+test('hermes adapter spawn carries HERMES_HOME from instance env into child env', async () => {
+  const { buildHermesSpawnOptions } = await import('./agent_adapters.mjs');
+  const opts = buildHermesSpawnOptions({
+    parentEnv: { PATH: '/usr/bin', HERMES_HOME: '/parent/.hermes' },
+    instanceEnv: { HERMES_HOME: '/home/you/.hermes/profiles/my-project' },
+  });
+  assert.equal(opts.env.HERMES_HOME, '/home/you/.hermes/profiles/my-project');
+  assert.equal(opts.env.PATH, '/usr/bin');
+});

package/app-node/agent_contract.mjs

@@ -0,0 +1,45 @@
+export const AGENT_ADAPTER_CONTRACT_VERSION = 1;
+
+export function agentAdapterCapabilities(settings = {}) {
+  const backend = settings.backend || 'custom';
+  return {
+    contractVersion: AGENT_ADAPTER_CONTRACT_VERSION,
+    backend,
+    label: settings.label || backend,
+    supportsSessionResume: Boolean(settings.supportsHermesSession),
+    supportsStreamingProgress: true,
+    supportsCancellation: true,
+    returnsFinalText: true,
+  };
+}
+
+export function createAgentRunResult({
+  status = 'ok',
+  answer = '',
+  backend = 'custom',
+  label = 'Agent',
+  elapsedMs = 0,
+  sessionId = null,
+  recoveredFromSession = false,
+  error = null,
+} = {}) {
+  return {
+    contractVersion: AGENT_ADAPTER_CONTRACT_VERSION,
+    status,
+    answer: String(answer || ''),
+    backend,
+    label,
+    elapsedMs,
+    sessionId,
+    recoveredFromSession,
+    error,
+  };
+}
+
+export function assertAgentAdapterContract(adapter) {
+  const missing = ['backend', 'label', 'capabilities', 'run', 'ask', 'buildArgs'].filter(key => !(key in (adapter || {})));
+  if (missing.length) throw new Error(`Agent adapter contract missing: ${missing.join(', ')}`);
+  if (typeof adapter.run !== 'function') throw new Error('Agent adapter contract requires run(request, signal, plan)');
+  if (typeof adapter.ask !== 'function') throw new Error('Agent adapter contract requires ask(text, signal, plan)');
+  return true;
+}

package/app-node/barge_in.mjs

@@ -0,0 +1,148 @@
+export function pcm16StereoLevels(pcm) {
+  if (!pcm || pcm.length < 2) return { meanDb: -Infinity, maxDb: -Infinity, sampleCount: 0 };
+  const usable = pcm.length - (pcm.length % 2);
+  let sumSquares = 0;
+  let maxAbs = 0;
+  let sampleCount = 0;
+  for (let offset = 0; offset < usable; offset += 2) {
+    const sample = pcm.readInt16LE(offset);
+    const abs = Math.abs(sample);
+    if (abs > maxAbs) maxAbs = abs;
+    const normalized = sample / 32768;
+    sumSquares += normalized * normalized;
+    sampleCount += 1;
+  }
+  if (!sampleCount) return { meanDb: -Infinity, maxDb: -Infinity, sampleCount: 0 };
+  const rms = Math.sqrt(sumSquares / sampleCount);
+  return {
+    meanDb: rms > 0 ? 20 * Math.log10(rms) : -Infinity,
+    maxDb: maxAbs > 0 ? 20 * Math.log10(maxAbs / 32768) : -Infinity,
+    sampleCount,
+  };
+}
+
+export function isBargeInCandidate(pcmBytes, levels, thresholds) {
+  const minBytes = Number(thresholds?.minBytes ?? 0);
+  const minMeanDb = Number(thresholds?.minMeanDb ?? -Infinity);
+  const minMaxDb = Number(thresholds?.minMaxDb ?? -Infinity);
+  const requireBoth = Boolean(thresholds?.requireBoth);
+  if (pcmBytes < minBytes) return false;
+  if (requireBoth) return levels.meanDb >= minMeanDb && levels.maxDb >= minMaxDb;
+  return levels.meanDb >= minMeanDb || levels.maxDb >= minMaxDb;
+}
+
+export function bargeInThresholdsForMode(mode, base = {}) {
+  const minSeconds = Number(base.minSeconds ?? 1.4);
+  const minMeanDb = Number(base.minMeanDb ?? -30);
+  const minMaxDb = Number(base.minMaxDb ?? -14);
+  if (mode === 'conservative') {
+    const conservativeSeconds = Number(base.conservativeMinSeconds ?? Math.max(minSeconds, 1.8));
+    return {
+      minBytes: 48000 * 2 * 2 * conservativeSeconds,
+      minSeconds: conservativeSeconds,
+      minMeanDb: Number(base.conservativeMinMeanDb ?? Math.max(minMeanDb, -27)),
+      minMaxDb: Number(base.conservativeMinMaxDb ?? Math.max(minMaxDb, -12)),
+      mode: 'conservative',
+    };
+  }
+  return {
+    minBytes: 48000 * 2 * 2 * minSeconds,
+    minSeconds,
+    minMeanDb,
+    minMaxDb,
+    mode: 'normal',
+  };
+}
+
+export function sensitivityModeFromTranscript(text) {
+  const compact = String(text || '').toLowerCase().replace(/\s+/g, '');
+  if (!compact) return null;
+  // Do not treat complaints/questions that merely mention a mode as commands.
+  if (/(누가|왜|뭐|아니|안|하지마|말고|싫|바꾸랬|하랬|랬어|랬냐|\?)/u.test(compact)) return null;
+  if (/(실내|집|조용|평소|기본|일반).*(감도|모드).*(해|켜|바꿔|변경|설정)|감도(올려|높여|평소|기본|일반)(해|로|으로|켜|바꿔|변경|설정)?/u.test(compact)) {
+    return { mode: 'normal', reason: 'indoor' };
+  }
+  if (/(외부|밖|야외|시끄럽|소음|지하철|버스|길거리|카페).*(감도|모드|낮춰|보수|둔감).*(해|켜|바꿔|변경|설정)|감도(낮춰|내려)(해|줘|라|켜|바꿔|변경|설정)?|보수모드(해|켜|바꿔|변경|설정)/u.test(compact)) {
+    return { mode: 'conservative', reason: 'outdoor' };
+  }
+  return null;
+}
+
+export function isRepeatedNoiseTranscript(text) {
+  const compact = String(text || '')
+    .normalize('NFC')
+    .replace(/\s+/g, '')
+    .replace(/[\p{P}\p{S}_]+/gu, '');
+  if (!compact) return true;
+  // Keep common short-but-valid Korean utterances. These are frequent phone-call
+  // probes/answers and should not be erased after Whisper correctly hears them.
+  if (/^(안녕|안녕하세요|야|네|예|응|그래|좋아|오케이|okay|ok)$/iu.test(compact)) return false;
+  if (compact.length <= 1) return true;
+  if (/^(쒸|쉬|쉿|씁|흠|음|어|아|으|앗|악)$/u.test(compact)) return true;
+  if (compact.length <= 3 && !/(잠깐|멈춰|그만|중지|스톱|stop)/iu.test(compact)) return true;
+
+  // Repetition/low-unique-ratio filtering is for short Korean noise/hallucination
+  // fragments. English sentences often repeat ordinary letters/words ("the problem",
+  // "fuck you") and were being deleted here after Whisper recognized them correctly.
+  const hasLatin = /\p{Script=Latin}/u.test(compact);
+  const hasHangul = /\p{Script=Hangul}/u.test(compact);
+  if (hasLatin && !hasHangul) return false;
+
+  for (let size = 1; size <= Math.floor(compact.length / 2); size += 1) {
+    if (compact.length % size !== 0) continue;
+    const unit = compact.slice(0, size);
+    if (unit.repeat(compact.length / size) === compact) return true;
+  }
+  const chars = [...compact];
+  const uniqueRatio = new Set(chars).size / chars.length;
+  return chars.length >= 4 && uniqueRatio <= 0.35 && !/(잠깐|멈춰|그만|중지|스톱|stop)/iu.test(compact);
+}
+
+export function isExplicitBargeInTranscript(text) {
+  const compact = String(text || '')
+    .normalize('NFC')
+    .replace(/\s+/g, '')
+    .replace(/[\p{P}\p{S}_]+/gu, '')
+    .toLowerCase();
+  if (!compact || isRepeatedNoiseTranscript(compact)) return false;
+  return /(잠깐|멈춰|그만|중지|취소|끊어|스톱|스탑|stop|cancel|abort|shutup|quiet|silence|enough|stopit|stoptalking|말하지마|말그만|조용)/iu.test(compact);
+}
+
+export function shouldUseLivePlaybackBargeIn({ speaking, processing }) {
+  return Boolean(speaking && !processing);
+}
+
+export function createLiveBargeInMonitor({
+  minBytes,
+  minMeanDb,
+  minMaxDb,
+  requireBoth = false,
+  onConfirm,
+  log = () => {},
+}) {
+  const chunks = [];
+  let bytes = 0;
+  let confirmed = false;
+  return {
+    push(chunk) {
+      if (confirmed || !chunk?.length) return false;
+      chunks.push(chunk);
+      bytes += chunk.length;
+      if (bytes < minBytes) return false;
+      const levels = pcm16StereoLevels(Buffer.concat(chunks, bytes));
+      if (!isBargeInCandidate(bytes, levels, { minBytes, minMeanDb, minMaxDb, requireBoth })) {
+        log('live barge-in below volume threshold', 'pcmBytes', bytes, 'meanDb', levels.meanDb, 'maxDb', levels.maxDb);
+        return false;
+      }
+      confirmed = true;
+      onConfirm?.({ pcmBytes: bytes, levels });
+      return true;
+    },
+    get confirmed() {
+      return confirmed;
+    },
+    get bytes() {
+      return bytes;
+    },
+  };
+}