@lucas_zaia/agent-voice 1.0.0

package/src/core/handle.js

@@ -0,0 +1,94 @@
+// The only component that remembers or decides anything. Adapters hand it a
+// canonical event; it completes that event from state, applies the rules,
+// builds the sentence and dispatches to every active output.
+import { cleanSpeech } from './speech.js';
+import {
+  agentName, where as whereOf, durationPhrase, phraseTaskDone, phraseBackgroundDone, phraseNeedsInput,
+} from './phrases.js';
+
+const str = (v) => (typeof v === 'string' ? v : '');
+
+export async function speakAll(agent, session, sentence, ctx) {
+  ctx.state.cooldownStamp(agent, session);
+  for (const out of ctx.outputs) {
+    if (!out.speak) {
+      ctx.log(agent, session, `no such output: ${out.name}${out.reason ? ` (${out.reason})` : ''}`);
+      continue;
+    }
+    try {
+      await out.speak(sentence);
+      ctx.log(agent, session, `spoke via ${out.name}: ${sentence}`);
+    } catch (e) {
+      // "container down", "token missing" and "HTTP 401" must stay distinguishable
+      // from each other, and from a hook that simply chose to stay quiet.
+      const reason = String(e?.message ?? e).split(/\r?\n/)[0].slice(0, 120) || 'failed with no reason';
+      ctx.log(agent, session, `FAILED via ${out.name} (${reason}): ${sentence}`);
+    }
+  }
+}
+
+export async function handle(event, ctx) {
+  const e = event && typeof event === 'object' ? event : {};
+  const type = str(e.type);
+  const agent = str(e.agent);
+  const session = str(e.session_id);
+  if (!type || !agent || !session) {
+    ctx.log(agent || '?', session || '?', 'ignored: incomplete event');
+    return;
+  }
+
+  // session_name and project come straight from the agent (an AI-written title,
+  // a directory name) — never speech-safe by construction, so cleaned here once.
+  const clean = (t) => cleanSpeech(t, ctx.config.maxSpeechChars);
+  const who = agentName(agent);
+  const place = whereOf(session, clean(str(e.session_name)), clean(str(e.project)));
+  const text = str(e.text);
+  let sentence;
+
+  switch (type) {
+    case 'turn_start':
+      ctx.state.turnStart(agent, session, text);
+      ctx.log(agent, session, 'turn started');
+      return;
+
+    case 'task_done': {
+      const elapsed = ctx.state.turnElapsed(agent, session);
+      if (elapsed === null) {
+        ctx.log(agent, session, 'ignored: task_done with no turn marker');
+        return;
+      }
+      // The request came from turn_start; the stop hook never carries it.
+      const asked = ctx.state.turnText(agent, session);
+      ctx.state.turnClear(agent, session);
+      if (elapsed < ctx.config.minSeconds) {
+        ctx.log(agent, session, `silent (turn ${elapsed}s < ${ctx.config.minSeconds}s)`);
+        return;
+      }
+      sentence = phraseTaskDone(who, place, durationPhrase(elapsed), clean(asked));
+      break;
+    }
+
+    case 'background_done':
+      if (!ctx.state.cooldownOk(agent, session, ctx.config.cooldownSeconds)) {
+        ctx.log(agent, session, `silent (cooldown ${ctx.config.cooldownSeconds}s)`);
+        return;
+      }
+      // Background events fire often; a sentence with no content is noise.
+      if (!text) {
+        ctx.log(agent, session, 'silent (background_done with no content)');
+        return;
+      }
+      sentence = phraseBackgroundDone(who, place, clean(text));
+      break;
+
+    case 'needs_input':
+      sentence = phraseNeedsInput(who, place, clean(text));
+      break;
+
+    default:
+      ctx.log(agent, session, `ignored: unknown type ${type}`);
+      return;
+  }
+
+  await speakAll(agent, session, sentence, ctx);
+}

package/src/core/hash.js

