ava-engine 0.2.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

@@ -149,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/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";
@@ -20,6 +21,8 @@ const HELP = `
     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 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})
@@ -77,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 = [];
@@ -118,6 +150,7 @@ 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, downloadKokoro } = await import("./setup.mjs");

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

@@ -16,6 +16,7 @@ import { CONFIG_FILE, MODELS_DIR, DEFAULT_PORT, readConfig, writeConfig, checkOp
 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([
@@ -51,6 +52,8 @@ export async function runWebSetup({ preferredPort, formPort, onReady } = {}) {
   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"] || ""));
@@ -120,6 +123,20 @@ export async function runWebSetup({ preferredPort, formPort, onReady } = {}) {
       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." });
 
@@ -143,6 +160,15 @@ export async function runWebSetup({ preferredPort, formPort, onReady } = {}) {
         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" });
@@ -151,9 +177,10 @@ export async function runWebSetup({ preferredPort, formPort, onReady } = {}) {
       }
       if (route === "POST /api/setup/save") {
         const a = body.answers || {};
-        // "keep" means: leave the saved key as it is.
+        // "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 : String(a.openrouterKey || "") || null,
+          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,

package/lib/cli/setup.mjs

@@ -1,7 +1,8 @@
 // `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 { 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";
@@ -83,8 +84,31 @@ export async function runSetup() {
   } else {
     let key = prev.OPENROUTER_API_KEY;
     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);

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) };

package/lib/platforms.mjs

@@ -2,8 +2,13 @@
 // talker/planner enough to act like a real product specialist for that product:
 // the sign-up → dashboard path, a clean short "journey" for the live progress
 // tracker, and a small knowledge base the agent can retrieve from (RAG).
+//
+// These are built-in samples. Your own products go in playbook files (see
+// lib/playbooks.mjs and docs/setup/customize.md); they're merged in below.
 
