@lucas_zaia/agent-voice 1.0.0

package/src/cli/main.js

@@ -0,0 +1,69 @@
+import { runNotify, readStdin } from './notify.js';
+import { createPrompter, isCancelled } from './prompt.js';
+import { runWrap } from './wrap.js';
+import { runOutput, testActive } from './output.js';
+import { runConfig } from './config.js';
+import { runConnect, runDisconnect } from './connect.js';
+import { runStatus } from './status.js';
+import { runSetup } from './setup.js';
+
+const HELP = `Usage: agent-voice <command>
+
+  setup                             guided setup: connect agents, add a speaker, test it
+  connect <claude-code|codex>       add agent-voice's hooks to the agent (asks first; --yes skips)
+  disconnect <claude-code|codex>    remove agent-voice's hooks from the agent
+  output add <alexa|local|command> [name]
+  output list | remove <name> | enable <name> | disable <name> | test [name]
+  wrap [--name <label>] -- <command> [args...]
+                                    announce when any command finishes
+  status                            agents, outputs, settings and the latest log lines
+  config get [key] | set <key> <value>
+                                    keys: minSeconds, cooldownSeconds, maxSpeechChars
+  test                              speak a test sentence on every active output
+  notify <agent> <subcommand>       hook entry point (called by your agent, not by you)`;
+
+export function defaultIO(env = process.env) {
+  return {
+    env,
+    out: (s) => process.stdout.write(`${s}\n`),
+    err: (s) => process.stderr.write(`${s}\n`),
+    prompt: null,
+  };
+}
+
+// Each later task registers its command here: name → async (args, io) => exit code.
+const COMMANDS = {
+  setup: runSetup,
+  wrap: (args, io) => runWrap(args, { env: io.env }),
+  output: runOutput,
+  config: async (args, io) => runConfig(args, io),
+  test: async (args, io) => testActive(io),
+  connect: runConnect,
+  disconnect: runDisconnect,
+  status: runStatus,
+};
+
+export async function main(argv, io = defaultIO()) {
+  const [cmd, ...rest] = argv;
+  if (cmd === 'notify') return runNotify(rest, { input: await readStdin(), env: io.env });
+  if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+    io.out(HELP);
+    return 0;
+  }
+  const run = Object.hasOwn(COMMANDS, cmd) ? COMMANDS[cmd] : null;
+  if (!run) {
+    io.err(`agent-voice: unknown command "${cmd}". Run "agent-voice help".`);
+    return 1;
+  }
+  let prompter = null;
+  const withPrompt = { ...io, get prompt() { return io.prompt ?? (prompter ??= createPrompter()); } };
+  try {
+    return await run(rest, withPrompt);
+  } catch (e) {
+    io.err(`agent-voice: ${e.message}`);
+    // 130 is what a shell reports for a command stopped by Ctrl+C.
+    return isCancelled(e) && e.signal === 'SIGINT' ? 130 : 1;
+  } finally {
+    prompter?.close();
+  }
+}

package/src/cli/notify.js

