ava-engine 0.2.0 → 0.4.0

package/lib/platforms.mjs

@@ -2,8 +2,16 @@
 // 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 { mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { loadPlaybooks, mergePlaybooks, validatePlaybook, PLAYBOOKS_DIR } from "./playbooks.mjs";
+
+export const BUILTIN_PLATFORMS = [
   {
     id: "todoist", name: "Todoist", url: "https://app.todoist.com",
     category: "Productivity", accent: "#E44332",
@@ -194,6 +202,74 @@ export const PLATFORMS = [
   },
 ];
 
+import { onSettingsChange } from "./settings.mjs";
+
+const builtinsHidden = () => /^(off|0|false|no)$/i.test(process.env.BUILTIN_PLAYBOOKS || "");
+// Live bindings: reloadPlaybooks() swaps these in place. Calls already running keep
+// the playbook they started with.
+export let PLATFORMS = [];
+export let CUSTOM_PLAYBOOKS = { count: 0, dir: PLAYBOOKS_DIR, problems: [], playbooks: [] };
+
+/** Re-read your playbook files (at startup, and after the dashboard saves one). */
+export function reloadPlaybooks({ quiet = false } = {}) {
+  const custom = loadPlaybooks();
+  if (!quiet) 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}`);
+  }
+  PLATFORMS = mergePlaybooks(BUILTIN_PLATFORMS, custom.playbooks, { hideBuiltins: builtinsHidden() });
+  CUSTOM_PLAYBOOKS = { count: custom.playbooks.length, dir: PLAYBOOKS_DIR, problems: custom.problems, playbooks: custom.playbooks };
+  return CUSTOM_PLAYBOOKS;
+}
+reloadPlaybooks();
+onSettingsChange((k) => { if (k.has("BUILTIN_PLAYBOOKS")) reloadPlaybooks({ quiet: true }); });
+
+/** Every playbook for the dashboard: yours (editable), the built-ins, and files that need fixing. */
+export function playbooksAdminView() {
+  const mine = new Set(CUSTOM_PLAYBOOKS.playbooks.map((p) => p.id));
+  const row = (p, source) => ({ ...p, source, file: p.source || null, shown: PLATFORMS.includes(p) && !p.demoOnly });
+  return {
+    dir: PLAYBOOKS_DIR.replace(homedir(), "~"), hideBuiltins: builtinsHidden(),
+    playbooks: [
+      ...CUSTOM_PLAYBOOKS.playbooks.map((p) => row(p, "yours")),
+      ...BUILTIN_PLATFORMS.map((p) => ({ ...row(p, "built-in"), overridden: mine.has(p.id) })),
+    ],
+    problems: CUSTOM_PLAYBOOKS.problems,
+  };
+}
+
+/** Check and save one of your playbooks as <id>.json, then reload. Returns { playbook } or { errors }. */
+export function savePlaybook(raw, { previousId } = {}) {
+  const r = validatePlaybook(raw);
+  if (r.errors) return { errors: r.errors };
+  const { id } = r.playbook;
+  const clash = CUSTOM_PLAYBOOKS.playbooks.find((p) => p.id === id && p.id !== previousId);
+  if (clash) return { errors: [`You already have a playbook with the id “${id}”.`] };
+  mkdirSync(PLAYBOOKS_DIR, { recursive: true });
+  const { knowledge, ...rest } = r.playbook;
+  const file = { ...rest, knowledge: knowledge.map((k) => ({ keywords: k.k, text: k.text })) };
+  for (const k of Object.keys(file)) if (file[k] == null || file[k] === "") delete file[k];
+  const path = join(PLAYBOOKS_DIR, `${id}.json`), tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(file, null, 2) + "\n");
+  renameSync(tmp, path);
+  if (previousId && previousId !== id) removePlaybookFile(previousId); // renamed
+  reloadPlaybooks({ quiet: true });
+  return { playbook: platformById(id) };
+}
+
+function removePlaybookFile(id) {
+  const p = CUSTOM_PLAYBOOKS.playbooks.find((x) => x.id === id);
+  if (!p?.source) return false;
+  rmSync(join(PLAYBOOKS_DIR, p.source), { force: true });
+  return true;
+}
+/** Delete one of your playbook files. Built-ins can't be deleted. */
+export function deletePlaybook(id) {
+  const ok = removePlaybookFile(id);
+  if (ok) reloadPlaybooks({ quiet: true });
+  return ok;
+}
+
 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,120 @@
+// 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", "author", "origin", "$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`);
+  if (raw.author !== undefined && !str(raw.author, 80)) errors.push(`"author" must be a name (up to 80 characters)`);
+  // origin: where an installed copy came from ({ library, sha256, installedAt }), kept so updates can be offered
+  let origin;
+  if (raw.origin !== undefined) {
+    const o = raw.origin;
+    if (!o || typeof o !== "object" || !str(o.library, 300) || !/^[0-9a-f]{64}$/.test(String(o.sha256 || ""))) errors.push(`"origin" is set by the library installer; remove it if you edited this by hand`);
+    else origin = { library: o.library, sha256: o.sha256, installedAt: typeof o.installedAt === "string" ? o.installedAt.slice(0, 40) : undefined };
+  }
+  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, author } = 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 } : {}),
+      ...(author ? { author } : {}), ...(origin ? { origin } : {}),
+    },
+  };
+}
+
+/** 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/safe-fetch.mjs

@@ -0,0 +1,79 @@
+// Fetch a public web page for "Draft with AI", and nothing else.
+//
+// The address comes from a dashboard user, so the server must not become a way
+// to read private networks (cloud metadata at 169.254.169.254, localhost admin
+// pages, the office LAN). Every connection, including each redirect, is checked
+// at the moment it's made: the DNS answer is filtered in the socket's own lookup,
+// so a name can't resolve to a public address for the check and a private one
+// for the request. Small, slow-capped and text only.
+
+import http from "node:http";
+import https from "node:https";
+import dns from "node:dns";
+import net from "node:net";
+
+const MAX_BYTES = 2 * 1024 * 1024, TIMEOUT_MS = 12_000, MAX_REDIRECTS = 3;
+
+/** True for addresses a public fetch must never reach. */
+export function isPrivateAddress(ip) {
+  if (net.isIPv4(ip)) {
+    const [a, b] = ip.split(".").map(Number);
+    return a === 0 || a === 10 || a === 127 || (a === 100 && b >= 64 && b <= 127) || (a === 169 && b === 254)
+      || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 192 && b === 0) || (a === 198 && (b === 18 || b === 19)) || a >= 224;
+  }
+  const v = ip.toLowerCase();
+  if (v.startsWith("::ffff:")) return isPrivateAddress(v.slice(7));
+  return v === "::" || v === "::1" || /^f[cd]/.test(v) || /^fe[89ab]/.test(v) || v.startsWith("ff");
+}
+
+function publicLookup(host, opts, cb) {
+  dns.lookup(host, { all: true }, (err, list) => {
+    if (err) return cb(err);
+    const ok = list.find((a) => !isPrivateAddress(a.address));
+    if (!ok || list.some((a) => isPrivateAddress(a.address))) return cb(Object.assign(new Error("That address points to a private network."), { code: "EPRIVATE" }));
+    opts?.all ? cb(null, [ok]) : cb(null, ok.address, ok.family);
+  });
+}
+
+function once(url) {
+  return new Promise((resolve, reject) => {
+    const lib = url.protocol === "https:" ? https : http;
+    if (net.isIP(url.hostname.replace(/^\[|\]$/g, "")) && isPrivateAddress(url.hostname.replace(/^\[|\]$/g, ""))) return reject(new Error("That address points to a private network."));
+    const req = lib.get(url, { lookup: publicLookup, timeout: TIMEOUT_MS, headers: { "User-Agent": "ava-engine (playbook drafting)", Accept: "text/html,text/plain,text/markdown;q=0.9,*/*;q=0.1" } }, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) { res.resume(); return resolve({ redirect: new URL(res.headers.location, url) }); }
+      if (res.statusCode !== 200) { res.resume(); return reject(new Error(`The page answered ${res.statusCode}.`)); }
+      const type = String(res.headers["content-type"] || "");
+      if (!/text\/|application\/(xhtml|json|xml)/.test(type)) { res.resume(); return reject(new Error("That address isn't a web page or text.")); }
+      let size = 0; const chunks = [];
+      res.on("data", (c) => { size += c.length; if (size > MAX_BYTES) { req.destroy(new Error("That page is too large (over 2 MB).")); } else chunks.push(c); });
+      res.on("end", () => resolve({ body: Buffer.concat(chunks).toString("utf8"), type }));
+      res.on("error", reject);
+    });
+    req.on("timeout", () => req.destroy(new Error("The page took too long to answer.")));
+    req.on("error", reject);
+  });
+}
+
+/** GET a public http(s) page. Returns { text, type, url }. */
+export async function fetchPublic(address) {
+  let url;
+  try { url = new URL(address); } catch { throw new Error("That isn't a valid web address."); }
+  for (let i = 0; i <= MAX_REDIRECTS; i++) {
+    if (!/^https?:$/.test(url.protocol)) throw new Error("Only http:// and https:// addresses can be read.");
+    const r = await once(url);
+    if (r.redirect) { url = r.redirect; continue; }
+    return { text: r.body, type: r.type, url: url.href };
+  }
+  throw new Error("That page redirects too many times.");
+}
+
+/** Readable text from HTML: headings and paragraphs, without scripts, styles and navigation. */
+export function htmlToText(html) {
+  return String(html)
+    .replace(/<(script|style|noscript|svg|nav|footer|header|form|iframe)\b[\s\S]*?<\/\1>/gi, " ")
+    .replace(/<(h[1-6])\b[^>]*>/gi, "\n\n## ").replace(/<(br|\/p|\/li|\/h[1-6]|\/tr|\/div)\b[^>]*>/gi, "\n").replace(/<li\b[^>]*>/gi, "\n- ")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;|&apos;/g, "'")
+    .replace(/&#(\d+);/g, (_, n) => String.fromCodePoint(Number(n)))
+    .replace(/[ \t\f\r]+/g, " ").replace(/ *\n */g, "\n").replace(/\n{3,}/g, "\n\n").trim();
+}

