ava-engine 0.1.0 → 0.3.0

package/.env.example

@@ -16,11 +16,22 @@ PORT=5190
 # ACCESS_PASSWORD=
 # TRUST_PROXY=1                     # behind Fly/Cloudflare/nginx: rate-limit by the real client IP
 # SESSION_BUDGET_USD=2              # model spend cap per call
+# DAILY_BUDGET_USD=20               # model spend cap per UTC day across all calls (unset = none)
 # MAX_SESSIONS=50                   # concurrent calls (idle ones expire after 30 min)
 # MAX_ASR_CONNECTIONS=40            # concurrent speech-to-text streams
 # RATE_SESSIONS_PER_MIN=10          # new calls per client IP per minute
 # RATE_API_PER_MIN=240              # other API requests per client IP per minute
 
+# ── Your products ──
+# PLAYBOOKS_DIR=/srv/ava/playbooks   # one JSON file per product (default ~/.ava-engine/playbooks): npx ava-engine playbooks new <id>
+# BUILTIN_PLAYBOOKS=off             # hide the built-in sample products from the lobby
+
+# ── Events & handoff alerts ──
+# WEBHOOK_URL=https://your-app.example/ava-events   # receives every call event as JSON (comma-separate several)
+# WEBHOOK_SECRET=                   # signs deliveries: X-Ava-Signature: sha256=HMAC(secret, "<timestamp>.<body>")
+# SLACK_WEBHOOK_URL=                # Slack incoming webhook: posts when a customer asks for a person
+# PUBLIC_URL=https://ava.your-site.example   # base for the specialist links in those alerts
+
 # ── Models (OpenRouter slugs) — one per role ──
 # MODEL_TALKER=meta-llama/llama-3.3-70b-instruct     # the spoken reply (latency-critical)
 # MODEL_PERCEPTION=google/gemini-2.5-flash           # reads the shared screen

package/README.md

@@ -11,6 +11,8 @@
 </p>
 
 <p align="center">
+  <a href="https://www.npmjs.com/package/ava-engine"><img alt="npm" src="https://img.shields.io/npm/v/ava-engine?color=0A0A0C&label=npm"></a>
+  <a href="https://scorecard.dev/viewer/?uri=github.com/Mr-vero/ava-engine"><img alt="OpenSSF Scorecard" src="https://api.scorecard.dev/projects/github.com/Mr-vero/ava-engine/badge"></a>
   <a href="https://github.com/Mr-vero/ava-engine/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Mr-vero/ava-engine/actions/workflows/ci.yml/badge.svg"></a>
   <a href="COMMERCIAL-LICENSE.md"><img alt="License: Ava Engine License (source-available)" src="https://img.shields.io/badge/license-source--available-0A0A0C"></a>
   <img alt="Node 22.9+" src="https://img.shields.io/badge/node-22.9%2B-4F46E5">
@@ -56,25 +58,25 @@ Requires **Node 22.9+** and desktop **Chrome**. One command installs Ava and wal
 npx ava-engine
 ```
 
-The setup wizard:
-1. checks your OpenRouter key (or lets you look around with no keys in MOCK mode);
-2. lets you pick Ava's voice;
-3. downloads offline speech recognition, with a progress bar;
-4. protects Ava with a password if other people will use it;
-5. starts Ava and opens **http://localhost:5190/app**.
+Set up **in your browser** (a step-by-step page) or **in the terminal**; both do the same:
+1. check your OpenRouter key (or look around with no keys, in MOCK mode);
+2. pick Ava's voice, and download the free offline voice (Kokoro, ~90 MB) with progress;
+3. download offline speech recognition, also with progress;
+4. protect Ava with a password if other people will use it;
+5. start Ava and open **http://localhost:5190/app**.
 
 After that, `npx ava-engine` just starts Ava.
 
 | Command | What it does |
 | --- | --- |
-| `npx ava-engine setup` | Re-run the wizard to change keys, voice, password or port |
+| `npx ava-engine setup` | Re-run setup to change keys, voice, password or port (`--web` for the browser, `--terminal` for here) |
 | `npx ava-engine doctor` | Check everything and get a fix for anything that's wrong |
-| `npx ava-engine models` | Add or remove offline speech models |
+| `npx ava-engine models` | Download speech models or the Kokoro voice (`models kokoro`) |
 | `npx ava-engine start --port 8080` | Start on another port |
 
 Settings live in `~/.ava-engine` (set `AVA_HOME` to move them). **Watch the demo locally** at `http://localhost:5190/app?demo=simple`.
 