@@ -0,0 +1,72 @@
+// The hook entry point. Exits 0 in every scenario, on purpose: a hook that
+// hangs or fails is worse than one that does not exist. The log is the only
+// place a failure is reported.
+import { ADAPTERS } from '../adapters/index.js';
+import { createContext } from '../core/context.js';
+import { handle } from '../core/handle.js';
+import { log } from '../core/log.js';
+import { stateDir } from '../platform.js';
+
+// Bounded: an agent that leaves stdin open without writing must not hang us.
+export function readStdin(stream = process.stdin, timeoutMs = 3000) {
+  if (stream.isTTY) return Promise.resolve('');
+  return new Promise((resolve) => {
+    let data = '';
+    let done = false;
+    const finish = () => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      stream.removeAllListeners?.('data');
+      stream.destroy?.();
+      resolve(data);
+    };
+    const timer = setTimeout(finish, timeoutMs);
+    stream.setEncoding?.('utf8');
+    stream.on('data', (chunk) => { data += chunk; });
+    stream.on('end', finish);
+    stream.on('error', finish);
+  });
+}
+
+const errorLine = (e) => `error: ${String(e?.message ?? e).split(/\r?\n/)[0].slice(0, 200)}`;
+
+export async function runNotify(args, { input = '', env = process.env, write = (s) => process.stdout.write(s) } = {}) {
+  const [agent = '', sub = ''] = args;
+  const fallbackLog = (a, s, m) => log(stateDir(env), a, s, m);
+  try {
+    if (!agent || !sub) {
+      fallbackLog(agent || '?', '-', 'ignored: usage is notify <agent> <subcommand>');
+      return 0;
+    }
+    const adapter = Object.hasOwn(ADAPTERS, agent) ? ADAPTERS[agent] : null;
+    if (!adapter) {
+      fallbackLog(agent, '-', `no adapter for ${agent}`);
+      return 0;
+    }
+    const reply = adapter.hookReply(sub);
+    if (reply) write(reply);
+    let payload = {};
+    try { payload = JSON.parse(input); } catch { /* garbage in: the core logs the incomplete event */ }
+    const event = adapter.translate(sub, payload);
+    if (!event) return 0;
+    await handle(event, createContext(env));
+  } catch (e) {
+    fallbackLog(agent || '?', '-', errorLine(e));
+  }
+  return 0;
+}
+
+// The notify process must exit 0 even for failures no try/catch can see: an
+// agent that closes our stdout before we write (async EPIPE), or a stray
+// error from a callback. They are logged, like every other failure.
+export function guardNotifyProcess(args, env = process.env, proc = process) {
+  const agent = args[0] || '?';
+  const report = (e) => {
+    log(stateDir(env), agent, '-', errorLine(e));
+    proc.exitCode = 0;
+  };
+  proc.stdout.on('error', () => { /* the agent stopped listening; nothing to tell it */ });
+  proc.on('uncaughtException', report);
+  proc.on('unhandledRejection', report);
+}

package/src/cli/output.js