package/lib/settings.mjs

@@ -0,0 +1,187 @@
+// Settings you can change from the dashboard, applied without a restart.
+//
+// Ava's settings are environment variables, saved in a .env file: the CLI's
+// ~/.ava-engine/.env (AVA_CONFIG_FILE), or ./.env when run from source. Saving
+// here edits that file in place (other lines and comments are kept), updates
+// the running process, and tells every module that caches a value to reload.
+//
+// A variable set by the host itself (Fly secrets, Docker -e, the shell) wins over
+// the file on the next start, so the dashboard shows those as read-only.
+
+import { existsSync, readFileSync, renameSync, writeFileSync, chmodSync, mkdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+export const CONFIG_PATH = process.env.AVA_CONFIG_FILE || resolve(".env");
+
+const SLUG = /^[\w.-]+\/[\w.:-]+$/;
+const num = (min, max, int = false) => ({ type: "number", min, max, int });
+
+/**
+ * Every editable setting. `secret`: never sent to the browser. `restart`: saved,
+ * but only takes effect after Ava restarts. `section` groups them on the page.
+ */
+export const SCHEMA = [
+  // AI
+  { key: "OPENROUTER_API_KEY", section: "ai", label: "OpenRouter API key", type: "secret", min: 20, hint: "Empty = demo mode with canned replies." },
+  { key: "MODEL_TALKER", section: "ai", label: "Talker model", type: "slug", def: "meta-llama/llama-3.3-70b-instruct", hint: "Writes the spoken reply. Latency matters most here." },
+  { key: "MODEL_PERCEPTION", section: "ai", label: "Screen-reading model", type: "slug", def: "google/gemini-2.5-flash", hint: "Must accept images." },
+  { key: "MODEL_INTENT", section: "ai", label: "Intent model", type: "slug", def: "google/gemini-2.5-flash-lite", hint: "Classifies turns and checks workflow steps." },
+  { key: "MODEL_PLANNER", section: "ai", label: "Planner model", type: "slug", def: "anthropic/claude-sonnet-4.5", hint: "Keeps the goal and plan. Runs after the reply." },
+  { key: "TALKER_PROVIDER", section: "ai", label: "Talker provider", type: "provider", def: "groq", hint: "An OpenRouter provider to prefer, or auto." },
+  { key: "PERCEPTION_PROVIDER", section: "ai", label: "Screen-reading provider", type: "provider", def: "", hint: "Optional. Empty or auto lets OpenRouter choose." },
+  // voice
+  { key: "TTS_DEFAULT", section: "voice", label: "Ava's voice", type: "enum", options: ["kokoro", "elevenlabs", "hume", "browser"], def: "kokoro" },
+  { key: "ELEVENLABS_API_KEY", section: "voice", label: "ElevenLabs API key", type: "secret", min: 20 },
+  { key: "ELEVEN_VOICE_ID", section: "voice", label: "ElevenLabs voice ID", type: "text", max: 64, def: "XrExE9yKIg1WjnnlVkGX" },
+  { key: "HUME_API_KEY", section: "voice", label: "Hume API key", type: "secret", min: 20 },
+  { key: "KOKORO_VOICE", section: "voice", label: "Kokoro voice", type: "text", max: 32, def: "af_heart", hint: "e.g. af_heart, af_bella, am_michael, bf_emma." },
+  { key: "KOKORO", section: "voice", label: "Offline Kokoro voice", type: "enum", options: ["on", "off"], def: "on", restart: true },
+  { key: "DEEPGRAM_API_KEY", section: "voice", label: "Deepgram API key", type: "secret", min: 20, hint: "Cloud speech-to-text, used only without offline models." },
+  // access
+  { key: "ACCESS_PASSWORD", section: "access", label: "Access password", type: "secret", min: 10, hint: "Needed for the dashboard and test page from other computers. Share links don't need it." },
+  { key: "PUBLIC_URL", section: "access", label: "Public address", type: "url", def: "", hint: "Where customers reach Ava, e.g. https://ava.example.com. Used in share links and alerts." },
+  { key: "HOST", section: "access", label: "Listen on", type: "enum", options: ["127.0.0.1", "0.0.0.0"], def: "0.0.0.0", restart: true, hint: "127.0.0.1 = this computer only." },
+  { key: "PORT", section: "access", label: "Port", ...num(1, 65535, true), def: "5190", restart: true },
+  { key: "TRUST_PROXY", section: "access", label: "Behind a proxy", type: "enum", options: ["1", "0"], def: "0", restart: true, hint: "1 when Fly, Cloudflare or nginx sits in front." },
+  // limits
+  { key: "SESSION_BUDGET_USD", section: "limits", label: "Spend cap per call (USD)", ...num(0.01, 1000), def: "2" },
+  { key: "DAILY_BUDGET_USD", section: "limits", label: "Spend cap per day (USD)", ...num(0, 1_000_000), def: "", hint: "All calls together. Empty or 0 = no cap." },
+  { key: "MAX_SESSIONS", section: "limits", label: "Calls at once", ...num(1, 10_000, true), def: "50" },
+  { key: "RATE_SESSIONS_PER_MIN", section: "limits", label: "New calls per visitor per minute", ...num(1, 10_000, true), def: "10" },
+  { key: "RATE_API_PER_MIN", section: "limits", label: "Requests per visitor per minute", ...num(10, 100_000, true), def: "240" },
+  // events
+  { key: "WEBHOOK_URL", section: "events", label: "Webhook URLs", type: "urls", secret: true, hint: "Comma-separated. Every call event is POSTed here as JSON." },
+  { key: "WEBHOOK_SECRET", section: "events", label: "Webhook signing secret", type: "secret", min: 16 },
+  { key: "SLACK_WEBHOOK_URL", section: "events", label: "Slack incoming webhook", type: "url", secret: true, hint: "Posts when a customer asks for a person." },
+  { key: "SLACK_BOT_TOKEN", section: "events", label: "Slack bot token", type: "secret", min: 20, hint: "Optional, instead of the webhook: one thread per handoff with updates. Needs a bot with chat:write in the channel." },
+  { key: "SLACK_CHANNEL", section: "events", label: "Slack channel", type: "text", max: 80, hint: "The channel ID for the bot, e.g. C0123ABCD." },
+  // data
+  { key: "TRANSCRIPTS", section: "data", label: "Keep call transcripts", type: "enum", options: ["off", "on"], def: "off", hint: "Off: only numbers are kept. On: what was said is saved for the call detail page." },
+  { key: "TRANSCRIPT_DAYS", section: "data", label: "Delete transcripts after (days)", ...num(1, 3650, true), def: "30" },
+  // playbooks
+  { key: "PLAYBOOK_LIBRARY_URL", section: "playbooks", label: "Playbook library", type: "url", def: "https://raw.githubusercontent.com/Mr-vero/ava-playbooks/main", hint: "Where Playbooks → Library comes from. Point it at your own fork to curate playbooks for your team." },
+  { key: "BUILTIN_PLAYBOOKS", section: "playbooks", label: "Sample products", type: "enum", options: ["on", "off"], def: "on", hint: "Off hides the built-in samples from the test page." },
+];
+const BY_KEY = new Map(SCHEMA.map((s) => [s.key, s]));
+const isSecret = (s) => s.type === "secret" || s.secret;
+
+// ── the .env file ──
+function parseEnv(text) {
+  const out = {};
+  for (const line of text.split(/\r?\n/)) {
+    const m = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/);
+    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);
+    else v = v.replace(/\s+#.*$/, "");
+    out[m[1]] = v;
+  }
+  return out;
+}
+function readFile() { try { return parseEnv(readFileSync(CONFIG_PATH, "utf8")); } catch { return {}; } }
+/** A value as it must appear in .env, readable by both Node's --env-file and the CLI. */
+function envValue(v) {
+  if (/^[A-Za-z0-9_@%+=:,./-]*$/.test(v)) return v;
+  if (!v.includes("'")) return `'${v}'`;
+  if (!v.includes('"') && !v.includes("\\")) return `"${v}"`;
+  throw new Error("Values can't contain both kinds of quotes.");
+}
+function writeFile(patch) {
+  const lines = existsSync(CONFIG_PATH) ? readFileSync(CONFIG_PATH, "utf8").split(/\r?\n/) : ["# Ava settings. Edit here or in the dashboard (Settings)."];
+  for (const [k, v] of Object.entries(patch)) {
+    const re = new RegExp(`^\\s*(?:export\\s+)?${k}\\s*=`);
+    const i = lines.findIndex((l) => re.test(l));
+    if (v === "") { if (i >= 0) lines.splice(i, 1); continue; }
+    const line = `${k}=${envValue(v)}`;
+    if (i >= 0) lines[i] = line; else lines.splice(lines.length && lines.at(-1) === "" ? lines.length - 1 : lines.length, 0, line);
+  }
+  mkdirSync(dirname(CONFIG_PATH), { recursive: true });
+  const tmp = join(dirname(CONFIG_PATH), `.env.${process.pid}.tmp`);
+  writeFileSync(tmp, lines.join("\n").replace(/\n*$/, "\n"), { mode: 0o600 });
+  renameSync(tmp, CONFIG_PATH);
+  try { chmodSync(CONFIG_PATH, 0o600); } catch {}
+}
+
+// Variables the host set itself (not from our file) win on the next start: read-only here.
+const fileAtStart = readFile();
+const hostSet = new Set(SCHEMA.map((s) => s.key).filter((k) => process.env[k] !== undefined && process.env[k] !== fileAtStart[k]));
+
+// ── validation ──
+function check(s, raw) {
+  const v = String(raw ?? "").trim();
+  if (v === "") return { value: "" }; // empty = back to the default / turn off
+  if (/[\r\n\0]/.test(v)) return { error: `${s.label}: must be one line.` };
+  switch (s.type) {
+    case "secret": return v.length < (s.min || 1) ? { error: `${s.label}: at least ${s.min} characters.` } : v.length > 500 ? { error: `${s.label}: too long.` } : { value: v };
+    case "slug": return SLUG.test(v) ? { value: v } : { error: `${s.label}: use an OpenRouter model id like provider/model-name.` };
+    case "provider": return /^[a-z0-9][a-z0-9_.-]{0,40}$/i.test(v) ? { value: v } : { error: `${s.label}: a provider name like groq, or auto.` };
+    case "enum": return s.options.includes(v) ? { value: v } : { error: `${s.label}: choose one of ${s.options.join(", ")}.` };
+    case "text": return v.length <= (s.max || 200) && /^[\w.: -]+$/.test(v) ? { value: v } : { error: `${s.label}: letters, digits, dashes and dots only.` };
+    case "url": try { const u = new URL(v); return /^https?:$/.test(u.protocol) ? { value: v.replace(/\/+$/, "") } : { error: `${s.label}: must start with http:// or https://.` }; } catch { return { error: `${s.label}: isn't a valid web address.` }; }
+    case "urls": {
+      const list = v.split(",").map((x) => x.trim()).filter(Boolean);
+      for (const u of list) { try { if (!/^https?:$/.test(new URL(u).protocol)) throw 0; } catch { return { error: `${s.label}: “${u}” isn't a valid http(s) address.` }; } }
+      return { value: list.join(",") };
+    }
+    case "number": {
+      const n = Number(v);
+      if (!Number.isFinite(n) || n < s.min || n > s.max || (s.int && !Number.isInteger(n))) return { error: `${s.label}: ${s.int ? "a whole number" : "a number"} from ${s.min} to ${s.max}.` };
+      return { value: String(n) };
+    }
+  }
+  return { error: `${s.label}: unsupported.` };
+}
+
+// ── what the dashboard sees ──
+function mask(k, v) {
+  if (!v) return "";
+  if (k.endsWith("_URL")) return v.split(",").map((u) => { try { return `${new URL(u).host}/…`; } catch { return "…"; } }).join(", ");
+  return v.length > 12 ? `${v.slice(0, 6)}…${v.slice(-4)}` : "••••••";
+}
+/** Every setting, with secrets masked, for the Settings page. */
+export function settingsView() {
+  return {
+    file: CONFIG_PATH,
+    settings: SCHEMA.map((s) => {
+      const v = process.env[s.key] ?? "";
+      return {
+        key: s.key, section: s.section, label: s.label, type: s.type, options: s.options, hint: s.hint, min: s.min, max: s.max,
+        default: s.def ?? "", secret: isSecret(s), restart: !!s.restart, set: v !== "",
+        value: isSecret(s) ? mask(s.key, v) : v,
+        locked: hostSet.has(s.key), pending: !!s.restart && pendingRestart.has(s.key),
+      };
+    }),
+  };
+}
+
+// ── saving ──
+const listeners = [];
+const pendingRestart = new Set();
+/** Run fn(changedKeys) after every save, so cached values reload. */
+export function onSettingsChange(fn) { listeners.push(fn); }
+
+/**
+ * Save changes: { KEY: "value" } ("" removes it). Secrets are only changed when
+ * sent. Returns { changed, restart } or { errors }.
+ */
+export function updateSettings(patch) {
+  const errors = [], clean = {};
+  for (const [k, raw] of Object.entries(patch || {})) {
+    const s = BY_KEY.get(k);
+    if (!s) { errors.push(`Unknown setting ${k}.`); continue; }
+    if (hostSet.has(k)) { errors.push(`${s.label} is set by your host's environment; change it there.`); continue; }
+    const r = check(s, raw);
+    if (r.error) errors.push(r.error); else if ((process.env[k] ?? "") !== r.value) clean[k] = r.value;
+  }
+  if (errors.length) return { errors };
+  const keys = Object.keys(clean);
+  if (!keys.length) return { changed: [], restart: [] };
+  writeFile(clean);
+  for (const k of keys) { if (clean[k] === "") delete process.env[k]; else process.env[k] = clean[k]; }
+  const restart = keys.filter((k) => BY_KEY.get(k).restart);
+  for (const k of restart) pendingRestart.add(k);
+  for (const fn of listeners) { try { fn(new Set(keys)); } catch (e) { console.error("  [settings] reload failed:", e.message); } }
+  console.log(`  [settings] updated ${keys.join(", ")}${restart.length ? " (restart to apply " + restart.join(", ") + ")" : ""}`);
+  return { changed: keys, restart };
+}