@@ -0,0 +1,17 @@
+// POSIX `cksum` CRC, so state paths and spoken session colours stay identical
+// to the bash version (which shelled out to cksum). Not a security hash.
+const TABLE = new Uint32Array(256);
+for (let i = 0; i < 256; i++) {
+  let c = i << 24;
+  for (let k = 0; k < 8; k++) c = c & 0x80000000 ? (c << 1) ^ 0x04c11db7 : c << 1;
+  TABLE[i] = c >>> 0;
+}
+
+export function cksum(str) {
+  const bytes = Buffer.from(String(str), 'utf8');
+  let crc = 0;
+  const feed = (b) => { crc = ((crc << 8) ^ TABLE[((crc >>> 24) ^ b) & 0xff]) >>> 0; };
+  for (const b of bytes) feed(b);
+  for (let n = bytes.length; n > 0; n = Math.floor(n / 256)) feed(n & 0xff);
+  return (~crc) >>> 0;
+}

package/src/core/log.js

@@ -0,0 +1,24 @@
+// One line per firing. Without this, a hook that chose to stay silent and a
+// hook that died look identical from the outside.
+import { mkdirSync, appendFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const pad2 = (n) => String(n).padStart(2, '0');
+
+export function timestamp(d = new Date()) {
+  return `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())} ` +
+    `${pad2(d.getHours())}:${pad2(d.getMinutes())}:${pad2(d.getSeconds())}`;
+}
+
+export function formatLine(agent, session, message, d = new Date()) {
+  return `${timestamp(d)} ${String(agent).padEnd(12)} ${String(session).slice(0, 8).padEnd(10)} ${message}\n`;
+}
+
+export function log(stateDir, agent, session, message, d = new Date()) {
+  try {
+    mkdirSync(stateDir, { recursive: true });
+    appendFileSync(join(stateDir, 'events.log'), formatLine(agent, session, message, d));
+  } catch {
+    // The log is the last resort; there is nothing left to report a failure to.
+  }
+}

package/src/core/phrases.js

@@ -0,0 +1,54 @@
+// Everything spoken lives here, and it is the only file in Portuguese. Adding a
+// language, or changing what the speaker says, touches this file and nothing else.
+import { cksum } from './hash.js';
+import { stripTrailingPunct } from './speech.js';
+
+const AGENT_NAMES = { 'claude-code': 'Claude Code', codex: 'Codex', wrap: 'O comando' };
+
+// Spoken fallback identity when an agent cannot supply a session name.
+// "sessão zero quatro cê zero" is useless to hear; a colour is not.
+export const LABELS = ['azul', 'verde', 'vermelha', 'amarela', 'roxa', 'laranja', 'dourada', 'prateada', 'turquesa', 'violeta'];
+
+export const TEST_SENTENCE = 'Teste do agent voice. Se você está ouvindo, está funcionando.';
+
+export const agentName = (agent) => (Object.hasOwn(AGENT_NAMES, agent) ? AGENT_NAMES[agent] : agent);
+
+export const sessionLabel = (sessionId) => LABELS[cksum(sessionId) % LABELS.length];
+
+export function where(sessionId, name, project) {
+  if (name) return `na sessão ${name}`;
+  if (project) return `na sessão ${sessionLabel(sessionId)}, do projeto ${project}`;
+  return `na sessão ${sessionLabel(sessionId)}`;
+}
+
+export function durationPhrase(seconds) {
+  const minutes = Math.floor((seconds + 30) / 60);
+  return minutes <= 1 ? 'cerca de um minuto' : `cerca de ${minutes} minutos`;
+}
+
+export function phraseTaskDone(agent, place, duration, text) {
+  const s = `${agent} terminou ${place}, depois de ${duration}.`;
+  return text ? `${s} Você tinha pedido: ${stripTrailingPunct(text)}.` : s;
+}
+
+export function phraseBackgroundDone(agent, place, text) {
+  const s = `${agent} terminou um trabalho em segundo plano ${place}.`;
+  return text ? `${s} Era: ${stripTrailingPunct(text)}.` : s;
+}
+
+// Agent notices arrive in English. Speaking one verbatim after a Portuguese
+// sentence says the same thing twice, so known notices are translated — and the
+// one that merely restates the sentence is dropped. Unknown ones are kept.
+export function translateNotice(text) {
+  const marker = 'needs your permission to use ';
+  const at = text.lastIndexOf(marker);
+  if (at !== -1) return `, para usar o ${text.slice(at + marker.length)}`;
+  if (text.includes('needs your permission')) return '';
+  if (text.includes('waiting for your input')) return ', e está esperando sua resposta';
+  return `. ${text}`;
+}
+
+export function phraseNeedsInput(agent, place, text) {
+  const s = `${agent} precisa de você ${place}`;
+  return text ? `${s}${translateNotice(stripTrailingPunct(text))}.` : `${s}.`;
+}

package/src/core/speech.js

@@ -0,0 +1,30 @@
+// Turns written text into something worth hearing. A speaker reading a URL or
+// a card id out loud is unbearable, and markdown syntax is noise in speech.
+const EMOJI = /[\u{2190}-\u{27BF}\u{2300}-\u{23FF}\u{2B00}-\u{2BFF}\u{FE00}-\u{FE0F}\u{1F000}-\u{1FFFF}]/gu;
+
+export function cleanSpeech(input, max) {
+  const text = (typeof input === 'string' ? input : '')
+    .replace(/\n/g, ' ')
+    // Tags from agent-injected markup (<task-id>, <br/>): keep the text, drop the tag.
+    .replace(/<\/?[A-Za-z][\w-]*(\s[^<>]*)?\/?>/g, ' ')
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+    .replace(/https?:\/\/[^ ]*/g, '')
+    // File paths. Must run after the URL rule: by now every URL is gone, so this
+    // cannot eat half of one. Needs two slashes; a lone "/etc" is left alone.
+    .replace(/\/[^ ]*\/[^ ]*/g, '')
+    .replace(/\[#?[0-9]+\]\s*/g, '')
+    .replace(/[[\]]/g, '')
+    .replace(/[`*#>]/g, '')
+    .replace(/_/g, ' ')
+    .replace(EMOJI, '')
+    .replace(/\.{2,}/g, '.')
+    .replace(/\s+/g, ' ')
+    .replace(/^ /, '')
+    .replace(/ $/, '');
+  return Array.from(text).slice(0, max).join('');
+}
+
+// Used before joining two fragments, so "travados." + "." does not become "travados..".
+export function stripTrailingPunct(text) {
+  return String(text).replace(/[\s.!:;,-]+$/u, '');
+}

package/src/core/state.js

@@ -0,0 +1,56 @@
+// Per-session state, used by the core only. Keyed by agent and session so that
+// concurrent sessions — and concurrent agents — never clobber each other.
+// Layout is identical to the bash version, so existing state carries over.
+import { mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { cksum } from './hash.js';
+
+const segment = (raw) => {
+  const s = String(raw);
+  return `${s.replace(/[^a-zA-Z0-9_-]/g, '') || 'unknown'}_${cksum(s)}`;
+};
+
+const epochNow = () => Math.floor(Date.now() / 1000);
+
+export function createState(stateDir, now = epochNow) {
+  const path = (agent, session) => {
+    const dir = join(stateDir, segment(agent));
+    mkdirSync(dir, { recursive: true });
+    return join(dir, segment(session));
+  };
+  const read = (file) => {
+    try { return readFileSync(file, 'utf8'); } catch { return null; }
+  };
+  const readEpoch = (file) => {
+    const v = read(file)?.trim();
+    return v && /^[0-9]+$/.test(v) ? Number(v) : null;
+  };
+
+  return {
+    path,
+    turnStart(agent, session, text) {
+      const p = path(agent, session);
+      writeFileSync(`${p}.start`, String(now()));
+      writeFileSync(`${p}.text`, text ?? '');
+    },
+    turnElapsed(agent, session) {
+      const started = readEpoch(`${path(agent, session)}.start`);
+      return started === null ? null : Math.max(0, now() - started);
+    },
+    turnText(agent, session) {
+      return read(`${path(agent, session)}.text`) ?? '';
+    },
+    turnClear(agent, session) {
+      const p = path(agent, session);
+      rmSync(`${p}.start`, { force: true });
+      rmSync(`${p}.text`, { force: true });
+    },
+    cooldownStamp(agent, session) {
+      writeFileSync(`${path(agent, session)}.cooldown`, String(now()));
+    },
+    cooldownOk(agent, session, seconds) {
+      const last = readEpoch(`${path(agent, session)}.cooldown`);
+      return last === null || now() - last >= seconds;
+    },
+  };
+}

package/src/outputs/alexa.js

@@ -0,0 +1,66 @@
+// Makes an Echo speak through Home Assistant's notify.send_message service —
+// the same call the old falar.sh made, without needing that script.
+import { SPEAK_TIMEOUT_MS } from './run.js';
+
+export const type = 'alexa';
+
+const base = (url) => String(url ?? '').replace(/\/+$/, '');
+
+export const describe = (conf) => `${conf.entity} @ ${base(conf.url)}`;
+
+async function call(conf, path, init = {}, deps = {}) {
+  const doFetch = deps.fetch ?? fetch;
+  const timeoutMs = deps.timeoutMs ?? SPEAK_TIMEOUT_MS;
+  let res;
+  try {
+    res = await doFetch(`${base(conf.url)}${path}`, {
+      ...init,
+      headers: { Authorization: `Bearer ${conf.token}`, 'Content-Type': 'application/json' },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (e) {
+    if (e.name === 'TimeoutError' || e.name === 'AbortError') {
+      throw new Error(`Home Assistant did not answer within ${Math.round(timeoutMs / 1000)}s`);
+    }
+    throw new Error(`cannot reach Home Assistant at ${base(conf.url)} (${e.cause?.code ?? e.message})`);
+  }
+  if (res.status === 401) throw new Error('Home Assistant rejected the token (HTTP 401)');
+  if (!res.ok) throw new Error(`Home Assistant answered HTTP ${res.status}`);
+  return res;
+}
+
+export async function speak(sentence, conf, deps = {}) {
+  if (!conf.url || !conf.token || !conf.entity) throw new Error('alexa output is missing url, token or entity');
+  await call(conf, '/api/services/notify/send_message', {
+    method: 'POST',
+    body: JSON.stringify({ entity_id: conf.entity, message: sentence }),
+  }, deps);
+}
+
+export async function listNotifyEntities(conf, deps = {}) {
+  const res = await call(conf, '/api/states', {}, deps);
+  const states = await res.json();
+  return (Array.isArray(states) ? states : [])
+    .map((s) => s?.entity_id)
+    .filter((id) => typeof id === 'string' && id.startsWith('notify.'))
+    .sort();
+}
+
+export async function questions(prompt, current = {}, deps = {}) {
+  const url = base(await prompt.ask('Home Assistant URL', current.url ?? 'http://localhost:8123'));
+  // A saved token is never echoed back: Enter keeps it, the hint shows its end.
+  const tail = String(current.token ?? '').length >= 16 ? ` …${String(current.token).slice(-4)}` : '';
+  const saved = current.token ? ` [saved token${tail}, Enter keeps it]` : '';
+  const token = (await prompt.ask(`Long-lived access token (Home Assistant → your profile → Security)${saved}`, '')) || current.token || '';
+  const conf = { type, url, token, entity: '' };
+  await call(conf, '/api/', {}, deps);
+  const entities = await listNotifyEntities(conf, deps);
+  if (entities.length === 0) {
+    throw new Error('Home Assistant has no notify.* entities — is the Alexa Media Player integration set up?');
+  }
+  const ordered = [...entities.filter((e) => e.endsWith('_announce')), ...entities.filter((e) => !e.endsWith('_announce'))];
+  const def = Math.max(0, ordered.indexOf(current.entity));
+  const i = await prompt.choose('Which device should speak? (_announce plays a chime first)', ordered, def);
+  conf.entity = ordered[i];
+  return conf;
+}

package/src/outputs/command.js

@@ -0,0 +1,66 @@
+// Runs any command that makes noise. {text} in its arguments is replaced by the
+// sentence; without {text}, the sentence goes on stdin. No shell is involved.
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { run as runProcess, SPEAK_TIMEOUT_MS } from './run.js';
+
+export const type = 'command';
+
+export function parseCommandLine(line) {
+  const out = [];
+  let cur = '';
+  let quote = null;
+  let started = false;
+  for (const ch of String(line)) {
+    if (quote) {
+      if (ch === quote) quote = null;
+      else cur += ch;
+    } else if (ch === '"' || ch === "'") {
+      quote = ch;
+      started = true;
+    } else if (/\s/.test(ch)) {
+      if (started) out.push(cur);
+      cur = '';
+      started = false;
+    } else {
+      cur += ch;
+      started = true;
+    }
+  }
+  if (quote) throw new Error('unclosed quote in command');
+  if (started) out.push(cur);
+  return out;
+}
+
+// No shell means no ~ expansion, yet `~/softwares/falar.sh -a {text}` is what
+// people type. A leading ~, $HOME, ${HOME} or %USERPROFILE% in the command or
+// an argument is the home directory; the sentence is never expanded.
+const HOME_PREFIX = /^(?:~|\$HOME|\$\{HOME\}|%USERPROFILE%)(?=$|[\\/])/i;
+
+export function expandHome(arg, home = homedir()) {
+  const m = HOME_PREFIX.exec(arg);
+  if (!m) return arg;
+  const rest = arg.slice(m[0].length).replace(/^[\\/]+/, '');
+  return rest ? join(home, rest) : home;
+}
+
+export const describe = (conf) => (conf.argv ?? []).join(' ');
+
+export async function questions(prompt, current = {}) {
+  const line = await prompt.ask(
+    'Command that speaks a sentence ({text} marks where the sentence goes; without it, the sentence is sent on stdin)',
+    current.argv ? current.argv.join(' ') : '',
+  );
+  const argv = parseCommandLine(line);
+  if (argv.length === 0) throw new Error('a command is required');
+  return { type, argv };
+}
+
+export async function speak(sentence, conf, deps = {}) {
+  if (!Array.isArray(conf.argv) || conf.argv.length === 0) throw new Error('command output has no argv');
+  const [cmd, ...rest] = conf.argv.map((a) => expandHome(String(a), deps.home));
+  const placeholder = rest.some((a) => a.includes('{text}'));
+  const args = rest.map((a) => a.replaceAll('{text}', sentence));
+  const run = deps.run ?? runProcess;
+  await run(cmd, args, { input: placeholder ? '' : sentence, spawn: deps.spawn, timeoutMs: deps.timeoutMs ?? SPEAK_TIMEOUT_MS });
+}

package/src/outputs/index.js

@@ -0,0 +1,23 @@
+import * as alexa from './alexa.js';
+import * as command from './command.js';
+import * as local from './local.js';
+import { readOutputInstance } from '../config.js';
+
+export const OUTPUT_TYPES = { alexa, local, command };
+
+// Turns the active output names into speak() closures for the core. A name with
+// no usable instance gets speak: null, which the core logs as "no such output".
+export function resolveOutputs(names, env = process.env) {
+  return names.map((name) => {
+    let conf;
+    try {
+      conf = readOutputInstance(name, env);
+    } catch (e) {
+      return { name, speak: null, reason: e.message };
+    }
+    if (!conf) return { name, speak: null };
+    const mod = Object.hasOwn(OUTPUT_TYPES, conf.type) ? OUTPUT_TYPES[conf.type] : null;
+    if (!mod) return { name, speak: null, reason: `unknown output type ${conf.type}` };
+    return { name, speak: (sentence) => mod.speak(sentence, conf) };
+  });
+}

package/src/outputs/local.js

@@ -0,0 +1,87 @@
+// The computer's own voice: `say` on macOS, SAPI through PowerShell on Windows,
+// speech-dispatcher or eSpeak on Linux.
+import { run as runProcess, SPEAK_TIMEOUT_MS } from './run.js';
+import { findOnPath } from '../platform.js';
+
+export const type = 'local';
+
+// The sentence arrives on stdin, never spliced into the script, so no quoting
+// of user text is ever needed.
+const SAPI_SPEAK = [
+  '[Console]::InputEncoding = [Text.Encoding]::UTF8;',
+  'Add-Type -AssemblyName System.Speech;',
+  '$s = New-Object System.Speech.Synthesis.SpeechSynthesizer;',
+  'if ($env:AV_VOICE) { $s.SelectVoice($env:AV_VOICE) };',
+  '$s.Speak([Console]::In.ReadToEnd())',
+].join(' ');
+
+const SAPI_VOICES = [
+  'Add-Type -AssemblyName System.Speech;',
+  '(New-Object System.Speech.Synthesis.SpeechSynthesizer).GetInstalledVoices() |',
+  "ForEach-Object { $_.VoiceInfo.Culture.Name + '|' + $_.VoiceInfo.Name }",
+].join(' ');
+
+export function detectBackend(platform = process.platform, env = process.env, find = findOnPath) {
+  if (platform === 'darwin') return 'say';
+  if (platform === 'win32') return 'sapi';
+  for (const backend of ['spd-say', 'espeak-ng', 'espeak']) if (find(backend, env, platform)) return backend;
+  return null;
+}
+
+export function commandFor(backend, sentence, voice) {
+  switch (backend) {
+    case 'say':
+      return { cmd: 'say', args: voice ? ['-v', voice, sentence] : [sentence], input: '' };
+    case 'sapi':
+      return {
+        cmd: 'powershell.exe',
+        args: ['-NoProfile', '-NonInteractive', '-Command', SAPI_SPEAK],
+        input: sentence,
+        env: { ...process.env, AV_VOICE: voice ?? '' },
+      };
+    case 'spd-say':
+      return { cmd: 'spd-say', args: ['-w', '-l', voice || 'pt', sentence], input: '' };
+    case 'espeak-ng':
+    case 'espeak':
+      return { cmd: backend, args: ['-v', voice || 'pt-br', sentence], input: '' };
+    default:
+      throw new Error(`unknown local voice backend: ${backend}`);
+  }
+}
+
+export async function defaultVoice(backend, deps = {}) {
+  const run = deps.run ?? runProcess;
+  try {
+    if (backend === 'say') {
+      const out = await run('say', ['-v', '?']);
+      const line = out.split('\n').find((l) => /\bpt_BR\b/.test(l));
+      return line ? line.trim().split(/\s{2,}/)[0] : '';
+    }
+    if (backend === 'sapi') {
+      const out = await run('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', SAPI_VOICES]);
+      const line = out.split(/\r?\n/).find((l) => l.startsWith('pt-BR|'));
+      return line ? line.slice('pt-BR|'.length).trim() : '';
+    }
+  } catch {
+    return '';
+  }
+  return backend === 'spd-say' ? 'pt' : 'pt-br';
+}
+
+export const describe = (conf) => `${conf.backend}${conf.voice ? ` (${conf.voice})` : ''}`;
+
+export async function questions(prompt, current = {}, deps = {}) {
+  const backend = detectBackend(deps.platform, deps.env, deps.find);
+  if (!backend) {
+    throw new Error('no local voice found — install espeak-ng (e.g. apt install espeak-ng) or speech-dispatcher');
+  }
+  const suggested = current.backend === backend && current.voice ? current.voice : await defaultVoice(backend, deps);
+  const voice = await prompt.ask(`Voice for ${backend} (Enter keeps the suggestion)`, suggested);
+  return { type, backend, voice };
+}
+
+export async function speak(sentence, conf, deps = {}) {
+  const { cmd, args, input, env } = commandFor(conf.backend, sentence, conf.voice);
+  const run = deps.run ?? runProcess;
+  await run(cmd, args, { input, env, spawn: deps.spawn, timeoutMs: deps.timeoutMs ?? SPEAK_TIMEOUT_MS });
+}

package/src/outputs/run.js

@@ -0,0 +1,53 @@
+// Runs a speaker process with a hard timeout. A hook that hangs is worse than
+// one that fails, so every child gets killed eventually.
+import { spawn as nodeSpawn } from 'node:child_process';
+import { spawnCommand, spawnErrorMessage } from '../spawn-command.js';
+
+// Every output gets at most this long. Hooks run outputs one after another and
+// agents kill a hook at its timeout (60s for the async hooks), so three slow
+// outputs still leave time to log why they failed.
+export const SPEAK_TIMEOUT_MS = 15000;
+
+export function run(cmd, args, { input = '', timeoutMs = SPEAK_TIMEOUT_MS, env, spawn = nodeSpawn, platform = process.platform } = {}) {
+  return new Promise((resolve, reject) => {
+    const startError = (e) => new Error(spawnErrorMessage(e, cmd, env ?? process.env, platform));
+    let child;
+    try {
+      child = spawnCommand(cmd, args, { stdio: ['pipe', 'pipe', 'pipe'], env, windowsHide: true }, { spawn, platform });
+    } catch (e) {
+      reject(startError(e));
+      return;
+    }
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    let grace = null;
+    const finish = (fn, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      clearTimeout(grace);
+      fn(value);
+    };
+    const timer = setTimeout(() => {
+      child.kill();
+      finish(reject, new Error(`timed out after ${Math.round(timeoutMs / 1000)}s`));
+    }, timeoutMs);
+    child.stdout.on('data', (d) => { stdout += d; });
+    child.stderr.on('data', (d) => { stderr += d; });
+    child.on('error', (e) => finish(reject, startError(e)));
+    // Done when the speaker exits, not when its pipes close: one that leaves
+    // audio playing in the background (`sh -c "play x &"`) hands the pipes to
+    // that player. Output still in flight gets a moment to arrive.
+    const done = (code, signal) => {
+      child.stdout.destroy();
+      child.stderr.destroy();
+      if (code === 0) finish(resolve, stdout);
+      else finish(reject, new Error(stderr.trim().split(/\r?\n/)[0] || `exited ${code ?? signal} with no output`));
+    };
+    child.on('exit', (code, signal) => { grace = setTimeout(() => done(code, signal), 200); });
+    child.on('close', done);
+    child.stdin.on('error', () => {});
+    child.stdin.end(input);
+  });
+}

package/src/platform.js

@@ -0,0 +1,54 @@
+// Everything that differs between macOS, Windows and Linux lives here.
+import { homedir } from 'node:os';
+import path, { join } from 'node:path';
+import { existsSync } from 'node:fs';
+
+export function configDir(env = process.env, platform = process.platform, home = homedir()) {
+  if (env.AV_CONFIG_DIR) return env.AV_CONFIG_DIR;
+  if (platform === 'win32') return join(env.APPDATA || join(home, 'AppData', 'Roaming'), 'agent-voice');
+  if (platform === 'darwin') return join(home, 'Library', 'Application Support', 'agent-voice');
+  return join(env.XDG_CONFIG_HOME || join(home, '.config'), 'agent-voice');
+}
+
+export function stateDir(env = process.env, platform = process.platform, home = homedir()) {
+  if (env.AV_STATE_DIR) return env.AV_STATE_DIR;
+  if (platform === 'win32') return join(env.LOCALAPPDATA || join(home, 'AppData', 'Local'), 'agent-voice');
+  if (platform === 'darwin') return join(home, 'Library', 'Application Support', 'agent-voice', 'state');
+  return join(env.XDG_STATE_HOME || join(home, '.local', 'state'), 'agent-voice');
+}
+
+// Windows environment names are case-insensitive, but a copied env object
+// ({ ...process.env }) is not: PATH may arrive as "Path".
+export function envValue(env, name, platform = process.platform) {
+  if (env[name] !== undefined || platform !== 'win32') return env[name];
+  const key = Object.keys(env).find((k) => k.toUpperCase() === name);
+  return key === undefined ? undefined : env[key];
+}
+
+// Where the OS would find `cmd`. On Windows this follows cmd.exe: a name that
+// already carries a PATHEXT extension is taken as is, otherwise each PATHEXT
+// extension is tried — so npm's extensionless sh script never wins over its
+// .cmd twin. A name containing a separator is checked where it points.
+export function findOnPath(cmd, env = process.env, platform = process.platform, exists = existsSync) {
+  const win = platform === 'win32';
+  const p = win ? path.win32 : path.posix;
+  const name = String(cmd ?? '');
+  if (!name) return null;
+  let exts = [''];
+  if (win) {
+    const pathext = (envValue(env, 'PATHEXT', platform) || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean).map((e) => e.toLowerCase());
+    // Windows file lookup is case-insensitive; lower-case keeps the result predictable.
+    if (!pathext.includes(p.extname(name).toLowerCase())) exts = pathext;
+  }
+  const hasDir = win ? /[\\/]/.test(name) : name.includes('/');
+  const dirs = hasDir
+    ? ['']
+    : (envValue(env, 'PATH', platform) ?? '').split(p.delimiter).map((d) => d.replace(/^"(.*)"$/, '$1')).filter(Boolean);
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      const candidate = dir ? p.join(dir, name + ext) : name + ext;
+      if (exists(candidate)) return candidate;
+    }
+  }
+  return null;
+}