ava-engine 0.0.0-stage → 0.1.0

package/lib/asr.mjs

@@ -0,0 +1,143 @@
+// Offline streaming speech-to-text — free, on-device, no key. Two engines the
+// user picks before the call:
+//   - "zipformer"  : English streaming zipformer. Live word-by-word partials.
+//   - "sensevoice" : SenseVoice multilingual (zh/en/ja/ko/yue). Utterance-based
+//                    via Silero VAD; cased + punctuated; more accurate on accents.
+
+import { createRequire } from "node:module";
+import { existsSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const require = createRequire(import.meta.url);
+const __dir = dirname(fileURLToPath(import.meta.url));
+const MODELS = process.env.AVA_MODELS_DIR || join(__dir, "../models"); // the CLI points this at ~/.ava-engine/models
+
+// zipformer: prefer the larger model, fall back to the 20M; SHERPA_MODEL_DIR overrides
+const ZIP_CANDIDATES = [
+  process.env.SHERPA_MODEL_DIR,
+  join(MODELS, "sherpa-onnx-streaming-zipformer-en-2023-06-26"),
+  join(MODELS, "sherpa-onnx-streaming-zipformer-en-20M-2023-02-17"),
+].filter(Boolean);
+const ZIP_DIR = ZIP_CANDIDATES.find((d) => existsSync(join(d, "tokens.txt")));
+const SV_DIR = join(MODELS, "sherpa-onnx-sense-voice-zh-en-ja-ko-yue-2024-07-17");
+const VAD_MODEL = join(MODELS, "silero_vad.onnx");
+
+let sherpa = null, online = null, offline = null, initErr = null;
+
+function loadSherpa() {
+  if (!sherpa && !initErr) { try { sherpa = require("sherpa-onnx-node"); } catch (e) { initErr = e; console.log("  sherpa unavailable:", e.message); } }
+  return sherpa;
+}
+
+// Which engines have their model files on disk.
+export function availableEngines() {
+  const e = [];
+  if (ZIP_DIR) e.push("zipformer");
+  if (existsSync(join(SV_DIR, "tokens.txt")) && existsSync(VAD_MODEL)) e.push("sensevoice");
+  return e;
+}
+export function asrAvailable() { return !initErr && availableEngines().length > 0; }
+export function defaultEngine() { const e = availableEngines(); return e.includes("zipformer") ? "zipformer" : (e[0] || null); }
+export const ENGINE_LABELS = { zipformer: "English · streaming", sensevoice: "Multilingual · SenseVoice" };
+
+function pick(dir, kind, preferInt8) {
+  const files = readdirSync(dir).filter((f) => f.startsWith(kind) && f.endsWith(".onnx"));
+  const int8 = files.find((f) => f.includes("int8")), fp = files.find((f) => !f.includes("int8"));
+  return join(dir, preferInt8 ? int8 || fp : fp || int8);
+}
+
+function getOnline() {
+  if (online || !ZIP_DIR) return online;
+  const s = loadSherpa(); if (!s) return null;
+  online = new s.OnlineRecognizer({
+    featConfig: { sampleRate: 16000, featureDim: 80 },
+    modelConfig: {
+      transducer: { encoder: pick(ZIP_DIR, "encoder", true), decoder: pick(ZIP_DIR, "decoder", false), joiner: pick(ZIP_DIR, "joiner", true) },
+      tokens: join(ZIP_DIR, "tokens.txt"), numThreads: 2, provider: "cpu",
+    },
+    decodingMethod: "greedy_search",
+    enableEndpoint: true, rule1MinTrailingSilence: 2.4, rule2MinTrailingSilence: 0.9, rule3MinUtteranceLength: 20,
+  });
+  return online;
+}
+function getOffline() {
+  if (offline) return offline;
+  const s = loadSherpa(); if (!s) return null;
+  offline = new s.OfflineRecognizer({
+    featConfig: { sampleRate: 16000, featureDim: 80 },
+    modelConfig: {
+      senseVoice: { model: pick(SV_DIR, "model", true), language: process.env.SENSEVOICE_LANG || "en", useInverseTextNormalization: 1 },
+      tokens: join(SV_DIR, "tokens.txt"), numThreads: 2, provider: "cpu",
+    },
+    decodingMethod: "greedy_search",
+  });
+  return offline;
+}
+
+export function warmAsr() {
+  if (!asrAvailable()) { console.log("  sherpa ASR: no models found at", MODELS); return; }
+  const e = availableEngines();
+  if (e.includes("zipformer") && getOnline()) console.log("  sherpa ASR ready — English streaming (zipformer)");
+  if (e.includes("sensevoice")) console.log("  sherpa ASR ready — multilingual (SenseVoice), lazy-loaded on first use");
+}
+
+// SenseVoice text can carry <|lang|><|emo|> tags; strip them.
+function cleanSV(t) { return String(t || "").replace(/<\|[^|]*\|>/g, "").replace(/\s+/g, " ").trim(); }
+// ws hands us pooled Buffers at arbitrary byte offsets — read alignment-safe.
+function toFloat32(buf) {
+  if (buf instanceof Int16Array) { const o = new Float32Array(buf.length); for (let i = 0; i < buf.length; i++) o[i] = buf[i] / 32768; return o; }
+  const n = Math.floor(buf.length / 2); const o = new Float32Array(n); for (let i = 0; i < n; i++) o[i] = buf.readInt16LE(i * 2) / 32768; return o;
+}
+
+/** One live transcription session for a WebSocket connection. */
+export function createAsrSession(engine) {
+  const eng = availableEngines().includes(engine) ? engine : defaultEngine();
+  if (!eng) return null;
+  return eng === "sensevoice" ? sensevoiceSession() : zipformerSession();
+}
+
+function zipformerSession() {
+  const rec = getOnline(); if (!rec) return null;
+  const stream = rec.createStream(); let last = "";
+  return {
+    engine: "zipformer",
+    feed(buf) {
+      const samples = toFloat32(buf);
+      stream.acceptWaveform({ sampleRate: 16000, samples });
+      while (rec.isReady(stream)) rec.decode(stream);
+      const text = (rec.getResult(stream).text || "").trim();
+      const out = {};
+      if (rec.isEndpoint(stream)) { if (text) out.final = text; rec.reset(stream); last = ""; }
+      else if (text && text !== last) { last = text; out.partial = text; }
+      return out;
+    },
+    close() { try { stream.free && stream.free(); } catch {} },
+  };
+}
+
+function sensevoiceSession() {
+  const rec = getOffline(); const s = loadSherpa(); if (!rec || !s) return null;
+  const vad = new s.Vad({
+    sileroVad: { model: VAD_MODEL, threshold: 0.5, minSilenceDuration: 0.5, minSpeechDuration: 0.25, windowSize: 512 },
+    sampleRate: 16000, numThreads: 1, provider: "cpu",
+  }, 30);
+  return {
+    engine: "sensevoice",
+    feed(buf) {
+      vad.acceptWaveform(toFloat32(buf));
+      const out = {};
+      while (!vad.isEmpty()) {
+        const seg = vad.front(); vad.pop();
+        const st = rec.createStream();
+        st.acceptWaveform({ sampleRate: 16000, samples: seg.samples });
+        rec.decode(st);
+        const text = cleanSV(rec.getResult(st).text);
+        try { st.free && st.free(); } catch {}
+        if (text) out.final = out.final ? out.final + " " + text : text;
+      }
+      return out;
+    },
+    close() { try { vad.free && vad.free(); } catch {} },
+  };
+}

package/lib/cli/config.mjs

@@ -0,0 +1,95 @@
+// Where the installed CLI keeps its state, and small helpers the commands share.
+//
+//   ~/.ava-engine/.env      settings (API keys, password, port…), mode 600
+//   ~/.ava-engine/models/   offline speech-to-text models
+//
+// AVA_HOME moves the whole folder (handy for servers, Docker and tests).
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { createServer } from "node:net";
+import { spawn } from "node:child_process";
+import { randomInt } from "node:crypto";
+
+export const AVA_HOME = process.env.AVA_HOME || join(homedir(), ".ava-engine");
+export const CONFIG_FILE = join(AVA_HOME, ".env");
+export const MODELS_DIR = join(AVA_HOME, "models");
+export const DEFAULT_PORT = 5190;
+
+/** Parse a .env file into an object (no expansion, last value wins). */
+export function readConfig(file = CONFIG_FILE) {
+  if (!existsSync(file)) return null;
+  const out = {};
+  for (const line of readFileSync(file, "utf8").split(/\r?\n/)) {
+    const m = line.match(/^\s*([A-Z0-9_]+)\s*=\s*(.*)\s*$/);
+    if (!m) continue;
+    let v = m[2];
+    if (/^".*"$/.test(v)) v = v.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+    out[m[1]] = v;
+  }
+  return out;
+}
+
+const quote = (v) => (/^[A-Za-z0-9_@%+=:,./-]*$/.test(v) ? v : `"${String(v).replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`);
+
+/** Write settings to the config file (readable only by you). Empty values are dropped. */
+export function writeConfig(values, file = CONFIG_FILE) {
+  mkdirSync(AVA_HOME, { recursive: true });
+  const lines = [
+    "# Ava Engine settings, written by `ava-engine setup`. Edit freely, or re-run setup.",
+    "# Every option is documented at https://github.com/Mr-vero/ava-engine/blob/main/.env.example",
+    "",
+    ...Object.entries(values).filter(([, v]) => v !== undefined && v !== null && v !== "").map(([k, v]) => `${k}=${quote(v)}`),
+    "",
+  ];
+  writeFileSync(file, lines.join("\n"), { mode: 0o600 });
+  try { chmodSync(file, 0o600); } catch {}
+}
+
+/** Check an OpenRouter key. Returns { ok, label?, limit?, error? }. */
+export async function checkOpenRouterKey(key) {
+  try {
+    const r = await fetch("https://openrouter.ai/api/v1/key", { headers: { Authorization: `Bearer ${key}` }, signal: AbortSignal.timeout(10_000) });
+    if (r.status === 401 || r.status === 403) return { ok: false, error: "OpenRouter rejected this key" };
+    if (!r.ok) return { ok: false, error: `OpenRouter answered ${r.status}` };
+    const d = (await r.json()).data || {};
+    return { ok: true, label: d.label, limit: d.limit, usage: d.usage };
+  } catch (e) {
+    return { ok: false, error: `couldn't reach OpenRouter (${e.name === "TimeoutError" ? "timed out" : e.message})`, offline: true };
+  }
+}
+
+/** Check an ElevenLabs key. Returns { ok, error? }. */
+export async function checkElevenLabsKey(key) {
+  try {
+    const r = await fetch("https://api.elevenlabs.io/v1/user", { headers: { "xi-api-key": key }, signal: AbortSignal.timeout(10_000) });
+    if (r.status === 401 || r.status === 403) return { ok: false, error: "ElevenLabs rejected this key" };
+    return r.ok ? { ok: true } : { ok: false, error: `ElevenLabs answered ${r.status}` };
+  } catch (e) {
+    return { ok: false, error: `couldn't reach ElevenLabs (${e.message})`, offline: true };
+  }
+}
+
+/** True if nothing is listening on the port. */
+export function portFree(port, host) {
+  return new Promise((res) => {
+    const s = createServer();
+    s.once("error", () => res(false));
+    s.listen({ port, host }, () => s.close(() => res(true)));
+  });
+}
+
+export function openBrowser(url) {
+  const [cmd, args] = process.platform === "darwin" ? ["open", [url]]
+    : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]]
+    : ["xdg-open", [url]];
+  try { spawn(cmd, args, { stdio: "ignore", detached: true }).unref(); } catch {}
+}
+
+/** A random password like "k7fq-9xm4-r3pz": 12 characters, 60 bits, no look-alike letters. */
+export function suggestPassword() {
+  const alphabet = "abcdefghjkmnpqrstuvwxyz23456789"; // 31 chars: no i, l, o, 0, 1
+  const group = () => Array.from({ length: 4 }, () => alphabet[randomInt(alphabet.length)]).join("");
+  return `${group()}-${group()}-${group()}`;
+}

