ava-engine 0.2.0 → 0.4.0

package/lib/library.mjs

@@ -0,0 +1,76 @@
+// The playbook library: ready-made playbooks from a public repo
+// (default https://github.com/Mr-vero/ava-playbooks), installed as your own files.
+//
+// The library's index.json lists each playbook with the sha256 of its file. A
+// download must match that hash and pass the same checks as any playbook file
+// before it's saved. Installed copies remember where they came from (origin), so
+// the dashboard can offer an update when the library's version changes.
+
+import { createHash } from "node:crypto";
+import { validatePlaybook } from "./playbooks.mjs";
+import { CUSTOM_PLAYBOOKS, savePlaybook } from "./platforms.mjs";
+
+export const DEFAULT_LIBRARY = "https://raw.githubusercontent.com/Mr-vero/ava-playbooks/main";
+const base = () => (process.env.PLAYBOOK_LIBRARY_URL || DEFAULT_LIBRARY).replace(/\/+$/, "");
+const FILE = /^playbooks\/[a-z0-9][a-z0-9-]{0,39}\.json$/;
+const MAX_INDEX = 512 * 1024, MAX_FILE = 256 * 1024, TTL_MS = 10 * 60_000;
+
+async function get(url, max) {
+  const r = await fetch(url, { signal: AbortSignal.timeout(10_000), headers: { "User-Agent": "ava-engine" } });
+  if (!r.ok) throw new Error(`The library answered ${r.status}.`);
+  const buf = Buffer.from(await r.arrayBuffer());
+  if (buf.length > max) throw new Error("A library file is too large.");
+  return buf;
+}
+
+let cache = null; // { source, at, playbooks }
+/** The library's list. Cached for 10 minutes; `fresh` skips the cache. */
+export async function libraryIndex({ fresh = false } = {}) {
+  const source = base();
+  if (!fresh && cache && cache.source === source && Date.now() - cache.at < TTL_MS) return cache;
+  let j;
+  try { j = JSON.parse((await get(`${source}/index.json`, MAX_INDEX)).toString("utf8")); }
+  catch (e) { throw new Error(`Couldn't load the playbook library (${e.message.replace(/\.$/, "")}). Check your connection, or the library address in Settings.`); }
+  const playbooks = (Array.isArray(j?.playbooks) ? j.playbooks : []).filter((p) => p && /^[a-z0-9][a-z0-9-]{0,39}$/.test(p.id) && FILE.test(p.file) && /^[0-9a-f]{64}$/.test(p.sha256))
+    .map((p) => ({
+      id: p.id, name: String(p.name || p.id).slice(0, 60), category: String(p.category || "").slice(0, 80), tagline: String(p.tagline || "").slice(0, 300),
+      accent: /^#[0-9a-f]{3,6}$/i.test(p.accent || "") ? p.accent : null, url: typeof p.url === "string" && /^https?:\/\//.test(p.url) ? p.url : null,
+      journey: Array.isArray(p.journey) ? p.journey.slice(0, 10).map((s) => String(s).slice(0, 60)) : [], facts: Number(p.facts) || 0,
+      author: String(p.author || "").slice(0, 80), file: p.file, sha256: p.sha256,
+    }));
+  cache = { source, at: Date.now(), playbooks };
+  return cache;
+}
+
+/** Each library playbook with whether you have it: available, installed, update, or taken (you have your own with that id). */
+export async function libraryView() {
+  const idx = await libraryIndex();
+  const mine = new Map(CUSTOM_PLAYBOOKS.playbooks.map((p) => [p.id, p]));
+  return {
+    source: idx.source, fetchedAt: new Date(idx.at).toISOString(),
+    playbooks: idx.playbooks.map((p) => {
+      const have = mine.get(p.id);
+      const state = !have ? "available" : have.origin?.library !== idx.source ? "taken" : have.origin.sha256 === p.sha256 ? "installed" : "update";
+      return { ...p, state };
+    }),
+  };
+}
+
+/** Download, verify and save one playbook. `overwrite` replaces your own file with the same id. */
+export async function installFromLibrary(id, { overwrite = false } = {}) {
+  const idx = await libraryIndex({ fresh: true });
+  const entry = idx.playbooks.find((p) => p.id === id);
+  if (!entry) return { status: 404, errors: ["That playbook isn't in the library."] };
+  const have = CUSTOM_PLAYBOOKS.playbooks.find((p) => p.id === id);
+  if (have && !overwrite && have.origin?.library !== idx.source) return { status: 409, errors: [`You already have your own playbook called “${id}”. Rename yours first, or replace it.`] };
+  const buf = await get(`${idx.source}/${entry.file}`, MAX_FILE);
+  if (createHash("sha256").update(buf).digest("hex") !== entry.sha256) return { status: 502, errors: ["The download doesn't match the library's checksum, so it wasn't installed."] };
+  let raw;
+  try { raw = JSON.parse(buf.toString("utf8")); } catch { return { status: 502, errors: ["The library file isn't valid JSON."] }; }
+  if (raw.id !== id) return { status: 502, errors: ["The library file's id doesn't match its listing."] };
+  delete raw.origin; // only the installer writes this
+  const check = validatePlaybook(raw);
+  if (check.errors) return { status: 502, errors: check.errors.map((e) => `Library file: ${e}`) };
+  const r = savePlaybook({ ...raw, origin: { library: idx.source, sha256: entry.sha256, installedAt: new Date().toISOString() } }, { previousId: have ? id : undefined });
+  return r.errors ? { status: 400, errors: r.errors } : { playbook: r.playbook };
+}

