ava-engine 0.2.0 → 0.4.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

@@ -58,20 +58,37 @@ Requires **Node 22.9+** and desktop **Chrome**. One command installs Ava and wal
 npx ava-engine
 ```
 
-Set up **in your browser** (a step-by-step page) or **in the terminal**; both do the same:
+First it asks where to set up: **in your browser** (a guided page) or **in the terminal**. Both do the same:
 1. check your OpenRouter key (or look around with no keys, in MOCK mode);
 2. pick Ava's voice, and download the free offline voice (Kokoro, ~90 MB) with progress;
 3. download offline speech recognition, also with progress;
 4. protect Ava with a password if other people will use it;
-5. start Ava and open **http://localhost:5190/app**.
+5. start Ava and open your **dashboard** at **http://localhost:5190/dashboard**.
 
 After that, `npx ava-engine` just starts Ava.
 
+### Run it from the dashboard
+
+| | |
+| --- | --- |
+| **Overview** | Live status, today's calls and spend, who's waiting for a person, and a getting-started checklist |
+| **Inbox** | Customers who asked for a person, live. A sound and a notification when someone new is waiting; **Pick up** marks it yours and opens the specialist console |
+| **Calls** | Live calls (join a customer who asked for a person) and history with search, filters and CSV export. Each call has a page: outcome, journey, length, cost, and (if you turn transcripts on) the conversation and recap |
+| **Analytics** | How many finish onboarding, the step where people get stuck (with a hint on what to fix), how often they need a person, and cost per finished onboarding. By period, product and link |
+| **Share links** | One link per product and case, e.g. a trial welcome email or your app's help menu. Customers land on a simple start page with no pickers and no console. Pause, expire or cap a link per day. **Embed** gives you one line of HTML for a "Talk to Ava" button in your own product |
+| **Playbooks** | Describe your product in a form, or **Draft with AI** from your docs page. Or install one from the shared [playbook library](https://github.com/Mr-vero/ava-playbooks) and adapt it. Live on new calls as soon as you save |
+| **Team** | Everyone signs in with their own account: owners (everything), editors (links, playbooks, calls) and specialists (the inbox). API keys for n8n, Zapier or your backend: everything the dashboard does, over [the API](docs/API.md). Locked out? `npx ava-engine team reset you@company.com` |
+| **Settings** | Edit keys, models, voice, password, public address, limits and webhooks, applied without a restart (host, port and proxy mode need one). Connect OpenRouter from here too. Secrets are never shown back |
+
+`/app` stays as your own test bench. Preselect it with `/app?mode=onboarding&product=<playbook id>`.
+
 | Command | What it does |
 | --- | --- |
 | `npx ava-engine setup` | Re-run setup to change keys, voice, password or port (`--web` for the browser, `--terminal` for here) |
 | `npx ava-engine doctor` | Check everything and get a fix for anything that's wrong |
 | `npx ava-engine models` | Download speech models or the Kokoro voice (`models kokoro`) |
+| `npx ava-engine playbooks` | Check your playbook files (`playbooks new <id>` writes a starter) |
+| `npx ava-engine team` | List team accounts (`team add <email>`, `team reset <email>`) |
 | `npx ava-engine start --port 8080` | Start on another port |
 
 Settings live in `~/.ava-engine` (set `AVA_HOME` to move them). **Watch the demo locally** at `http://localhost:5190/app?demo=simple`.
@@ -105,6 +122,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
 | 🎧 | [**Speech-to-text**](docs/setup/speech-to-text.md) | Offline sherpa-onnx models, English or multilingual |
 | 🧩 | [**Customizing**](docs/setup/customize.md) | Products in the onboarding catalogue, persona, look |
 | 🚀 | [**Deploying**](DEPLOY.md) | A Cloudflare tunnel, Fly.io or any Docker host |
+| 🔌 | [**API**](docs/API.md) | Drive Ava from scripts and tools with an API key |
 | 📚 | [**Reference**](docs/REFERENCE.md) | Every route, file and setting |
 
 ---
@@ -149,12 +167,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/admin.mjs