package/lib/cli/main.mjs

@@ -0,0 +1,152 @@
+// The `ava-engine` command.
+import { existsSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+import { AVA_HOME, CONFIG_FILE, MODELS_DIR, DEFAULT_PORT, readConfig, checkOpenRouterKey, portFree, openBrowser } from "./config.mjs";
+import { MODEL_PACKS, installedPacks } from "../fetch-models.mjs";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const VERSION = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8")).version;
+
+const HELP = `
+  ΛVΛ  Ava Engine ${VERSION}: a screen-aware voice agent
+
+  Usage
+    npx ava-engine              first run: setup wizard, then start. After that: start
+    npx ava-engine setup        (re)run the setup wizard
+    npx ava-engine start        start the server
+    npx ava-engine doctor       check your setup and tell you what to fix
+    npx ava-engine models [..]  download speech models: ${Object.keys(MODEL_PACKS).join(", ")}
+
+  Options
+    --port <n>       port to listen on (default ${DEFAULT_PORT})
+    --open           open the browser once Ava is up (default on a first run)
+    --no-open        don't open the browser
+    --yes            setup without questions, from environment variables
+    --models <a,b>   with --yes: model packs to download
+    -v, --version    print the version
+    -h, --help       show this help
+
+  Settings live in ${CONFIG_FILE}
+  (set AVA_HOME to keep them somewhere else). Docs: https://github.com/Mr-vero/ava-engine
+`;
+
+function parseArgs(argv) {
+  const out = { _: [], flags: {} };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-h" || a === "--help") out.flags.help = true;
+    else if (a === "-v" || a === "--version") out.flags.version = true;
+    else if (a === "--yes" || a === "-y") out.flags.yes = true;
+    else if (a === "--open") out.flags.open = true;
+    else if (a === "--no-open") out.flags.open = false;
+    else if (a === "--port") out.flags.port = Number(argv[++i]);
+    else if (a.startsWith("--port=")) out.flags.port = Number(a.slice(7));
+    else if (a === "--models") out.flags.models = String(argv[++i] || "").split(",").filter(Boolean);
+    else if (a.startsWith("--")) throw new Error(`unknown option ${a} (see --help)`);
+    else out._.push(a);
+  }
+  if (out.flags.port !== undefined && !(Number.isInteger(out.flags.port) && out.flags.port > 0 && out.flags.port < 65536)) throw new Error("--port needs a number between 1 and 65535");
+  return out;
+}
+
+/** Load the saved settings into the environment (real env vars win), then run the server. */
+async function start({ port, open }) {
+  const cfg = readConfig() || {};
+  for (const [k, v] of Object.entries(cfg)) if (process.env[k] === undefined) process.env[k] = v;
+  process.env.AVA_MODELS_DIR ??= MODELS_DIR;
+  if (port) process.env.PORT = String(port);
+  const p = Number(process.env.PORT) || DEFAULT_PORT;
+  if (!(await portFree(p, process.env.HOST))) {
+    console.error(`\n  ✗ Port ${p} is already in use. Try: npx ava-engine start --port ${p + 1}\n`);
+    process.exit(1);
+  }
+  await import("../../server.mjs");
+  if (open) {
+    const url = `http://localhost:${p}/app`;
+    for (let i = 0; i < 50; i++) { // wait until the server answers, then open the app
+      try { if ((await fetch(`http://127.0.0.1:${p}/api/health`)).ok) break; } catch {}
+      await new Promise((r) => setTimeout(r, 200));
+    }
+    openBrowser(url);
+  }
+}
+
+async function doctor() {
+  const cfg = readConfig();
+  const rows = [];
+  const add = (ok, label, fix) => rows.push({ ok, label, fix });
+  const [maj, min] = process.versions.node.split(".").map(Number);
+  add(maj > 22 || (maj === 22 && min >= 9) ? "ok" : "fail", `Node ${process.versions.node}`, "Ava needs Node 22.9 or newer: https://nodejs.org");
+  add(cfg ? "ok" : "fail", cfg ? `Settings: ${CONFIG_FILE}` : "No settings yet", "Run: npx ava-engine setup");
+  const c = cfg || {};
+  if (c.OPENROUTER_API_KEY) {
+    const r = await checkOpenRouterKey(c.OPENROUTER_API_KEY);
+    add(r.ok ? "ok" : r.offline ? "warn" : "fail", r.ok ? `OpenRouter key works${r.limit != null ? ` (limit $${r.limit}, used $${(r.usage ?? 0).toFixed(2)})` : ""}` : r.error, "Check the key at https://openrouter.ai/keys, then: npx ava-engine setup");
+  } else add("warn", "No OpenRouter key: MOCK mode (canned replies)", "Add one with: npx ava-engine setup");
+  if (c.TTS_DEFAULT === "elevenlabs" && !c.ELEVENLABS_API_KEY) add("fail", "Voice is ElevenLabs but there's no ElevenLabs key", "Run: npx ava-engine setup");
+  const packs = installedPacks(c.AVA_MODELS_DIR || MODELS_DIR);
+  add(packs.length ? "ok" : "warn", packs.length ? `Speech models: ${packs.map((x) => MODEL_PACKS[x].label).join(", ")}` : "No offline speech models: browser speech recognition only", "Download with: npx ava-engine models english-small");
+  try { createRequire(import.meta.url)("sherpa-onnx-node"); add("ok", "Speech engine (sherpa-onnx) loads"); }
+  catch (e) { add(packs.length ? "fail" : "warn", `Speech engine (sherpa-onnx) doesn't load: ${e.message.split("\n")[0]}`, "Reinstall: npx --yes ava-engine@latest (Linux also needs libgomp1)"); }
+  if (c.HOST !== "127.0.0.1" && !c.ACCESS_PASSWORD) add("warn", "Reachable from the network with NO password: anyone can spend your API credit", "Run setup and choose a password, or set HOST=127.0.0.1");
+  const port = Number(c.PORT) || DEFAULT_PORT;
+  const free = await portFree(port, c.HOST);
+  add(free ? "ok" : "warn", `Port ${port} ${free ? "is free" : "is in use (maybe Ava is already running)"}`, `Use another: npx ava-engine start --port ${port + 1}`);
+
+  const icon = { ok: "✓", warn: "!", fail: "✗" };
+  console.log(`\n  ΛVΛ  Ava Engine doctor (${VERSION})\n`);
+  for (const r of rows) console.log(`  ${icon[r.ok]} ${r.label}${r.ok !== "ok" && r.fix ? `\n      → ${r.fix}` : ""}`);
+  const failed = rows.some((r) => r.ok === "fail");
+  console.log(failed ? "\n  Some checks failed. Fix those, then run doctor again.\n" : "\n  Ready. Start Ava with: npx ava-engine\n");
+  return failed ? 1 : 0;
+}
+
+export async function main(argv) {
+  let args;
+  try { args = parseArgs(argv); } catch (e) { console.error(`✗ ${e.message}`); return 2; }
+  const { flags } = args;
+  if (flags.version) { console.log(VERSION); return 0; }
+  const cmd = args._[0] || (flags.help ? "help" : existsSync(CONFIG_FILE) ? "start" : "first-run");
+  const interactive = process.stdin.isTTY && process.stdout.isTTY && !flags.yes;
+
+  switch (cmd) {
+    case "help": console.log(HELP); return 0;
+    case "doctor": return doctor();
+    case "start": await start({ port: flags.port, open: flags.open === true }); return null; // keeps running
+    case "models": {
+      const { downloadPacks } = await import("./setup.mjs");
+      let packs = args._.slice(1);
+      if (!packs.length && interactive) {
+        const p = await import("@clack/prompts");
+        const have = installedPacks(MODELS_DIR);
+        const sel = await p.multiselect({ message: "Which speech models?", required: false, initialValues: have, options: Object.entries(MODEL_PACKS).map(([id, m]) => ({ value: id, label: `${m.label} · ${m.size}`, hint: have.includes(id) ? "installed" : m.hint })) });
+        if (p.isCancel(sel)) return 0;
+        packs = sel;
+      }
+      if (!packs.length) packs = ["english-small"];
+      const bad = packs.filter((x) => !MODEL_PACKS[x]);
+      if (bad.length) { console.error(`✗ unknown model pack: ${bad.join(", ")}. Choose from: ${Object.keys(MODEL_PACKS).join(", ")}`); return 2; }
+      await downloadPacks(packs);
+      return 0;
+    }
+    case "setup":
+    case "first-run": {
+      const setup = await import("./setup.mjs");
+      if (!interactive) {
+        await setup.runSetupNonInteractive({ models: flags.models || [], port: flags.port });
+        if (cmd === "first-run") { await start({ port: flags.port, open: flags.open === true }); return null; }
+        return 0;
+      }
+      const r = await setup.runSetup();
+      if (r.start) { await start({ port: flags.port || r.port, open: flags.open !== false }); return null; }
+      return 0;
+    }
+    default:
+      console.error(`✗ unknown command "${cmd}" (see --help)`);
+      return 2;
+  }
+}
+
+export { AVA_HOME };