package/lib/links.mjs

@@ -0,0 +1,148 @@
+// Share links: a URL you give customers (/c/<id>) that opens a call already set up
+// for one product and case, with no pickers and no console.
+//
+// The id is a random 128-bit capability. Anyone holding it can start calls with
+// that link's settings, and nothing else: no dashboard, no other products, no
+// other people's calls. Pause or delete a link to stop it working. Links are
+// saved to LINKS_FILE (default ~/.ava-engine/links.json, readable only by you).
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, chmodSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { randomBytes } from "node:crypto";
+
+const FILE = process.env.LINKS_FILE || join(process.env.AVA_HOME || join(homedir(), ".ava-engine"), "links.json");
+const ID = /^[A-Za-z0-9_-]{22}$/;
+const today = () => new Date().toISOString().slice(0, 10);
+
+let links = load();
+
+function load() {
+  try {
+    const j = JSON.parse(readFileSync(FILE, "utf8"));
+    return Array.isArray(j.links) ? j.links.filter((l) => ID.test(l?.id)) : [];
+  } catch { return []; }
+}
+function save() {
+  mkdirSync(dirname(FILE), { recursive: true });
+  const tmp = `${FILE}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ links }, null, 2), { mode: 0o600 });
+  renameSync(tmp, FILE); // atomic: a crash never leaves half a file
+  try { chmodSync(FILE, 0o600); } catch {}
+}
+
+const str = (v, max) => typeof v === "string" && v.trim().length > 0 && v.length <= max;
+
+/** Check dashboard input. `productExists(id)` says whether a playbook id is real. Returns { value } or { errors }. */
+export function validateLink(input, { productExists }) {
+  const i = input && typeof input === "object" ? input : {};
+  const errors = [];
+  if (!str(i.name, 80)) errors.push("Give the link a name (up to 80 characters), e.g. “Acme onboarding: new trials”.");
+  const mode = i.mode === "flexible" ? "flexible" : "onboarding";
+  const product = i.product ? String(i.product) : null;
+  if (mode === "onboarding" && !product) errors.push("Pick the product this link onboards people onto.");
+  if (product && !productExists(product)) errors.push(`There's no playbook called “${product}”.`);
+  for (const [k, max] of [["title", 80], ["intro", 240]]) if (i[k] != null && i[k] !== "" && !str(i[k], max)) errors.push(`“${k}” can be up to ${max} characters.`);
+  let expiresAt = null;
+  if (i.expiresAt) {
+    const t = Date.parse(i.expiresAt);
+    if (!Number.isFinite(t)) errors.push("The expiry date isn't a valid date.");
+    else expiresAt = new Date(t).toISOString();
+  }
+  let dailyLimit = null;
+  if (i.dailyLimit != null && i.dailyLimit !== "") {
+    dailyLimit = Number(i.dailyLimit);
+    if (!(Number.isInteger(dailyLimit) && dailyLimit >= 1 && dailyLimit <= 100_000)) errors.push("The daily call limit must be a whole number from 1 to 100,000.");
+  }
+  if (errors.length) return { errors };
+  return {
+    value: {
+      name: i.name.trim(), mode, product,
+      title: str(i.title, 80) ? i.title.trim() : null,
+      intro: str(i.intro, 240) ? i.intro.trim() : null,
+      handoff: i.handoff !== false, steps: i.steps !== false, recap: i.recap !== false,
+      expiresAt, dailyLimit, enabled: i.enabled !== false,
+    },
+  };
+}
+
+export function listLinks() { return links.map((l) => ({ ...l, usage: usage(l) })); }
+export function getLink(id) { return typeof id === "string" && ID.test(id) ? links.find((l) => l.id === id) || null : null; }
+
+export function createLink(value) {
+  const now = new Date().toISOString();
+  const link = { id: randomBytes(16).toString("base64url"), ...value, createdAt: now, updatedAt: now, calls: 0, lastUsedAt: null, day: { date: today(), n: 0 } };
+  links.unshift(link);
+  save();
+  return link;
+}
+export function updateLink(id, value) {
+  const l = getLink(id);
+  if (!l) return null;
+  Object.assign(l, value, { updatedAt: new Date().toISOString() });
+  save();
+  return l;
+}
+export function deleteLink(id) {
+  const n = links.length;
+  links = links.filter((l) => l.id !== id);
+  if (links.length !== n) { save(); return true; }
+  return false;
+}
+
+function usage(l) {
+  const n = l.day?.date === today() ? l.day.n : 0;
+  return { today: n, total: l.calls || 0, lastUsedAt: l.lastUsedAt };
+}
+
+/** Why a link can't start a call right now (shown to the customer), or null. */
+export function linkBlocked(l) {
+  if (!l) return "This link doesn't exist. Ask whoever sent it for a new one.";
+  if (!l.enabled) return "This link is paused right now. Try again later.";
+  if (l.expiresAt && Date.parse(l.expiresAt) <= Date.now()) return "This link has expired. Ask whoever sent it for a new one.";
+  if (l.dailyLimit && usage(l).today >= l.dailyLimit) return "This link has reached today's limit. Try again tomorrow.";
+  return null;
+}
+
+/** Count a call started from a link. */
+export function countLinkCall(l) {
+  if (l.day?.date !== today()) l.day = { date: today(), n: 0 };
+  l.day.n += 1; l.calls = (l.calls || 0) + 1; l.lastUsedAt = new Date().toISOString();
+  try { save(); } catch (e) { console.warn("  [links] couldn't save usage:", e.message); }
+}
+
+/** What the customer's page needs. Nothing internal (name, limits, usage). */
+export function publicLinkView(l, platform) {
+  return {
+    id: l.id, mode: l.mode,
+    title: l.title || (platform ? `Get set up on ${platform.name}` : "Talk to Ava"),
+    intro: l.intro || (platform ? `Ava will guide you through ${platform.name}, step by step, on your own screen.` : "Share your screen and ask anything. Ava sees what you see and helps you through it."),
+    platform: platform ? { id: platform.id, name: platform.name, accent: platform.accent || null, tagline: platform.tagline || "", journey: platform.journey || [] } : null,
+    options: { handoff: l.handoff, steps: l.steps, recap: l.recap },
+  };
+}
+
+// The customer's browser proves it opened /c/<id> with a per-link cookie, so
+// WebSockets and every API call are covered without the operator password.
+export const linkCookieName = (id) => `ava_l_${id}`;
+export function linkCookieHeader(id, secure) {
+  return `${linkCookieName(id)}=1; Path=/; HttpOnly; SameSite=Lax; Max-Age=43200${secure ? "; Secure" : ""}`;
+}
+/**
+ * Live links whose cookie this request carries. Pausing, expiring or deleting a
+ * link cuts its calls off; the daily limit only stops new calls (linkBlocked),
+ * so it never drops someone mid-call.
+ */
+export function linksFromRequest(req) {
+  const out = [];
+  for (const part of String(req.headers.cookie || "").split(";")) {
+    const m = part.trim().match(/^ava_l_([A-Za-z0-9_-]{22})=1$/);
+    if (!m) continue;
+    const l = getLink(m[1]);
+    if (l && l.enabled && !(l.expiresAt && Date.parse(l.expiresAt) <= Date.now())) out.push(l);
+  }
+  return out;
+}
+
+export const LINKS_FILE = FILE;
+export function linksFileExists() { return existsSync(FILE); }