@@ -0,0 +1,284 @@
+// The dashboard's API (/api/admin/*): overview, calls, share links, playbooks and
+// settings. Only for the operator: the server checks access before calling in.
+
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { liveSessions, getSession } from "./state.mjs";
+import { listUsers, createUser, updateUser, setPassword, deleteUser, hasUsers, getUser, verifyLogin, suggestPassword, ROLES, listKeys, createKey, deleteKey } from "./team.mjs";
+import { analytics } from "./analytics.mjs";
+import { recentCalls, callsToday, getCall, deleteCall, getTranscript, transcriptsOn, deleteAllTranscripts } from "./calls.mjs";
+import { listLinks, getLink, createLink, updateLink, deleteLink, validateLink, LINKS_FILE } from "./links.mjs";
+import { PLATFORMS, platformById, playbooksAdminView, savePlaybook, deletePlaybook } from "./platforms.mjs";
+import { validatePlaybook, template } from "./playbooks.mjs";
+import { DAILY_BUDGET_USD, spentToday, dailyCapReached } from "./spend.mjs";
+import { emitEvent, WEBHOOK_INFO } from "./webhooks.mjs";
+import { MOCK } from "./openrouter.mjs";
+import { MODELS, PROVIDER } from "./models.mjs";
+import { AUTH_ENABLED, refreshAuth, sessionCookieFor, logoutCookie } from "./guard.mjs";
+import { settingsView, updateSettings } from "./settings.mjs";
+import { libraryView, installFromLibrary } from "./library.mjs";
+import { draftPlaybook } from "./draft.mjs";
+import { pkce, authUrl, exchangeCode, callbackPage, FLOW_TIMEOUT_MS } from "./cli/openrouter-oauth.mjs";
+
+const VERSION = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8")).version;
+const round = (n, d = 4) => Math.round(n * 10 ** d) / 10 ** d;
+const productExists = (id) => PLATFORMS.some((p) => p.id === id);
+
+/**
+ * ctx: { send, readBody, LOCAL_ONLY, HOST, PORT, sessionBudget(), voice(), speech() }
+ * Returns a handler(req, res, url) for /api/admin/* paths.
+ */
+export function createAdmin(ctx) {
+  const { send, readBody } = ctx;
+  const publicUrl = () => (process.env.PUBLIC_URL || "").replace(/\/+$/, "") || null;
+
+  function status() {
+    return {
+      version: VERSION, mock: MOCK,
+      access: { password: AUTH_ENABLED, localOnly: ctx.LOCAL_ONLY, publicUrl: publicUrl() },
+      spend: { today: round(spentToday()), dailyCap: DAILY_BUDGET_USD || null, capReached: !MOCK && dailyCapReached(), perCall: ctx.sessionBudget() },
+    };
+  }
+
+  function liveView() {
+    return liveSessions().map((s) => ({ ...s, handoff: s.handoff ? { state: s.handoff.state, since: s.handoff.since, pickedUpBy: s.handoff.pickedUpBy?.name || null, joinPath: s.handoff.specialistKey ? `/specialist?key=${encodeURIComponent(s.handoff.specialistKey)}` : null } : null }));
+  }
+
+  function overview() {
+    const live = liveView(), done = callsToday();
+    const all = [...done, ...live];
+    const view = playbooksAdminView();
+    const links = listLinks();
+    return {
+      status: status(),
+      today: {
+        calls: all.length, live: live.length,
+        waiting: live.filter((s) => s.handoff && s.handoff.state !== "joined").length,
+        minutes: Math.round(all.reduce((a, c) => a + (c.durationSec || 0), 0) / 60),
+        completed: all.filter((c) => c.workflow?.completed).length,
+        handoffs: all.filter((c) => c.handoffRequested).length,
+      },
+      live, recent: recentCalls(8),
+      checklist: [
+        { id: "key", done: !MOCK, label: "Connect OpenRouter for real answers", hint: "npx ava-engine setup" },
+        { id: "playbook", done: view.playbooks.some((p) => p.source === "yours"), label: "Describe your product in a playbook" },
+        { id: "link", done: links.length > 0, label: "Create a share link for your customers" },
+        { id: "access", done: AUTH_ENABLED || false, label: "Let customers reach Ava (password + public address)", hint: "npx ava-engine setup → “My team or customers”" },
+        { id: "events", done: WEBHOOK_INFO.endpoints > 0 || WEBHOOK_INFO.slack, label: "Get handoff alerts in Slack or your own systems", hint: "SLACK_WEBHOOK_URL / WEBHOOK_URL" },
+      ],
+    };
+  }
+
+  function linkView(l) {
+    const p = l.product ? platformById(l.product) : null;
+    return { ...l, product: l.product, productName: p ? p.name : null, productAccent: p?.accent || null, productMissing: !!l.product && !p, path: `/c/${l.id}` };
+  }
+
+  function settings() {
+    return {
+      ...status(), ...settingsView(),
+      ai: { models: MODELS, providers: PROVIDER },
+      voice: ctx.voice(), speech: ctx.speech(),
+      server: { host: ctx.HOST || "all network interfaces", port: ctx.PORT, trustProxy: process.env.TRUST_PROXY === "1" },
+      limits: { perCallUsd: ctx.sessionBudget(), dailyUsd: DAILY_BUDGET_USD || null, maxSessions: Number(process.env.MAX_SESSIONS) || 50, sessionsPerMin: Number(process.env.RATE_SESSIONS_PER_MIN) || 10, apiPerMin: Number(process.env.RATE_API_PER_MIN) || 240 },
+      events: WEBHOOK_INFO,
+      files: { config: process.env.AVA_CONFIG_FILE || null, playbooks: playbooksAdminView().dir, links: LINKS_FILE },
+    };
+  }
+
+  // "Connect OpenRouter" from the dashboard: same PKCE flow as setup. OpenRouter
+  // sends the browser back to /dashboard/openrouter-callback, which the server
+  // routes to finishOpenRouter() (a cross-site redirect carries no login cookie,
+  // so the single-use state proves the request is ours).
+  let oauth = null;
+  function startOpenRouter(origin) {
+    const { verifier, challenge, state } = pkce();
+    oauth = { verifier, state, at: Date.now() };
+    return authUrl({ callbackUrl: `${origin}/dashboard/openrouter-callback`, challenge, state });
+  }
+  async function finishOpenRouter(req, res, url) {
+    const page = (ok) => send(res, ok ? 200 : 400, callbackPage(ok, { cssHref: "/dashboard.css" }).replace("You can close this tab and go back to setup.", "Ava is using your new key. You can close this tab."), { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store" });
+    const f = oauth;
+    if (!f || Date.now() - f.at > FLOW_TIMEOUT_MS || url.searchParams.get("state") !== f.state || !url.searchParams.get("code")) return page(false);
+    oauth = null; // single use
+    try {
+      const key = await exchangeCode({ code: url.searchParams.get("code"), verifier: f.verifier });
+      const r = updateSettings({ OPENROUTER_API_KEY: key });
+      return page(!r.errors);
+    } catch { return page(false); }
+  }
+
+  // What each role may do. Specialists see calls and the inbox; editors also
+  // manage links and playbooks; owners also settings and the team.
+  const RANK = { specialist: 1, editor: 2, owner: 3 };
+  const NEED = [
+    [/^\w+ \/api\/admin\/(settings|openrouter|webhooks|transcripts|team|keys)\b/, "owner"],
+    [/^(POST|PUT|DELETE) \/api\/admin\/(links|playbooks|library)\b(?!\/check$)/, "editor"],
+    [/^DELETE \/api\/admin\/calls\//, "editor"],
+  ];
+
+  async function handle(req, res, url, user) {
+    const route = `${req.method} ${url.pathname}`;
+    const tail = (prefix) => (url.pathname.startsWith(prefix) ? decodeURIComponent(url.pathname.slice(prefix.length)) : null);
+    const need = NEED.find(([re]) => re.test(route))?.[1];
+    if (need && RANK[user.role] < RANK[need]) return send(res, 403, { error: `Only ${need === "owner" ? "owners" : "owners and editors"} can do that. You're signed in as ${user.role === "editor" ? "an" : "a"} ${user.role}.` });
+
+    // ── you ──
+    if (route === "GET /api/admin/me") return send(res, 200, { user, accounts: hasUsers() });
+    if (route === "POST /api/admin/me/password") {
+      const acct = getUser(user.id);
+      if (!acct) return send(res, 400, { error: "You're signed in with the shared password, which is changed in Settings." });
+      const body = await readBody(req);
+      if (!verifyLogin(acct.email, body.current)) return send(res, 400, { error: "Your current password isn't right." });
+      const r = setPassword(acct.id, body.password);
+      if (r.errors) return send(res, 400, { errors: r.errors });
+      return send(res, 200, { ok: true }, { "Set-Cookie": sessionCookieFor(getUser(acct.id), req) }); // stay signed in here, out everywhere else
+    }
+
+    // ── team (owners) ──
+    if (route === "GET /api/admin/team") return send(res, 200, { users: listUsers(), roles: ROLES, me: user.id, first: !hasUsers() });
+    if (route === "POST /api/admin/team") {
+      const body = await readBody(req);
+      const first = !hasUsers();
+      const password = body.password || suggestPassword();
+      const r = createUser({ email: body.email, name: body.name, role: first ? "owner" : body.role, password });
+      if (r.errors) return send(res, 400, { errors: r.errors });
+      refreshAuth(); // the first account turns sign-in on
+      // The first owner is whoever set it up: sign them in, or they'd be locked out.
+      return send(res, 201, { user: r.user, password: body.password ? undefined : password }, first ? { "Set-Cookie": sessionCookieFor(getUser(r.user.id), req) } : {});
+    }
+    const pw = url.pathname.match(/^\/api\/admin\/team\/([\w-]+)\/password$/);
+    if (pw && req.method === "POST") {
+      const password = (await readBody(req)).password || suggestPassword();
+      const r = setPassword(pw[1], password);
+      return r.errors ? send(res, 400, { errors: r.errors }) : send(res, 200, { user: r.user, password });
+    }
+    const memberId = tail("/api/admin/team/");
+    if (memberId != null && !pw) {
+      if (req.method === "PUT") { const r = updateUser(memberId, await readBody(req)); return r.errors ? send(res, 400, { errors: r.errors }) : send(res, 200, r); }
+      if (req.method === "DELETE") {
+        const r = deleteUser(memberId);
+        if (r.errors) return send(res, 400, { errors: r.errors });
+        refreshAuth();
+        return send(res, 200, r, memberId === user.id ? { "Set-Cookie": logoutCookie(req) } : {});
+      }
+    }
+
+    // ── API keys (owners) ──
+    if (route === "GET /api/admin/keys") return send(res, 200, { keys: listKeys(), roles: ROLES });
+    if (route === "POST /api/admin/keys") {
+      if (user.apiKey) return send(res, 403, { error: "API keys can't make more API keys. Use the dashboard." });
+      const b = await readBody(req);
+      const r = createKey({ name: b.name, role: b.role, createdBy: user.name });
+      return r.errors ? send(res, 400, { errors: r.errors }) : send(res, 201, r);
+    }
+    const keyId = tail("/api/admin/keys/");
+    if (keyId != null && req.method === "DELETE") return deleteKey(keyId) ? send(res, 200, { deleted: true }) : send(res, 404, { error: "unknown key" });
+
+    // ── inbox: pick up a customer who asked for a person ──
+    const pick = url.pathname.match(/^\/api\/admin\/calls\/([0-9a-f-]{36})\/pickup$/);
+    if (pick && req.method === "POST") {
+      const s = getSession(pick[1]);
+      const h = s?.ours.handoff;
+      if (!s || !h?.requested || !s.specialistKey) return send(res, 409, { error: "That customer isn't waiting any more." });
+      if (h.pickedUpBy && h.pickedUpBy.id !== user.id) return send(res, 409, { error: `${h.pickedUpBy.name} already picked this up.` });
+      h.pickedUpBy = { id: user.id, name: user.name, at: Date.now() };
+      emitEvent("handoff.picked_up", { sessionId: s.id, by: user.name, link: s.link ? { id: s.link.id, name: s.link.name } : null });
+      return send(res, 200, { joinPath: `/specialist?key=${encodeURIComponent(s.specialistKey)}` });
+    }
+
+    if (route === "GET /api/admin/overview") return send(res, 200, overview());
+    if (route === "GET /api/admin/analytics") {
+      const q = url.searchParams, days = [0, 7, 30, 90].includes(Number(q.get("days"))) ? Number(q.get("days")) : 30;
+      const all = recentCalls(5000);
+      const products = [...new Map(all.filter((c) => c.platform).map((c) => [c.platform.id, c.platform.name])).entries()].map(([id, name]) => ({ id, name }));
+      const links = [...new Map(all.filter((c) => c.link).map((c) => [c.link.id, c.link.name])).entries()].map(([id, name]) => ({ id, name }));
+      return send(res, 200, { ...analytics(all, { days, product: q.get("product") || "", link: q.get("link") || "" }), options: { products, links } });
+    }
+    if (route === "GET /api/admin/calls") return send(res, 200, { live: liveView(), recent: recentCalls(500), transcripts: transcriptsOn() });
+    if (route === "DELETE /api/admin/transcripts") { deleteAllTranscripts(); return send(res, 200, { deleted: true }); }
+    const callId = tail("/api/admin/calls/");
+    if (callId != null) {
+      const c = getCall(callId);
+      if (!c) return send(res, 404, { error: "That call isn't in the history (it may still be running, or was deleted)." });
+      if (req.method === "GET") return send(res, 200, { call: c, transcript: getTranscript(callId), transcripts: transcriptsOn() });
+      if (req.method === "DELETE") return send(res, 200, { deleted: deleteCall(callId) });
+    }
+    if (route === "GET /api/admin/settings") return send(res, 200, settings());
+    if (route === "PUT /api/admin/settings") {
+      const r = updateSettings((await readBody(req)).values);
+      if (r.errors) return send(res, 400, { errors: r.errors });
+      return send(res, 200, { ...r, ...settings() });
+    }
+    if (route === "POST /api/admin/openrouter/start") return send(res, 200, { url: startOpenRouter(ctx.origin(req)) });
+
+    // ── share links ──
+    if (route === "GET /api/admin/links") return send(res, 200, { links: listLinks().map(linkView), publicUrl: publicUrl(), localOnly: ctx.LOCAL_ONLY, password: AUTH_ENABLED });
+    if (route === "POST /api/admin/links") {
+      const r = validateLink(await readBody(req), { productExists });
+      if (r.errors) return send(res, 400, { errors: r.errors });
+      return send(res, 201, { link: linkView(createLink(r.value)) });
+    }
+    const linkId = tail("/api/admin/links/");
+    if (linkId != null) {
+      if (!getLink(linkId)) return send(res, 404, { error: "unknown link" });
+      if (req.method === "PUT") {
+        const r = validateLink(await readBody(req), { productExists });
+        if (r.errors) return send(res, 400, { errors: r.errors });
+        return send(res, 200, { link: linkView(updateLink(linkId, r.value)) });
+      }
+      if (req.method === "DELETE") return send(res, 200, { deleted: deleteLink(linkId) });
+    }
+
+    // ── playbooks ──
+    if (route === "GET /api/admin/playbooks") return send(res, 200, { ...playbooksAdminView(), template: template("my-product") });
+    // ── library and drafting ──
+    if (route === "GET /api/admin/library") {
+      try { return send(res, 200, await libraryView()); } catch (e) { return send(res, 502, { error: e.message }); }
+    }
+    const lib = url.pathname.match(/^\/api\/admin\/library\/([a-z0-9-]{1,40})\/install$/);
+    if (lib && req.method === "POST") {
+      try {
+        const r = await installFromLibrary(lib[1], { overwrite: !!(await readBody(req)).overwrite });
+        return r.errors ? send(res, r.status, { errors: r.errors }) : send(res, 200, r);
+      } catch (e) { return send(res, 502, { error: e.message }); }
+    }
+    if (route === "POST /api/admin/playbooks/draft") {
+      try { return send(res, 200, await draftPlaybook(await readBody(req))); }
+      catch (e) { return send(res, e.code === "daily_cap" ? 503 : e.status || 502, { error: e.code === "daily_cap" ? "Today's spending cap is reached, so drafting is paused until tomorrow." : e.message || "Drafting failed. Try again." }); }
+    }
+    if (route === "POST /api/admin/playbooks/check") {
+      const r = validatePlaybook((await readBody(req)).playbook);
+      return send(res, 200, { ok: !r.errors, errors: r.errors || [], warnings: r.warnings || [] });
+    }
+    const pbId = tail("/api/admin/playbooks/");
+    if (pbId != null && pbId !== "check") {
+      if (req.method === "PUT") {
+        const body = await readBody(req);
+        const previousId = body.previousId ? String(body.previousId) : undefined;
+        const r = savePlaybook(body.playbook, { previousId });
+        if (r.errors) return send(res, 400, { errors: r.errors });
+        if (previousId && previousId !== r.playbook.id) for (const l of listLinks()) if (l.product === previousId) updateLink(l.id, { product: r.playbook.id });
+        return send(res, 200, { playbook: r.playbook });
+      }
+      if (req.method === "DELETE") {
+        const using = listLinks().filter((l) => l.product === pbId);
+        if (using.length) return send(res, 409, { error: `Share links use this playbook: ${using.map((l) => `“${l.name}”`).join(", ")}. Point them at another product or delete them first.` });
+        return deletePlaybook(pbId) ? send(res, 200, { deleted: true }) : send(res, 404, { error: "Only your own playbooks can be deleted." });
+      }
+    }
+
+    // ── events ──
+    if (route === "POST /api/admin/webhooks/test") {
+      if (!WEBHOOK_INFO.endpoints && !WEBHOOK_INFO.slack) return send(res, 400, { error: "No webhooks are set up. Add WEBHOOK_URL or SLACK_WEBHOOK_URL to your settings and restart Ava." });
+      const results = await emitEvent("ava.test", { message: "Test event from the Ava dashboard" });
+      const ok = results.filter((r) => r.status === "fulfilled" && r.value === true).length;
+      return send(res, 200, { sent: results.length, delivered: ok });
+    }
+
+    return send(res, 404, { error: "unknown endpoint" });
+  }
+  handle.finishOpenRouter = finishOpenRouter;
+  return handle;
+}

package/lib/analytics.mjs

@@ -0,0 +1,73 @@
+// Analytics for the dashboard, computed from the call history (finished calls).
+// Answers what a team running onboarding wants to know: how many people finish,
+// where they get stuck, how often they need a person, and what a finished
+// onboarding costs.
+
+const DAY = 86_400_000;
+const median = (xs) => { if (!xs.length) return 0; const s = [...xs].sort((a, b) => a - b), m = s.length >> 1; return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2; };
+const rate = (n, d) => (d ? n / d : null);
+const round = (n, k = 4) => (n == null ? null : Math.round(n * 10 ** k) / 10 ** k);
+
+/** calls: finished-call records (newest first). Filters: days (0 = all), product id, link id ("test" = test calls). */
+export function analytics(calls, { days = 30, product = "", link = "", now = Date.now() } = {}) {
+  const since = days ? now - days * DAY : 0;
+  const rows = calls.filter((c) => Date.parse(c.startedAt) >= since
+    && (!product || c.platform?.id === product)
+    && (!link || (link === "test" ? !c.link : c.link?.id === link)));
+  const onboarding = rows.filter((c) => c.workflow);
+  const completed = onboarding.filter((c) => c.workflow.completed);
+  const spend = rows.reduce((a, c) => a + (c.costUsd || 0), 0);
+
+  // calls per day, oldest first, with empty days filled in
+  const byDay = new Map();
+  for (const c of rows) {
+    const d = c.startedAt.slice(0, 10);
+    const b = byDay.get(d) || { date: d, calls: 0, completed: 0, handoffs: 0 };
+    b.calls++; if (c.workflow?.completed) b.completed++; if (c.handoffRequested) b.handoffs++;
+    byDay.set(d, b);
+  }
+  const span = days || Math.min(365, Math.max(1, Math.ceil((now - Math.min(now, ...rows.map((c) => Date.parse(c.startedAt)))) / DAY) + 1));
+  const daily = [];
+  for (let i = span - 1; i >= 0; i--) { const d = new Date(now - i * DAY).toISOString().slice(0, 10); daily.push(byDay.get(d) || { date: d, calls: 0, completed: 0, handoffs: 0 }); }
+
+  // the journey funnel per product: how many calls got each step done, and the biggest drop
+  const funnels = [];
+  const byProduct = new Map();
+  for (const c of onboarding) {
+    if (!c.platform || !c.steps) continue;
+    const f = byProduct.get(c.platform.id) || { product: c.platform, calls: 0, steps: new Map() };
+    f.calls++;
+    c.steps.forEach((s, i) => { const k = `${i}:${s.title}`; const e = f.steps.get(k) || { index: i, title: s.title, reached: 0 }; if (s.done) e.reached++; f.steps.set(k, e); });
+    byProduct.set(c.platform.id, f);
+  }
+  for (const f of byProduct.values()) {
+    const steps = [...f.steps.values()].sort((a, b) => a.index - b.index).map((s) => ({ ...s, pct: round(rate(s.reached, f.calls)) }));
+    let stuck = null, prev = 1;
+    steps.forEach((s, i) => { const drop = prev - (s.pct ?? 0); if (drop > 0.001 && (!stuck || drop > stuck.drop)) stuck = { index: i, title: s.title, drop: round(drop) }; prev = s.pct ?? 0; });
+    funnels.push({ product: f.product, calls: f.calls, steps, stuck });
+  }
+  funnels.sort((a, b) => b.calls - a.calls);
+
+  // by share link
+  const byLink = new Map();
+  for (const c of rows) {
+    const key = c.link?.id || "test";
+    const e = byLink.get(key) || { id: key, name: c.link?.name || "Test calls", calls: 0, onboarding: 0, completed: 0, handoffs: 0, spend: 0 };
+    e.calls++; if (c.workflow) e.onboarding++; if (c.workflow?.completed) e.completed++; if (c.handoffRequested) e.handoffs++; e.spend += c.costUsd || 0;
+    byLink.set(key, e);
+  }
+  const links = [...byLink.values()].map((e) => ({ ...e, spend: round(e.spend), completionRate: round(rate(e.completed, e.onboarding)), handoffRate: round(rate(e.handoffs, e.calls)), costPerCompletion: e.completed ? round(e.spend / e.completed) : null }))
+    .sort((a, b) => b.calls - a.calls);
+
+  return {
+    days, product: product || null, link: link || null,
+    totals: {
+      calls: rows.length, onboarding: onboarding.length, completed: completed.length,
+      completionRate: round(rate(completed.length, onboarding.length)),
+      handoffRate: round(rate(rows.filter((c) => c.handoffRequested).length, rows.length)),
+      medianMinutes: round(median(rows.map((c) => c.durationSec || 0)) / 60, 1),
+      spend: round(spend), costPerCompletion: completed.length ? round(spend / completed.length) : null,
+    },
+    daily, funnels, links,
+  };
+}

package/lib/calls.mjs

@@ -0,0 +1,97 @@
+// Call history for the dashboard.
+//
+// Every finished call: one line of numbers and step results (never what was said
+// or shown), kept in memory (the latest 500) and appended to CALLS_FILE (default
+// ~/.ava-engine/calls.jsonl) so a restart keeps it.
+//
+// Transcripts are separate and off by default (TRANSCRIPTS=on in Settings): what
+// was said and the recap, one file per call in ~/.ava-engine/transcripts/ (mode
+// 600), deleted after TRANSCRIPT_DAYS (default 30).
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+const HOME = process.env.AVA_HOME || join(homedir(), ".ava-engine");
+const FILE = process.env.CALLS_FILE || join(HOME, "calls.jsonl");
+const TRANSCRIPTS = join(HOME, "transcripts");
+const ID = /^[0-9a-f-]{36}$/;
+const KEEP = 5000; // enough history for analytics
+let history = load();
+
+function load() {
+  try {
+    const lines = readFileSync(FILE, "utf8").trim().split("\n").slice(-KEEP);
+    return lines.map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean).reverse();
+  } catch { return []; }
+}
+
+/** Remember a finished call (newest first). */
+export function recordCall(c) {
+  history.unshift(c);
+  if (history.length > KEEP) history.length = KEEP;
+  try {
+    mkdirSync(dirname(FILE), { recursive: true });
+    if (!existsSync(FILE)) writeFileSync(FILE, "", { mode: 0o600 });
+    appendFileSync(FILE, JSON.stringify(c) + "\n");
+  } catch (e) { console.warn("  [calls] couldn't save the call history:", e.message); }
+}
+
+export function recentCalls(limit = 100) { return history.slice(0, limit); }
+
+/** Finished calls that started today (UTC). */
+export function callsToday() {
+  const d = new Date().toISOString().slice(0, 10);
+  return history.filter((c) => String(c.startedAt || "").startsWith(d));
+}
+
+export function getCall(id) { return history.find((c) => c.id === id) || null; }
+
+/** Forget a call: its history line and its transcript (e.g. a customer's deletion request). */
+export function deleteCall(id) {
+  const n = history.length;
+  history = history.filter((c) => c.id !== id);
+  deleteTranscript(id);
+  if (history.length === n) return false;
+  try { writeFileSync(FILE, history.slice().reverse().map((c) => JSON.stringify(c) + "\n").join(""), { mode: 0o600 }); } catch {}
+  return true;
+}
+
+// ── transcripts (opt-in) ──
+export const transcriptsOn = () => process.env.TRANSCRIPTS === "on";
+const keepDays = () => Number(process.env.TRANSCRIPT_DAYS) || 30;
+const tfile = (id) => join(TRANSCRIPTS, `${id}.json`);
+
+/** Save what was said on a call. Only when transcripts are on. */
+export function saveTranscript(id, data) {
+  if (!transcriptsOn() || !ID.test(id)) return false;
+  try {
+    mkdirSync(TRANSCRIPTS, { recursive: true, mode: 0o700 });
+    writeFileSync(tfile(id), JSON.stringify(data), { mode: 0o600 });
+    return true;
+  } catch (e) { console.warn("  [calls] couldn't save a transcript:", e.message); return false; }
+}
+export function getTranscript(id) {
+  if (!ID.test(id)) return null;
+  try { return JSON.parse(readFileSync(tfile(id), "utf8")); } catch { return null; }
+}
+export function deleteTranscript(id) { if (ID.test(id)) rmSync(tfile(id), { force: true }); }
+/** Delete every saved transcript. */
+export function deleteAllTranscripts() {
+  rmSync(TRANSCRIPTS, { recursive: true, force: true });
+  for (const c of history) c.transcript = false;
+}
+
+/** Delete transcripts older than TRANSCRIPT_DAYS. Runs at start and every hour. */
+export function sweepTranscripts(now = Date.now()) {
+  let removed = 0;
+  try {
+    for (const f of readdirSync(TRANSCRIPTS)) {
+      const p = join(TRANSCRIPTS, f);
+      if (now - statSync(p).mtimeMs > keepDays() * 86_400_000) { rmSync(p, { force: true }); removed++; }
+    }
+  } catch { /* no transcripts yet */ }
+  return removed;
+}
+sweepTranscripts();
+setInterval(sweepTranscripts, 3_600_000).unref();

package/lib/cli/config.mjs

@@ -26,6 +26,7 @@ export function readConfig(file = CONFIG_FILE) {
     if (!m) continue;
     let v = m[2];
     if (/^".*"$/.test(v)) v = v.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+    else if (/^'.*'$/.test(v)) v = v.slice(1, -1); // written by the dashboard's Settings page
     out[m[1]] = v;
   }
   return out;