ava-engine 0.2.0 → 0.4.0

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

package/lib/tts.mjs

@@ -4,20 +4,28 @@
 // is the on-device Web Speech fallback.
 
 import { loadKokoro, kokoroInstalled } from "./kokoro-model.mjs";
+import { onSettingsChange } from "./settings.mjs";
 
-const HAS_ELEVEN = !!process.env.ELEVENLABS_API_KEY;
-const HAS_HUME = !!process.env.HUME_API_KEY;
-const HAS_KOKORO = process.env.KOKORO !== "off"; // local, free — on by default
-
-const ELEVEN_VOICE = process.env.ELEVEN_VOICE_ID || "XrExE9yKIg1WjnnlVkGX";
+const HAS_KOKORO = process.env.KOKORO !== "off"; // local, free — on by default (loading it needs a restart)
 const ELEVEN_MODEL = process.env.ELEVEN_MODEL || "eleven_turbo_v2_5";
-const ELEVEN_LABEL = process.env.ELEVEN_LABEL || "Matilda";
-const HUME_VOICE = process.env.HUME_VOICE_ID || "a7ecc00a-6fc0-4546-8126-e12cfd8de3bf";
-const HUME_LABEL = process.env.HUME_LABEL || "Aria";
 const HUME_DESC = process.env.HUME_DESCRIPTION || "Warm, empathetic, natural and reassuring";
-const KOKORO_VOICE = process.env.KOKORO_VOICE || "af_heart";
 
-export const TTS_ENABLED = HAS_KOKORO || HAS_ELEVEN || HAS_HUME;
+// Keys and voices can change from the dashboard; these reload when they do.
+let HAS_ELEVEN, HAS_HUME, ELEVEN_VOICE, ELEVEN_LABEL, HUME_VOICE, HUME_LABEL, KOKORO_VOICE;
+export let TTS_ENABLED, ELEVEN_STREAMS;
+function load() {
+  HAS_ELEVEN = !!process.env.ELEVENLABS_API_KEY;
+  HAS_HUME = !!process.env.HUME_API_KEY;
+  ELEVEN_VOICE = process.env.ELEVEN_VOICE_ID || "XrExE9yKIg1WjnnlVkGX";
+  ELEVEN_LABEL = process.env.ELEVEN_LABEL || "Matilda";
+  HUME_VOICE = process.env.HUME_VOICE_ID || "a7ecc00a-6fc0-4546-8126-e12cfd8de3bf";
+  HUME_LABEL = process.env.HUME_LABEL || "Aria";
+  KOKORO_VOICE = process.env.KOKORO_VOICE || "af_heart";
+  TTS_ENABLED = HAS_KOKORO || HAS_ELEVEN || HAS_HUME;
+  ELEVEN_STREAMS = HAS_ELEVEN;
+}
+load();
+onSettingsChange(load);
 const FETCH_TIMEOUT_MS = 20_000;
 const MAX_KOKORO_QUEUE = Number(process.env.KOKORO_MAX_QUEUE) || 6;
 
@@ -132,7 +140,6 @@ async function eleven(text) {
    as Kokoro) so first audio lands in ~0.3-0.5s instead of waiting for the whole
    clip. previous_text is passed so prosody stays continuous across chunks. Each
    chunk is a complete MP3 the client decodes independently. onChunk(mp3, text). */