@@ -0,0 +1,121 @@
+import { OUTPUT_TYPES } from '../outputs/index.js';
+import {
+  loadConfig, readStoredConfig, saveConfig, readOutputInstance, writeOutputInstance,
+  removeOutputInstance, listOutputInstances, isValidOutputName, outputInstanceExists,
+} from '../config.js';
+import { TEST_SENTENCE } from '../core/phrases.js';
+
+const USAGE = 'usage: agent-voice output add <alexa|local|command> [name] | list | remove <name> | enable <name> | disable <name> | test [name]';
+
+const storedOutputs = (env) => {
+  const list = readStoredConfig(env).outputs;
+  return Array.isArray(list) ? list : [];
+};
+
+export function enableOutput(name, env) {
+  if (!readOutputInstance(name, env)) throw new Error(`no output named "${name}"`);
+  const list = storedOutputs(env);
+  if (!list.includes(name)) saveConfig({ outputs: [...list, name] }, env);
+}
+
+export function disableOutput(name, env) {
+  saveConfig({ outputs: storedOutputs(env).filter((n) => n !== name) }, env);
+}
+
+export function nextFreeName(type, env) {
+  let name = type;
+  for (let i = 2; readOutputInstance(name, env); i++) name = `${type}-${i}`;
+  return name;
+}
+
+const typeModule = (type) => {
+  if (!Object.hasOwn(OUTPUT_TYPES, type ?? '')) {
+    throw new Error(`unknown output type "${type}" (available: ${Object.keys(OUTPUT_TYPES).join(', ')})`);
+  }
+  return OUTPUT_TYPES[type];
+};
+
+export async function addOutput(type, name, { env, out, prompt, deps }) {
+  const mod = typeModule(type);
+  const finalName = name || nextFreeName(type, env);
+  if (!isValidOutputName(finalName)) throw new Error(`invalid output name "${finalName}" (use a-z, 0-9 and -)`);
+  const current = readOutputInstance(finalName, env) ?? {};
+  if (current.type && current.type !== type) throw new Error(`output "${finalName}" already exists with type ${current.type}`);
+  const conf = await mod.questions(prompt, current, deps);
+  writeOutputInstance(finalName, conf, env);
+  enableOutput(finalName, env);
+  out(`Saved output "${finalName}" (${mod.describe(conf)}) and enabled it.`);
+  return finalName;
+}
+
+// Reports instead of throwing, so `test` goes on to the next output.
+export async function testOutput(name, { env, out, deps }) {
+  try {
+    const conf = readOutputInstance(name, env);
+    if (!conf) throw new Error(`no output named "${name}"`);
+    if (!Object.hasOwn(OUTPUT_TYPES, conf.type ?? '')) throw new Error(`unknown output type "${conf.type}"`);
+    await OUTPUT_TYPES[conf.type].speak(TEST_SENTENCE, conf, deps);
+    out(`ok    ${name}`);
+    return true;
+  } catch (e) {
+    out(`FAIL  ${name}: ${e.message}`);
+    return false;
+  }
+}
+
+export async function testActive(io) {
+  const names = loadConfig(io.env).outputs;
+  if (names.length === 0) throw new Error('no active outputs — add one with: agent-voice output add <alexa|local|command>');
+  let ok = true;
+  for (const name of names) ok = (await testOutput(name, io)) && ok;
+  return ok ? 0 : 1;
+}
+
+export async function runOutput(args, io) {
+  const [sub, a, b] = args;
+  const { env, out } = io;
+  switch (sub) {
+    case 'add': {
+      const name = await addOutput(a, b, io);
+      return (await testOutput(name, io)) ? 0 : 1;
+    }
+    case 'list': {
+      const active = loadConfig(env).outputs;
+      const all = listOutputInstances(env);
+      if (all.length === 0) {
+        out('No outputs yet. Add one with: agent-voice output add <alexa|local|command>');
+        return 0;
+      }
+      for (const { name, conf, error } of all) {
+        const mark = active.includes(name) ? '*' : ' ';
+        const what = conf ? `${String(conf.type).padEnd(8)} ${Object.hasOwn(OUTPUT_TYPES, conf.type) ? OUTPUT_TYPES[conf.type].describe(conf) : '(unknown type)'}` : `broken   ${error}`;
+        out(`${mark} ${name.padEnd(16)} ${what}`);
+      }
+      out('(* = enabled)');
+      return 0;
+    }
+    case 'remove':
+      if (!a) throw new Error(USAGE);
+      if (!isValidOutputName(a)) throw new Error(`invalid output name "${a}" (use a-z, 0-9 and -)`);
+      // An enabled name with no instance ("missing" in status) can be removed too.
+      if (!outputInstanceExists(a, env) && !storedOutputs(env).includes(a)) throw new Error(`no output named "${a}"`);
+      removeOutputInstance(a, env);
+      disableOutput(a, env);
+      out(`Removed output "${a}".`);
+      return 0;
+    case 'enable':
+      if (!a) throw new Error(USAGE);
+      enableOutput(a, env);
+      out(`Enabled "${a}".`);
+      return 0;
+    case 'disable':
+      if (!a) throw new Error(USAGE);
+      disableOutput(a, env);
+      out(`Disabled "${a}".`);
+      return 0;
+    case 'test':
+      return a ? ((await testOutput(a, io)) ? 0 : 1) : testActive(io);
+    default:
+      throw new Error(USAGE);
+  }
+}

package/src/cli/prompt.js