-export const PLATFORMS = [
+import { loadPlaybooks, mergePlaybooks, PLAYBOOKS_DIR } from "./playbooks.mjs";
+
+export const BUILTIN_PLATFORMS = [
   {
     id: "todoist", name: "Todoist", url: "https://app.todoist.com",
     category: "Productivity", accent: "#E44332",
@@ -194,6 +199,15 @@ export const PLATFORMS = [
   },
 ];
 
+const custom = loadPlaybooks();
+for (const p of custom.problems) {
+  for (const e of p.errors) console.warn(`  [playbooks] ${p.file} skipped: ${e}`);
+  for (const w of p.warnings) console.warn(`  [playbooks] ${p.file}: ${w}`);
+}
+const hideBuiltins = /^(off|0|false|no)$/i.test(process.env.BUILTIN_PLAYBOOKS || "");
+export const PLATFORMS = mergePlaybooks(BUILTIN_PLATFORMS, custom.playbooks, { hideBuiltins });
+export const CUSTOM_PLAYBOOKS = { count: custom.playbooks.length, dir: PLAYBOOKS_DIR };
+
 export function platformById(id) { return PLATFORMS.find((p) => p.id === id) || null; }
 // Trimmed shape for the onboarding picker in the client (demo-only entries hidden).
 // Demo-only (fictional) products are included, flagged, so demo mode can select

package/lib/playbooks.mjs

@@ -0,0 +1,111 @@
+// Playbooks: the products Ava can onboard people onto, as JSON files you own.
+//
+// Put one file per product in PLAYBOOKS_DIR (default ~/.ava-engine/playbooks), for
+// example acme.json. A file whose id matches a built-in product replaces it.
+// BUILTIN_PLAYBOOKS=off hides the built-in sample products, so the lobby shows only
+// yours. Files are checked when Ava starts: a broken one is skipped with a message
+// saying what to fix, and never stops the server. `ava-engine playbooks` checks
+// them without starting anything.
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const home = (p) => p.replace(/^~(?=$|[\\/])/, homedir()); // .env files don't expand ~
+export const PLAYBOOKS_DIR = home(process.env.PLAYBOOKS_DIR || join(process.env.AVA_HOME || join(homedir(), ".ava-engine"), "playbooks"));
+
+const ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
+const HEX = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+const KNOWN = new Set(["id", "name", "url", "category", "accent", "tagline", "firstWin", "path", "optional", "journey", "etaMin", "knowledge", "demoOnly", "$schema"]);
+
+/** Starter file for `ava-engine playbooks new <id>`. */
+export function template(id) {
+  return {
+    id, name: "Acme", url: "https://app.acme.example",
+    category: "Your product", accent: "#4F46E5",
+    tagline: "One line on what the product does and why setup takes a hand.",
+    firstWin: "the moment they get value, e.g. their first report open on the dashboard",
+    path: [
+      "sign in or sign up",
+      "create a workspace (name it, keep the Free plan)",
+      "connect a data source from the Sources page",
+      "open the dashboard and see the first report",
+    ],
+    optional: "Things that can wait until after the first win, e.g. inviting teammates.",
+    journey: ["Sign in", "Create a workspace", "Connect a source", "See your first report"],
+    etaMin: 5,
+    knowledge: [
+      { keywords: "workspace create name plan free", text: "Workspaces hold everything. The Free plan is enough to start and can be upgraded later from Settings → Billing." },
+      { keywords: "source connect csv database import", text: "Sources → Add source connects a database or uploads a CSV. The first sync takes about a minute." },
+    ],
+  };
+}
+
+const str = (v, max) => typeof v === "string" && v.trim().length > 0 && v.length <= max;
+const strList = (v, maxItems, maxLen) => Array.isArray(v) && v.length <= maxItems && v.every((s) => str(s, maxLen));
+
+/**
+ * Check one playbook. Returns { playbook } (normalized, ready to use) or { errors: [...] }.
+ * `fallbackId` is the file name, used when the JSON has no id.
+ */
+export function validatePlaybook(raw, fallbackId) {
+  const errors = [], warnings = [];
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return { errors: ["the file must contain one JSON object"], warnings };
+  const id = raw.id ?? fallbackId;
+  if (!ID.test(String(id ?? ""))) errors.push(`"id" must be lowercase letters, digits and dashes, up to 40 characters (got ${JSON.stringify(id)})`);
+  if (!str(raw.name, 60)) errors.push(`"name" is required (up to 60 characters)`);
+  if (raw.url !== undefined && !(str(raw.url, 300) && /^https?:\/\/[^\s]+$/i.test(raw.url))) errors.push(`"url" must start with http:// or https://`);
+  if (raw.accent !== undefined && !HEX.test(String(raw.accent))) errors.push(`"accent" must be a hex colour like "#4F46E5"`);
+  for (const k of ["category", "tagline", "firstWin", "optional"]) if (raw[k] !== undefined && !str(raw[k], 300)) errors.push(`"${k}" must be text (up to 300 characters)`);
+  if (!strList(raw.journey, 10, 60) || raw.journey.length === 0) errors.push(`"journey" is required: 1 to 10 short step names (up to 60 characters each), shown in the progress tracker`);
+  if (raw.path !== undefined && !strList(raw.path, 12, 400)) errors.push(`"path" must be a list of up to 12 how-to lines (up to 400 characters each)`);
+  if (raw.etaMin !== undefined && !(Number.isInteger(raw.etaMin) && raw.etaMin >= 1 && raw.etaMin <= 120)) errors.push(`"etaMin" must be a whole number of minutes from 1 to 120`);
+  if (raw.demoOnly !== undefined && typeof raw.demoOnly !== "boolean") errors.push(`"demoOnly" must be true or false`);
+  let knowledge = [];
+  if (raw.knowledge !== undefined) {
+    if (!Array.isArray(raw.knowledge) || raw.knowledge.length > 200) errors.push(`"knowledge" must be a list of up to 200 entries`);
+    else raw.knowledge.forEach((e, i) => {
+      const kw = Array.isArray(e?.keywords) ? e.keywords.join(" ") : e?.keywords ?? e?.k;
+      if (!str(e?.text, 1000)) errors.push(`knowledge[${i}]: "text" is required (up to 1000 characters)`);
+      else if (!str(kw, 300)) errors.push(`knowledge[${i}]: "keywords" is required: the words a question would use, e.g. "invoice export csv download"`);
+      else knowledge.push({ k: kw.toLowerCase(), text: e.text });
+    });
+  }
+  for (const k of Object.keys(raw)) if (!KNOWN.has(k)) warnings.push(`unknown field "${k}" is ignored`);
+  if (errors.length) return { errors, warnings };
+  const { name, url, category, accent, tagline, firstWin, optional, etaMin, demoOnly } = raw;
+  return {
+    warnings,
+    playbook: {
+      id, name, url, category: category || "Your product", accent, tagline: tagline || "", firstWin: firstWin || "the first step done",
+      path: raw.path || [], optional, journey: raw.journey, etaMin: etaMin || null, knowledge, ...(demoOnly ? { demoOnly: true } : {}),
+    },
+  };
+}
+
+/** Read every *.json in `dir`. Returns { playbooks, problems: [{file, errors, warnings}] }. */
+export function loadPlaybooks(dir = PLAYBOOKS_DIR) {
+  const playbooks = [], problems = [];
+  if (!existsSync(dir)) return { playbooks, problems, dir };
+  const seen = new Map();
+  for (const file of readdirSync(dir).filter((f) => f.endsWith(".json")).sort()) {
+    let raw;
+    try { raw = JSON.parse(readFileSync(join(dir, file), "utf8")); }
+    catch (e) { problems.push({ file, errors: [`not valid JSON: ${e.message}`], warnings: [] }); continue; }
+    const r = validatePlaybook(raw, file.replace(/\.json$/, ""));
+    if (r.playbook && seen.has(r.playbook.id)) r.errors = [`id "${r.playbook.id}" is already used by ${seen.get(r.playbook.id)}`];
+    if (r.errors?.length) { problems.push({ file, errors: r.errors, warnings: r.warnings }); continue; }
+    if (r.warnings.length) problems.push({ file, errors: [], warnings: r.warnings });
+    seen.set(r.playbook.id, file);
+    playbooks.push({ ...r.playbook, source: file });
+  }
+  return { playbooks, problems, dir };
+}
+
+/** Built-ins plus your files: yours replace a built-in with the same id. */
+export function mergePlaybooks(builtins, custom, { hideBuiltins = false } = {}) {
+  const ids = new Set(custom.map((p) => p.id));
+  // Demo-only built-ins stay: demo mode needs them and the lobby never lists them.
+  const kept = builtins.filter((b) => !ids.has(b.id) && (!hideBuiltins || b.demoOnly));
+  return [...custom, ...kept];
+}

package/lib/spend.mjs

@@ -0,0 +1,59 @@
+// Daily spending cap across every session: DAILY_BUDGET_USD (unset or 0 = no cap).
+//
+// Counts what OpenRouter bills for model calls (its reported usage.cost, or our
+// estimate), per UTC day. Once today's total reaches the cap, new paid calls are
+// refused until midnight UTC. Calls already in flight finish, so the total can
+// overshoot by a few cents. Speech providers (Deepgram, ElevenLabs, Hume) bill
+// separately and aren't counted.
+//
+// The total is saved to SPEND_FILE (default ~/.ava-engine/spend.json) so a restart
+// doesn't reset it. Nothing is written when no cap is set.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export const DAILY_BUDGET_USD = Math.max(0, Number(process.env.DAILY_BUDGET_USD) || 0);
+const FILE = process.env.SPEND_FILE || join(process.env.AVA_HOME || join(homedir(), ".ava-engine"), "spend.json");
+
+const today = () => new Date().toISOString().slice(0, 10);
+let ledger = load();
+
+function load() {
+  if (!DAILY_BUDGET_USD) return { day: today(), usd: 0 };
+  try {
+    const j = JSON.parse(readFileSync(FILE, "utf8"));
+    if (typeof j.day === "string" && Number.isFinite(j.usd) && j.usd >= 0) return { day: j.day, usd: j.usd };
+  } catch { /* first run or unreadable: start from zero */ }
+  return { day: today(), usd: 0 };
+}
+
+function current() {
+  const d = today();
+  if (ledger.day !== d) ledger = { day: d, usd: 0 };
+  return ledger;
+}
+
+/** Add the cost of a finished call to today's total. */
+export function recordSpend(usd) {
+  if (!(usd > 0)) return;
+  const l = current();
+  l.usd += usd;
+  if (!DAILY_BUDGET_USD) return;
+  try {
+    if (!existsSync(dirname(FILE))) mkdirSync(dirname(FILE), { recursive: true });
+    writeFileSync(FILE, JSON.stringify(l));
+  } catch (e) { console.warn("  [spend] couldn't save the daily total:", e.message); }
+}
+
+/** True once today's spend has reached DAILY_BUDGET_USD. */
+export function dailyCapReached() {
+  return DAILY_BUDGET_USD > 0 && current().usd >= DAILY_BUDGET_USD;
+}
+
+/** Today's total, for logs and tests. */
+export function spentToday() { return current().usd; }
+
+export class DailyCapError extends Error {
+  constructor() { super("daily spending cap reached"); this.status = 402; this.code = "daily_cap"; }
+}

package/lib/state.mjs

@@ -1,6 +1,7 @@
 // In-memory session store for the flexible agent.
 
 import { randomUUID } from "node:crypto";
+import { emitEvent } from "./webhooks.mjs";
 
 const sessions = new Map();
 const byKey = new Map(); // specialist key → session id (see mintSpecialistKey)
@@ -13,16 +14,24 @@ const MAX_SESSIONS = Number(process.env.MAX_SESSIONS) || 50;
 const MAX_AGE_MS = 6 * 3600 * 1000;
 const IDLE_MS = 30 * 60 * 1000;
 
-function drop(id) {
+function drop(id, reason) {
   const s = sessions.get(id);
-  if (s?.specialistKey) revokeSpecialistKey(s);
+  if (!s) return;
+  if (s.specialistKey) revokeSpecialistKey(s);
   sessions.delete(id);
+  const o = s.ours, wf = o.workflow;
+  emitEvent("session.ended", {
+    sessionId: id, reason, mode: o.mode, platform: o.platform ? { id: o.platform.id, name: o.platform.name } : null,
+    durationSec: Math.round((Date.now() - s.createdAt) / 1000), turns: s.score.ours.turns, costUsd: Math.round(s.score.ours.cost * 1e4) / 1e4,
+    workflow: wf ? { title: wf.title, done: wf.steps.filter((x) => x.status === "done").length, total: wf.steps.length, completed: !!wf.complete } : null,
+    handoffRequested: !!o.handoff?.requested,
+  });
 }
 
 /** Room for one more session? Expired and idle sessions are pruned first. */
 export function hasCapacity() {
   const now = Date.now();
-  for (const [id, s] of sessions) { if (now - s.createdAt > MAX_AGE_MS || now - s.lastActive > IDLE_MS) drop(id); }
+  for (const [id, s] of sessions) { if (now - s.createdAt > MAX_AGE_MS || now - s.lastActive > IDLE_MS) drop(id, "expired"); }
   return sessions.size < MAX_SESSIONS;
 }
 
@@ -39,6 +48,7 @@ export function newSession(opts = {}) {
     lastActive: Date.now(),
     specialistKey: null,         // capability for the human-specialist console; minted on handoff
     ours: {
+      sessionId: id,           // for the events this session's agents report (webhooks)
       mode,                    // "flexible" | "onboarding"
       platform,                // onboarding target {id,name,url,firstWin,path,...} or null
       screenState: null,       // last structured screen state {app,page,elements,state,v}
@@ -108,8 +118,7 @@ export function revokeSpecialistKey(sess) {
 export function endSession(id) {
   const s = sessions.get(id);
   if (!s) return false;
-  revokeSpecialistKey(s);
-  drop(id);
+  drop(id, "hangup");
   return true;
 }
 export function getSessionBySpecialistKey(key) {

package/lib/webhooks.mjs

@@ -0,0 +1,68 @@
+// Event webhooks: tell your own systems what happens on calls.
+//
+//   WEBHOOK_URL        one or more URLs (comma-separated) that receive every event as JSON
+//   WEBHOOK_SECRET     signs each delivery: X-Ava-Signature: sha256=HMAC(secret, `${timestamp}.${body}`)
+//   SLACK_WEBHOOK_URL  a Slack incoming webhook; posts when a customer asks for a person
+//   PUBLIC_URL         where specialists open Ava (for the links in those messages)
+//
+// Events: session.started, step.completed, workflow.completed, handoff.requested,
+// session.ended. Delivery is fire-and-forget with one retry, so a slow or broken
+// endpoint never holds up a call.
+
+import { createHmac, randomUUID } from "node:crypto";
+
+const URLS = (process.env.WEBHOOK_URL || "").split(",").map((u) => u.trim()).filter(Boolean);
+const SECRET = process.env.WEBHOOK_SECRET || "";
+const SLACK = process.env.SLACK_WEBHOOK_URL || "";
+const TIMEOUT_MS = 5_000, RETRY_MS = 2_000;
+
+export const WEBHOOKS_ENABLED = URLS.length > 0 || !!SLACK;
+
+/** The URL a specialist opens to join a call. */
+export function specialistUrl(key) {
+  const base = (process.env.PUBLIC_URL || `http://localhost:${Number(process.env.PORT) || 5190}`).replace(/\/+$/, "");
+  return `${base}/specialist?key=${encodeURIComponent(key)}`;
+}
+
+async function post(url, body, headers, label) {
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const r = await fetch(url, { method: "POST", headers: { "Content-Type": "application/json", "User-Agent": "ava-engine", ...headers }, body, signal: AbortSignal.timeout(TIMEOUT_MS) });
+      if (r.ok || (r.status >= 400 && r.status < 500 && r.status !== 429)) {
+        if (!r.ok) console.warn(`  [${label}] endpoint refused the event (${r.status})`);
+        return r.ok;
+      }
+    } catch { /* network error or timeout: retry once */ }
+    if (attempt === 0) await new Promise((r) => setTimeout(r, RETRY_MS));
+  }
+  console.warn(`  [${label}] delivery failed after a retry`); // never log the URL: Slack URLs are secrets
+  return false;
+}
+
+/** Signature headers for a delivery body (exported for tests and for receivers to copy). */
+export function sign(body, timestamp, secret = SECRET) {
+  return "sha256=" + createHmac("sha256", secret).update(`${timestamp}.${body}`).digest("hex");
+}
+
+function slackText(type, data) {
+  if (type !== "handoff.requested") return null;
+  const where = data.platform ? ` on ${data.platform.name}` : "";
+  const step = data.workflow?.currentStep ? `\n*Stuck on:* ${data.workflow.currentStep} (${data.workflow.done}/${data.workflow.total} steps done)` : "";
+  const said = data.lastUserMessage ? `\n*Last said:* “${data.lastUserMessage}”` : "";
+  return `:raising_hand: A customer${where} asked to talk to a person.${step}${said}\n<${data.specialistUrl}|Join the call>`;
+}
+
+/** Send an event to every configured endpoint. Returns a promise tests can await; callers needn't. */
+export function emitEvent(type, data) {
+  if (!WEBHOOKS_ENABLED) return Promise.resolve();
+  const event = { id: randomUUID(), type, createdAt: new Date().toISOString(), data };
+  const body = JSON.stringify(event);
+  const jobs = URLS.map((url) => {
+    const ts = String(Math.floor(Date.now() / 1000));
+    const headers = { "X-Ava-Event": type, "X-Ava-Delivery": event.id, "X-Ava-Timestamp": ts, ...(SECRET ? { "X-Ava-Signature": sign(body, ts) } : {}) };
+    return post(url, body, headers, "webhook");
+  });
+  const text = SLACK && slackText(type, data);
+  if (text) jobs.push(post(SLACK, JSON.stringify({ text }), {}, "slack"));
+  return Promise.allSettled(jobs);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ava-engine",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "A screen-aware voice agent: sees the tab a user shares, talks them through it, and hands off to a human when needed.",
   "keywords": [

package/public/app.js

@@ -25,6 +25,8 @@ let pip = null;
   try {
     const h = await (await fetch("/api/health")).json();
     S.tts = h.tts || { enabled: false };
+    // Demo mode (no API key): say so up front, in the lobby and on the call.
+    if (h.mock) { $("obDemo").hidden = false; $("demoPill").hidden = false; }
     S.stt = !!(h.stt && h.stt.enabled);
     S.sttStream = !!(h.stt && h.stt.streaming); // offline sherpa streaming ASR on the server
     // speech-recognition engine picker (green room)

package/public/index.html

@@ -47,6 +47,7 @@
       <div class="ob-header">
         <h1>Start a session</h1>
         <p>Choose how Ava should work, then check your audio before connecting.</p>
+        <p class="ob-demo" id="obDemo" hidden><b>Demo mode.</b> Replies are canned until you add an OpenRouter key: run <code>npx ava-engine setup</code>.</p>
       </div>
 
       <div class="ob-section">
@@ -129,6 +130,7 @@
   <span class="vdiv"></span>
   <span class="apptitle" id="apptitle">Flexible Agent</span>
   <span class="mono meta hide-narrow" id="topsub">screen-aware assistant</span>
+  <span id="demoPill" class="pill demo" hidden title="Replies are canned until an OpenRouter key is added">DEMO MODE</span>
   <span id="livepill" class="pill standby"><span class="dot"></span><span id="livepilltext">STANDBY</span></span>
   <div class="grow"></div>
   <span id="privacy" class="privacypill" hidden>

package/public/setup.css

@@ -54,6 +54,9 @@ input.short { max-width: 160px; flex: none; }
 .keep label, .check { font-weight: 400 !important; display: flex; gap: 10px; align-items: center; font-size: 15px; }
 .keep input, .check input { width: 18px; height: 18px; accent-color: var(--accent); }
 
+.connect { display: flex; flex-direction: column; gap: 8px; align-items: flex-start; }
+.or { display: flex; align-items: center; gap: 12px; margin: 10px 0 2px; color: var(--meta); font-size: 14px; }
+.or::before, .or::after { content: ""; flex: 1; height: 1px; background: var(--line); }
 .status { margin: 0; min-height: 22px; font-size: 14.5px; }
 .status.ok { color: var(--ok); } .status.err { color: var(--err); }
 .banner { padding: 14px 18px; border-radius: 12px; margin-bottom: 24px; }

package/public/setup.html

@@ -40,6 +40,12 @@
       <div class="field" id="keyField">
         <div id="keepKeyRow" class="keep" hidden><label><input type="checkbox" id="keepKey" checked> Keep my current key <code id="currentKey"></code></label></div>
         <div id="newKeyRow">
+          <div class="connect">
+            <button type="button" class="btn primary" id="connectOr">Connect OpenRouter</button>
+            <p class="hint">Sign in to OpenRouter and approve, and Ava gets its own key. Nothing to copy.</p>
+            <p class="status" id="connectStatus" role="status" aria-live="polite"></p>
+          </div>
+          <p class="or"><span>or paste a key</span></p>
           <label for="orKey">OpenRouter API key</label>
           <div class="row">
             <input id="orKey" type="password" autocomplete="off" spellcheck="false" placeholder="sk-or-v1-…">

package/public/setup.js

@@ -39,7 +39,7 @@
   }
   function canLeave(step) {
     if (step === "ai" && radio("mode") === "full" && !(S.state.current.openrouterKey && $("keepKey").checked) && !S.keyOk) {
-      setStatus($("keyStatus"), "Check your key first, or choose “Just look around first”.", "err"); return false;
+      setStatus($("keyStatus"), "Connect OpenRouter or check a key first, or choose “Just look around first”.", "err"); return false;
     }
     if (step === "voice" && radio("voice") === "elevenlabs" && !(S.state.current.elevenKey && $("keepEleven").checked) && !S.elevenOk) {
       setStatus($("elevenStatus"), "Check your ElevenLabs key first, or pick another voice.", "err"); return false;
@@ -56,6 +56,30 @@
   });
 
   // ── 1 · AI ──
+  // Connect OpenRouter: sign-in opens in a new tab; the setup server receives the
+  // key and keeps it. This page only learns that it worked, plus a masked key.
+  async function connectOpenRouter() {
+    const tab = window.open("about:blank", "_blank"); // open now, while the click still counts, so it isn't blocked
+    setStatus($("connectStatus"), "Opening OpenRouter…");
+    try {
+      const { url } = await api("openrouter/start", {});
+      if (tab) { tab.opener = null; tab.location = url; } else location.assign(url);
+      setStatus($("connectStatus"), "Waiting for you to approve in the OpenRouter tab…");
+      clearInterval(S.connectTimer);
+      S.connectTimer = setInterval(async () => {
+        let r; try { r = await api("openrouter/status"); } catch { return; }
+        if (r.status === "connected") {
+          clearInterval(S.connectTimer);
+          S.connected = true; S.keyOk = true; $("orKey").value = "";
+          setStatus($("connectStatus"), `✓ Connected (${r.key}). Set a credit limit on it at openrouter.ai/keys.`, "ok");
+          setStatus($("keyStatus"), "");
+        } else if (r.status === "error") {
+          clearInterval(S.connectTimer);
+          setStatus($("connectStatus"), `✗ ${r.error}`, "err");
+        }
+      }, 1500);
+    } catch (e) { tab?.close(); setStatus($("connectStatus"), `✗ ${e.message}`, "err"); }
+  }
   function syncMode() {
     const full = radio("mode") === "full";
     $("keyField").hidden = !full;
@@ -163,7 +187,7 @@
     const mode = radio("mode"), voice = radio("voice"), audience = radio("audience");
     return {
       mode,
-      openrouterKey: mode === "mock" ? null : S.state.current.openrouterKey && $("keepKey").checked ? "keep" : $("orKey").value.trim(),
+      openrouterKey: mode === "mock" ? null : S.state.current.openrouterKey && $("keepKey").checked ? "keep" : S.connected && !$("orKey").value.trim() ? "connected" : $("orKey").value.trim(),
       voice,
       elevenKey: voice === "elevenlabs" ? (S.state.current.elevenKey && $("keepEleven").checked ? "keep" : $("elKey").value.trim()) : undefined,
       elevenVoice: voice === "elevenlabs" ? $("elVoice").value.trim() || null : undefined,
@@ -246,7 +270,8 @@
     $("keepEleven").addEventListener("change", syncVoice);
     document.querySelectorAll('input[name="audience"]').forEach((i) => i.addEventListener("change", syncAudience));
     $("keepPass").addEventListener("change", syncAudience);
-    $("orKey").addEventListener("input", () => { S.keyOk = false; setStatus($("keyStatus"), ""); });
+    $("orKey").addEventListener("input", () => { S.keyOk = !!S.connected && !$("orKey").value.trim(); setStatus($("keyStatus"), ""); });
+    $("connectOr").addEventListener("click", connectOpenRouter);
     $("elKey").addEventListener("input", () => { S.elevenOk = false; setStatus($("elevenStatus"), ""); });
     $("checkKey").addEventListener("click", () => checkKey("openrouter", $("orKey"), $("keyStatus"), "keyOk"));
     $("checkEleven").addEventListener("click", () => checkKey("elevenlabs", $("elKey"), $("elevenStatus"), "elevenOk"));

package/public/style.css

@@ -96,6 +96,10 @@ b { font-weight: 600; }
 .pill { display: flex; align-items: center; gap: 7px; padding: 5px 11px 5px 9px; border-radius: 999px; font-family: var(--mono); font-size: 10px; font-weight: 500; letter-spacing: 0.1em; }
 .pill .dot { width: 6px; height: 6px; border-radius: 50%; }
 .pill.standby { background: var(--control); border: 1px solid var(--edge); color: var(--ink2); }
+.pill.demo { background: #FFF6E5; border: 1px solid #F2D49A; color: #7A4B00; }
+.pill.demo[hidden], .ob-demo[hidden] { display: none; }
+.ob-demo { margin-top: 12px; padding: 10px 14px; border-radius: 10px; background: #FFF6E5; border: 1px solid #F2D49A; color: #5C3A00; font-size: 13.5px; }
+.ob-demo code { font-family: var(--mono); font-size: 12.5px; }
 .pill.standby .dot { border: 1px solid var(--meta); }
 .pill.live { background: var(--brandtint); border: 1px solid var(--brandline); color: var(--amber); }
 .pill.live .dot { background: var(--amber); }

package/server.mjs

@@ -12,8 +12,10 @@ import { oursTurnStream, greetStream, observeUpdate, screenOff, proactiveNudge,
 import { synth, TTS_ENABLED, providers, defaultProvider, warmKokoro, kokoroStream, KOKORO_STREAMS, elevenStream, ELEVEN_STREAMS, TtsBusyError } from "./lib/tts.mjs";
 import { transcribe, STT_ENABLED } from "./lib/stt.mjs";
 import { createAsrSession, asrAvailable, warmAsr, availableEngines, defaultEngine, ENGINE_LABELS } from "./lib/asr.mjs";
-import { platformsView, platformById } from "./lib/platforms.mjs";
+import { platformsView, platformById, CUSTOM_PLAYBOOKS } from "./lib/platforms.mjs";
 import { AUTH_ENABLED, isAuthorized, challengeHeaders, authCookieHeader, clientIp, sameOrigin, limiter } from "./lib/guard.mjs";
+import { emitEvent, WEBHOOKS_ENABLED } from "./lib/webhooks.mjs";
+import { DAILY_BUDGET_USD, dailyCapReached, spentToday } from "./lib/spend.mjs";
 import { WebSocketServer } from "ws";
 
 // A stray rejection is logged, not fatal. An uncaught exception leaves the process
@@ -93,6 +95,7 @@ function send(res, code, body, headers = {}) {
 // Upstream errors (OpenRouter, ElevenLabs, Deepgram…) can carry account or quota
 // detail. Log it here; the browser only gets a short, generic reason.
 function upstreamFail(res, e, what) {
+  if (e?.code === "daily_cap") return send(res, 503, { error: CAP_MSG }, { "Retry-After": untilMidnightUtc() });
   console.error(`  [${what}]`, e?.message || e);
   return send(res, e?.status === 429 ? 429 : 502, { error: `${what} failed` });
 }
@@ -125,7 +128,14 @@ function readBody(req, limit = 3 * 1024 * 1024) {
 
 function safeHost(req) { const h = String(req.headers.host || ""); return /^[a-z0-9.-]+(:\d+)?$/i.test(h) ? h : ""; }
 function validFrame(f) { return typeof f === "string" && f.length <= MAX_FRAME_BYTES && FRAME_RE.test(f) ? f : null; }
-function overBudget(sess) { return sess.score.ours.cost >= SESSION_BUDGET_USD; }
+const CAP_MSG = "Ava has reached today's usage limit — try again tomorrow";
+/** Why a session can't spend more (its own budget, or the daily cap across all sessions), or null. */
+function spendLimit(sess) {
+  if (!MOCK && dailyCapReached()) return CAP_MSG;
+  if (sess.score.ours.cost >= SESSION_BUDGET_USD) return "this session reached its spend limit — start a new call";
+  return null;
+}
+const untilMidnightUtc = () => String(Math.ceil((new Date().setUTCHours(24, 0, 0, 0) - Date.now()) / 1000));
 
 async function serveStatic(req, res, pathname) {
   let p;
@@ -201,6 +211,7 @@ async function handle(req, res) {
     if (req.method === "GET" && url.pathname === "/api/health") {
       return send(res, 200, {
         mock: MOCK,
+        dailyCapReached: !MOCK && dailyCapReached(),
         models: { talker: MODELS.talker, perception: MODELS.perception, planner: MODELS.planner, intent: MODELS.intent },
         labels: ROLE_LABEL,
         tts: { enabled: TTS_ENABLED, providers: providers(), default: defaultProvider() },
@@ -285,11 +296,13 @@ async function handle(req, res) {
     if (req.method === "POST" && url.pathname === "/api/session") {
       if (!rate.session(clientIp(req))) return send(res, 429, { error: "too many new sessions — try again in a minute" }, { "Retry-After": "60" });
       if (!hasCapacity()) return send(res, 503, { error: "Ava is at capacity right now — try again in a few minutes" }, { "Retry-After": "60" });
+      if (!MOCK && dailyCapReached()) return send(res, 503, { error: CAP_MSG }, { "Retry-After": untilMidnightUtc() });
       const body = await readBody(req);
       const mode = body.mode === "onboarding" ? "onboarding" : "flexible";
       const platform = typeof body.platformId === "string" ? platformById(body.platformId) : null; // knowledge in any mode
       const s = newSession({ mode, platform });
       if (!s) return send(res, 503, { error: "Ava is at capacity right now — try again in a few minutes" }, { "Retry-After": "60" });
+      emitEvent("session.started", { sessionId: s.id, mode, platform: platform ? { id: platform.id, name: platform.name } : null });
       // pre-warm the talker route so the greeting isn't a cold start
       if (!MOCK) chat({ model: MODELS.talker, role: "talker", provider: PROVIDER.talker, messages: [{ role: "user", content: "hi" }], maxTokens: 1 }).catch(() => {});
       return send(res, 200, { sessionId: s.id, mock: MOCK, models: MODELS, mode, platform: platform ? { id: platform.id, name: platform.name, url: platform.url } : null });
@@ -300,7 +313,8 @@ async function handle(req, res) {
       const { sessionId, frameHash = null, greet = false, voice = false, changed = false, screenActive = false } = body;
       const sess = getSession(sessionId);
       if (!sess) return send(res, 404, { error: "unknown session" });
-      if (overBudget(sess)) return send(res, 402, { error: "this session reached its spend limit — start a new call" });
+      const limit = spendLimit(sess);
+      if (limit) return send(res, 402, { error: limit });
       const userText = String(body.userText ?? "").slice(0, MAX_USER_TEXT);
       const frame = validFrame(body.frame);
 
@@ -310,8 +324,8 @@ async function handle(req, res) {
         if (greet) await greetStream(sess, emit, !!voice);
         else await oursTurnStream(sess, userText, frame, !!screenActive, frameHash, emit, !!voice, !!changed);
       } catch (e) {
-        console.error("  [turn]", e?.message || e);
-        emit("error", { error: "Ava couldn't answer that one — try again" });
+        if (e?.code === "daily_cap") emit("error", { error: CAP_MSG });
+        else { console.error("  [turn]", e?.message || e); emit("error", { error: "Ava couldn't answer that one — try again" }); }
       }
       res.end();
       return;
@@ -322,7 +336,7 @@ async function handle(req, res) {
       const sess = getSession(sessionId);
       if (!sess) return send(res, 404, { error: "unknown session" });
       if (stopped) return send(res, 200, screenOff(sess)); // user stopped sharing → mark state stale now
-      if (overBudget(sess)) return send(res, 402, { error: "spend limit reached" });
+      if (spendLimit(sess)) return send(res, 402, { error: spendLimit(sess) });
       const frame = validFrame(rawFrame);
       if (!frame) return send(res, 400, { error: "no frame" });
       try { return send(res, 200, await observeUpdate(sess, frame, frameHash, !!changed)); }
@@ -382,7 +396,7 @@ async function handle(req, res) {
       const { sessionId } = await readBody(req);
       const sess = getSession(sessionId);
       if (!sess) return send(res, 404, { error: "unknown session" });
-      if (overBudget(sess)) return send(res, 402, { error: "spend limit reached" });
+      if (spendLimit(sess)) return send(res, 402, { error: spendLimit(sess) });
       try { return send(res, 200, await proactiveNudge(sess)); }
       catch (e) { return upstreamFail(res, e, "nudge"); }
     }
@@ -493,6 +507,9 @@ server.listen(PORT, HOST, () => {
   console.log(`  → http://localhost:${PORT}/app`);
   console.log(`  mode: ${MOCK ? "MOCK (no OPENROUTER_API_KEY set — synthetic replies)" : "LIVE (OpenRouter)"}`);
   if (!MOCK) console.log(`  models: talker=${MODELS.talker}  perception=${MODELS.perception}  planner=${MODELS.planner}  intent=${MODELS.intent}`);
+  if (!MOCK) console.log(DAILY_BUDGET_USD ? `  daily cap: $${DAILY_BUDGET_USD} (spent today: $${spentToday().toFixed(2)})` : "  daily cap: none (set DAILY_BUDGET_USD to limit spend across all calls)");
+  if (CUSTOM_PLAYBOOKS.count) console.log(`  playbooks: ${CUSTOM_PLAYBOOKS.count} from ${CUSTOM_PLAYBOOKS.dir}`);
+  if (WEBHOOKS_ENABLED) console.log("  webhooks: on");
   if (LOCAL_ONLY) console.log("  access: this computer only");
   else if (!AUTH_ENABLED) console.log("  access: OPEN — anyone who can reach this server can spend your API credit. Set ACCESS_PASSWORD before exposing it.");
   else console.log("  access: password protected");