ava-engine 0.1.0 → 0.3.0

package/lib/cli/setup.mjs

@@ -1,12 +1,16 @@
-// `ava-engine setup`: the guided first-run wizard (and its non-interactive twin).
+// `ava-engine setup` in the terminal: the guided wizard (and its non-interactive twin).
+// The browser version lives in setup-server.mjs; both save through apply.mjs.
 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 { CONFIG_FILE, MODELS_DIR, DEFAULT_PORT, readConfig, writeConfig, checkOpenRouterKey, checkElevenLabsKey, portFree, suggestPassword, openBrowser } from "./config.mjs";
+import { connectInBrowser } from "./openrouter-oauth.mjs";
+import { buildConfig, VOICES } from "./apply.mjs";
 import { MODEL_PACKS, installedPacks, fetchPack } from "../fetch-models.mjs";
+import { loadKokoro, kokoroInstalled, KOKORO_SIZE } from "../kokoro-model.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. */
+/** Download speech model packs with a progress bar per pack. */
 export async function downloadPacks(packs) {
   for (const pack of packs) {
     const spec = MODEL_PACKS[pack];
@@ -24,18 +28,37 @@ export async function downloadPacks(packs) {
       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}`);
+      p.log.error(`${e.message}\nYou can retry later with: npx ava-engine models ${pack}`);
     }
   }
 }
 
+/** Download the Kokoro voice now, so the first call doesn't wait for it. */
+export async function downloadKokoro() {
+  process.env.AVA_MODELS_DIR ??= MODELS_DIR;
+  if (kokoroInstalled()) { p.log.success("Kokoro voice already installed"); return true; }
+  const bar = p.progress({ max: 100, style: "heavy" });
+  bar.start(`Downloading the Kokoro voice (${KOKORO_SIZE})`);
+  let last = 0;
+  try {
+    await loadKokoro({ onProgress: ({ pct }) => { if (pct > last) { bar.advance(pct - last, `Downloading the Kokoro voice: ${pct}%`); last = pct; } } });
+    bar.stop("Kokoro voice ready");
+    return true;
+  } catch (e) {
+    bar.error("Kokoro voice download failed");
+    p.log.error(`${e.message}\nAva will retry when it starts, or use the browser's voice meanwhile.`);
+    return false;
+  }
+}
+
 /**
  * The interactive wizard. Returns { start: boolean, port }.
  * Existing settings are kept unless you change them.
  */
 export async function runSetup() {
+  process.env.AVA_MODELS_DIR ??= MODELS_DIR; // so "is Kokoro installed?" looks in ~/.ava-engine/models
   const prev = readConfig() || {};
-  const cfg = { ...prev };
+  const answers = {};
 
   console.log("");
   p.intro(" ΛVΛ  Ava Engine setup ");
@@ -43,31 +66,49 @@ export async function runSetup() {
     "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,
+    "`npx ava-engine setup`, or by editing " + CONFIG_FILE,
     "Welcome",
   );
 
-  // 1 · how to start
+  // 1 · AI replies
   const mode = bail(await p.select({
-    message: "How do you want to start?",
+    message: "How should Ava think?",
     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" },
+      { value: "full", label: "With real AI", hint: "recommended; needs an OpenRouter key" },
+      { value: "mock", label: "Just look around first", hint: "no key; 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.");
+    answers.openrouterKey = null;
+    p.log.info("MOCK mode: Ava will use canned replies. Add a key any time with `npx ava-engine setup`.");
   } 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;
-    }
+    if (key && !bail(await p.confirm({ message: `Keep your current OpenRouter key (${mask(key)})?`, initialValue: true }))) key = undefined;
+    if (!key) p.log.message("Ava's AI runs through OpenRouter: one key for every model.");
     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 how = bail(await p.select({
+        message: "How do you want to add your OpenRouter key?",
+        options: [
+          { value: "connect", label: "Connect my OpenRouter account", hint: "recommended; sign in and approve in your browser" },
+          { value: "paste", label: "Paste a key", hint: "from https://openrouter.ai/keys" },
+          { value: "mock", label: "Skip for now", hint: "MOCK mode" },
+        ],
+      }));
+      if (how === "mock") break;
+      if (how === "connect") {
+        const s = p.spinner();
+        try {
+          key = await connectInBrowser({
+            onUrl: (url) => {
+              p.log.message(`Opening OpenRouter in your browser. If it doesn't open, go to:\n${url}`);
+              openBrowser(url);
+              s.start("Waiting for you to approve in the browser (Ctrl+C to stop)");
+            },
+          });
+          s.stop("Connected to OpenRouter. Tip: set a credit limit on the new key at https://openrouter.ai/keys");
+        } catch (e) { s.error(e.message); }
+        continue;
+      }
       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);
@@ -89,96 +130,88 @@ export async function runSetup() {
         if (next === "mock") break;
       }
     }