@@ -0,0 +1,75 @@
+// Interactive questions over readline. Commands receive this through io.prompt,
+// so tests can swap in a scripted prompter.
+//
+// Lines are queued as they arrive rather than read per question: piped input
+// (`printf 'y\n3\n' | agent-voice setup`) delivers every line at once, before
+// most questions are asked. When input ends (EOF, Ctrl+D) or Ctrl+C is pressed,
+// every question still waiting — and every later one — fails with a
+// "cancelled" error, which main turns into one line and an exit code.
+import { createInterface } from 'node:readline';
+
+export const cancelledError = (signal) => Object.assign(new Error('cancelled'), { code: 'CANCELLED', signal });
+export const isCancelled = (e) => e?.code === 'CANCELLED';
+
+export function createPrompter({ input = process.stdin, output = process.stdout, terminal } = {}) {
+  const rl = createInterface({ input, output, terminal: terminal ?? Boolean(input.isTTY && output.isTTY) });
+  const lines = [];
+  const waiting = [];
+  let ended = null;
+  let closed = false;
+  const end = (error) => {
+    ended ??= error;
+    // A question is on screen with the cursor after it; the error goes below.
+    if (waiting.length) output.write('\n');
+    for (const w of waiting.splice(0)) w.reject(ended);
+  };
+  rl.on('line', (line) => {
+    const w = waiting.shift();
+    if (w) w.resolve(line);
+    else lines.push(line);
+  });
+  rl.on('SIGINT', () => {
+    end(cancelledError('SIGINT'));
+    rl.close();
+  });
+  rl.on('close', () => {
+    closed = true;
+    end(cancelledError());
+  });
+
+  const question = (text) => {
+    // Through readline while it is open, so redrawing the line (backspace in
+    // a terminal) keeps the question on screen.
+    if (closed) output.write(text);
+    else {
+      rl.setPrompt(text);
+      rl.prompt();
+    }
+    if (lines.length) return Promise.resolve(lines.shift());
+    if (ended) return Promise.reject(ended);
+    return new Promise((resolve, reject) => waiting.push({ resolve, reject }));
+  };
+
+  return {
+    async ask(q, def = '') {
+      const answer = (await question(def ? `${q} [${def}]: ` : `${q}: `)).trim();
+      return answer || def;
+    },
+    async confirm(q, def = true) {
+      const answer = (await question(`${q} ${def ? '[Y/n]' : '[y/N]'} `)).trim().toLowerCase();
+      return answer ? answer.startsWith('y') || answer.startsWith('s') : def;
+    },
+    async choose(q, options, def = 0) {
+      output.write(`${q}\n`);
+      options.forEach((o, i) => output.write(`  ${i + 1}) ${o}\n`));
+      for (;;) {
+        const answer = (await question(`Choose 1-${options.length} [${def + 1}]: `)).trim();
+        if (!answer) return def;
+        const n = Number(answer);
+        if (Number.isInteger(n) && n >= 1 && n <= options.length) return n - 1;
+        output.write('Not a valid choice.\n');
+      }
+    },
+    close() { rl.close(); },
+  };
+}

package/src/cli/setup.js