-export const ELEVEN_STREAMS = HAS_ELEVEN;
 export async function elevenStream(text, onChunk) {
   const clean = String(text || "").slice(0, 800).trim();
   if (!clean) throw new Error("empty text");

package/lib/webhooks.mjs

@@ -0,0 +1,112 @@
+// Event webhooks: tell your own systems what happens on calls.
+//
+//   WEBHOOK_URL        one or more URLs (comma-separated) that receive every event as JSON
+//   WEBHOOK_SECRET     signs each delivery: X-Ava-Signature: sha256=HMAC(secret, `${timestamp}.${body}`)
+//   SLACK_WEBHOOK_URL  a Slack incoming webhook; posts when a customer asks for a person
+//   SLACK_BOT_TOKEN + SLACK_CHANNEL  instead: one thread per handoff, with "picked up
+//                      by…" and "call ended…" replies (a bot with chat:write)
+//   PUBLIC_URL         where specialists open Ava (for the links in those messages)
+//
+// Events: session.started, step.completed, workflow.completed, handoff.requested,
+// session.ended. Delivery is fire-and-forget with one retry, so a slow or broken
+// endpoint never holds up a call.
+
+import { createHmac, randomUUID } from "node:crypto";
+
+import { onSettingsChange } from "./settings.mjs";
+
+const TIMEOUT_MS = 5_000, RETRY_MS = 2_000;
+let URLS = [], SECRET = "", SLACK = "", BOT = "", CHANNEL = "";
+export let WEBHOOKS_ENABLED = false;
+/** What's configured, for the dashboard. Never the URLs themselves (Slack URLs are secrets). */
+export const WEBHOOK_INFO = { endpoints: 0, hosts: [], signed: false, slack: false };
+function load() {
+  URLS = (process.env.WEBHOOK_URL || "").split(",").map((u) => u.trim()).filter(Boolean);
+  SECRET = process.env.WEBHOOK_SECRET || "";
+  SLACK = process.env.SLACK_WEBHOOK_URL || "";
+  BOT = process.env.SLACK_BOT_TOKEN || ""; CHANNEL = process.env.SLACK_CHANNEL || "";
+  WEBHOOKS_ENABLED = URLS.length > 0 || !!SLACK || !!(BOT && CHANNEL);
+  Object.assign(WEBHOOK_INFO, { endpoints: URLS.length, hosts: URLS.map((u) => { try { return new URL(u).host; } catch { return "?"; } }), signed: !!SECRET, slack: !!SLACK || !!(BOT && CHANNEL), slackThreads: !!(BOT && CHANNEL) });
+}
+load();
+onSettingsChange(load);
+
+/** The URL a specialist opens to join a call. */
+export function specialistUrl(key) {
+  const base = (process.env.PUBLIC_URL || `http://localhost:${Number(process.env.PORT) || 5190}`).replace(/\/+$/, "");
+  return `${base}/specialist?key=${encodeURIComponent(key)}`;
+}
+
+async function post(url, body, headers, label) {
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const r = await fetch(url, { method: "POST", headers: { "Content-Type": "application/json", "User-Agent": "ava-engine", ...headers }, body, signal: AbortSignal.timeout(TIMEOUT_MS) });
+      if (r.ok || (r.status >= 400 && r.status < 500 && r.status !== 429)) {
+        if (!r.ok) console.warn(`  [${label}] endpoint refused the event (${r.status})`);
+        return r.ok;
+      }
+    } catch { /* network error or timeout: retry once */ }
+    if (attempt === 0) await new Promise((r) => setTimeout(r, RETRY_MS));
+  }
+  console.warn(`  [${label}] delivery failed after a retry`); // never log the URL: Slack URLs are secrets
+  return false;
+}
+
+/** Signature headers for a delivery body (exported for tests and for receivers to copy). */
+export function sign(body, timestamp, secret = SECRET) {
+  return "sha256=" + createHmac("sha256", secret).update(`${timestamp}.${body}`).digest("hex");
+}
+
+function slackText(type, data) {
+  if (type === "ava.test") return ":white_check_mark: Ava is connected to this channel. You'll get a message here when a customer asks for a person.";
+  if (type === "handoff.picked_up") return null; // threads only
+  if (type !== "handoff.requested") return null;
+  const where = data.platform ? ` on ${data.platform.name}` : "";
+  const step = data.workflow?.currentStep ? `\n*Stuck on:* ${data.workflow.currentStep} (${data.workflow.done}/${data.workflow.total} steps done)` : "";
+  const said = data.lastUserMessage ? `\n*Last said:* “${data.lastUserMessage}”` : "";
+  return `:raising_hand: A customer${where} asked to talk to a person.${step}${said}\n<${data.specialistUrl}|Join the call>`;
+}
+
+/** Send an event to every configured endpoint. Returns a promise tests can await; callers needn't. */
+export function emitEvent(type, data) {
+  if (!WEBHOOKS_ENABLED) return Promise.resolve();
+  const event = { id: randomUUID(), type, createdAt: new Date().toISOString(), data };
+  const body = JSON.stringify(event);
+  const jobs = URLS.map((url) => {
+    const ts = String(Math.floor(Date.now() / 1000));
+    const headers = { "X-Ava-Event": type, "X-Ava-Delivery": event.id, "X-Ava-Timestamp": ts, ...(SECRET ? { "X-Ava-Signature": sign(body, ts) } : {}) };
+    return post(url, body, headers, "webhook");
+  });
+  if (BOT && CHANNEL) jobs.push(slackBot(type, data));
+  else { const text = SLACK && slackText(type, data); if (text) jobs.push(post(SLACK, JSON.stringify({ text }), {}, "slack")); }
+  return Promise.allSettled(jobs);
+}
+
+// ── Slack threads (bot token): the handoff opens a thread; updates reply in it ──
+const threads = new Map(); // sessionId → thread ts (bounded)
+async function slackApi(body) {
+  try {
+    const r = await fetch("https://slack.com/api/chat.postMessage", { method: "POST", headers: { "Content-Type": "application/json; charset=utf-8", Authorization: `Bearer ${BOT}` }, body: JSON.stringify({ channel: CHANNEL, unfurl_links: false, ...body }), signal: AbortSignal.timeout(TIMEOUT_MS) });
+    const j = await r.json();
+    if (!j.ok) console.warn(`  [slack] ${j.error || r.status}`);
+    return j.ok ? j : null;
+  } catch { console.warn("  [slack] delivery failed"); return null; }
+}
+const mins = (s) => `${Math.floor(s / 60)}:${String(Math.round(s % 60)).padStart(2, "0")}`;
+async function slackBot(type, data) {
+  if (type === "ava.test") return !!(await slackApi({ text: slackText(type, data) }));
+  if (type === "handoff.requested") {
+    const j = await slackApi({ text: slackText(type, data) });
+    if (j) { threads.set(data.sessionId, j.ts); if (threads.size > 500) threads.delete(threads.keys().next().value); }
+    return !!j;
+  }
+  const ts = threads.get(data.sessionId);
+  if (!ts) return true;
+  if (type === "handoff.picked_up") return !!(await slackApi({ thread_ts: ts, text: `:handshake: Picked up by *${data.by}*.` }));
+  if (type === "session.ended") {
+    threads.delete(data.sessionId);
+    const steps = data.workflow ? ` · ${data.workflow.done}/${data.workflow.total} steps${data.workflow.completed ? " (finished)" : ""}` : "";
+    return !!(await slackApi({ thread_ts: ts, text: `:checkered_flag: Call ended after ${mins(data.durationSec)}${steps}.` }));
+  }
+  return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ava-engine",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "A screen-aware voice agent: sees the tab a user shares, talks them through it, and hands off to a human when needed.",
   "keywords": [
@@ -39,9 +39,9 @@
   "scripts": {
     "start": "node --env-file-if-exists=.env server.mjs",
     "dev": "node --watch --env-file-if-exists=.env server.mjs",
-    "test": "node --test test/*.test.mjs",
+    "test": "node --test --import ./test/env.mjs test/*.test.mjs",
     "check": "node --check server.mjs && for f in lib/*.mjs public/*.js; do node --check \"$f\" || exit 1; done",
-    "test:e2e": "node --test --test-concurrency=1 test/e2e/*.e2e.mjs",
+    "test:e2e": "node --test --import ./test/env.mjs --test-concurrency=1 test/e2e/*.e2e.mjs",
     "lint": "eslint .",
     "test:all": "npm run lint && npm run check && npm test && npm run test:e2e",
     "demo:record": "node scripts/record-demo.mjs",

package/public/app.js

@@ -17,6 +17,10 @@ const S = {
   workflow: null, handoffTimer: null, knowTimer: null,
   specialistPresent: false, bridgeSince: 0, bridgeTimer: null, rtc: null, rtcMic: null,
 };
+// Opened from a share link (/c/<id>)? Then this is a customer's call, set up by the link.
+const LINK_ID = (location.pathname.match(/^\/c\/([A-Za-z0-9_-]{22})\/?$/) || [])[1] || null;
+S.link = null; // the link's public view: { title, intro, mode, platform, options }
+if (LINK_ID) document.documentElement.classList.add("customer");
 const video = $("video"), capcanvas = $("capcanvas"), hashcanvas = $("hashcanvas");
 let pip = null;
 
@@ -25,6 +29,8 @@ let pip = null;
   try {
     const h = await (await fetch("/api/health")).json();
     S.tts = h.tts || { enabled: false };
+    // Demo mode (no API key): say so up front, in the lobby and on the call.
+    if (h.mock) { $("obDemo").hidden = false; $("demoPill").hidden = false; }
     S.stt = !!(h.stt && h.stt.enabled);
     S.sttStream = !!(h.stt && h.stt.streaming); // offline sherpa streaming ASR on the server
     // speech-recognition engine picker (green room)
@@ -52,10 +58,51 @@ let pip = null;
       sel.onchange = () => { S.voice = sel.value; $("voicesel").value = S.voice; $("voicesel2").value = S.voice; };
     }
     initOnboard(h);
+    if (LINK_ID) await initLink(!!h.mock); else applyUrlParams();
   } catch {}
   populateMics();
 })();
 