-    if (key) cfg.OPENROUTER_API_KEY = key; else delete cfg.OPENROUTER_API_KEY;
+    answers.openrouterKey = key || null;
+  }
 
-    // 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;
+  // 2 · voice (free and offline by default, so offered in every mode)
+  answers.voice = bail(await p.select({
+    message: "Which voice should Ava speak with?",
+    initialValue: VOICES[prev.TTS_DEFAULT] ? prev.TTS_DEFAULT : "kokoro",
+    options: Object.entries(VOICES).map(([value, v]) => ({ value, label: v.label, hint: value === "kokoro" && kokoroInstalled() ? "free, runs on this computer (installed)" : v.hint })),
+  }));
+  if (answers.voice === "kokoro") await downloadKokoro();
+  if (answers.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 }))) { answers.voice = "kokoro"; await downloadKokoro(); break; }
       }
     }
-
-    // 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).");
+    if (ek) {
+      answers.elevenKey = ek;
+      answers.elevenVoice = bail(await p.text({ message: "ElevenLabs voice ID (Enter for the default voice, Matilda)", placeholder: "XrExE9yKIg1WjnnlVkGX", defaultValue: prev.ELEVEN_VOICE_ID || "" })).trim() || null;
+    }
   }
 
-  // 5 · who can reach it
-  const audience = bail(await p.select({
+  // 3 · speech recognition (offered in every mode)
+  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). Add them later with `npx ava-engine models`.");
+
+  // 4 · who can reach it
+  answers.audience = bail(await p.select({
     message: "Who will use this Ava?",
-    initialValue: prev.HOST === "127.0.0.1" || !prev.ACCESS_PASSWORD ? "me" : "others",
+    initialValue: prev.ACCESS_PASSWORD ? "others" : "me",
     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;
+  if (answers.audience === "others") {
     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: "gen", label: `Use a generated one: ${suggested}`, hint: "recommended; it's saved in the settings 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;
+    answers.password = how === "keep" ? prev.ACCESS_PASSWORD : how === "gen" ? suggested
+      : bail(await p.password({ message: "Access password (at least 10 characters)", validate: (v) => (!v || v.length < 10 ? "Use at least 10 characters" : undefined) }));
+    answers.proxy = bail(await p.confirm({ message: "Will it run behind a proxy or host (Fly.io, Cloudflare, nginx, Render…)?", initialValue: prev.TRUST_PROXY === "1" }));
   }
 
-  // 6 · port
+  // 5 · 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>\`.`);
+  answers.port = Number(portStr) || DEFAULT_PORT;
 
-  // 7 · save
-  cfg.AVA_MODELS_DIR = MODELS_DIR;
+  // 6 · save
+  const cfg = buildConfig(prev, answers);
+  if (!(await portFree(Number(cfg.PORT), cfg.HOST))) p.log.warn(`Port ${cfg.PORT} is in use right now. Stop that program, or run \`npx ava-engine start --port <other>\`.`);
   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)"}`,
+      `Voice          ${VOICES[cfg.TTS_DEFAULT]?.label || "Kokoro"}`,
       `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`,
@@ -209,11 +242,16 @@ export async function runSetupNonInteractive({ models = [], port } = {}) {
   cfg.AVA_MODELS_DIR = MODELS_DIR;
   writeConfig(cfg);
   for (const pack of models) {
-    console.log(`↓ ${MODEL_PACKS[pack]?.label || pack}`);
+    if (pack === "kokoro") {
+      process.env.AVA_MODELS_DIR ??= MODELS_DIR;
+      console.log("↓ Kokoro voice");
+      if (!kokoroInstalled()) await loadKokoro();
+      continue;
+    }
+    if (!MODEL_PACKS[pack]) throw new Error(`unknown model "${pack}" (choose: ${Object.keys(MODEL_PACKS).join(", ")}, kokoro)`);
+    console.log(`↓ ${MODEL_PACKS[pack].label}`);
     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 };

package/lib/kokoro-model.mjs

@@ -0,0 +1,51 @@
+// The offline Kokoro voice model: where it's cached, whether it's there, and
+// loading it with download progress. Shared by the server and the setup wizard.
+//
+// It's cached under the models folder (~/.ava-engine/models/kokoro for the CLI),
+// not inside node_modules, so it survives `npx` updates instead of downloading
+// again after every new version.
+
+import { existsSync, readdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const KOKORO_MODEL = process.env.KOKORO_MODEL || "onnx-community/Kokoro-82M-v1.0-ONNX";
+export const KOKORO_DTYPE = process.env.KOKORO_DTYPE || "q8";
+export const KOKORO_SIZE = "~90 MB";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+export function kokoroCacheDir() {
+  return process.env.KOKORO_CACHE_DIR || join(process.env.AVA_MODELS_DIR || join(ROOT, "models"), "kokoro");
+}
+
+/** True once the model's weights are on disk (no network needed to start). */
+export function kokoroInstalled(dir = kokoroCacheDir()) {
+  const onnx = join(dir, ...KOKORO_MODEL.split("/"), "onnx");
+  try { return existsSync(onnx) && readdirSync(onnx).some((f) => f.endsWith(".onnx")); } catch { return false; }
+}
+
+/**
+ * Load Kokoro, downloading it first if needed.
+ * onProgress({ loaded, total, pct }) reports the overall download.
+ */
+export async function loadKokoro({ onProgress } = {}) {
+  const { env } = await import("@huggingface/transformers");
+  env.cacheDir = kokoroCacheDir();
+  const { KokoroTTS } = await import("kokoro-js");
+  const files = new Map(); // file → { loaded, total }
+  // Count only the large files (the weights). The small config/tokenizer files
+  // finish first and would make the bar jump to 100% and back.
+  const progress_callback = (e) => {
+    if (!onProgress || e.status !== "progress" || !(e.total > 1_000_000)) return;
+    files.set(e.file, { loaded: e.loaded, total: e.total });
+    let loaded = 0, total = 0;
+    for (const f of files.values()) { loaded += f.loaded; total += f.total; }
+    onProgress({ loaded, total, pct: Math.min(100, Math.floor((loaded / total) * 100)) });
+  };
+  // transformers.js warns about a missing content-length on every download; it's
+  // harmless and would break the setup wizard's progress bar, so hide just that line.
+  const warn = console.warn;
+  console.warn = (...args) => { if (!String(args[0]).includes("content-length")) warn(...args); };
+  try { return await KokoroTTS.from_pretrained(KOKORO_MODEL, { dtype: KOKORO_DTYPE, device: "cpu", progress_callback }); }
+  finally { console.warn = warn; }
+}

package/lib/mock.mjs

@@ -0,0 +1,78 @@
+// Demo mode (no OPENROUTER_API_KEY): what each agent "says" without a model.
+//
+// Rules: always say it's a demo and how to switch real answers on; never claim to
+// see a screen (there's no vision without a model); and use the context we really
+// have: the chosen product, the current onboarding step, what the user asked.
+
+// Spoken aloud too, so no command names here; the lobby shows the exact command.
+const KEY_HINT = "add an OpenRouter key in setup for real answers";
+
+function quote(text, max = 70) {
+  const t = String(text || "").replace(/\s+/g, " ").trim();
+  return t.length > max ? t.slice(0, max - 1).trimEnd() + "…" : t;
+}
+
+/** The onboarding step the user is on, with its how-to line from the playbook. */
+function currentStep(o) {
+  if (o.mode !== "onboarding" || !o.platform || !o.workflow) return null;
+  const i = o.workflow.current ?? 0;
+  return { title: o.workflow.steps[i]?.title, how: o.platform.path?.[i] };
+}
+
+const sharing = (o) => !!(o.screenState && !o.screenState.stale);
+
+/** Greeting. */
+export function greet(o) {
+  if (o.mode === "onboarding" && o.platform) {
+    return `Hi, I'm Ava, your ${o.platform.name} guide. Heads up: this is demo mode, so my replies are canned until you ${KEY_HINT}. Voice, screen sharing and the step tracker all work, so share your ${o.platform.name} tab and try it.`;
+  }
+  return `Hi, I'm Ava. Heads up: this is demo mode, so my replies are canned until you ${KEY_HINT}. Voice and screen sharing work, so share a tab or ask me anything to see how a call feels.`;
+}
+
+/** The talker's reply to a user turn. `kind` is the router's mode (help/support/wrap…). */
+export function reply(o, userText, kind = "") {
+  if (/WRAP/i.test(kind)) return "Demo reply: no problem, we can pick this up whenever you like.";
+  if (/SUPPORT/i.test(kind)) return `Demo reply: sorry this is being a pain. I'm in demo mode right now, so ${KEY_HINT}, or ask for a person with “Talk to a person”.`;
+  const asked = quote(userText);
+  const step = currentStep(o);
+  if (step?.title) {
+    return `Demo reply: on ${o.platform.name}, the next step is “${step.title}”${step.how ? `: ${step.how}` : ""}. In demo mode I can't read your screen, so ${KEY_HINT} and I'll guide you based on what's actually there.`;
+  }
+  if (sharing(o)) {
+    return `Demo reply: you're sharing a tab, but in demo mode I can't read it. ${KEY_HINT[0].toUpperCase() + KEY_HINT.slice(1)}, and I'll answer “${asked}” based on what's on your screen.`;
+  }
+  return asked
+    ? `Demo reply: you asked “${asked}”. I'm in demo mode, so ${KEY_HINT}. Sharing a tab works now too.`
+    : `Demo reply: I'm in demo mode, so ${KEY_HINT}.`;
+}
+
+/** Perception: honest about not reading the screen. */
+export function vision() {
+  return JSON.stringify({
+    app: "Shared tab", page: "not read in demo mode", elements: [], content: [],
+    state: "Demo mode can't read screens without an OpenRouter key.",
+    look: "", activity: "no real change",
+  });
+}
+
+export function thinking() {
+  return JSON.stringify({ resolved: false, stuck: false, blocker: "", thought: "Demo mode: reasoning needs an OpenRouter key.", nextTactic: "" });
+}
+
+export function planner(o) {
+  if (o.mode === "onboarding" && o.platform) {
+    return JSON.stringify({ goal: `Get set up on ${o.platform.name} and into the dashboard`, understanding: "demo mode: following the playbook's steps", plan: (o.platform.journey || []).slice(0, 3), guidance: "demo mode" });
+  }
+  return JSON.stringify({ goal: "Try Ava in demo mode", understanding: "exploring the demo", plan: ["Share a tab", "Ask a question", "Add an OpenRouter key for real answers"], guidance: "demo mode" });
+}
+
+/** Intention guess while browsing silently: low confidence, so it's ignored. */
+export function guess() {
+  return JSON.stringify({ goal: "explore Ava in demo mode", understanding: "demo mode", confidence: 0.2 });
+}
+
+export function nudge(o) {
+  return o.mode === "onboarding" && o.platform
+    ? `Demo mode: share your ${o.platform.name} tab or ask me about a step to see how I respond.`
+    : "Demo mode: share a tab or ask me something to see how I respond.";
+}

package/lib/openrouter.mjs

@@ -1,5 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { estimateCost } from "./models.mjs";
+import { dailyCapReached, recordSpend, DailyCapError } from "./spend.mjs";
 
 // The HTTP request a model call belongs to. When that client disconnects mid-turn,
 // its in-flight calls are aborted instead of spending tokens nobody will read.
@@ -63,6 +64,7 @@ export async function chat({ model, role, messages, maxTokens = 350, temperature
     };
   }
 
+  if (dailyCapReached()) throw new DailyCapError();
   const body = {
     model,
     messages,
@@ -96,6 +98,7 @@ export async function chat({ model, role, messages, maxTokens = 350, temperature
   const promptTokens = u.prompt_tokens ?? 0;
   const completionTokens = u.completion_tokens ?? 0;
   const cost = typeof u.cost === "number" ? u.cost : estimateCost(model, promptTokens, completionTokens);
+  recordSpend(cost);
   return { text, model, role, promptTokens, completionTokens, cost, latencyMs, mocked: false };
 }
 
@@ -113,6 +116,7 @@ export async function chatStream({ model, role, messages, maxTokens = 220, tempe
     return { text, model, role, promptTokens, completionTokens, cost: estimateCost(model, promptTokens, completionTokens), latencyMs: Date.now() - t0, mocked: true };
   }
 
+  if (dailyCapReached()) throw new DailyCapError();
   const res = await fetch(OR_URL, {
     method: "POST",
     headers: {
@@ -149,5 +153,6 @@ export async function chatStream({ model, role, messages, maxTokens = 220, tempe
   const promptTokens = usage?.prompt_tokens ?? 0;
   const completionTokens = usage?.completion_tokens ?? 0;
   const cost = typeof usage?.cost === "number" ? usage.cost : estimateCost(model, promptTokens, completionTokens);
+  recordSpend(cost);
   return { text, model, role, promptTokens, completionTokens, cost, latencyMs: Date.now() - t0, mocked: false };
 }

package/lib/ours.mjs

@@ -6,6 +6,8 @@
 
 import { chat, chatStream, estTokens } from "./openrouter.mjs";
 import { MODELS, PROVIDER } from "./models.mjs";
+import * as demo from "./mock.mjs";
+import { emitEvent, specialistUrl } from "./webhooks.mjs";
 import { record, scoreView, addTokens, mintSpecialistKey, revokeSpecialistKey } from "./state.mjs";
 
 const HAMMING_SAME = 20; // on the 2048-bit (32×32) dHash — ~1%; a tab switch or text change flips more
@@ -121,13 +123,6 @@ function similar(a, b) {
 function activityLine(o) { return o.activity.length ? o.activity.slice(-6).map((a) => "• " + a.action).join("\n") : "—"; }
 
 /* ---------- 1. Perception (diff-gated, rich) ---------- */
-function mockVision(userText) {
-  const t = (userText || "").toLowerCase();
-  let app = "OpenRouter", page = "Credits";
-  if (/ai studio|gemini/.test(t)) { app = "Google AI Studio"; page = "Playground"; }
-  else if (/gmail|inbox|email/.test(t)) { app = "Gmail"; page = "Inbox"; }
-  return JSON.stringify({ app, page, elements: ["Manage", "Auto Top-Up: enabled", "Add Credits (disabled)"], state: "Auto top-up is on; Add Credits looks greyed out", look: "clean light UI, indigo accents, roomy spacing — feels friendly and modern", changed: ["screen updated"] });
-}
 // Serialize perception per session: /api/observe and /api/turn can arrive
 // concurrently, and both write screenState/lastHash — unserialized, a slow
 // response can overwrite a fresher read and clobber the diff-gate hash.
@@ -150,7 +145,7 @@ async function doPerceive(o, frameDataUrl, screenActive, frameHash, userText, us
     { role: "system", content: "Read this app screenshot for an assistant that will guide the user (the assistant does NOT see the image — your JSON is its only eyes, including for OPINIONS about the design AND for naming actual content on screen). Output ONLY minified JSON: {\"app\":string,\"page\":string,\"elements\":[\"up to 14 KEY buttons/links/toggles/fields — EXACT on-screen text + state like (disabled)/(selected)/(greyed)\"],\"content\":[\"up to 16 of the MAIN CONTENT items actually visible, copied VERBATIM and IN THE ORDER SHOWN top-to-bottom (the FIRST entry is the topmost/newest). Include identifying detail: for a list/feed (emails, videos, results) give each row as 'primary — secondary — time/meta', e.g. email row 'The Daily Byte — Your daily AI news — 9:12 AM', video 'Se7en Review — Nerdwriter — 1.2M views'. COMPARISON / PRICING / PLAN layouts (side-by-side cards, tables): capture EVERY tier/column as its own entry with ALL its key numbers — name, price WITH period, AND the headline quota/limit like credits or seats per period, e.g. 'Pro — $99/mo — 500,000 credits/mo'. NEVER drop the quota/credits in favor of the price — small or low-contrast numbers still count. For an OPENED item being VIEWED (an email, doc, video) capture its header FULLY: sender NAME and their email ADDRESS if shown (e.g. 'The Daily Byte <news@dailybyte.example>'), the subject/title, and the date. Never invent — copy only what is truly on screen; [] if none\"],\"state\":\"one line: what's shown, WHICH TAB/SECTION is selected, key values/numbers\",\"look\":\"1-2 lines on the VISUAL design: dominant colors (names + hex if shown), typography and layout feel, density, overall vibe\",\"activity\":\"short phrase: what the user most likely just DID vs the PREVIOUS screen, or 'no real change'\"}. Copy on-screen text VERBATIM; never guess text that isn't visible; keep each entry terse." },
     { role: "user", content: [{ type: "image_url", image_url: { url: frameDataUrl } }, { type: "text", text: `PREVIOUS screen was: ${prevSummary}\nRead the CURRENT screen and infer the activity (what the user just did).` }] },
   ];
-  const out = await chat({ model: MODELS.perception, role: "perception", provider: PROVIDER.perception, messages, maxTokens: 1100, temperature: 0.1, mock: () => mockVision(userText) });
+  const out = await chat({ model: MODELS.perception, role: "perception", provider: PROVIDER.perception, messages, maxTokens: 1100, temperature: 0.1, mock: () => demo.vision() });
   usages.push(out);
   const parsed = parseJSON(out.text, null);
   const usable = parsed && ((parsed.elements && parsed.elements.length) || (parsed.state && String(parsed.state).length > 3) || (parsed.app && !/^unknown/i.test(parsed.app)));
@@ -208,7 +203,7 @@ async function think(o, userText, usages) {
     { role: "system", content: THINK_SYS },
     { role: "user", content: `GOAL: ${o.goal}\nSCREEN NOW: ${screenLine(o, true)}\nRECENT ACTIVITY (newest last):\n${activityLine(o)}\nCONVERSATION:\n${recent}\nYOUR RECENT INSTRUCTIONS (don't just repeat these): ${myLines}\nUSER JUST SAID: "${userText}"` },
   ];
-  const out = await chat({ model: MODELS.intent, role: "thinking", messages, maxTokens: 150, temperature: 0.2, mock: () => JSON.stringify({ resolved: false, stuck: false, blocker: "", thought: "Following the sign-in steps — screen is advancing, nothing stuck yet.", nextTactic: "" }) });
+  const out = await chat({ model: MODELS.intent, role: "thinking", messages, maxTokens: 150, temperature: 0.2, mock: () => demo.thinking() });
   usages.push(out);
   const p = parseJSON(out.text, { resolved: false, stuck: false, blocker: "", thought: "", nextTactic: "" });
   o.lastThink = { resolved: !!p.resolved, stuck: !!p.stuck, blocker: p.blocker || "", thought: p.thought || "", nextTactic: p.nextTactic || "" };
@@ -226,7 +221,7 @@ function buildWorkflowFromPlan(o) {
   if (o.workflow || !o.plan || !o.plan.length) return;
   o.workflow = { title: o.goal && o.goal !== "—" ? cap(o.goal) : "Your task", steps: o.plan.map((t, i) => ({ title: cap(t), status: i === 0 ? "active" : "todo" })), current: 0, etaMin: null, note: "" };
 }
-function applyWorkflow(o, p) {
+export function applyWorkflow(o, p) { // exported for tests
   const wf = o.workflow; if (!wf || !p) return;
   const n = wf.steps.length;
   let cur = Number.isInteger(p.current) ? p.current : wf.current;
@@ -252,6 +247,23 @@ function applyWorkflow(o, p) {
   wf.complete = wf.steps.length > 0 && wf.steps.every((s) => s.status === "done");
   o.done = wf.complete;
   if (!o.done) o.doneAnnounced = false; // regressed → allow a fresh wrap-up later
+  reportProgress(o);
+}
+// Each step (and the whole journey) is reported once, the first time it's done on
+// screen. The tracker can regress, but a webhook receiver shouldn't see repeats.
+function reportProgress(o) {
+  const wf = o.workflow;
+  wf.reported ??= new Set();
+  const total = wf.steps.length;
+  wf.steps.forEach((s, i) => {
+    if (s.status !== "done" || wf.reported.has(i)) return;
+    wf.reported.add(i);
+    emitEvent("step.completed", { sessionId: o.sessionId, workflow: wf.title, step: { index: i, title: s.title }, done: wf.reported.size, total });
+  });
+  if (wf.complete && !wf.reportedComplete) {
+    wf.reportedComplete = true;
+    emitEvent("workflow.completed", { sessionId: o.sessionId, workflow: wf.title, total, platform: o.platform ? { id: o.platform.id, name: o.platform.name } : null });
+  }
 }
 async function trackWorkflow(o, usages) {
   if (!o.workflow) return null;
@@ -342,16 +354,13 @@ function compileContext(o, route, intent, userText, screenActive) {
 }
 
 /* ---------- 4. Planner (async: goal + grounded plan) ---------- */
-function mockPlanner(o) {
-  return JSON.stringify({ goal: "add credits manually on " + (o.screenState?.app || "the site"), understanding: "user wants to top up manually", plan: ["disable auto top-up", "find Add Credits", "enter amount & pay"], guidance: "be precise and grounded in the screen" });
-}
 async function plan(o, usages) {
   const hist = o.history.slice(-10).map((t) => `${t.role}: ${t.text}`).join("\n");
   const messages = [
     { role: "system", content: 'You are the planner for a screen-aware assistant. Re-derive the goal from the user\'s LATEST messages and the CURRENT screen — the newest signals always outweigh older ones. If the user has pivoted to a new task, topic, or app, REPLACE the goal and plan entirely; never carry forward a goal the user has moved past. If there is no clear task yet, keep the goal broad ("help with whatever they ask") rather than inventing one. Output ONLY JSON: {"goal":"<one line: the concrete thing the user is trying to accomplish RIGHT NOW>","understanding":"<one line>","plan":["<=3 short next steps, grounded in real UI>"],"guidance":"<one line tone/pace note>"}.' },
     { role: "user", content: `Screen: ${o.screenState && !o.screenState.stale ? o.screenState.app + " · " + o.screenState.page + " — " + (o.screenState.state || "") : "not shared"}\nVisible: ${(o.screenState?.elements || []).join(" | ")}\nRecent activity:\n${activityLine(o)}\nConversation:\n${hist}` },
   ];
-  const out = await chat({ model: MODELS.planner, role: "planner", messages, maxTokens: 200, temperature: 0.4, mock: () => mockPlanner(o) });
+  const out = await chat({ model: MODELS.planner, role: "planner", messages, maxTokens: 200, temperature: 0.4, mock: () => demo.planner(o) });
   usages.push(out);
   const p = parseJSON(out.text, null);
   if (p) { o.goal = p.goal || o.goal; o.understanding = p.understanding || o.understanding; o.plan = Array.isArray(p.plan) ? p.plan.slice(0, 3) : o.plan; o.guidance = p.guidance || o.guidance; }
@@ -363,14 +372,6 @@ async function plan(o, usages) {
   return out;
 }
 
-function mockTalker(messages) {
-  const c = messages[messages.length - 1].content;
-  const txt = Array.isArray(c) ? (c.find((x) => x.type === "text")?.text || "") : c;
-  if (/GREET/.test(txt)) return "Hey! I'm Ava — I can see your screen and help with pretty much anything on it. Share a window whenever you like, or just tell me what you're working on.";
-  if (/MODE: SUPPORT/.test(txt)) return "I've got you — looking at your screen now. Tap 'Manage' next to Auto Top-Up; the disable option is inside there.";
-  if (/MODE: WRAP/.test(txt)) return "All good — we can pick this up whenever. I'll be right here.";
-  return "Looking at your screen — tap 'Manage' next to Auto Top-Up, then choose Disable. That unlocks the manual Add Credits option.";
-}
 
 /* ---------- greeting ---------- */
 export async function greetStream(sess, emit, voiceMode = false) {
@@ -381,7 +382,7 @@ export async function greetStream(sess, emit, voiceMode = false) {
     : "GREET: open the call. In 1–2 short sentences, warmly introduce yourself as a screen-aware assistant that can help with anything on their screen, and invite them to share their screen or say what they're working on.";
   const messages = [{ role: "system", content: sys }, { role: "user", content: greetMsg }];
   emit("talkerStart", { model: MODELS.talker });
-  const tk = await chatStream({ model: MODELS.talker, role: "talker", provider: PROVIDER.talker, messages, maxTokens: 120, temperature: 0.6, mock: mockTalker, onDelta: (d) => emit("delta", { text: d }) });
+  const tk = await chatStream({ model: MODELS.talker, role: "talker", provider: PROVIDER.talker, messages, maxTokens: 120, temperature: 0.6, mock: () => demo.greet(sess.ours), onDelta: (d) => emit("delta", { text: d }) });
   tk.text = sanitizeReply(stripLabel(tk.text));
   usages.push(tk); remember(sess.ours, "assistant", tk.text); pushBridge(sess, "ava", tk.text);
   emit("talkerDone", { text: tk.text, model: MODELS.talker, prompt: tk.promptTokens, output: tk.completionTokens, tokens: tk.promptTokens + tk.completionTokens, latencyMs: tk.latencyMs, cost: tk.cost });
@@ -494,7 +495,7 @@ export async function oursTurnStream(sess, userText, frameDataUrl, screenActive,
   const sys = talkerSystem(o, voiceMode);
   let tk;
   try {
-    tk = await chatStream({ model: MODELS.talker, role: "talker", provider: PROVIDER.talker, messages: [{ role: "system", content: sys }, { role: "user", content: compiled }], maxTokens: voiceMode ? 140 : 200, temperature: voiceMode ? 0.65 : 0.5, mock: mockTalker, onDelta: (d) => emit("delta", { text: d }) });
+    tk = await chatStream({ model: MODELS.talker, role: "talker", provider: PROVIDER.talker, messages: [{ role: "system", content: sys }, { role: "user", content: compiled }], maxTokens: voiceMode ? 140 : 200, temperature: voiceMode ? 0.65 : 0.5, mock: () => demo.reply(o, userText, route.mode), onDelta: (d) => emit("delta", { text: d }) });
   } catch (e) {
     // The talker failed or the client hung up mid-reply. Calls that already ran
     // (vision, intent, thinking) were billed — count them toward the budget.
@@ -631,8 +632,19 @@ export async function observeUpdate(sess, frameDataUrl, frameHash, force = false
 // believable connecting → waiting state. (No live agent backend here.)
 export function requestHandoff(sess) {
   const o = sess.ours;
-  if (!o.handoff.requested) o.handoff = { requested: true, state: "connecting", at: Date.now() };
-  return { handoff: o.handoff, specialistKey: mintSpecialistKey(sess), workflow: o.workflow ? workflowView(o) : null };
+  const first = !o.handoff.requested;
+  if (first) o.handoff = { requested: true, state: "connecting", at: Date.now() };
+  const specialistKey = mintSpecialistKey(sess);
+  if (first) {
+    const wf = o.workflow;
+    emitEvent("handoff.requested", {
+      sessionId: sess.id, specialistUrl: specialistUrl(specialistKey), mode: o.mode,
+      platform: o.platform ? { id: o.platform.id, name: o.platform.name } : null, goal: o.goal !== "—" ? o.goal : null,
+      workflow: wf ? { title: wf.title, currentStep: wf.steps[wf.current]?.title || null, done: wf.steps.filter((s) => s.status === "done").length, total: wf.steps.length } : null,
+      lastUserMessage: [...o.history].reverse().find((t) => t.role === "user")?.text?.slice(0, 200) || null,
+    });
+  }
+  return { handoff: o.handoff, specialistKey, workflow: o.workflow ? workflowView(o) : null };
 }
 export function handoffStatus(sess) {
   const o = sess.ours;
@@ -710,7 +722,7 @@ async function guessIntention(o, usages) {
     { role: "system", content: 'From a user\'s screen journey, infer what they are most likely TRYING TO DO overall — a concrete task, not a description of where they are. Output ONLY JSON: {"goal":"<one concrete line, e.g. \'top up their OpenRouter credits\'>","understanding":"<one line: where they are in that journey>","confidence":<0..1>}. Ambiguous journey → confidence below 0.5.' },
     { role: "user", content: `Screens/actions (oldest first): ${acts}\nCurrent screen: ${screenLine(o, true)}\nPrevious guess: ${o.goal}` },
   ];
-  const out = await chat({ model: MODELS.intent, role: "intent", messages, maxTokens: 90, temperature: 0.3, mock: () => JSON.stringify({ goal: "top up their OpenRouter credits", understanding: "circling the billing pages", confidence: 0.8 }) });
+  const out = await chat({ model: MODELS.intent, role: "intent", messages, maxTokens: 90, temperature: 0.3, mock: () => demo.guess() });
   usages.push(out);
   o.lastGuessAt = Date.now();
   const p = parseJSON(out.text, null);
@@ -753,7 +765,7 @@ export async function proactiveNudge(sess) {
     { role: "system", content: momentSys },
     { role: "user", content: `SCREEN NOW: ${screenLine(o, true)}\nGOAL${o.goalGuessed ? " (your inference from their journey — engage with it, confirm it naturally when useful)" : ""}: ${o.goal}\nPLAN: ${planLine}\nRECENT ACTIVITY (newest last — this is what just happened):\n${activityLine(o)}\nYOU LAST SPOKE: ${since}. Your recent lines (never repeat these): ${recentMine.join(" / ") || "—"}${directive}` },
   ];
-  const out = await chat({ model: MODELS.talker, role: "talker", provider: PROVIDER.talker, messages, maxTokens: 60, temperature: 0.7, mock: () => "Want a hand with anything here?" });
+  const out = await chat({ model: MODELS.talker, role: "talker", provider: PROVIDER.talker, messages, maxTokens: 60, temperature: 0.7, mock: () => demo.nudge(o) });
   usages.push(out); addTokens(sess, "ours", usages);
   const t = sanitizeReply(stripLabel(out.text));
   const base = { goal: o.goal, understanding: o.understanding, goalGuessedNow: !!guessedNow, workflow: o.workflow ? workflowView(o) : null, session: scoreView(sess.score.ours) };