package/lib/spend.mjs

@@ -0,0 +1,62 @@
+// 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";
+
+import { onSettingsChange } from "./settings.mjs";
+
+export let DAILY_BUDGET_USD = Math.max(0, Number(process.env.DAILY_BUDGET_USD) || 0);
+onSettingsChange((k) => { if (k.has("DAILY_BUDGET_USD")) 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,8 @@
 // In-memory session store for the flexible agent.
 
 import { randomUUID } from "node:crypto";
+import { emitEvent } from "./webhooks.mjs";
+import { recordCall, saveTranscript } from "./calls.mjs";
 
 const sessions = new Map();
 const byKey = new Map(); // specialist key → session id (see mintSpecialistKey)
@@ -9,21 +11,56 @@ function emptyScore() {
   return { turns: 0, promptTokens: 0, completionTokens: 0, cost: 0, latencies: [], perception: { captured: 0, analysed: 0 } };
 }
 
-const MAX_SESSIONS = Number(process.env.MAX_SESSIONS) || 50;
+const maxSessions = () => Number(process.env.MAX_SESSIONS) || 50; // read live: editable in Settings
 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 c = callSummary(s);
+  emitEvent("session.ended", { sessionId: id, reason, ...c });
+  const wf = s.ours.workflow;
+  const transcript = saveTranscript(id, {
+    lines: (s.ours.bridge?.log || []).map((l) => ({ role: l.role, text: l.text, at: new Date(l.at).toISOString() })),
+    recap: s.recap || null,
+  });
+  recordCall({
+    id, reason, startedAt: new Date(s.createdAt).toISOString(), endedAt: new Date().toISOString(), ...c,
+    steps: wf ? wf.steps.map((x) => ({ title: x.title, done: x.status === "done" })) : null, // product data, not what was said
+    transcript,
+  });
+}
+
+/** The numbers about a call: what the dashboard shows and webhooks send. No transcript. */
+function callSummary(s) {
+  const o = s.ours, wf = o.workflow;
+  return {
+    mode: o.mode, platform: o.platform ? { id: o.platform.id, name: o.platform.name } : null,
+    link: s.link ? { id: s.link.id, name: s.link.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,
+  };
+}
+
+/** Calls happening now, for the dashboard. */
+export function liveSessions() {
+  return [...sessions.values()].map((s) => ({
+    id: s.id, startedAt: new Date(s.createdAt).toISOString(), lastActiveAt: new Date(s.lastActive).toISOString(),
+    ...callSummary(s),
+    currentStep: s.ours.workflow ? s.ours.workflow.steps[s.ours.workflow.current]?.title || null : null,
+    handoff: s.ours.handoff?.requested ? { state: s.ours.handoff.state, since: s.ours.handoff.at ? new Date(s.ours.handoff.at).toISOString() : null, specialistKey: s.specialistKey, pickedUpBy: s.ours.handoff.pickedUpBy || null } : null,
+  })).sort((a, b) => b.startedAt.localeCompare(a.startedAt));
 }
 
 /** 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); }
-  return sessions.size < MAX_SESSIONS;
+  for (const [id, s] of sessions) { if (now - s.createdAt > MAX_AGE_MS || now - s.lastActive > IDLE_MS) drop(id, "expired"); }
+  return sessions.size < maxSessions();
 }
 
 export function newSession(opts = {}) {
@@ -38,7 +75,10 @@ export function newSession(opts = {}) {
     createdAt: Date.now(),
     lastActive: Date.now(),
     specialistKey: null,         // capability for the human-specialist console; minted on handoff
+    link: opts.link ? { id: opts.link.id, name: opts.link.name } : null, // the share link this call came from
     ours: {
+      sessionId: id,           // for the events this session's agents report (webhooks)
+      customer: !!opts.link,   // a customer on a share link (not the operator testing)
       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 +148,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/stt.mjs

@@ -1,7 +1,10 @@
 // Deepgram speech-to-text (nova-3): the cloud fallback that turns a recorded
 // utterance into text when the offline sherpa models aren't available.
 
-export const STT_ENABLED = !!process.env.DEEPGRAM_API_KEY;
+import { onSettingsChange } from "./settings.mjs";
+
+export let STT_ENABLED = !!process.env.DEEPGRAM_API_KEY;
+onSettingsChange((k) => { if (k.has("DEEPGRAM_API_KEY")) STT_ENABLED = !!process.env.DEEPGRAM_API_KEY; });
 const MODEL = process.env.DEEPGRAM_MODEL || "nova-3";
 
 // buffer: raw audio bytes; contentType e.g. "audio/webm" or "audio/mpeg".