+/* ═══════════ share links + URL presets ═══════════ */
+// /app?mode=onboarding&product=<id> preselects the lobby (the dashboard's "Test" buttons use it).
+function applyUrlParams() {
+  const q = new URLSearchParams(location.search);
+  const mode = q.get("mode"), product = q.get("product");
+  if (mode === "onboarding" || mode === "flexible") selectMode(mode);
+  if (product && S.platforms.some((p) => p.id === product)) { if (!mode) selectMode("onboarding"); selectPlatform(product); }
+}
+async function initLink(demo) {
+  let v;
+  try {
+    const r = await fetch(`/api/link/${LINK_ID}`);
+    v = await r.json().catch(() => ({}));
+    if (!r.ok) return linkUnavailable(v.error || "This link isn't available right now.");
+  } catch { return linkUnavailable("Couldn't reach Ava. Check your connection and reload the page."); }
+  S.link = v;
+  $("transcript").classList.add("noagents"); // customers see the conversation, not the agents' work
+  S.agentMode = v.mode;
+  S.platform = v.platform ? { ...v.platform, category: "" } : null;
+  if (S.platform && S.platform.accent) applyBrand(S.platform.accent);
+  document.title = v.platform ? `${v.platform.name} · Live guide` : "Ava · Live guide";
+  $("obAsideTitle").textContent = v.title;
+  $("obAsideLead").textContent = v.intro;
+  $("obTitle").textContent = "Ready when you are";
+  $("obLead").textContent = "Check your microphone, then start. You can type instead of talking at any time.";
+  $("obAudioLabel").textContent = "Your microphone";
+  $("joinvoiceText").textContent = "Start with voice";
+  $("jointext").textContent = "Type instead";
+  if (demo) $("obDemoText").textContent = "Ava's replies are canned for now.";
+  const steps = v.platform && v.options.steps ? v.platform.journey : [];
+  $("obJourneyBlock").hidden = !steps.length;
+  $("obJourney").innerHTML = steps.map((s) => `<li>${esc(s)}</li>`).join("");
+}
+function linkUnavailable(msg) {
+  document.querySelector(".ob-panel").classList.add("ob-unavailable");
+  $("obTitle").textContent = "This link isn't available";
+  $("obLead").textContent = msg;
+  $("joinvoice").disabled = true; $("jointext").disabled = true;
+}
+
 /* ═══════════ onboard: agent mode + platform pickers ═══════════ */
 function initOnboard(h) {
   const modes = (h.modes && h.modes.length) ? h.modes : [
@@ -227,7 +274,7 @@ async function joinCall(mode) {
     fetch("/api/tts", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ text: "Hi.", provider: S.voice }) }).then((r) => r.arrayBuffer()).catch(() => {});
   }
   try {
-    const res = await fetch("/api/session", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ mode: S.agentMode, platformId: S.platform ? S.platform.id : null }) });
+    const res = await fetch("/api/session", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ mode: S.agentMode, platformId: S.platform ? S.platform.id : null, ...(LINK_ID ? { link: LINK_ID } : {}) }) });
     const r = await res.json().catch(() => ({}));
     if (!res.ok || !r.sessionId) throw new Error(r.error || `server error ${res.status}`);
     S.sessionId = r.sessionId; S.joined = true;