package/lib/cli/setup.mjs

@@ -0,0 +1,219 @@
+// `ava-engine setup`: the guided first-run wizard (and its non-interactive twin).
+import * as p from "@clack/prompts";
+import { AVA_HOME, CONFIG_FILE, MODELS_DIR, DEFAULT_PORT, readConfig, writeConfig, checkOpenRouterKey, checkElevenLabsKey, portFree, suggestPassword } from "./config.mjs";
+import { MODEL_PACKS, installedPacks, fetchPack } from "../fetch-models.mjs";
+
+const mask = (v) => (v ? `${v.slice(0, 6)}…${v.slice(-4)}` : "");
+function bail(v) { if (p.isCancel(v)) { p.cancel("Setup cancelled. Nothing was changed."); process.exit(0); } return v; }
+
+/** Download model packs with a progress bar per file. */
+export async function downloadPacks(packs) {
+  for (const pack of packs) {
+    const spec = MODEL_PACKS[pack];
+    let bar = null, last = 0;
+    try {
+      await fetchPack(pack, MODELS_DIR, (ev) => {
+        if (ev.phase === "skip") return;
+        if (ev.phase === "download") {
+          if (!bar) { bar = p.progress({ max: 100, style: "heavy" }); bar.start(`Downloading ${spec.label} (${spec.size})`); }
+          const pct = ev.total ? Math.floor((ev.done / ev.total) * 100) : 0;
+          if (pct > last) { bar.advance(pct - last, `Downloading ${spec.label}: ${pct}%`); last = pct; }
+        }
+        if (ev.phase === "extract" && bar) bar.message(`Unpacking ${spec.label}…`);
+      });
+      if (bar) bar.stop(`${spec.label} ready`); else p.log.success(`${spec.label} already installed`);
+    } catch (e) {
+      if (bar) bar.error(`${spec.label} failed`);
+      p.log.error(`${e.message}\nYou can retry later with: ava-engine models ${pack}`);
+    }
+  }
+}
+
+/**
+ * The interactive wizard. Returns { start: boolean, port }.
+ * Existing settings are kept unless you change them.
+ */
+export async function runSetup() {
+  const prev = readConfig() || {};
+  const cfg = { ...prev };
+
+  console.log("");
+  p.intro(" ΛVΛ  Ava Engine setup ");
+  p.note(
+    "A screen-aware voice agent: it joins a call, sees the tab your\n" +
+    "customer shares, and talks them through it.\n\n" +
+    "This takes about 2 minutes. You can change anything later with\n" +
+    "`ava-engine setup`, or by editing " + CONFIG_FILE,
+    "Welcome",
+  );
+
+  // 1 · how to start
+  const mode = bail(await p.select({
+    message: "How do you want to start?",
+    options: [
+      { value: "full", label: "Full setup", hint: "recommended: real AI replies, voice, speech recognition" },
+      { value: "mock", label: "Just look around", hint: "no API keys; canned replies, everything else works" },
+    ],
+  }));
+
+  // 2 · language models
+  if (mode === "mock") {
+    delete cfg.OPENROUTER_API_KEY;
+    p.log.info("MOCK mode: Ava will use canned replies. Run `ava-engine setup` again any time to add a key.");
+  } else {
+    let key = prev.OPENROUTER_API_KEY;
+    if (key) {
+      const keep = bail(await p.confirm({ message: `Keep your current OpenRouter key (${mask(key)})?`, initialValue: true }));
+      if (!keep) key = undefined;
+    }
+    while (!key) {
+      p.log.message("Ava's AI runs through OpenRouter: one key for every model.\nGet one at https://openrouter.ai/keys (set a credit limit on it).");
+      const entered = bail(await p.password({ message: "Paste your OpenRouter API key", validate: (v) => (!v || v.trim().length < 20 ? "That doesn't look like a full key" : undefined) })).trim();
+      const s = p.spinner(); s.start("Checking the key with OpenRouter");
+      const r = await checkOpenRouterKey(entered);
+      if (r.ok) {
+        const named = r.label && !/^sk-or/i.test(r.label) ? ` (${r.label})` : ""; // unnamed keys report a masked key as their label
+        s.stop(`Key works${named}${r.limit != null ? `, credit limit $${r.limit}` : ""}`);
+        key = entered;
+      } else {
+        s.error(r.error);
+        const next = bail(await p.select({
+          message: "What now?",
+          options: [
+            { value: "retry", label: "Try another key" },
+            ...(r.offline ? [{ value: "keep", label: "Save it anyway", hint: "I'm offline right now" }] : []),
+            { value: "mock", label: "Skip for now", hint: "MOCK mode" },
+          ],
+        }));
+        if (next === "keep") key = entered;
+        if (next === "mock") break;
+      }
+    }
+    if (key) cfg.OPENROUTER_API_KEY = key; else delete cfg.OPENROUTER_API_KEY;
+
+    // 3 · voice
+    const voice = bail(await p.select({
+      message: "Which voice should Ava speak with?",
+      initialValue: prev.TTS_DEFAULT || "kokoro",
+      options: [
+        { value: "kokoro", label: "Kokoro", hint: "free, runs on this machine; downloads ~90 MB on first start" },
+        { value: "elevenlabs", label: "ElevenLabs", hint: "premium cloud voices, needs an ElevenLabs key" },
+        { value: "browser", label: "The browser's voice", hint: "no setup, sounds robotic" },
+      ],
+    }));
+    cfg.TTS_DEFAULT = voice;
+    cfg.KOKORO = voice === "kokoro" ? "on" : prev.KOKORO === "on" ? "on" : "off";
+    if (voice === "elevenlabs") {
+      let ek = prev.ELEVENLABS_API_KEY;
+      if (ek && !bail(await p.confirm({ message: `Keep your current ElevenLabs key (${mask(ek)})?`, initialValue: true }))) ek = undefined;
+      while (!ek) {
+        const entered = bail(await p.password({ message: "Paste your ElevenLabs API key (elevenlabs.io → API keys)" })).trim();
+        const s = p.spinner(); s.start("Checking the key with ElevenLabs");
+        const r = await checkElevenLabsKey(entered);
+        if (r.ok || r.offline) { s.stop(r.ok ? "Key works" : `${r.error}; saved anyway`); ek = entered; }
+        else { s.error(r.error); if (!bail(await p.confirm({ message: "Try another key?", initialValue: true }))) { cfg.TTS_DEFAULT = "kokoro"; cfg.KOKORO = "on"; break; } }
+      }
+      if (ek) {
+        cfg.ELEVENLABS_API_KEY = ek;
+        const vid = bail(await p.text({ message: "ElevenLabs voice ID (Enter for the default voice, Matilda)", placeholder: "XrExE9yKIg1WjnnlVkGX", defaultValue: prev.ELEVEN_VOICE_ID || "" }));
+        if (vid) cfg.ELEVEN_VOICE_ID = vid.trim(); else delete cfg.ELEVEN_VOICE_ID;
+      }
+    }
+
+    // 4 · speech recognition models
+    const have = installedPacks(MODELS_DIR);
+    const packs = bail(await p.multiselect({
+      message: "Download offline speech recognition? (space to toggle, enter to confirm)",
+      required: false,
+      initialValues: have.length ? have : ["english-small"],
+      options: Object.entries(MODEL_PACKS).map(([id, m]) => ({ value: id, label: `${m.label} · ${m.size}`, hint: have.includes(id) ? "installed" : m.hint })),
+    }));
+    const missing = packs.filter((x) => !have.includes(x));
+    if (missing.length) await downloadPacks(missing);
+    else if (!packs.length) p.log.info("No models: Ava will use the browser's speech recognition (Chrome).");
+  }
+
+  // 5 · who can reach it
+  const audience = bail(await p.select({
+    message: "Who will use this Ava?",
+    initialValue: prev.HOST === "127.0.0.1" || !prev.ACCESS_PASSWORD ? "me" : "others",
+    options: [
+      { value: "me", label: "Just me, on this computer", hint: "safest; reachable only at localhost" },
+      { value: "others", label: "My team or customers", hint: "over a network or the internet; needs a password" },
+    ],
+  }));
+  if (audience === "me") {
+    cfg.HOST = "127.0.0.1";
+    delete cfg.ACCESS_PASSWORD; delete cfg.TRUST_PROXY;
+  } else {
+    delete cfg.HOST;
+    const suggested = suggestPassword();
+    const how = bail(await p.select({
+      message: "Set an access password (every call spends your API credit)",
+      options: [
+        ...(prev.ACCESS_PASSWORD ? [{ value: "keep", label: "Keep the current password" }] : []),
+        { value: "gen", label: `Use a generated one: ${suggested}`, hint: "recommended; it's saved in the config file" },
+        { value: "own", label: "Choose my own" },
+      ],
+    }));
+    if (how === "gen") cfg.ACCESS_PASSWORD = suggested;
+    if (how === "own") cfg.ACCESS_PASSWORD = bail(await p.password({ message: "Access password (at least 10 characters)", validate: (v) => (!v || v.length < 10 ? "Use at least 10 characters" : undefined) }));
+    const proxied = bail(await p.confirm({ message: "Will it run behind a proxy or host (Fly.io, Cloudflare, nginx, Render…)?", initialValue: prev.TRUST_PROXY === "1" }));
+    if (proxied) cfg.TRUST_PROXY = "1"; else delete cfg.TRUST_PROXY;
+  }
+
+  // 6 · port
+  const portStr = bail(await p.text({
+    message: "Port",
+    defaultValue: String(prev.PORT || DEFAULT_PORT),
+    placeholder: String(prev.PORT || DEFAULT_PORT),
+    validate: (v) => { if (!v) return undefined; const n = Number(v); return Number.isInteger(n) && n > 0 && n < 65536 ? undefined : "Use a number between 1 and 65535"; },
+  }));
+  cfg.PORT = String(Number(portStr) || DEFAULT_PORT);
+  if (!(await portFree(Number(cfg.PORT), cfg.HOST))) p.log.warn(`Port ${cfg.PORT} is in use right now. Stop that program, or run \`ava-engine start --port <other>\`.`);
+
+  // 7 · save
+  cfg.AVA_MODELS_DIR = MODELS_DIR;
+  writeConfig(cfg);
+  p.note(
+    [
+      `AI replies     ${cfg.OPENROUTER_API_KEY ? `OpenRouter (${mask(cfg.OPENROUTER_API_KEY)})` : "MOCK mode (canned replies)"}`,
+      `Voice          ${{ kokoro: "Kokoro (offline)", elevenlabs: "ElevenLabs", browser: "the browser's voice" }[cfg.TTS_DEFAULT] || "Kokoro (offline)"}`,
+      `Speech models  ${installedPacks(MODELS_DIR).map((x) => MODEL_PACKS[x].label).join(", ") || "none (browser speech recognition)"}`,
+      `Access         ${cfg.HOST === "127.0.0.1" ? "this computer only" : `password protected${cfg.ACCESS_PASSWORD ? ` (${cfg.ACCESS_PASSWORD})` : ""}`}`,
+      `Address        http://localhost:${cfg.PORT}/app`,
+      "",
+      `Saved to ${CONFIG_FILE}`,
+    ].join("\n"),
+    "Your Ava",
+  );
+
+  const start = bail(await p.confirm({ message: "Start Ava now?", initialValue: true }));
+  p.outro(start ? "Starting Ava…" : "All set. Start Ava any time with: npx ava-engine");
+  return { start, port: Number(cfg.PORT) };
+}
+
+/**
+ * Non-interactive setup for scripts, servers and CI: settings come from the
+ * environment and flags, with safe defaults. Returns the written config.
+ */
+export async function runSetupNonInteractive({ models = [], port } = {}) {
+  const prev = readConfig() || {};
+  const env = process.env;
+  const pick = (k) => env[k] ?? prev[k];
+  const cfg = { ...prev };
+  for (const k of ["OPENROUTER_API_KEY", "ELEVENLABS_API_KEY", "ELEVEN_VOICE_ID", "TTS_DEFAULT", "ACCESS_PASSWORD", "TRUST_PROXY", "KOKORO"]) if (pick(k)) cfg[k] = pick(k);
+  cfg.PORT = String(port || pick("PORT") || DEFAULT_PORT);
+  if (!cfg.ACCESS_PASSWORD) cfg.HOST = pick("HOST") || "127.0.0.1"; // never expose an open server by default
+  else if (pick("HOST")) cfg.HOST = pick("HOST");
+  cfg.AVA_MODELS_DIR = MODELS_DIR;
+  writeConfig(cfg);
+  for (const pack of models) {
+    console.log(`↓ ${MODEL_PACKS[pack]?.label || pack}`);
+    await fetchPack(pack, MODELS_DIR);
+  }
+  console.log(`Saved ${CONFIG_FILE}${cfg.OPENROUTER_API_KEY ? "" : " (MOCK mode: no OPENROUTER_API_KEY)"}`);
+  return cfg;
+}
+
+export { AVA_HOME };