@@ -0,0 +1,71 @@
+// The front door: connect the agents found on this machine, add one speaker,
+// prove it speaks. Safe to re-run — it only offers what is still missing.
+import { ADAPTERS } from '../adapters/index.js';
+import { fileStatus } from '../adapters/hooks-json.js';
+import { OUTPUT_TYPES } from '../outputs/index.js';
+import { loadConfig, readOutputInstance, removeOutputInstance } from '../config.js';
+import { connectAgent } from './connect.js';
+import { addOutput, testOutput, disableOutput } from './output.js';
+import { isCancelled } from './prompt.js';
+
+const LABELS = {
+  alexa: 'alexa    an Echo, through Home Assistant',
+  local: "local    this computer's own voice",
+  command: 'command  any command that speaks a sentence',
+};
+
+export async function runSetup(args, io) {
+  const { env, out, prompt } = io;
+  out('agent-voice setup');
+  out('');
+
+  const found = Object.values(ADAPTERS).filter((a) => a.detect(env));
+  if (found.length === 0) {
+    out('No supported agent found (Claude Code, Codex). Any other CLI works through: agent-voice wrap -- <command>');
+  }
+  for (const adapter of found) {
+    if (fileStatus(adapter.configFile(env), adapter.name, adapter.hooks) === 'connected') {
+      out(`${adapter.name}: already connected.`);
+      continue;
+    }
+    // One agent's broken config file must not keep the others from connecting.
+    try {
+      await connectAgent(adapter, { env, out, prompt, yes: false });
+    } catch (e) {
+      if (isCancelled(e)) throw e;
+      out(`${adapter.name}: could not connect — ${e.message}`);
+    }
+  }
+  out('');
+
+  const active = loadConfig(env).outputs.filter((n) => readOutputInstance(n, env));
+  let wantOutput = active.length === 0 || await prompt.confirm(`Active outputs: ${active.join(', ')}. Add another?`, false);
+  const types = Object.keys(OUTPUT_TYPES);
+
+  while (wantOutput) {
+    const i = await prompt.choose('How should agent-voice speak?', types.map((t) => LABELS[t] ?? t), 0);
+    let name;
+    try {
+      name = await addOutput(types[i], undefined, io);
+    } catch (e) {
+      if (isCancelled(e)) throw e;
+      out(`Could not set up ${types[i]}: ${e.message}`);
+      if (!(await prompt.confirm('Try again?', true))) break;
+      continue;
+    }
+    out('Speaking a test sentence…');
+    const spoke = await testOutput(name, io);
+    if (spoke && await prompt.confirm('Did you hear it?', true)) {
+      wantOutput = false;
+    } else {
+      removeOutputInstance(name, env);
+      disableOutput(name, env);
+      out(`Removed "${name}".`);
+      if (!(await prompt.confirm('Try again?', true))) break;
+    }
+  }
+
+  out('');
+  out('Done. Check everything with: agent-voice status');
+  return 0;
+}

package/src/cli/status.js

@@ -0,0 +1,43 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ADAPTERS } from '../adapters/index.js';
+import { fileStatus } from '../adapters/hooks-json.js';
+import { loadConfig, listOutputInstances, NUMERIC_KEYS } from '../config.js';
+import { OUTPUT_TYPES } from '../outputs/index.js';
+
+export async function runStatus(args, { env, out }) {
+  const cfg = loadConfig(env);
+
+  out('Agents');
+  for (const a of Object.values(ADAPTERS)) {
+    const state = a.detect(env) ? fileStatus(a.configFile(env), a.name, a.hooks) : 'not installed';
+    const hint = state === 'legacy' ? ' (old bash hooks — run "agent-voice connect ' + a.name + '" to upgrade)' : '';
+    out(`  ${a.name.padEnd(12)} ${state}${hint}`);
+  }
+
+  out('Outputs (* = enabled)');
+  const instances = listOutputInstances(env);
+  const known = new Set(instances.map((i) => i.name));
+  for (const { name, conf, error } of instances) {
+    const mark = cfg.outputs.includes(name) ? '*' : ' ';
+    const what = conf && Object.hasOwn(OUTPUT_TYPES, conf.type)
+      ? `${conf.type.padEnd(8)} ${OUTPUT_TYPES[conf.type].describe(conf)}`
+      : `broken   ${error ?? `unknown type ${conf?.type}`}`;
+    out(`  ${mark} ${name.padEnd(16)} ${what}`);
+  }
+  for (const name of cfg.outputs.filter((n) => !known.has(n))) {
+    out(`  * ${name.padEnd(16)} (missing — enabled but not configured)`);
+  }
+  if (instances.length === 0 && cfg.outputs.length === 0) out('  none — add one with: agent-voice output add <alexa|local|command>');
+
+  out('Settings');
+  for (const k of Object.keys(NUMERIC_KEYS)) out(`  ${k}=${cfg[k]}`);
+
+  const logFile = join(cfg.stateDir, 'events.log');
+  out(`Log (${logFile})`);
+  let lines = [];
+  try { lines = readFileSync(logFile, 'utf8').trimEnd().split('\n').filter(Boolean); } catch { /* no log yet */ }
+  if (lines.length === 0) out('  (empty)');
+  for (const line of lines.slice(-10)) out(`  ${line}`);
+  return 0;
+}

package/src/cli/wrap.js