@@ -264,6 +311,12 @@ async function joinCall(mode) {
 }
 function setTopbarForMode() {
   const onb = S.agentMode === "onboarding" && S.platform;
+  if (S.link) { // customers see the product, not the engine
+    $("apptitle").textContent = S.platform ? S.platform.name : "Ava";
+    $("topsub").textContent = "your live guide";
+    $("footmode").textContent = "recording off · transcript on";
+    return;
+  }
   $("apptitle").textContent = onb ? `${S.platform.name} Onboarding` : "Flexible Agent";
   $("topsub").textContent = onb ? `onboarding guide · ${S.platform.category || "platform"}` : "screen-aware assistant";
   $("footmode").textContent = onb ? `onboarding ${S.platform.name} · transcript on` : "recording off · transcript on";
@@ -578,6 +631,7 @@ function frameHash() {
 
 /* ═══════════ console drawer ═══════════ */
 function consoleToggle(force) {
+  if (S.link) return; // no console on customers' calls
   const open = force != null ? force : $("console").hidden;
   $("console").hidden = !open;
   $("consolebtn").classList.toggle("on", open);
@@ -861,6 +915,8 @@ function setStuck(stuck) {
 /* ═══════════ workflow tracker + human handoff + RAG indicator ═══════════ */
 function renderWorkflow(wf) {
   S.workflow = wf || null;
+  $("workflow").classList.toggle("wf-nosteps", !!(S.link && !S.link.options.steps));
+  $("wfHandoff").hidden = !!(S.link && !S.link.options.handoff);
   if (wf && wf.handoff) S.handoff = wf.handoff;
   if (!wf) {
     // A re-plan can clear the tracker mid-handoff; keep the panel (and its
@@ -896,6 +952,10 @@ function renderHandoff(h) {
     link.hidden = true;
   } else {
     spin.style.display = "";
+    if (S.link) { // the team is told (dashboard, Slack); the customer never handles the specialist key
+      txt.textContent = "We've let the team know. A specialist will join you here shortly.";
+      link.hidden = true; return;
+    }
     txt.textContent = "Share this link with a specialist so they can join:";
     link.hidden = !S.specialistKey; link.textContent = specialistURL();
   }
@@ -1050,7 +1110,17 @@ async function showReport(sid, durMs, rawTape) {
   $("repPlay").disabled = !tape.length;
   $("report").hidden = false;
 
+  if (S.link) {
+    $("repFootnote").textContent = "Thanks for using your live guide.";
+    $("repNew").textContent = "Start again";
+  }
   if (!sid) { $("repSummary").textContent = "Recap unavailable — no active session."; return; }
+  if (S.link && !S.link.options.recap) { // this link skips the AI recap: just free the session
+    fetch("/api/end", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ sessionId: sid }), keepalive: true }).catch(() => {});
+    $("repHeadline").textContent = "Thanks, you're all set";
+    $("repSummary").textContent = "You can close this tab, or start again if you need more help.";
+    return;
+  }
   try {
     const s = await fetch("/api/summary", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ sessionId: sid }) }).then((r) => r.json())
       .finally(() => { // the recap was the last use — free the session slot now
@@ -1613,7 +1683,16 @@ async function playWavStream(res, abort) {
   return true;
 }
 
-async function speak(text, force, ignoreMute) {
+// Ava keeps one voice. If the chosen server voice (Kokoro by default) can't speak
+// a line, it retries once, then shows the reply as text: it never swaps to the
+// browser's robotic voice mid-call. The browser voice is used only when picked.
+let voiceNoticeShown = false;
+function voiceUnavailable() {
+  if (voiceNoticeShown) return;
+  voiceNoticeShown = true;
+  addSysLine("voice", "Ava's voice couldn't play that reply, so it's shown as text. Ava will keep trying her voice.");
+}
+async function speak(text, force, ignoreMute, retried = false) {
   if (!ignoreMute && !$("speak").checked) return false;
   if (!force && lastSpoken && simText(text, lastSpoken) > 0.7) { lastSpoken = text; return false; }
   lastSpoken = text; S.curSpokenText = text;
@@ -1624,7 +1703,7 @@ async function speak(text, force, ignoreMute) {
     const abort = ttsFetch = new AbortController();
     try {
       const res = await fetch("/api/tts", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ text, provider: prov }), signal: abort.signal });
-      if (!res.ok) throw new Error("tts " + res.status);
+      if (!res.ok) throw Object.assign(new Error("tts " + res.status), { status: res.status });
       if ((res.headers.get("Content-Type") || "").includes("x-wav-stream")) {
         if (ttsFetch === abort) ttsFetch = null; // playWavStream owns the abort from here
         if (await playWavStream(res, abort)) return true;
@@ -1642,6 +1721,10 @@ async function speak(text, force, ignoreMute) {
       // an aborted request means a newer speak/barge-in superseded this one —
       // stay silent instead of re-speaking the text in the browser voice
       if (abort.signal.aborted || (e && e.name === "AbortError")) return false;
+      // busy (another line still synthesising) or a hiccup: one more try with the same voice
+      if (!retried) { await wait(e?.status === 429 ? 900 : 400); if (!abort.signal.aborted && ttsFetch !== null && ttsFetch !== abort) return false; return speak(text, true, ignoreMute, true); }
+      voiceUnavailable();
+      return false;
     }
   }
   if ("speechSynthesis" in window) {