-**For servers and scripts:** `OPENROUTER_API_KEY=… ACCESS_PASSWORD=… npx ava-engine setup --yes --models english-small` sets everything up without questions. There's also a Docker image; see [DEPLOY.md](DEPLOY.md).
+**On a server:** `npx ava-engine setup --web` works over SSH too. Forward the port (`ssh -L 5190:localhost:5190 your-server`) and open the link it prints. Or skip the questions: `OPENROUTER_API_KEY=… ACCESS_PASSWORD=… npx ava-engine setup --yes --models english-small,kokoro`. There's also a Docker image; see [DEPLOY.md](DEPLOY.md).
 
 <details>
 <summary><b>Working on Ava itself? Run from source</b></summary>
@@ -147,12 +149,14 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
 **For the customer**
 - **Talks, naturally.** Live voice with streamed replies, interruptible at any time (barge-in), in text or voice.
 - **Sees their screen.** Reads the shared tab — the page, what's selected, the numbers on it — and grounds every answer in it. Never invents buttons; if it isn't sure, it takes another look.
-- **Helps with anything on the page.** A *Flexible agent* for whatever the customer is doing, and an *Onboarding agent* that walks a journey step by step on a chosen product (Todoist, Supabase, Stripe, AWS Console, Salesforce, Datadog, Vercel).
+- **Helps with anything on the page.** A *Flexible agent* for whatever the customer is doing, and an *Onboarding agent* that walks a journey step by step on your product, described in a JSON [playbook](docs/setup/customize.md) (samples included for Todoist, Supabase, Stripe, AWS Console, Salesforce, Datadog and Vercel).
 - **Speaks up.** Reacts when the screen changes, and flags risky or costly moves before they happen (a $9,900 seat count, a destructive click).
 - **Knows when it's done.** Confirms each step actually worked, and goes quiet once the task is complete.
 - **A person, one tap away.** Hands off to a human specialist with the goal, the screen and the progress already shared — the specialist joins the same call over WebRTC.
 
 **For the team running it**
+- **Events** — webhooks for call started, step completed, handoff requested and call ended, plus a Slack alert with a join link when a customer asks for a person.
+- **Spend caps** — per call and per day across all calls.
 - **Session recap** — an AI summary, highlights and stats, plus a replay of how the agents worked, with a timestamped timeline.
 - **Console** — end-to-end latency per turn, which agents ran and how long each took, the compiled context the talker saw, and live spend.
 - **Per-platform theming** — onboarding calls take on the product's brand colour.

package/lib/asr.mjs