@@ -0,0 +1,73 @@
+// For agents with no hooks: run the command, marking the turn's start and end.
+// The core applies the usual rules, so a short command stays silent.
+import { spawn as nodeSpawn } from 'node:child_process';
+import { constants } from 'node:os';
+import { createContext } from '../core/context.js';
+import { handle } from '../core/handle.js';
+import { projectOf } from '../adapters/common.js';
+import { spawnCommand, spawnErrorMessage } from '../spawn-command.js';
+
+const USAGE = 'usage: agent-voice wrap [--name <label>] -- <command> [args...]';
+
+export function parseWrapArgs(args) {
+  let name = '';
+  let i = 0;
+  while (i < args.length && args[i] !== '--') {
+    if (args[i] === '--name') {
+      name = args[i + 1] ?? '';
+      i += 2;
+      continue;
+    }
+    throw new Error(`wrap: unknown option ${args[i]} (${USAGE})`);
+  }
+  const command = args.slice(i + 1);
+  if (i >= args.length || command.length === 0) throw new Error(USAGE);
+  return { name, command };
+}
+
+export async function runWrap(args, {
+  env = process.env, spawn = nodeSpawn, platform = process.platform, cwd = process.cwd(), pid = process.pid, notify,
+  err = (s) => process.stderr.write(`${s}\n`),
+} = {}) {
+  const { name, command } = parseWrapArgs(args);
+  const emit = notify ?? (async (event) => {
+    try { await handle(event, createContext(env)); } catch { /* announcing must never break the wrapped command */ }
+  });
+  const base = { agent: 'wrap', session_id: `wrap-${pid}`, session_name: name, project: projectOf(cwd) };
+
+  await emit({ ...base, type: 'turn_start', text: command.join(' ') });
+
+  const code = await new Promise((resolve) => {
+    let child;
+    let settled = false;
+    // Ctrl+C already reaches the child through the terminal; the parent just
+    // must not die first. SIGTERM is forwarded.
+    const onInt = () => {};
+    const onTerm = () => { try { child?.kill('SIGTERM'); } catch { /* already gone */ } };
+    const finish = (c) => {
+      if (settled) return;
+      settled = true;
+      process.off('SIGINT', onInt);
+      process.off('SIGTERM', onTerm);
+      resolve(c);
+    };
+    process.on('SIGINT', onInt);
+    process.on('SIGTERM', onTerm);
+    try {
+      // No shell on any OS: `git commit -m "fix a & b"` must commit, not run b.
+      child = spawnCommand(command[0], command.slice(1), { stdio: 'inherit', env }, { spawn, platform });
+    } catch (e) {
+      err(`agent-voice wrap: ${spawnErrorMessage(e, command[0], env, platform)}`);
+      finish(127);
+      return;
+    }
+    child.on('error', (e) => {
+      err(`agent-voice wrap: ${spawnErrorMessage(e, command[0], env, platform)}`);
+      finish(127);
+    });
+    child.on('exit', (c, signal) => finish(c ?? 128 + (constants.signals[signal] ?? 0)));
+  });
+
+  await emit({ ...base, type: 'task_done', text: '' });
+  return code;
+}

package/src/config.js

