ava-engine 0.3.0 → 0.4.0

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

@@ -3,6 +3,8 @@
 //   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,
@@ -11,12 +13,23 @@
 
 import { createHmac, randomUUID } from "node:crypto";
 
-const URLS = (process.env.WEBHOOK_URL || "").split(",").map((u) => u.trim()).filter(Boolean);
-const SECRET = process.env.WEBHOOK_SECRET || "";
-const SLACK = process.env.SLACK_WEBHOOK_URL || "";
-const TIMEOUT_MS = 5_000, RETRY_MS = 2_000;
+import { onSettingsChange } from "./settings.mjs";
 
-export const WEBHOOKS_ENABLED = URLS.length > 0 || !!SLACK;
+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) {
@@ -45,6 +58,8 @@ export function sign(body, timestamp, secret = SECRET) {
 }
 
 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)` : "";
@@ -62,7 +77,36 @@ export function emitEvent(type, data) {
     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");
   });
-  const text = SLACK && slackText(type, data);
-  if (text) jobs.push(post(SLACK, JSON.stringify({ text }), {}, "slack"));
+  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.3.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;
 
@@ -54,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 : [
@@ -229,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;
@@ -266,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";
@@ -580,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);
@@ -863,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
@@ -898,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();
   }
@@ -1052,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
@@ -1615,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;
@@ -1626,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;
@@ -1644,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) {