@@ -76,7 +76,11 @@ function getOffline() {
 }
 
 export function warmAsr() {
-  if (!asrAvailable()) { console.log("  sherpa ASR: no models found at", MODELS); return; }
+  if (!asrAvailable()) {
+    if (initErr) console.log("  speech recognition: the offline engine didn't load; using the browser's (run `npx ava-engine doctor`)");
+    else console.log("  speech recognition: using the browser's. For offline recognition: npx ava-engine 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");

package/lib/cli/apply.mjs

@@ -0,0 +1,58 @@
+// Turning setup answers into saved settings. Shared by the terminal wizard and
+// the browser setup, so both produce exactly the same configuration.
+import { MODELS_DIR, DEFAULT_PORT } from "./config.mjs";
+
+export const VOICES = {
+  kokoro: { label: "Kokoro", hint: "free, runs on this computer (~90 MB download)" },
+  elevenlabs: { label: "ElevenLabs", hint: "premium cloud voices, needs an ElevenLabs key" },
+  browser: { label: "The browser's voice", hint: "no setup, sounds robotic" },
+};
+
+/**
+ * answers: {
+ *   openrouterKey?: string | null   (null/"" → MOCK mode; undefined → keep the current key)
+ *   voice: "kokoro" | "elevenlabs" | "browser",
+ *   elevenKey?, elevenVoice?,
+ *   audience: "me" | "others", password?, proxy?: boolean,
+ *   port?: number
+ * }
+ */
+export function buildConfig(prev, a) {
+  const cfg = { ...prev };
+  const set = (k, v) => { if (v === undefined || v === null || v === "") delete cfg[k]; else cfg[k] = String(v); };
+
+  if (a.openrouterKey !== undefined) set("OPENROUTER_API_KEY", a.openrouterKey);
+
+  const voice = VOICES[a.voice] ? a.voice : "kokoro";
+  set("TTS_DEFAULT", voice);
+  set("KOKORO", voice === "kokoro" ? "on" : "off");
+  if (voice === "elevenlabs") {
+    if (a.elevenKey !== undefined) set("ELEVENLABS_API_KEY", a.elevenKey);
+    if (a.elevenVoice !== undefined) set("ELEVEN_VOICE_ID", a.elevenVoice);
+  }
+
+  if (a.audience === "others") {
+    set("HOST", "");
+    if (a.password !== undefined) set("ACCESS_PASSWORD", a.password);
+    set("TRUST_PROXY", a.proxy ? "1" : "");
+  } else {
+    set("HOST", "127.0.0.1");
+    set("ACCESS_PASSWORD", "");
+    set("TRUST_PROXY", "");
+  }
+
+  const port = Number(a.port);
+  set("PORT", Number.isInteger(port) && port > 0 && port < 65536 ? port : prev.PORT || DEFAULT_PORT);
+  set("AVA_MODELS_DIR", MODELS_DIR);
+  return cfg;
+}
+
+/** Problems that must be fixed before saving, as a list of human messages. */
+export function validateAnswers(a) {
+  const errors = [];
+  if (a.audience === "others" && (!a.password || String(a.password).length < 10)) errors.push("Choose an access password of at least 10 characters.");
+  if (a.voice === "elevenlabs" && a.elevenKey === "") errors.push("Add your ElevenLabs key, or pick another voice.");
+  const port = Number(a.port);
+  if (a.port !== undefined && !(Number.isInteger(port) && port > 0 && port < 65536)) errors.push("The port must be a number between 1 and 65535.");
+  return errors;
+}

package/lib/cli/main.mjs

@@ -1,6 +1,7 @@
 // The `ava-engine` command.
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join, dirname } from "node:path";
+import { homedir } from "node:os";
 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";
@@ -14,17 +15,21 @@ const HELP = `
 
   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 setup        (re)run setup; asks: in the browser or the terminal
+    npx ava-engine setup --web  setup in your browser
+    npx ava-engine setup --terminal
     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(", ")}
+    npx ava-engine models [..]  download models: ${Object.keys(MODEL_PACKS).join(", ")}, kokoro (voice)
+    npx ava-engine playbooks    list and check your product playbooks
+    npx ava-engine playbooks new <id>   write a starter playbook to fill in
 
   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
+    --models <a,b>   with --yes: what to download, e.g. english-small,kokoro
     -v, --version    print the version
     -h, --help       show this help
 
@@ -40,6 +45,8 @@ function parseArgs(argv) {
     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 === "--web") out.flags.web = true;
+    else if (a === "--terminal") out.flags.terminal = 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));
@@ -73,6 +80,35 @@ async function start({ port, open }) {
   }
 }
 
+/** `ava-engine playbooks [new <id>]`: your products as JSON files. */
+async function playbooks(args) {
+  const { loadPlaybooks, validatePlaybook, template } = await import("../playbooks.mjs");
+  const cfg = readConfig() || {};
+  const dir = (process.env.PLAYBOOKS_DIR || cfg.PLAYBOOKS_DIR || join(AVA_HOME, "playbooks")).replace(/^~(?=$|[\\/])/, homedir());
+  if (args[0] === "new") {
+    const id = args[1];
+    if (!id || validatePlaybook({ ...template(id), id }).errors) { console.error("✗ usage: ava-engine playbooks new <id>  (lowercase letters, digits and dashes, e.g. acme)"); return 2; }
+    const file = join(dir, `${id}.json`);
+    if (existsSync(file)) { console.error(`✗ ${file} already exists`); return 1; }
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(file, JSON.stringify(template(id), null, 2) + "\n");
+    console.log(`\n  ✓ Wrote ${file}\n\n  Fill it in for your product, check it with: npx ava-engine playbooks\n  then restart Ava. Field guide: https://github.com/Mr-vero/ava-engine/blob/main/docs/setup/customize.md\n`);
+    return 0;
+  }
+  if (args.length) { console.error(`✗ unknown playbooks command "${args[0]}" (try: ava-engine playbooks new <id>)`); return 2; }
+  const { playbooks: ok, problems } = loadPlaybooks(dir);
+  console.log(`\n  ΛVΛ  Playbooks in ${dir}\n`);
+  if (!ok.length && !problems.length) console.log("  None yet. Create one with: npx ava-engine playbooks new <id>");
+  for (const p of ok) console.log(`  ✓ ${p.name} (${p.id}): ${p.journey.length} steps, ${p.knowledge.length} knowledge entries  [${p.source}]`);
+  for (const p of problems) {
+    for (const e of p.errors) console.log(`  ✗ ${p.file}: ${e}`);
+    for (const w of p.warnings) console.log(`  ! ${p.file}: ${w}`);
+  }
+  const hidden = /^(off|0|false|no)$/i.test(process.env.BUILTIN_PLAYBOOKS || cfg.BUILTIN_PLAYBOOKS || "");
+  console.log(`\n  Built-in sample products are ${hidden ? "hidden (BUILTIN_PLAYBOOKS=off)" : "shown too. Hide them with BUILTIN_PLAYBOOKS=off in " + CONFIG_FILE}.\n`);
+  return problems.some((p) => p.errors.length) ? 1 : 0;
+}
+
 async function doctor() {
   const cfg = readConfig();
   const rows = [];
@@ -114,9 +150,10 @@ export async function main(argv) {
   switch (cmd) {
     case "help": console.log(HELP); return 0;
     case "doctor": return doctor();
+    case "playbooks": return playbooks(args._.slice(1));
     case "start": await start({ port: flags.port, open: flags.open === true }); return null; // keeps running
     case "models": {
-      const { downloadPacks } = await import("./setup.mjs");
+      const { downloadPacks, downloadKokoro } = await import("./setup.mjs");
       let packs = args._.slice(1);
       if (!packs.length && interactive) {
         const p = await import("@clack/prompts");
@@ -126,19 +163,50 @@ export async function main(argv) {
         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);
+      const bad = packs.filter((x) => !MODEL_PACKS[x] && x !== "kokoro");
+      if (bad.length) { console.error(`✗ unknown model: ${bad.join(", ")}. Choose from: ${Object.keys(MODEL_PACKS).join(", ")}, kokoro`); return 2; }
+      if (packs.includes("kokoro")) await downloadKokoro();
+      await downloadPacks(packs.filter((x) => x !== "kokoro"));
       return 0;
     }
     case "setup":
     case "first-run": {
       const setup = await import("./setup.mjs");
-      if (!interactive) {
+      // --web needs a browser, not a terminal, so it works over SSH and from scripts too.
+      if (!interactive && !(flags.web && !flags.yes)) {
         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;
       }
+      // Where to run the wizard: the browser (default) or this terminal.
+      let where = flags.web ? "web" : flags.terminal ? "terminal" : null;
+      if (!where) {
+        const p = await import("@clack/prompts");
+        console.log("");
+        p.intro(" ΛVΛ  Ava Engine setup ");
+        where = await p.select({
+          message: "Where would you like to set up Ava?",
+          options: [
+            { value: "web", label: "In my browser", hint: "recommended; a step-by-step page" },
+            { value: "terminal", label: "Here in the terminal" },
+          ],
+        });
+        if (p.isCancel(where)) { p.cancel("Setup cancelled. Nothing was changed."); return 0; }
+      }
+      if (where === "web") {
+        const { runWebSetup } = await import("./setup-server.mjs");
+        const r = await runWebSetup({
+          preferredPort: flags.port,
+          formPort: flags.port,
+          onReady: ({ url }) => {
+            console.log(`\n  Setup is open in your browser. If it didn't open, go to:\n  ${url}\n\n  (Keep this terminal open. Press Ctrl+C to cancel.)\n`);
+            if (flags.open !== false) openBrowser(url);
+          },
+        });
+        console.log("  Settings saved. Starting Ava…");
+        await start({ port: r.port, open: false }); // the port chosen on the page wins; the page redirects itself
+        return null;
+      }
       const r = await setup.runSetup();
       if (r.start) { await start({ port: flags.port || r.port, open: flags.open !== false }); return null; }
       return 0;

package/lib/cli/openrouter-oauth.mjs

@@ -0,0 +1,87 @@
+// "Connect OpenRouter": get an API key by signing in, instead of copying one.
+//
+// OpenRouter's OAuth PKCE flow (https://openrouter.ai/docs/use-cases/oauth-pkce):
+//  1. open openrouter.ai/auth with a localhost callback and a S256 code challenge,
+//  2. the person approves; OpenRouter redirects to the callback with ?code=…,
+//  3. we trade the code (plus the verifier only we know) for a key.
+// The key is billed to their own OpenRouter credit. Codes expire after 10 minutes.
+
+import http from "node:http";
+import { createHash, randomBytes } from "node:crypto";
+
+// Overridable so tests can stand in for openrouter.ai; never set this in real use.
+const BASE = () => (process.env.AVA_OPENROUTER_BASE || "https://openrouter.ai").replace(/\/+$/, "");
+export const FLOW_TIMEOUT_MS = 10 * 60_000;
+
+/** A fresh PKCE pair and CSRF state. */
+export function pkce() {
+  const verifier = randomBytes(32).toString("base64url");
+  return { verifier, challenge: createHash("sha256").update(verifier).digest("base64url"), state: randomBytes(16).toString("base64url") };
+}
+
+export function authUrl({ callbackUrl, challenge, state }) {
+  const q = new URLSearchParams({ callback_url: callbackUrl, code_challenge: challenge, code_challenge_method: "S256", state, key_label: "Ava Engine" });
+  return `${BASE()}/auth?${q}`;
+}
+
+/** Trade the callback's code for an API key. Throws an Error with a message fit to show. */
+export async function exchangeCode({ code, verifier }) {
+  let r;
+  try {
+    r = await fetch(`${BASE()}/api/v1/auth/keys`, {
+      method: "POST", headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ code, code_verifier: verifier, code_challenge_method: "S256" }),
+      signal: AbortSignal.timeout(15_000),
+    });
+  } catch { throw new Error("Couldn't reach OpenRouter. Check your connection and try again."); }
+  // The docs say 403 for a bad or expired code; the live API answers 400.
+  if (r.status === 400 || r.status === 403) throw new Error("OpenRouter didn't accept the sign-in (it may have expired). Try connecting again.");
+  if (!r.ok) throw new Error(`OpenRouter answered ${r.status}. Try again, or paste a key instead.`);
+  const j = await r.json().catch(() => ({}));
+  if (typeof j.key !== "string" || j.key.length < 20) throw new Error("OpenRouter didn't return a key. Try again, or paste a key instead.");
+  return j.key;
+}
+
+/** The page the browser lands on after approving. Fixed text only: nothing from the request is echoed. */
+export function callbackPage(ok, { cssHref } = {}) {
+  const [title, text] = ok
+    ? ["OpenRouter is connected", "You can close this tab and go back to setup."]
+    : ["Not connected", "OpenRouter didn't connect. Close this tab and try again, or paste a key instead."];
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${title} · Ava setup</title>${cssHref ? `<link rel="stylesheet" href="${cssHref}">` : ""}</head>`
+    + `<body><main class="panel launching"><h1>${ok ? "✓ " : ""}${title}</h1><p class="lead">${text}</p></main></body></html>`;
+}
+
+/**
+ * Terminal flow: listen on 127.0.0.1, open the browser, wait for the callback.
+ * Resolves the key, or rejects (timeout, refused, bad state).
+ * onUrl(url) is told the sign-in URL (open it and print it).
+ */
+export function connectInBrowser({ onUrl, timeoutMs = FLOW_TIMEOUT_MS } = {}) {
+  const { verifier, challenge, state } = pkce();
+  return new Promise((resolve, reject) => {
+    let done = false;
+    const finish = (err, key) => {
+      if (done) return; done = true;
+      clearTimeout(timer);
+      setTimeout(() => server.close(), 200).unref(); // let the callback page finish sending
+      server.closeAllConnections?.();
+      if (err) reject(err); else resolve(key);
+    };
+    const server = http.createServer(async (req, res) => {
+      const url = new URL(req.url, "http://localhost");
+      if (url.pathname !== "/callback") { res.writeHead(404); return res.end(); }
+      const page = (ok) => { res.writeHead(ok ? 200 : 400, { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store", "Referrer-Policy": "no-referrer", "Content-Security-Policy": "default-src 'none'" }); res.end(callbackPage(ok)); };
+      const code = url.searchParams.get("code");
+      if (!code) { page(false); return finish(new Error("The sign-in was cancelled.")); }
+      if (url.searchParams.get("state") !== state) { page(false); return; } // not ours: keep waiting for the real one
+      try { const key = await exchangeCode({ code, verifier }); page(true); finish(null, key); }
+      catch (e) { page(false); finish(e); }
+    });
+    const timer = setTimeout(() => finish(new Error("Timed out waiting for the OpenRouter sign-in.")), timeoutMs);
+    timer.unref?.();
+    server.on("error", (e) => finish(e));
+    server.listen(0, "127.0.0.1", () => {
+      onUrl?.(authUrl({ callbackUrl: `http://localhost:${server.address().port}/callback`, challenge, state }));
+    });
+  });
+}