@@ -0,0 +1,98 @@
+// Precedence: built-in defaults < config.json < AV_* environment variables.
+// The environment wins so tests (and one-off runs) never touch real config.
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, rmSync, chmodSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { configDir, stateDir } from './platform.js';
+
+export const DEFAULTS = Object.freeze({ minSeconds: 30, cooldownSeconds: 120, maxSpeechChars: 90, outputs: [] });
+
+export const NUMERIC_KEYS = Object.freeze({
+  minSeconds: 'AV_MIN_SECONDS',
+  cooldownSeconds: 'AV_COOLDOWN_SECONDS',
+  maxSpeechChars: 'AV_MAX_SPEECH_CHARS',
+});
+
+const NAME_RE = /^[a-z0-9][a-z0-9-]{0,39}$/;
+export const isValidOutputName = (name) => typeof name === 'string' && NAME_RE.test(name);
+
+function readJson(file) {
+  let text;
+  try {
+    text = readFileSync(file, 'utf8');
+  } catch (e) {
+    if (e.code === 'ENOENT') return null;
+    throw e;
+  }
+  try {
+    return JSON.parse(text.replace(/^\uFEFF/, ''));
+  } catch (e) {
+    throw new Error(`${file}: invalid JSON (${e.message})`);
+  }
+}
+
+function writeJson(file, value, mode) {
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`, mode ? { mode } : undefined);
+  if (mode) {
+    try { chmodSync(file, mode); } catch { /* not supported on this OS */ }
+  }
+}
+
+const configFile = (env) => join(configDir(env), 'config.json');
+const instanceFile = (name, env) => join(configDir(env), 'outputs', `${name}.json`);
+
+export function readStoredConfig(env = process.env) {
+  const stored = readJson(configFile(env)) ?? {};
+  if (typeof stored !== 'object' || Array.isArray(stored)) {
+    throw new Error(`${configFile(env)}: expected a JSON object`);
+  }
+  return stored;
+}
+
+export function loadConfig(env = process.env) {
+  const cfg = { ...DEFAULTS, ...readStoredConfig(env) };
+  for (const [key, envName] of Object.entries(NUMERIC_KEYS)) {
+    // A hand-edited "30s" or 1.5 must not reach the core as a threshold.
+    if (!Number.isSafeInteger(cfg[key]) || cfg[key] < 0) cfg[key] = DEFAULTS[key];
+    if (/^[0-9]+$/.test(env[envName] ?? '')) cfg[key] = Number(env[envName]);
+  }
+  if (env.AV_OUTPUTS !== undefined) cfg.outputs = env.AV_OUTPUTS.split(/\s+/).filter(Boolean);
+  cfg.outputs = Array.isArray(cfg.outputs) ? cfg.outputs.filter((n) => typeof n === 'string') : [];
+  return { ...cfg, configDir: configDir(env), stateDir: stateDir(env) };
+}
+
+export function saveConfig(patch, env = process.env) {
+  const next = { ...readStoredConfig(env), ...patch };
+  writeJson(configFile(env), next);
+  return next;
+}
+
+export function readOutputInstance(name, env = process.env) {
+  if (!isValidOutputName(name)) return null;
+  return readJson(instanceFile(name, env));
+}
+
+export function writeOutputInstance(name, conf, env = process.env) {
+  if (!isValidOutputName(name)) throw new Error(`invalid output name "${name}" (use a-z, 0-9 and -)`);
+  writeJson(instanceFile(name, env), conf, 0o600);
+}
+
+// True even for a file too broken to read, so it can still be removed.
+export const outputInstanceExists = (name, env = process.env) => isValidOutputName(name) && existsSync(instanceFile(name, env));
+
+export function removeOutputInstance(name, env = process.env) {
+  if (isValidOutputName(name)) rmSync(instanceFile(name, env), { force: true });
+}
+
+export function listOutputInstances(env = process.env) {
+  let files;
+  try { files = readdirSync(join(configDir(env), 'outputs')); } catch { return []; }
+  return files
+    .filter((f) => f.endsWith('.json'))
+    .map((f) => f.slice(0, -5))
+    .filter(isValidOutputName)
+    .sort()
+    .map((name) => {
+      try { return { name, conf: readOutputInstance(name, env) }; } catch (e) { return { name, conf: null, error: e.message }; }
+    });
+}

package/src/core/context.js

@@ -0,0 +1,14 @@
+import { loadConfig } from '../config.js';
+import { createState } from './state.js';
+import { log } from './log.js';
+import { resolveOutputs } from '../outputs/index.js';
+
+export function createContext(env = process.env) {
+  const config = loadConfig(env);
+  return {
+    config,
+    state: createState(config.stateDir),
+    log: (agent, session, message) => log(config.stateDir, agent, session, message),
+    outputs: resolveOutputs(config.outputs, env),
+  };
+}