package/lib/mock.mjs

@@ -0,0 +1,88 @@
+// 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);
+
+// A customer on a share link can't add a key, so they get the same honesty
+// without the operator's instructions (o.customer is set for link calls).
+
+/** Greeting. */
+export function greet(o) {
+  if (o.customer) {
+    const what = o.mode === "onboarding" && o.platform ? `your ${o.platform.name} guide` : "your live guide";
+    return `Hi, I'm Ava, ${what}. Heads up: this is a demo, so my replies are canned for now. Voice and screen sharing work, so go ahead and try it.`;
+  }
+  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.";
+  const c = !!o.customer;
+  if (/SUPPORT/i.test(kind)) return c ? "Demo reply: sorry this is being a pain. I'm in demo mode right now, so the quickest help is “Talk to a person”." : `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}` : ""}. ${c ? "In demo mode I can't read your screen yet." : `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 c ? "Demo reply: you're sharing a tab, but in demo mode I can't read it yet."
+      : `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.`;
+  }
+  if (c) return asked ? `Demo reply: you asked “${asked}”. I'm in demo mode, so I can't answer that for real yet.` : "Demo reply: I'm in demo mode, so I can't answer for real yet.";
+  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: no reasoning model is connected.", 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/models.mjs

@@ -1,18 +1,21 @@
 // Central model config. Override any of these via env (see .env.example).
 // Slugs are OpenRouter model ids. Change freely — the UI shows whatever is set.
 
-export const MODELS = {
+import { onSettingsChange } from "./settings.mjs";
+
+const models = () => ({
   talker:     process.env.MODEL_TALKER     || "meta-llama/llama-3.3-70b-instruct", // the SPOKEN reply — latency-critical; on Groq ~0.2s TTFT (vs ~0.7s on gemini-flash-lite)
   perception: process.env.MODEL_PERCEPTION || "google/gemini-2.5-flash",
   planner:    process.env.MODEL_PLANNER    || "anthropic/claude-sonnet-4.5",
   intent:     process.env.MODEL_INTENT     || "google/gemini-2.5-flash-lite",
-};
+});
+export const MODELS = models();
 
 // Per-role provider routing (OpenRouter). Only the talker is latency-critical —
 // it's the reply the user actually hears — so we prefer Groq's very low
 // time-to-first-token. allow_fallbacks keeps replies working (just slower) if
 // Groq is briefly unavailable. Set TALKER_PROVIDER=auto to let OpenRouter pick.
-export const PROVIDER = {
+const providers = () => ({
   talker: process.env.TALKER_PROVIDER === "auto" ? undefined
     : { order: [process.env.TALKER_PROVIDER || "groq"], allow_fallbacks: true },
   // Perception (vision) is on the turn's hot path when the screen changed, so it
@@ -20,7 +23,10 @@ export const PROVIDER = {
   // default vision model may not be served by that provider).
   perception: process.env.PERCEPTION_PROVIDER && process.env.PERCEPTION_PROVIDER !== "auto"
     ? { order: [process.env.PERCEPTION_PROVIDER], allow_fallbacks: true } : undefined,
-};
+});
+export const PROVIDER = providers();
+// Settings saved in the dashboard apply to the next call (the objects are updated in place).
+onSettingsChange(() => { Object.assign(MODELS, models()); Object.assign(PROVIDER, providers()); });
 
 // Fallback price table ($ per 1M tokens) used only if OpenRouter doesn't
 // return a usage.cost for a call. Approximate; edit to taste. [in, out]

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.
@@ -10,7 +11,10 @@ function callSignal(ms) {
 }
 
 const OR_URL = "https://openrouter.ai/api/v1/chat/completions";
-export const MOCK = !process.env.OPENROUTER_API_KEY;
+import { onSettingsChange } from "./settings.mjs";
+// Live binding: adding or removing the key in the dashboard switches modes at once.
+export let MOCK = !process.env.OPENROUTER_API_KEY;
+onSettingsChange((k) => { if (k.has("OPENROUTER_API_KEY")) MOCK = !process.env.OPENROUTER_API_KEY; });
 // Optional app attribution on openrouter.ai (https://openrouter.ai/docs/app-attribution).
 const ATTRIBUTION = {
   ...(process.env.OPENROUTER_REFERER ? { "HTTP-Referer": process.env.OPENROUTER_REFERER } : {}),
@@ -63,6 +67,7 @@ export async function chat({ model, role, messages, maxTokens = 350, temperature
     };
   }
 
+  if (dailyCapReached()) throw new DailyCapError();
   const body = {
     model,
     messages,
@@ -96,6 +101,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 +119,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 +156,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.
@@ -576,7 +577,9 @@ export async function sessionSummary(sess) {
     highlights: [],
   };
   const p = out ? parseJSON(out.text, fallback) : fallback;
-  return { headline: p.headline || o.goal, summary: p.summary || "", highlights: Array.isArray(p.highlights) ? p.highlights.slice(0, 4) : [], goal: o.goal, session: scoreView(sess.score.ours) };
+  const recap = { headline: p.headline || o.goal, summary: p.summary || "", highlights: Array.isArray(p.highlights) ? p.highlights.slice(0, 4) : [] };
+  sess.recap = recap; // kept with the transcript, if transcripts are on
+  return { ...recap, goal: o.goal, session: scoreView(sess.score.ours) };
 }
 
 /* ---------- barge-in truncation ---------- */
@@ -631,8 +634,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 +724,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 +767,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) };