package/lib/cli/setup-server.mjs

@@ -0,0 +1,222 @@
+// `ava-engine setup --web`: the setup wizard as a page in your browser.
+//
+// A small, separate server that runs only during setup:
+//  - listens on 127.0.0.1 only,
+//  - every API call needs the one-time token from the URL the CLI opens,
+//  - rejects requests whose Host isn't localhost (stops DNS-rebinding attacks),
+//  - serves a strict Content-Security-Policy.
+// When you press "Launch", it saves the settings, closes, and the CLI starts Ava.
+
+import http from "node:http";
+import { readFile } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { CONFIG_FILE, MODELS_DIR, DEFAULT_PORT, readConfig, writeConfig, checkOpenRouterKey, checkElevenLabsKey, portFree, suggestPassword } from "./config.mjs";
+import { buildConfig, validateAnswers, VOICES } from "./apply.mjs";
+import { MODEL_PACKS, installedPacks, fetchPack } from "../fetch-models.mjs";
+import { loadKokoro, kokoroInstalled, KOKORO_SIZE } from "../kokoro-model.mjs";
+import { pkce, authUrl, exchangeCode, callbackPage, FLOW_TIMEOUT_MS } from "./openrouter-oauth.mjs";
+
+const PUBLIC = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "public");
+const STATIC = new Map([
+  ["/setup", ["setup.html", "text/html; charset=utf-8"]],
+  ["/setup.js", ["setup.js", "text/javascript; charset=utf-8"]],
+  ["/setup.css", ["setup.css", "text/css; charset=utf-8"]],
+  ["/favicon.svg", ["favicon.svg", "image/svg+xml"]],
+  ["/fonts/inter-var.woff2", ["fonts/inter-var.woff2", "font/woff2"]],
+  ["/fonts/inter-tight-var.woff2", ["fonts/inter-tight-var.woff2", "font/woff2"]],
+  ["/fonts/plex-mono-400.woff2", ["fonts/plex-mono-400.woff2", "font/woff2"]],
+  ["/fonts/plex-mono-500.woff2", ["fonts/plex-mono-500.woff2", "font/woff2"]],
+]);
+const HEADERS = {
+  "X-Content-Type-Options": "nosniff",
+  "Referrer-Policy": "no-referrer",
+  "Cache-Control": "no-store",
+  "Content-Security-Policy": "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; font-src 'self'; connect-src 'self' http://localhost:* http://127.0.0.1:*; frame-ancestors 'none'; base-uri 'none'; form-action 'self'",
+};
+
+const mask = (v) => (v ? `${v.slice(0, 6)}…${v.slice(-4)}` : "");
+
+async function findPort(preferred) {
+  for (let p = preferred; p < preferred + 20; p++) if (await portFree(p, "127.0.0.1")) return p;
+  return 0; // let the OS pick
+}
+
+/**
+ * Run the browser setup. Resolves { start: true, port } once you press Launch.
+ * onReady({ url }) is called when the page is ready to open.
+ */
+export async function runWebSetup({ preferredPort, formPort, onReady } = {}) {
+  process.env.AVA_MODELS_DIR ??= MODELS_DIR; // so Kokoro downloads land in ~/.ava-engine/models
+  const prev = readConfig() || {};
+  const token = randomBytes(24).toString("base64url");
+  const jobs = {}; // id → { label, state: "running" | "done" | "error", pct, error }
+  // "Connect OpenRouter": one sign-in at a time. The key stays here; the page only sees it masked.
+  let oauth = null; // { verifier, state, startedAt, status: "waiting" | "connected" | "error", key, error }
+
+  const okToken = (req) => {
+    const t = Buffer.from(String(req.headers["x-setup-token"] || ""));
+    const want = Buffer.from(token);
+    return t.length === want.length && timingSafeEqual(t, want);
+  };
+
+  function startJob(id) {
+    if (jobs[id]?.state === "running" || jobs[id]?.state === "done") return;
+    if (id === "kokoro") {
+      jobs[id] = { label: `Kokoro voice (${KOKORO_SIZE})`, state: "running", pct: 0 };
+      if (kokoroInstalled()) { jobs[id] = { ...jobs[id], state: "done", pct: 100 }; return; }
+      loadKokoro({ onProgress: ({ pct }) => { jobs[id].pct = pct; } })
+        .then(() => { jobs[id].state = "done"; jobs[id].pct = 100; })
+        .catch((e) => { jobs[id].state = "error"; jobs[id].error = e.message; });
+      return;
+    }
+    const spec = MODEL_PACKS[id];
+    jobs[id] = { label: `${spec.label} (${spec.size})`, state: "running", pct: 0 };
+    fetchPack(id, MODELS_DIR, (ev) => {
+      if (ev.phase === "download" && ev.total) jobs[id].pct = Math.min(99, Math.floor((ev.done / ev.total) * 100));
+      if (ev.phase === "extract") jobs[id].phase = "unpacking";
+    }).then(() => { jobs[id].state = "done"; jobs[id].pct = 100; })
+      .catch((e) => { jobs[id].state = "error"; jobs[id].error = e.message; });
+  }
+
+  function state() {
+    const c = readConfig() || prev;
+    return {
+      configFile: CONFIG_FILE,
+      current: {
+        openrouterKey: mask(c.OPENROUTER_API_KEY),
+        voice: VOICES[c.TTS_DEFAULT] ? c.TTS_DEFAULT : "kokoro",
+        elevenKey: mask(c.ELEVENLABS_API_KEY),
+        elevenVoice: c.ELEVEN_VOICE_ID || "",
+        audience: c.ACCESS_PASSWORD ? "others" : "me",
+        hasPassword: !!c.ACCESS_PASSWORD,
+        proxy: c.TRUST_PROXY === "1",
+        port: formPort || Number(c.PORT) || DEFAULT_PORT,
+      },
+      voices: VOICES,
+      kokoro: { installed: kokoroInstalled(), size: KOKORO_SIZE },
+      packs: Object.fromEntries(Object.entries(MODEL_PACKS).map(([id, m]) => [id, { label: m.label, size: m.size, hint: m.hint }])),
+      installedPacks: installedPacks(MODELS_DIR),
+      suggestedPassword: suggestPassword(),
+      jobs,
+    };
+  }
+
+  let finish;
+  const finished = new Promise((r) => { finish = r; });
+  let listenPort = 0;
+
+  const server = http.createServer(async (req, res) => {
+    const send = (code, body, type = "application/json") => {
+      res.writeHead(code, { ...HEADERS, "Content-Type": type });
+      res.end(typeof body === "string" || Buffer.isBuffer(body) ? body : JSON.stringify(body));
+    };
+    // DNS-rebinding guard: only answer requests addressed to this machine.
+    const host = String(req.headers.host || "");
+    if (!/^(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/i.test(host)) return send(403, { error: "forbidden host" });
+    let url;
+    try { url = new URL(req.url, "http://localhost"); } catch { return send(400, { error: "bad request" }); }
+
+    if (req.method === "GET" && STATIC.has(url.pathname)) {
+      const [file, type] = STATIC.get(url.pathname);
+      try { return send(200, await readFile(join(PUBLIC, file)), type); } catch { return send(404, "not found", "text/plain"); }
+    }
+    if (req.method === "GET" && url.pathname === "/") { res.writeHead(302, { Location: "/setup" }); return res.end(); }
+    // OpenRouter redirects the browser here after sign-in. It can't carry the page's
+    // token, so the one-time state from /openrouter/start proves it's ours.
+    if (req.method === "GET" && url.pathname === "/openrouter/callback") {
+      const page = (ok) => send(ok ? 200 : 400, callbackPage(ok, { cssHref: "/setup.css" }), "text/html; charset=utf-8");
+      const f = oauth;
+      if (!f || f.status !== "waiting" || Date.now() - f.startedAt > FLOW_TIMEOUT_MS) return page(false);
+      const code = url.searchParams.get("code");
+      if (!code) { f.status = "error"; f.error = "The sign-in was cancelled."; return page(false); }
+      const st = Buffer.from(String(url.searchParams.get("state") || "")), want = Buffer.from(f.state);
+      if (!(st.length === want.length && timingSafeEqual(st, want))) return page(false);
+      f.status = "exchanging";
+      try { f.key = await exchangeCode({ code, verifier: f.verifier }); f.status = "connected"; return page(true); }
+      catch (e) { f.status = "error"; f.error = e.message; return page(false); }
+    }
+    if (!url.pathname.startsWith("/api/setup/")) return send(404, "not found", "text/plain");
+    if (!okToken(req)) return send(401, { error: "This setup link has expired. Run `npx ava-engine setup --web` for a new one." });
+
+    let body = {};
+    if (req.method === "POST") {
+      if (!/^application\/json\b/i.test(String(req.headers["content-type"] || ""))) return send(415, { error: "expected application/json" });
+      const chunks = []; let size = 0;
+      for await (const c of req) { size += c.length; if (size > 64 * 1024) return send(413, { error: "too large" }); chunks.push(c); }
+      try { body = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}"); } catch { return send(400, { error: "invalid JSON" }); }
+    }
+
+    try {
+      const route = `${req.method} ${url.pathname}`;
+      if (route === "GET /api/setup/state") return send(200, state());
+      if (route === "GET /api/setup/jobs") return send(200, { jobs, installedPacks: installedPacks(MODELS_DIR), kokoroInstalled: kokoroInstalled() });
+      if (route === "GET /api/setup/password") return send(200, { password: suggestPassword() });
+      if (route === "POST /api/setup/check") {
+        const key = String(body.key || "").trim();
+        if (key.length < 20) return send(200, { ok: false, error: "That doesn't look like a full key." });
+        const r = body.service === "elevenlabs" ? await checkElevenLabsKey(key) : await checkOpenRouterKey(key);
+        if (r.ok && r.label && /^sk-or/i.test(r.label)) delete r.label; // unnamed keys report a masked key as their label
+        return send(200, r);
+      }
+      if (route === "POST /api/setup/openrouter/start") {
+        const { verifier, challenge, state: st } = pkce();
+        oauth = { verifier, state: st, startedAt: Date.now(), status: "waiting" };
+        return send(200, { url: authUrl({ callbackUrl: `http://localhost:${listenPort}/openrouter/callback`, challenge, state: st }) });
+      }
+      if (route === "GET /api/setup/openrouter/status") {
+        if (oauth?.status === "waiting" && Date.now() - oauth.startedAt > FLOW_TIMEOUT_MS) { oauth.status = "error"; oauth.error = "The sign-in timed out. Try again."; }
+        return send(200, oauth ? { status: oauth.status, key: oauth.key ? mask(oauth.key) : undefined, error: oauth.error } : { status: "none" });
+      }
+      if (route === "POST /api/setup/download") {
+        const id = String(body.id || "");
+        if (id !== "kokoro" && !MODEL_PACKS[id]) return send(400, { error: "unknown download" });
+        startJob(id);
+        return send(200, { ok: true, job: jobs[id] });
+      }
+      if (route === "POST /api/setup/save") {
+        const a = body.answers || {};
+        // "keep" means: leave the saved key as it is; "connected": the key from Connect OpenRouter.
+        if (a.mode !== "mock" && a.openrouterKey === "connected" && oauth?.status !== "connected") return send(400, { error: "Connect OpenRouter again: the sign-in didn't finish." });
+        const answers = {
+          openrouterKey: a.mode === "mock" ? null : a.openrouterKey === "keep" ? undefined : a.openrouterKey === "connected" ? oauth.key : String(a.openrouterKey || "") || null,
+          voice: a.voice,
+          elevenKey: a.elevenKey === "keep" ? undefined : a.elevenKey,
+          elevenVoice: a.elevenVoice,
+          audience: a.audience === "others" ? "others" : "me",
+          password: a.audience === "others" ? (a.password === "keep" ? prev.ACCESS_PASSWORD || readConfig()?.ACCESS_PASSWORD : a.password) : undefined,
+          proxy: !!a.proxy,
+          port: a.port,
+        };
+        const errors = validateAnswers(answers);
+        if (errors.length) return send(400, { error: errors.join(" ") });
+        const cfg = buildConfig(readConfig() || prev, answers);
+        const p = Number(cfg.PORT);
+        if (p !== listenPort && !(await portFree(p, cfg.HOST))) return send(409, { error: `Port ${p} is in use by another program. Pick another port.` });
+        writeConfig(cfg);
+        return send(200, { ok: true, port: p, url: `http://localhost:${p}/app`, configFile: CONFIG_FILE });
+      }
+      if (route === "POST /api/setup/finish") {
+        const cfg = readConfig();
+        if (!cfg) return send(400, { error: "Save your settings first." });
+        // Downloads still running (e.g. a voice you switched away from) keep going in
+        // this process after Ava starts; the page already waited for the ones you chose.
+        send(200, { ok: true, port: Number(cfg.PORT) || DEFAULT_PORT });
+        // let the response flush, then hand the port over to Ava
+        setTimeout(() => { server.closeAllConnections?.(); server.close(() => finish({ start: true, port: Number(cfg.PORT) || DEFAULT_PORT })); }, 150);
+        return;
+      }
+      return send(404, { error: "unknown endpoint" });
+    } catch (e) {
+      return send(500, { error: e.message });
+    }
+  });
+
+  listenPort = await findPort(preferredPort || Number(prev.PORT) || DEFAULT_PORT);
+  await new Promise((r) => server.listen(listenPort, "127.0.0.1", r));
+  listenPort = server.address().port;
+  const url = `http://localhost:${listenPort}/setup#token=${token}`;
+  onReady?.({ url, port: listenPort });
+  return finished;
+}