ava-engine 0.3.0 → 0.4.0

package/lib/playbooks.mjs

@@ -16,7 +16,7 @@ export const PLAYBOOKS_DIR = home(process.env.PLAYBOOKS_DIR || join(process.env.
 
 const ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
 const HEX = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
-const KNOWN = new Set(["id", "name", "url", "category", "accent", "tagline", "firstWin", "path", "optional", "journey", "etaMin", "knowledge", "demoOnly", "$schema"]);
+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) {
@@ -61,6 +61,14 @@ export function validatePlaybook(raw, fallbackId) {
   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`);
@@ -73,12 +81,13 @@ export function validatePlaybook(raw, fallbackId) {
   }
   for (const k of Object.keys(raw)) if (!KNOWN.has(k)) warnings.push(`unknown field "${k}" is ignored`);
   if (errors.length) return { errors, warnings };
-  const { name, url, category, accent, tagline, firstWin, optional, etaMin, demoOnly } = raw;
+  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 } : {}),
     },
   };
 }

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

@@ -13,7 +13,10 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
-export const DAILY_BUDGET_USD = Math.max(0, Number(process.env.DAILY_BUDGET_USD) || 0);
+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);

package/lib/state.mjs

@@ -2,6 +2,7 @@
 
 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)
@@ -10,7 +11,7 @@ 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;
 
@@ -19,20 +20,47 @@ function drop(id, reason) {
   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;
-  emitEvent("session.ended", {
-    sessionId: id, reason, mode: o.mode, platform: o.platform ? { id: o.platform.id, name: o.platform.name } : null,
+  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, "expired"); }
-  return sessions.size < MAX_SESSIONS;
+  return sessions.size < maxSessions();
 }
 
 export function newSession(opts = {}) {
@@ -47,8 +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}

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".

package/lib/team.mjs

@@ -0,0 +1,191 @@
+// Team accounts: who can sign in to the dashboard, and what each person may do.
+//
+//   owner       everything, including Settings and the team
+//   editor      share links, playbooks and calls
+//   specialist  the inbox and calls: picks up customers who asked for a person
+//
+// Accounts live in USERS_FILE (default ~/.ava-engine/users.json, mode 600) with
+// scrypt password hashes. Sign-ins are signed session cookies; the signing key is
+// generated once per install (~/.ava-engine/secret.key). Without any accounts Ava
+// works as before: ACCESS_PASSWORD, or this computer only.
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, chmodSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { createHash, createHmac, randomBytes, randomUUID, scryptSync, timingSafeEqual } from "node:crypto";
+
+const HOME = process.env.AVA_HOME || join(homedir(), ".ava-engine");
+const FILE = process.env.USERS_FILE || join(HOME, "users.json");
+const KEY_FILE = join(HOME, "secret.key");
+export const ROLES = ["owner", "editor", "specialist"];
+const EMAIL = /^[^\s@]{1,64}@[^\s@]{1,190}\.[^\s@]{2,}$/;
+
+let users = [], keys = [], loadedMtime = -1;
+// Re-read when the file changed underneath us (`ava-engine team` while Ava runs).
+function fresh() {
+  let m = 0;
+  try { m = statSync(FILE).mtimeMs; } catch {}
+  if (m === loadedMtime) return;
+  loadedMtime = m;
+  try { const j = JSON.parse(readFileSync(FILE, "utf8")); users = Array.isArray(j.users) ? j.users : []; keys = Array.isArray(j.keys) ? j.keys : []; } catch { users = []; keys = []; }
+}
+fresh();
+function save() {
+  mkdirSync(dirname(FILE), { recursive: true });
+  const tmp = `${FILE}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ users, keys }, null, 2), { mode: 0o600 });
+  renameSync(tmp, FILE);
+  try { chmodSync(FILE, 0o600); } catch {}
+  try { loadedMtime = statSync(FILE).mtimeMs; } catch {}
+}
+
+// ── signing key (one per install) ──
+let key = null;
+function signingKey() {
+  if (key) return key;
+  try { key = Buffer.from(readFileSync(KEY_FILE, "utf8").trim(), "base64url"); if (key.length >= 32) return key; } catch {}
+  key = randomBytes(32);
+  mkdirSync(dirname(KEY_FILE), { recursive: true });
+  writeFileSync(KEY_FILE, key.toString("base64url"), { mode: 0o600 });
+  return key;
+}
+const mac = (s) => createHmac("sha256", signingKey()).update(s).digest("base64url");
+const eq = (a, b) => { const x = Buffer.from(String(a)), y = Buffer.from(String(b)); return x.length === y.length && timingSafeEqual(x, y); };
+
+/** A signed, tamper-proof token for a cookie: payload is a small object. */
+export function signToken(payload) {
+  const body = Buffer.from(JSON.stringify(payload)).toString("base64url");
+  return `${body}.${mac(body)}`;
+}
+export function readToken(token) {
+  const [body, sig] = String(token || "").split(".");
+  if (!body || !sig || !eq(sig, mac(body))) return null;
+  try { return JSON.parse(Buffer.from(body, "base64url").toString("utf8")); } catch { return null; }
+}
+
+// ── passwords ──
+function hash(password, salt = randomBytes(16).toString("base64url")) {
+  return { salt, hash: scryptSync(password, salt, 64, { N: 16384, r: 8, p: 1 }).toString("base64url") };
+}
+const DUMMY = hash("not-a-real-password"); // equal work when the email is unknown
+export function passwordProblem(p) {
+  if (typeof p !== "string" || p.length < 10) return "Passwords need at least 10 characters.";
+  if (p.length > 200) return "That password is too long.";
+  return null;
+}
+export const suggestPassword = () => randomBytes(12).toString("base64url");
+
+// ── accounts ──
+const pub = (u) => u && { id: u.id, email: u.email, name: u.name, role: u.role, createdAt: u.createdAt, lastLoginAt: u.lastLoginAt || null };
+export const hasUsers = () => { fresh(); return users.length > 0; };
+export const listUsers = () => { fresh(); return users.map(pub); };
+export const getUser = (id) => { fresh(); return users.find((u) => u.id === id) || null; };
+const byEmail = (email) => { fresh(); return users.find((u) => u.email === String(email || "").trim().toLowerCase()) || null; };
+const owners = () => users.filter((u) => u.role === "owner");
+
+function validate({ email, name, role }, { existing } = {}) {
+  const errors = [];
+  if (email !== undefined) {
+    const e = String(email || "").trim().toLowerCase();
+    if (!EMAIL.test(e)) errors.push("Enter a valid email address.");
+    else if (byEmail(e) && byEmail(e).id !== existing?.id) errors.push("Someone on the team already uses that email.");
+  }
+  if (name !== undefined && !(typeof name === "string" && name.trim().length >= 1 && name.length <= 60)) errors.push("Enter a name (up to 60 characters).");
+  if (role !== undefined && !ROLES.includes(role)) errors.push("Pick a role: owner, editor or specialist.");
+  return errors;
+}
+
+/** Add someone. The first account must be an owner. Returns { user } or { errors }. */
+export function createUser({ email, name, role, password }) {
+  const errors = validate({ email, name, role });
+  const pw = passwordProblem(password); if (pw) errors.push(pw);
+  if (!users.length && role !== "owner") errors.push("The first account must be an owner.");
+  if (errors.length) return { errors };
+  const u = { id: randomUUID(), email: email.trim().toLowerCase(), name: name.trim(), role, ...hash(password), tv: 1, createdAt: new Date().toISOString() };
+  users.push(u); save();
+  return { user: pub(u) };
+}
+/** Change name or role. There's always at least one owner. */
+export function updateUser(id, { name, role }) {
+  const u = getUser(id);
+  if (!u) return { errors: ["That person isn't on the team."] };
+  const errors = validate({ name, role }, { existing: u });
+  if (role && role !== "owner" && u.role === "owner" && owners().length === 1) errors.push("Ava needs at least one owner. Make someone else an owner first.");
+  if (errors.length) return { errors };
+  if (name !== undefined) u.name = name.trim();
+  if (role !== undefined && role !== u.role) { u.role = role; u.tv += 1; } // new role: sign in again
+  save();
+  return { user: pub(u) };
+}
+/** Set a new password. Signs that person out everywhere. */
+export function setPassword(id, password) {
+  const u = getUser(id);
+  if (!u) return { errors: ["That person isn't on the team."] };
+  const pw = passwordProblem(password); if (pw) return { errors: [pw] };
+  Object.assign(u, hash(password)); u.tv += 1; save();
+  return { user: pub(u) };
+}
+export function deleteUser(id) {
+  const u = getUser(id);
+  if (!u) return { errors: ["That person isn't on the team."] };
+  if (u.role === "owner" && owners().length === 1) return { errors: ["You can't remove the last owner."] };
+  users = users.filter((x) => x.id !== id); save();
+  return { deleted: true };
+}
+
+/** Check an email and password. Returns the account or null (same work either way). */
+export function verifyLogin(email, password) {
+  const u = byEmail(email);
+  const h = hash(String(password || ""), u ? u.salt : DUMMY.salt).hash;
+  if (!u || !eq(h, u.hash)) return null;
+  u.lastLoginAt = new Date().toISOString(); save();
+  return u;
+}
+
+/** Session token for an account; invalid after a password or role change (tv). */
+export const sessionFor = (u) => signToken({ u: u.id, tv: u.tv, iat: Date.now() });
+/** The account a session token belongs to, if it's still valid. */
+export function userFromSession(payload, maxAgeMs) {
+  if (!payload || !payload.u || Date.now() - payload.iat > maxAgeMs) return null;
+  const u = getUser(payload.u);
+  return u && u.tv === payload.tv ? pub(u) : null;
+}
+
+// ── API keys: for scripts and tools (n8n, Zapier, your backend) ──
+// "ava_sk_" + 32 random bytes. Only a SHA-256 is stored, so a copied users.json
+// can't be used to call Ava; the key itself is shown once, when it's made.
+const sha = (s) => createHash("sha256").update(s).digest("hex");
+const keyPub = (k) => ({ id: k.id, name: k.name, role: k.role, prefix: k.prefix, createdAt: k.createdAt, createdBy: k.createdBy || null, lastUsedAt: k.lastUsedAt || null });
+export const listKeys = () => { fresh(); return keys.map(keyPub); };
+/** Make a key. Returns { key (shown once), apiKey } or { errors }. */
+export function createKey({ name, role, createdBy }) {
+  const errors = [];
+  if (!(typeof name === "string" && name.trim() && name.length <= 60)) errors.push("Name the key after what uses it, e.g. “n8n” (up to 60 characters).");
+  if (!ROLES.includes(role)) errors.push("Pick a role for the key: owner, editor or specialist.");
+  if (errors.length) return { errors };
+  fresh();
+  const key = `ava_sk_${randomBytes(32).toString("base64url")}`;
+  const k = { id: randomUUID(), name: name.trim(), role, prefix: key.slice(0, 11), hash: sha(key), createdAt: new Date().toISOString(), createdBy: createdBy || null };
+  keys.push(k); save();
+  return { key, apiKey: keyPub(k) };
+}
+export function deleteKey(id) {
+  fresh();
+  const n = keys.length;
+  keys = keys.filter((k) => k.id !== id);
+  if (keys.length === n) return false;
+  save(); return true;
+}
+/** The key behind a Bearer token, as a signed-in "user" with the key's role. */
+export function userFromApiKey(token) {
+  if (typeof token !== "string" || !token.startsWith("ava_sk_") || token.length > 100) return null;
+  fresh();
+  const h = sha(token);
+  const k = keys.find((x) => eq(x.hash, h));
+  if (!k) return null;
+  if (!k.lastUsedAt || Date.now() - Date.parse(k.lastUsedAt) > 600_000) { k.lastUsedAt = new Date().toISOString(); save(); } // at most every 10 minutes
+  return { id: `key:${k.id}`, name: k.name, role: k.role, apiKey: true };
+}
+
+export const USERS_FILE = FILE;
+export const usersFileExists = () => existsSync(FILE);