ava-engine 0.0.0-stage → 0.2.0

package/lib/ours.mjs

@@ -0,0 +1,766 @@
+// The flexible agent. Per turn: perception (diff-gated, rich) + intent (parallel)
+// → deterministic router → a MULTIMODAL talker that actually sees the screen and
+// drives toward a held goal → async planner that keeps goal + grounded plan.
+// A background observe loop keeps perception fresh and lets the agent react
+// proactively when the screen changes (parity with continuous-vision agents).
+
+import { chat, chatStream, estTokens } from "./openrouter.mjs";
+import { MODELS, PROVIDER } from "./models.mjs";
+import { record, scoreView, addTokens, mintSpecialistKey, revokeSpecialistKey } from "./state.mjs";
+
+const HAMMING_SAME = 20; // on the 2048-bit (32×32) dHash — ~1%; a tab switch or text change flips more
+const HISTORY_MAX = 60;  // prompts read at most the last 30 entries; keep a little slack
+
+function remember(o, role, text) {
+  o.history.push({ role, text });
+  if (o.history.length > HISTORY_MAX) o.history.splice(0, o.history.length - HISTORY_MAX);
+}
+
+const TALKER_SYS = [
+  "You are Ava, a sharp, proactive, screen-aware assistant. The SCREEN section in the context is a live reading of exactly what is on the user's screen right now (from a vision model) — treat it as your own eyes.",
+  "PERSONALITY: you're quick-witted, playful, and a little cheeky — the fun colleague who happens to be great at their job. Laugh when something's genuinely funny, tease gently, celebrate small wins ('there it is!'), and show real empathy when something goes sideways. If something on their screen is absurd or amusing, you're allowed to enjoy it out loud. Dry humor welcome; corporate blandness is not.",
+  "You've got their back. If you spot something risky or costly — a huge number, a likely typo, a destructive click, a charge that looks wrong ($10,000 when they probably meant $100) — SPEAK UP with genuine concern before they commit: 'Whoa, hold on — that says ten grand, did you mean a hundred?'. Catching that is the single most valuable thing you do, so never let it slide by with a bland remark.",
+  "Answer what the user actually asked FIRST, directly and concretely. If they ask what's on their screen, describe it from the SCREEN reading. Only then, if useful, offer one next step.",
+  "The GOAL line is background context, not a mandate. The user's LATEST message always wins: when they change topic, task, or app, drop the old thread completely and follow them — never steer the conversation back to a previous task, and never keep hunting for something they've moved past.",
+  "Ground every instruction in the SCREEN reading: name the exact button/label/section listed and where it is. If they can't find something, use the SCREEN details to say precisely where it is, or say honestly it isn't listed and what to do instead.",
+  "When you name, recommend, or point at CONTENT — a video, an email, a plan, a price, a search result, a file — use ONLY the real items in the SCREEN's ON-SCREEN CONTENT list, quoted as written, and USE ALL of them (if four plans with prices are listed, you know all four — never claim a listed one 'isn't shown'). NEVER invent a title, channel, price, or plan that isn't listed.",
+  "But do NOT flatly contradict the user about their own screen. If they insist something is there that you don't see in the list, it may be below the fold, in a menu, or just appeared — believe them: say you might not have the full view, ask them to scroll to it or point at it, and re-read rather than arguing 'it's not there'. Only say an item isn't present after you've genuinely looked and it's still absent.",
+  "NEVER send the user to a specific tab, section, or button to FIND missing information when you're only guessing it lives there (e.g. 'click the X tab to see the prices'). Guessing a destination sends them on a wrong chase. Only point at a control that's actually in the SCREEN reading. If the thing they want isn't in the reading, say plainly you don't see it here and ask them to scroll or point to it, or take another look — do not invent where it 'probably' is.",
+  "You have TASTE. When asked what you think of a design, a page, or a choice, GIVE a real opinion — commit to a view, grounded in the SCREEN reading's look/colors/layout, with one specific observation and (when useful) one suggestion. NEVER say you can't think, can't judge, or can't interpret design — the look line IS you seeing it.",
+  "Never say 'I can't see it' while a SCREEN reading exists. If the reading lacks the specific detail they're asking about, say what you DO see and ask them to point at or open the part they mean.",
+  "Use the SCREEN 'state' notes (what's selected, disabled, greyed/coloured) to reason about whether a step worked.",
+  "If the context says the screen CHANGED since your last reply, or the SCREEN no longer matches the step you were on, acknowledge it first in a few words (e.g. 'looks like you moved to X') and re-orient — never blindly continue the previous instruction.",
+  "If something didn't work, take a concrete DIFFERENT step. Never loop, and never keep asking 'do you see it?'.",
+  "When the user asks the SAME thing again, or asks whether something will work / is safe / what happens if they do it, do NOT repeat your previous instruction. ANSWER the real question concretely — say what the action actually does and what happens next (e.g. 'Yep — clicking Purchase charges your card the $10.85 and the credits land in your balance right away'), then reassure. Re-sending a near-identical message is a failure.",
+  "A REASONING line may appear in the context — that's your own honest read of whether they're stuck, hesitant, or done. Treat it as a directive: act on it, don't restate your last line.",
+  "Talk like a real person, not a script. NEVER start with 'It looks like you're on…' and don't narrate the screen every time — vary your wording, and often just give the next step directly, the way a friend sitting next to them would.",
+  "If SCREEN says 'not shared', you genuinely cannot see anything — NEVER invent or guess screen contents, and say so plainly if they ask about their screen. But if their question has nothing to do with the screen, just answer it — don't mention what you can or can't see.",
+  "Be brief, warm, human. One clear next step per turn. Never end with filler like 'Is there anything else I can help you with?'.",
+  "Write PLAIN spoken text only — no markdown, no asterisks, no **bold**, no bullet points, no headings, no emoji. Just natural sentences, like a person talking.",
+].join("\n");
+
+// Extra contract when the user joined as a VOICE call — replies are heard, not
+// read, so they must sound like a person on a call, not a chatbot.
+const VOICE_STYLE = [
+  "This is a LIVE VOICE CALL — your reply is spoken aloud. Keep it to one or two short sentences (under ~35 words), then stop.",
+  "Short does NOT mean flat. Sound warm, engaged, and human: use contractions, react naturally, vary your phrasing — like a sharp colleague on a call, not a status readout.",
+  "Be fun to talk to. React with genuine energy ('Oh, that green is bold — I like it'), take positions, tease gently when it fits. When they ask for your opinion, LEAD with the opinion, then the reason — never with a disclaimer.",
+  "Answer the literal question first, in as few words as it deserves: 'what is 2 plus 2' gets 'Four.' — and if the question has nothing to do with the screen, do not mention the screen or what you can or can't see at all.",
+  "When the answer is a 'no' or 'I don't see it', always add the one most useful follow-up — where it probably lives, a good guess, or what you can do instead. Never stop dead on a negative.",
+  "NEVER give the same answer twice. If they ask again or rephrase, they need something DIFFERENT: add detail, offer a guess, or say what you're unsure about — repeating your previous sentence word-for-word is the worst thing you can do.",
+  "Their words arrive through speech recognition and may be garbled ('scream' for 'screen', 'glas' for 'last'). Infer what they most likely meant from context and answer THAT; if you genuinely can't tell, ask a quick friendly clarifying question.",
+  "Never re-describe the screen and never repeat an instruction you already gave. If they check in ('are you there?'), just answer warmly in a few words.",
+  "Talk like you're mid-conversation: no preamble, no summaries, no sign-off questions.",
+].join("\n");
+
+// Proactive speech: every fresh screen read reaches Ava and SHE decides
+// whether this is a moment to speak — no client- or server-side lanes,
+// no rate-limit heuristics. One brain, one judgment call.
+const MOMENT_SYS = [
+  "You are Ava — playful, sharp, a little cheeky — on a LIVE CALL, watching the user's screen as they work. The screen just changed. Decide like a person would: is this a moment to speak?",
+  "SPEAK when a person watching would: they arrived somewhere new (glance over, react naturally); they completed a step (acknowledge in a word and give the next one toward the GOAL); they undid, closed, or abandoned something (react with real empathy or curiosity AND follow up — 'closed it without buying — everything okay, or want a hand?'); something looks RISKY, COSTLY, or WRONG (a huge amount, a likely typo, a destructive action — jump in with genuine concern BEFORE they commit: 'ten thousand dollars? double-check that's not a typo'); or something is genuinely funny (enjoy it out loud).",
+  "You are protective and engaged, not a passive narrator. A big number, a surprising change, or a reversal is your cue to REACT with feeling — surprise, concern, delight — never a flat observation. If you just watched them do something and there's an obvious 'wait, are you sure?', say it.",
+  "Lean toward engaging — a quiet assistant feels dead, and being present is the whole point. STAY QUIET (reply with exactly SKIP) only when a person truly would: they're mid-keystroke and don't need you, nothing actually changed, or anything you'd say just repeats a recent line.",
+  "When you speak: ONE short, natural, spoken sentence — and prefer SUBSTANCE over narration. Announcing the screen ('Oh, the credits page') is only for a genuinely new arrival; otherwise advance the GOAL, offer a concrete insight or save ('that auto top-up is what's greying out the button'), or check your read of what they're after ('Looks like you're trying to top up — want a hand?'). Never ask check-in questions ('are you finding it helpful?'), never repeat or paraphrase your recent lines. Plain text only, no markdown or emoji.",
+].join("\n");
+
+// ── Onboarding mode: turn Ava from a do-anything assistant into a focused
+// product-onboarding specialist for one platform. Appended AFTER the base
+// persona so its focus overrides the flexible "follow them anywhere" line. ──
+function onboardingAddendum(p) {
+  return [
+    ``,
+    `ONBOARDING MODE — you are a product-onboarding specialist for ${p.name} (${p.category}). This OVERRIDES the "follow them anywhere / goal is background" guidance above.`,
+    `Your ONE job: get this brand-new user signed in and all the way into their ${p.name} dashboard, fast and without overwhelm. You are DONE the moment they reach ${p.firstWin}.`,
+    `You know the path cold: ${p.path.join(" → ")}. Guide ONE concrete step at a time, always grounded in the SCREEN reading — name the exact button/field to use and where it is.`,
+    `Confirm each step worked from the SCREEN before moving to the next. If a step fails or looks different, adapt from what you actually SEE — never recite the next step blindly.`,
+    `VERIFY before you celebrate: only say a step is done — deployed, created, signed in, provisioned — when the SCREEN explicitly confirms it (a success message, a live URL, a 'Deployed'/'Healthy'/'Created' status, the new item clearly listed). A projects list or dashboard that may hold pre-existing items is NOT proof. If they cancelled, backed out, or you can't see the confirmation, do NOT congratulate them — say what you see and walk them through actually completing it.`,
+    `WHEN THE DASHBOARD IS REACHED (confirmed): stop. Celebrate it plainly ("you're in — that's your dashboard, nicely done") and DON'T invent extra chores. ${p.optional || ""}`.trim(),
+    `TRUST THE SCREEN over your memory of the product. If you sent them somewhere and they say it isn't there, believe them — read what's actually visible now and point to THAT. Never send them back to a section you already tried; that back-and-forth is the worst failure mode.`,
+    `Stay on task, but don't fabricate steps to prolong it. If they wander, warmly steer back ("one more step and you're at the dashboard"). Never dump the whole checklist at once, and never repeat an instruction you just gave — if they're stuck, do something DIFFERENT.`,
+  ].join("\n");
+}
+const ONBOARDING_MOMENT = "\nYOU ARE ONBOARDING them onto this specific product, and the screen JUST CHANGED — react now, don't wait to be asked. If they completed a step (with real on-screen proof), acknowledge it in a few words and give the very next action. If they landed on a new page, orient them and point at the next step. If they cancelled, backed out, or the expected result isn't visible, gently say what you see and help them finish it. Only reply SKIP if the screen truly did not meaningfully change. Never wait silently while they navigate.";
+
+// Build the talker's system prompt for this session: base persona, + onboarding
+// focus when in onboarding mode, + voice-call style when it's a voice call.
+function talkerSystem(o, voiceMode) {
+  let sys = TALKER_SYS;
+  if (o.mode === "onboarding" && o.platform) sys += "\n" + onboardingAddendum(o.platform);
+  if (voiceMode) sys += "\n" + VOICE_STYLE;
+  return sys;
+}
+
+function hamming(a, b) {
+  if (!a || !b || a.length !== b.length) return 64;
+  let d = 0;
+  for (let i = 0; i < a.length; i++) { let x = parseInt(a[i], 16) ^ parseInt(b[i], 16); while (x) { d += x & 1; x >>= 1; } }
+  return d;
+}
+function parseJSON(text, fallback) { try { const m = text.match(/\{[\s\S]*\}/); return JSON.parse(m ? m[0] : text); } catch { return fallback; } }
+// Models sometimes prefix their line with a speaker label ("Ava: ...") — strip
+// it so it never gets spoken or stored in history.
+function stripLabel(s) { return String(s || "").replace(/^\s*(ava|assistant|ai|agent)\s*[:>\-–]\s*/i, "").trim(); }
+// The talker is fed the compiled context as its user message, and occasionally
+// echoes part of that prompt back as its "reply" (e.g. the "SCREEN CHANGED…"
+// directive, or a "visible: … state: …" dump). Cut the reply at the first such
+// leaked marker so a prompt fragment is never spoken or shown.
+const LEAK_MARKERS = [/SCREEN CHANGED/i, /\bGOAL\s*[:(]/i, /\bSCREEN:\s/i, /\bvisible:\s/i, /\bstate:\s/i, /USER (INTENT|JUST SAID)/i, /RECENT ACTIVITY/i, /\bMODE:\s+[A-Z]/, /COMPILED CONTEXT/i, /\bPLAN:\s/i, /\bGUIDANCE:\s/i, /ONBOARDING MODE/i];
+function sanitizeReply(s) {
+  let t = String(s || "");
+  for (const m of LEAK_MARKERS) { const i = t.search(m); if (i >= 0) t = t.slice(0, i); }
+  return t.trim();
+}
+// Jaccard word-overlap similarity — used to stop the agent repeating itself.
+function similar(a, b) {
+  const w = (s) => new Set(String(s || "").toLowerCase().replace(/[^a-z0-9 ]/g, " ").split(/\s+/).filter((x) => x.length > 2));
+  const A = w(a), B = w(b); if (!A.size || !B.size) return 0;
+  let inter = 0; for (const x of A) if (B.has(x)) inter++;
+  return inter / (A.size + B.size - inter);
+}
+function activityLine(o) { return o.activity.length ? o.activity.slice(-6).map((a) => "• " + a.action).join("\n") : "—"; }
+
+/* ---------- 1. Perception (diff-gated, rich) ---------- */
+function mockVision(userText) {
+  const t = (userText || "").toLowerCase();
+  let app = "OpenRouter", page = "Credits";
+  if (/ai studio|gemini/.test(t)) { app = "Google AI Studio"; page = "Playground"; }
+  else if (/gmail|inbox|email/.test(t)) { app = "Gmail"; page = "Inbox"; }
+  return JSON.stringify({ app, page, elements: ["Manage", "Auto Top-Up: enabled", "Add Credits (disabled)"], state: "Auto top-up is on; Add Credits looks greyed out", look: "clean light UI, indigo accents, roomy spacing — feels friendly and modern", changed: ["screen updated"] });
+}
+// Serialize perception per session: /api/observe and /api/turn can arrive
+// concurrently, and both write screenState/lastHash — unserialized, a slow
+// response can overwrite a fresher read and clobber the diff-gate hash.
+function perceive(o, ...args) {
+  const run = (o._perceiveLock || Promise.resolve()).then(() => doPerceive(o, ...args));
+  o._perceiveLock = run.then(() => {}, () => {});
+  return run;
+}
+async function doPerceive(o, frameDataUrl, screenActive, frameHash, userText, usages, force) {
+  if (!screenActive) { o.screenState = o.screenState ? { ...o.screenState, stale: true } : null; return { ran: false, discarded: false, reason: "not sharing" }; }
+  if (!frameDataUrl) { return { ran: false, discarded: false, reason: "no frame this turn (keeping last read)" }; } // sharing but capture missed — don't go stale
+  const dist = hamming(o.lastHash, frameHash);
+  // force = a real user turn → always re-read (never guide off a stale screen).
+  // The diff-gate only saves calls in the background observe loop.
+  if (!force && o.lastHash != null && dist <= HAMMING_SAME) return { ran: false, discarded: true, reason: `diff ${dist} bits ≤ ${HAMMING_SAME} — reuse v${o.screenVersion}` };
+  const prevSummary = o.screenState && !o.screenState.stale
+    ? `${o.screenState.app} · ${o.screenState.page} — ${o.screenState.state || ""} — visible: ${(o.screenState.elements || []).join(" | ")}`
+    : "none (this may be the first screen)";
+  const messages = [
+    { role: "system", content: "Read this app screenshot for an assistant that will guide the user (the assistant does NOT see the image — your JSON is its only eyes, including for OPINIONS about the design AND for naming actual content on screen). Output ONLY minified JSON: {\"app\":string,\"page\":string,\"elements\":[\"up to 14 KEY buttons/links/toggles/fields — EXACT on-screen text + state like (disabled)/(selected)/(greyed)\"],\"content\":[\"up to 16 of the MAIN CONTENT items actually visible, copied VERBATIM and IN THE ORDER SHOWN top-to-bottom (the FIRST entry is the topmost/newest). Include identifying detail: for a list/feed (emails, videos, results) give each row as 'primary — secondary — time/meta', e.g. email row 'The Daily Byte — Your daily AI news — 9:12 AM', video 'Se7en Review — Nerdwriter — 1.2M views'. COMPARISON / PRICING / PLAN layouts (side-by-side cards, tables): capture EVERY tier/column as its own entry with ALL its key numbers — name, price WITH period, AND the headline quota/limit like credits or seats per period, e.g. 'Pro — $99/mo — 500,000 credits/mo'. NEVER drop the quota/credits in favor of the price — small or low-contrast numbers still count. For an OPENED item being VIEWED (an email, doc, video) capture its header FULLY: sender NAME and their email ADDRESS if shown (e.g. 'The Daily Byte <news@dailybyte.example>'), the subject/title, and the date. Never invent — copy only what is truly on screen; [] if none\"],\"state\":\"one line: what's shown, WHICH TAB/SECTION is selected, key values/numbers\",\"look\":\"1-2 lines on the VISUAL design: dominant colors (names + hex if shown), typography and layout feel, density, overall vibe\",\"activity\":\"short phrase: what the user most likely just DID vs the PREVIOUS screen, or 'no real change'\"}. Copy on-screen text VERBATIM; never guess text that isn't visible; keep each entry terse." },
+    { role: "user", content: [{ type: "image_url", image_url: { url: frameDataUrl } }, { type: "text", text: `PREVIOUS screen was: ${prevSummary}\nRead the CURRENT screen and infer the activity (what the user just did).` }] },
+  ];
+  const out = await chat({ model: MODELS.perception, role: "perception", provider: PROVIDER.perception, messages, maxTokens: 1100, temperature: 0.1, mock: () => mockVision(userText) });
+  usages.push(out);
+  const parsed = parseJSON(out.text, null);
+  const usable = parsed && ((parsed.elements && parsed.elements.length) || (parsed.state && String(parsed.state).length > 3) || (parsed.app && !/^unknown/i.test(parsed.app)));
+  if (!usable) {
+    // vision returned nothing usable (usually a truncated/garbled JSON) — DON'T go blind; keep the last good reading
+    if (o.screenState && !o.screenState.stale) { o.lastHash = frameHash; return { ran: false, discarded: false, reason: `vision unusable — kept last read v${o.screenVersion}` }; }
+    // no good previous read either: don't write an "unknown" state; leave the hash unset so the next frame retries
+    return { ran: true, discarded: false, reason: "vision unusable — will retry on the next frame" };
+  }
+  o.lastHash = frameHash; o.screenVersion += 1;
+  o.screenState = { ...parsed, v: o.screenVersion, stale: false };
+  const act = ((parsed && parsed.activity) || "").trim();
+  if (act && !/^no( real)? change/i.test(act)) { o.activity.push({ at: Date.now(), action: act }); if (o.activity.length > 10) o.activity.shift(); }
+  return { ran: true, discarded: false, reason: `change (diff ${dist} bits) → vision v${o.screenVersion}`, activity: act };
+}
+
+/* ---------- 2. Intent (fast, parallel) ---------- */
+function mockIntent(userText) {
+  const t = (userText || "").toLowerCase();
+  let intent = "task_help", frustrated = false, request = "";
+  if (/frustrat|angry|noo+|ugh|annoy|don'?t know|idk|hate/i.test(t)) { frustrated = true; intent = "frustrated"; }
+  if (/\?|how|what|why|where|can you|help/.test(t)) intent = frustrated ? "frustrated" : "question";
+  if (/stop|end (this|the)? ?call|done with|bye|quit/.test(t)) intent = "wants_to_stop";
+  if (/^(hi|hey|hello|yo|sup|nice|thanks|ok)\b/.test(t)) intent = "smalltalk";
+  return JSON.stringify({ intent, frustrated, request });
+}
+async function classifyIntent(o, userText, usages) {
+  const recent = o.history.slice(-6).map((t) => `${t.role}: ${t.text}`).join("\n");
+  const messages = [
+    { role: "system", content: 'Classify the user\'s latest message in a live screen-share help session. Output ONLY JSON: {"intent":"task_help|question|frustrated|wants_to_stop|smalltalk","frustrated":true|false,"request":"<=8 words on what they actually want, else empty"}.' },
+    { role: "user", content: `Conversation:\n${recent || "(none)"}\n\nLatest: "${userText}"` },
+  ];
+  const out = await chat({ model: MODELS.intent, role: "intent", messages, maxTokens: 70, temperature: 0, mock: () => mockIntent(userText) });
+  usages.push(out);
+  const p = parseJSON(out.text, { intent: "task_help", frustrated: false, request: "" });
+  return { intent: p.intent || "task_help", frustrated: !!p.frustrated, request: p.request || "", usage: out };
+}
+
+/* ---------- 3. Thinking (reasoning check: are we actually getting anywhere?) ---------- */
+// A short, honest reasoning pass the USER can see. It answers the questions a
+// good human helper asks themselves: is this working, are they stuck, is the
+// step actually done — and if stuck, what genuinely DIFFERENT thing to try.
+const THINK_SYS = [
+  "You are the reasoning check for a screen-aware assistant. Look at the goal, what's on the screen now, what the user just said, what they've been doing, and the assistant's own recent instructions — and judge, honestly, whether things are actually working.",
+  'Output ONLY JSON: {"resolved":true|false,"stuck":true|false,"blocker":"<one short line: what is actually blocking them right now, else empty>","thought":"<one short line of plain reasoning the user can read>","nextTactic":"<one short line: a genuinely DIFFERENT thing to try if stuck, else empty>"}.',
+  "stuck = the user has tried the same thing more than once, OR says something isn't working / can't be clicked / won't clear / is just text, OR the screen hasn't advanced since your last instruction, OR they keep asking whether it will work / hesitate to act (they want a concrete answer and reassurance, NOT the instruction repeated). When stuck, nextTactic MUST be a different route — NEVER a reword of the last instruction.",
+  "resolved = the current step or the whole goal is genuinely done, with explicit on-screen PROOF (a success message, a live/deployed URL, a 'Deployed'/'Healthy'/'Created' status, the created item clearly present). Being on a projects list or dashboard that could contain pre-existing items is NOT proof. If they cancelled, closed a dialog, or the confirmation isn't visible, resolved=false — and say so in 'thought' so the assistant doesn't wrongly congratulate them.",
+  "Trust the SCREEN and the user's words over your assumptions. If they say a control can't be clicked, believe them and reason about why (wrong element, it's a label not a link, a different screen than you think) and route around it.",
+  "Keep 'thought' to one honest sentence — it's shown live so a reviewer can see your reasoning.",
+].join("\n");
+async function think(o, userText, usages) {
+  const recent = o.history.slice(-8).map((t) => `${t.role}: ${t.text}`).join("\n") || "—";
+  const myLines = o.history.slice(-6).filter((t) => t.role === "assistant").map((t) => t.text).join(" | ") || "—";
+  const messages = [
+    { role: "system", content: THINK_SYS },
+    { role: "user", content: `GOAL: ${o.goal}\nSCREEN NOW: ${screenLine(o, true)}\nRECENT ACTIVITY (newest last):\n${activityLine(o)}\nCONVERSATION:\n${recent}\nYOUR RECENT INSTRUCTIONS (don't just repeat these): ${myLines}\nUSER JUST SAID: "${userText}"` },
+  ];
+  const out = await chat({ model: MODELS.intent, role: "thinking", messages, maxTokens: 150, temperature: 0.2, mock: () => JSON.stringify({ resolved: false, stuck: false, blocker: "", thought: "Following the sign-in steps — screen is advancing, nothing stuck yet.", nextTactic: "" }) });
+  usages.push(out);
+  const p = parseJSON(out.text, { resolved: false, stuck: false, blocker: "", thought: "", nextTactic: "" });
+  o.lastThink = { resolved: !!p.resolved, stuck: !!p.stuck, blocker: p.blocker || "", thought: p.thought || "", nextTactic: p.nextTactic || "" };
+  return { ...o.lastThink, usage: out };
+}
+
+/* ---------- workflow tracker (detect real progress through the journey) ---------- */
+function cap(s) { s = String(s || "").trim(); return s.charAt(0).toUpperCase() + s.slice(1); }
+function workflowView(o) {
+  const wf = o.workflow; if (!wf) return null;
+  const done = wf.steps.filter((s) => s.status === "done").length;
+  return { title: wf.title, steps: wf.steps.map((s) => ({ title: s.title, status: s.status })), current: wf.current, done, total: wf.steps.length, etaMin: wf.etaMin, note: wf.note, handoff: o.handoff };
+}
+function buildWorkflowFromPlan(o) {
+  if (o.workflow || !o.plan || !o.plan.length) return;
+  o.workflow = { title: o.goal && o.goal !== "—" ? cap(o.goal) : "Your task", steps: o.plan.map((t, i) => ({ title: cap(t), status: i === 0 ? "active" : "todo" })), current: 0, etaMin: null, note: "" };
+}
+function applyWorkflow(o, p) {
+  const wf = o.workflow; if (!wf || !p) return;
+  const n = wf.steps.length;
+  let cur = Number.isInteger(p.current) ? p.current : wf.current;
+  cur = Math.max(0, Math.min(n - 1, cur));
+  const done = new Set((p.done || []).filter((i) => Number.isInteger(i) && i >= 0 && i < n));
+  for (let i = 0; i < cur; i++) done.add(i); // steps before the current one are implicitly complete
+  const before = wf.steps.map((s) => s.status).join(",") + "|" + wf.current;
+  // NOT sticky: recompute every call so the tracker can REGRESS when the user
+  // cancels or backs out — a step is "done" only if this fresh read still says so.
+  wf.current = cur;
+  wf.steps.forEach((s, i) => { s.status = done.has(i) ? "done" : (i === cur ? "active" : "todo"); });
+  // Onboarding's final step is an "arrival / first win" step (open your dashboard,
+  // see it in Today) — reaching it IS the finish, so mark it done. The tracker only
+  // advances to the last step once the earlier ones are proven on screen, so this
+  // won't fire early. (Flexible tasks keep the strict all-steps-done rule.)
+  if (o.mode === "onboarding" && n > 0 && cur === n - 1) wf.steps[n - 1].status = "done";
+  wf.note = typeof p.note === "string" ? p.note : "";
+  if (typeof p.etaMin === "number") wf.etaMin = Math.max(0, Math.round(p.etaMin));
+  wf.changed = before !== (wf.steps.map((s) => s.status).join(",") + "|" + wf.current);
+  // The whole journey is finished when EVERY step is done on screen. This is the
+  // "stop" signal — the agent should celebrate once and go quiet, not keep
+  // guiding. Recomputed each call, so it regresses if the user backs out.
+  wf.complete = wf.steps.length > 0 && wf.steps.every((s) => s.status === "done");
+  o.done = wf.complete;
+  if (!o.done) o.doneAnnounced = false; // regressed → allow a fresh wrap-up later
+}
+async function trackWorkflow(o, usages) {
+  if (!o.workflow) return null;
+  const steps = o.workflow.steps.map((s, i) => `${i}: ${s.title}`).join("\n");
+  const messages = [
+    { role: "system", content: 'Given an ordered checklist and what is on the user\'s screen right now, report their progress HONESTLY and STRICTLY. Output ONLY JSON: {"current":<index of the step they are working on now>,"done":[<indices fully completed>],"note":"<=6 words naming the exact sub-action happening now, else empty","etaMin":<whole minutes left, rough>}.\nRULES:\n- A step is DONE only with explicit on-screen PROOF it finished: a success message, a live/deployed URL, a "Deployed"/"Healthy"/"Created" status, or the created item clearly present. Being on a page that merely COULD contain results (a projects list, a dashboard that may show pre-existing items) is NOT proof.\n- If the user cancelled, closed a dialog, hit an error, or the expected confirmation is NOT visible, the step is NOT done — set "current" to that step (it is fine to move BACKWARD from a previous reading).\n- When the FINAL step is confirmed complete on screen (the end goal / first win is visible), include EVERY index in "done" and set "current" to the last index — the whole task is finished.\n- Do not assume forward progress. Report only what the screen actually shows.' },
+    { role: "user", content: `CHECKLIST:\n${steps}\nSCREEN NOW: ${screenLine(o, true)}\nRECENT ACTIVITY (newest last):\n${activityLine(o)}` },
+  ];
+  const out = await chat({ model: MODELS.intent, role: "workflow", messages, maxTokens: 120, temperature: 0.1, mock: () => JSON.stringify({ current: o.workflow.current, done: o.workflow.steps.map((s, i) => i).filter((i) => o.workflow.steps[i].status === "done"), note: o.workflow.note, etaMin: o.workflow.etaMin }) });
+  usages.push(out);
+  const p = parseJSON(out.text, null);
+  if (p) applyWorkflow(o, p);
+  return p;
+}
+
+/* ---------- RAG: retrieve product knowledge (keyword overlap over the seeded KB) ---------- */
+function retrieveKnowledge(o, query) {
+  const kb = (o.platform && o.platform.knowledge) || [];
+  if (!kb.length) { o.knowledgeUsed = []; return []; }
+  const ss = o.screenState && !o.screenState.stale ? `${o.screenState.app} ${o.screenState.page} ${o.screenState.state || ""} ${(o.screenState.elements || []).join(" ")}` : "";
+  const terms = new Set((query + " " + ss).toLowerCase().replace(/[^a-z0-9 ]/g, " ").split(/\s+/).filter((w) => w.length > 2));
+  const scored = kb.map((s) => ({ s, score: s.k.split(/\s+/).reduce((n, k) => n + (terms.has(k) ? 1 : 0), 0) }));
+  scored.sort((a, b) => b.score - a.score);
+  const hits = scored.filter((x) => x.score >= 1).slice(0, 2).map((x) => x.s.text);
+  o.knowledgeUsed = hits;
+  return hits;
+}
+
+/* ---------- compiled context (blackboard) ---------- */
+function screenLine(o, screenActive) {
+  const ss = o.screenState;
+  if (!ss || ss.stale) {
+    return screenActive
+      ? "shared, but the first read isn't in yet — say you're just taking a look, and don't guess any specifics"
+      : "not shared — you cannot see the user's screen right now, so do not describe or guess any screen contents";
+  }
+  const content = Array.isArray(ss.content) && ss.content.length ? `\n  ON-SCREEN CONTENT (real items, top-to-bottom — the FIRST is the newest/topmost; reference ONLY these, verbatim; for a "latest"/"most recent" ask use the first): ${ss.content.map((c, i) => `${i + 1}. ${c}`).join("  ")}` : "";
+  return `${ss.app} · ${ss.page}\n  visible: ${(ss.elements || []).join(" | ")}${content}\n  state: ${ss.state || "—"}\n  look: ${ss.look || "—"}`;
+}
+function compileContext(o, route, intent, userText, screenActive) {
+  const app = o.screenState && !o.screenState.stale ? o.screenState.app : null;
+  const planStale = o.plan.length && o.planApp && app && app !== o.planApp;
+  const planLine = !o.plan.length ? "—"
+    : planStale ? `(made for ${o.planApp} — likely stale now that they're in ${app}; ignore if the user has moved on)`
+    : o.plan.map((p, i) => `${i + 1}) ${p}`).join("  ");
+  const recent = o.history.slice(-6).map((t) => `${t.role}: ${t.text}`).join("\n") || "—";
+  const seen = o.screenState && !o.screenState.stale ? `${o.screenState.app} · ${o.screenState.page}` : null;
+  const changed = seen && o.lastTalkerScreen && seen !== o.lastTalkerScreen;
+  // The goal was formed on a different app than the one they're looking at now
+  // → it's stale THIS turn (the planner only re-derives it after we reply, so
+  // without this she clings to the old goal on the very turn they pivot).
+  // In onboarding mode the goal is fixed (get them into the dashboard) — it never
+  // goes stale on an app switch; the whole point is to bring them back on task.
+  const onboarding = o.mode === "onboarding" && o.platform;
+  const goalStale = !onboarding && o.planApp && app && app !== o.planApp && o.goal !== "—";
+  return [
+    onboarding
+      ? `GOAL (stay focused — you are onboarding them onto ${o.platform.name}; keep steering here): ${o.goal}`
+      : goalStale
+      ? `GOAL: "${o.goal}" — ⚠ this was for ${o.planApp}; they're now in ${app}. DROP it and follow the SCREEN + their latest message. Do not steer back to it.`
+      : `GOAL (background only — the user's latest message wins): ${o.goal}`,
+    changed ? `⚠ SCREEN CHANGED since your last reply — acknowledge the new screen and re-orient; do NOT just continue the previous step.` : ``,
+    intent ? `USER INTENT: ${intent.intent}${intent.frustrated ? " · FRUSTRATED" : ""}${intent.request ? ` · wants: ${intent.request}` : ""}`
+      : o.lastIntent ? `USER INTENT (read a moment ago): ${o.lastIntent.intent}${o.lastIntent.frustrated ? " · FRUSTRATED" : ""}${o.lastIntent.request ? ` · wants: ${o.lastIntent.request}` : ""}` : ``,
+    `SCREEN: ${screenLine(o, screenActive)}`,
+    // RAG — inject retrieved product knowledge so answers are precise, not guessed
+    (() => { const kn = retrieveKnowledge(o, userText); return kn.length ? `PRODUCT KNOWLEDGE (retrieved from ${o.platform ? o.platform.name : "the product"} docs — use it to answer precisely; do not contradict or invent beyond it):\n${kn.map((t) => "• " + t).join("\n")}` : ""; })(),
+    `RECENT ACTIVITY (what the user has been doing on screen — reason about it):\n${activityLine(o)}`,
+    // Completion latch — the whole task is finished and confirmed on screen. This
+    // OVERRIDES the goal/plan: stop guiding, don't restart it, don't re-give steps.
+    o.done
+      ? `✓ TASK COMPLETE — every step is done and confirmed on screen; they've reached the goal. Do NOT give any more steps, do NOT re-explain the task, do NOT invent extra chores. If they're thanking you or wrapping up, respond warmly and briefly and let them go. Only take a new action if they explicitly ask for something new.`
+      : ``,
+    // Reasoning check — ALWAYS surfaced so the talker acts on a fresh diagnosis
+    // of whether they're stuck, done, or hesitant, instead of blindly continuing.
+    o.lastThink && o.lastThink.thought
+      ? `REASONING (your own honest read of the situation — you MUST act on this, do not ignore it): ${o.lastThink.thought}`
+        + (o.lastThink.stuck ? ` ⚠ STUCK: ${o.lastThink.blocker || "they're not getting through"}. Do NOT repeat your last instruction — instead ${o.lastThink.nextTactic || "answer the worry underneath their words and try a different route"}.` : ``)
+        + (o.lastThink.resolved ? ` ✓ This step is DONE on screen — acknowledge it and move on; don't re-give it.` : ``)
+      : ``,
+    `PLAN: ${planLine}`,
+    `GUIDANCE: ${o.guidance}`,
+    `MODE: ${route.mode.toUpperCase()} — ${route.instruction}`,
+    `RECENT:\n${recent}`,
+    `USER JUST SAID: "${userText}"`,
+    `(Ground your reply in the SCREEN reading above. Answer what they asked; the GOAL is context, not an agenda.)`,
+  ].filter(Boolean).join("\n");
+}
+
+/* ---------- 4. Planner (async: goal + grounded plan) ---------- */
+function mockPlanner(o) {
+  return JSON.stringify({ goal: "add credits manually on " + (o.screenState?.app || "the site"), understanding: "user wants to top up manually", plan: ["disable auto top-up", "find Add Credits", "enter amount & pay"], guidance: "be precise and grounded in the screen" });
+}
+async function plan(o, usages) {
+  const hist = o.history.slice(-10).map((t) => `${t.role}: ${t.text}`).join("\n");
+  const messages = [
+    { role: "system", content: 'You are the planner for a screen-aware assistant. Re-derive the goal from the user\'s LATEST messages and the CURRENT screen — the newest signals always outweigh older ones. If the user has pivoted to a new task, topic, or app, REPLACE the goal and plan entirely; never carry forward a goal the user has moved past. If there is no clear task yet, keep the goal broad ("help with whatever they ask") rather than inventing one. Output ONLY JSON: {"goal":"<one line: the concrete thing the user is trying to accomplish RIGHT NOW>","understanding":"<one line>","plan":["<=3 short next steps, grounded in real UI>"],"guidance":"<one line tone/pace note>"}.' },
+    { role: "user", content: `Screen: ${o.screenState && !o.screenState.stale ? o.screenState.app + " · " + o.screenState.page + " — " + (o.screenState.state || "") : "not shared"}\nVisible: ${(o.screenState?.elements || []).join(" | ")}\nRecent activity:\n${activityLine(o)}\nConversation:\n${hist}` },
+  ];
+  const out = await chat({ model: MODELS.planner, role: "planner", messages, maxTokens: 200, temperature: 0.4, mock: () => mockPlanner(o) });
+  usages.push(out);
+  const p = parseJSON(out.text, null);
+  if (p) { o.goal = p.goal || o.goal; o.understanding = p.understanding || o.understanding; o.plan = Array.isArray(p.plan) ? p.plan.slice(0, 3) : o.plan; o.guidance = p.guidance || o.guidance; }
+  // Onboarding: the destination is fixed. Let the planner set the next STEPS,
+  // but keep the goal anchored on getting them into the dashboard.
+  if (o.mode === "onboarding" && o.platform) o.goal = `Get set up on ${o.platform.name} and into the dashboard`;
+  o.planApp = o.screenState && !o.screenState.stale ? o.screenState.app : null; // remember what the plan was made for
+  o.goalGuessed = false; // the deep planner's goal is authoritative, not a guess
+  return out;
+}
+
+function mockTalker(messages) {
+  const c = messages[messages.length - 1].content;
+  const txt = Array.isArray(c) ? (c.find((x) => x.type === "text")?.text || "") : c;
+  if (/GREET/.test(txt)) return "Hey! I'm Ava — I can see your screen and help with pretty much anything on it. Share a window whenever you like, or just tell me what you're working on.";
+  if (/MODE: SUPPORT/.test(txt)) return "I've got you — looking at your screen now. Tap 'Manage' next to Auto Top-Up; the disable option is inside there.";
+  if (/MODE: WRAP/.test(txt)) return "All good — we can pick this up whenever. I'll be right here.";
+  return "Looking at your screen — tap 'Manage' next to Auto Top-Up, then choose Disable. That unlocks the manual Add Credits option.";
+}
+
+/* ---------- greeting ---------- */
+export async function greetStream(sess, emit, voiceMode = false) {
+  const o = sess.ours; const usages = [];
+  const sys = talkerSystem(o, voiceMode);
+  const greetMsg = (o.mode === "onboarding" && o.platform)
+    ? `GREET: open the call as a ${o.platform.name} onboarding specialist. In 1–2 short warm sentences, welcome them by name of the product, say you'll get them into their ${o.platform.name} dashboard quickly, and ask them to share the ${o.platform.name} tab${o.platform.demoOnly ? "" : ` (or open ${o.platform.url})`} so you can guide them step by step.`
+    : "GREET: open the call. In 1–2 short sentences, warmly introduce yourself as a screen-aware assistant that can help with anything on their screen, and invite them to share their screen or say what they're working on.";
+  const messages = [{ role: "system", content: sys }, { role: "user", content: greetMsg }];
+  emit("talkerStart", { model: MODELS.talker });
+  const tk = await chatStream({ model: MODELS.talker, role: "talker", provider: PROVIDER.talker, messages, maxTokens: 120, temperature: 0.6, mock: mockTalker, onDelta: (d) => emit("delta", { text: d }) });
+  tk.text = sanitizeReply(stripLabel(tk.text));
+  usages.push(tk); remember(sess.ours, "assistant", tk.text); pushBridge(sess, "ava", tk.text);
+  emit("talkerDone", { text: tk.text, model: MODELS.talker, prompt: tk.promptTokens, output: tk.completionTokens, tokens: tk.promptTokens + tk.completionTokens, latencyMs: tk.latencyMs, cost: tk.cost });
+  if (o.workflow) emit("workflow", workflowView(o)); // populate the tracker at call start
+  const hot = record(sess, "ours", usages, tk.latencyMs);
+  emit("metrics", { perModel: usages.map((u) => ({ role: u.role, model: u.model, tokens: u.promptTokens + u.completionTokens, cost: u.cost, latencyMs: u.latencyMs })), hotLatencyMs: hot, session: scoreView(sess.score.ours) });
+  emit("done", {});
+}
+
+/* ---------- deterministic quick router (instant, no model) ---------- */
+function quickRoute(o, userText) {
+  const t = (userText || "").toLowerCase();
+  const app = o.screenState && !o.screenState.stale ? o.screenState.app : null;
+  const SUPPORT_MSG = "They're stuck or frustrated — acknowledge it genuinely, look at the screen, and take a concrete new step yourself; don't ask them to look again.";
+  let mode = "help", instruction, bumped = false;
+  if (/\b(stop|end (the )?call|bye|quit|that'?s all|we'?re done|i'?m done|no thanks)\b/.test(t)) { mode = "wrap"; instruction = "They want to pause — acknowledge warmly and let them go."; }
+  else if (/frustrat|angry|ugh+|annoy|stupid|hate|i don'?t know|idk|wtf|come on|seriously/.test(t)) { mode = "support"; o.frustration = Math.min(3, o.frustration + 1); bumped = true; instruction = SUPPORT_MSG; }
+  else if (o.frustration >= 2) { mode = "support"; o.frustration -= 1; instruction = SUPPORT_MSG; } // stays supportive, but calm turns decay it
+  else { o.frustration = Math.max(0, o.frustration - 1); instruction = app ? `They're in ${app}. Look at the attached screen and give one precise, grounded next step toward the goal.` : "Help with what they asked; offer to look at their screen if it would help."; }
+  return { mode, instruction, app, frustration: o.frustration, bumped, willPlan: o.goal === "—" || o.turnsSincePlan >= 2 || o.frustration >= 2 };
+}
+
+/* ---------- one full turn ---------- */
+// How long we'll wait for a fresh screen read before talking anyway.
+//
+// The key fact: a screen that hasn't changed is diff-gated, so perceive() returns
+// almost INSTANTLY — the budget never bites and those turns are fast (~0.4s). The
+// budget only matters when a real vision read RUNS (the screen actually changed),
+// and vision costs ~2–2.6s here regardless of model or image size. On exactly
+// those turns the user is asking about the NEW screen, so grounding on a fresh
+// read matters more than shaving a second — otherwise the reply describes the OLD
+// screen (e.g. "$20 selected" after they switched to $10). So we wait for the
+// read. A read that overruns even this finishes in the background and grounds the
+// next turn. Tune with PERCEIVE_BUDGET_MS (lower = snappier but may lag one beat
+// on a just-changed screen).
+const PERCEIVE_BUDGET_MS = Number(process.env.PERCEIVE_BUDGET_MS) || 2800;
+
+export async function oursTurnStream(sess, userText, frameDataUrl, screenActive, frameHash, emit, voiceMode = false, changedHint = false) {
+  const o = sess.ours; const usages = [];
+  remember(o, "user", userText); pushBridge(sess, "user", userText);
+
+  // deterministic router — instant, no model, no waiting
+  const route = quickRoute(o, userText);
+  emit("gate", { mode: route.mode, app: route.app, frustration: route.frustration, willPlan: route.willPlan, reason: route.instruction });
+
+  // Intent runs concurrently. Its read is used in this turn's context when it lands
+  // in time (it usually beats a vision re-read), and always feeds the frustration
+  // signal + the next turn. Errors degrade to the regex route — they never escape.
+  let intentNow = null;
+  const iP = classifyIntent(o, userText, usages)
+    .then((i) => {
+      intentNow = { intent: i.intent, frustrated: i.frustrated, request: i.request };
+      o.lastIntent = intentNow;
+      if (i.frustrated && !route.bumped) o.frustration = Math.min(3, o.frustration + 1);
+      emit("intent", { intent: i.intent, frustrated: i.frustrated, request: i.request, model: MODELS.intent, tokens: i.usage.promptTokens + i.usage.completionTokens, latencyMs: i.usage.latencyMs, cost: i.usage.cost });
+    })
+    .catch((e) => emit("intent", { intent: "unavailable", frustrated: false, request: "", error: String(e?.message || e) }));
+
+  // Thinking runs concurrently too — a visible reasoning check on whether the
+  // user is actually progressing or stuck. Its verdict feeds this turn's context
+  // (so the talker adapts instead of repeating) and is surfaced in the transcript.
+  const kP = think(o, userText, usages)
+    .then((r) => emit("thinking", { resolved: r.resolved, stuck: r.stuck, blocker: r.blocker, thought: r.thought, nextTactic: r.nextTactic, model: MODELS.intent, tokens: r.usage.promptTokens + r.usage.completionTokens, latencyMs: r.usage.latencyMs, cost: r.usage.cost }))
+    .catch((e) => emit("thinking", { thought: "", error: String(e?.message || e) }));
+
+  // Perception: diff-gated re-read BEFORE the talker speaks, so the reply is
+  // grounded in the CURRENT screen. Unchanged screen → the gate skips the model
+  // call and resolves instantly. Slow vision → talk on the last good read rather
+  // than stall past the budget. Errors keep the last read — they never escape.
+  let perceptionPending = null;
+  if (screenActive && frameDataUrl) {
+    sess.score.ours.perception.captured += 1;
+    // When the user is explicitly asking Ava to LOOK or about what's on screen
+    // (contents, options, prices, what's selected), force a fresh read even if the
+    // coarse gate would reuse the last one — small but important changes (a moved
+    // selection, a newly revealed panel) can fall under the hash threshold.
+    // Two cases force a fresh read: (1) the user asks Ava to look / about screen
+    // contents, and (2) the user DISPUTES what Ava just said about the screen
+    // ("no, it's already there", "look again") — that's exactly when a stale or
+    // partial cached read needs refreshing before we answer.
+    const wantsFreshLook = /\b(what('?s| is| are| do)?\b.*\b(screen|see|show|there|here|option|plan|price|credit|selected|listed)|do you see|can you see|look (at|again)|check again|on (the|my) screen|read (the|my) screen|what am i|which (one|plan|option)|the options?\b|all (the|my) (option|plan))/i.test(userText || "")
+      || /\b(no,?\s+(it'?s|they'?re|there)|it'?s (already|right) (there|here|on|shown|showing|visible)|already (on the screen|there|shown|showing|visible|listed)|it'?s on the screen|its on the screen|you'?re wrong|look again|i can see (it|them|that)|they'?re (there|here|shown|listed))\b/i.test(userText || "");
+    // changedHint: the client's fine-grained detector saw a change the server
+    // hasn't read yet — bypass the coarse hash gate for this turn's frame.
+    const pP = perceive(o, frameDataUrl, true, frameHash, userText, usages, changedHint || wantsFreshLook)
+      .then((p) => {
+        if (p.ran) sess.score.ours.perception.analysed += 1;
+        const pu = usages.find((u) => u.role === "perception");
+        emit("perceive", { ran: p.ran, discarded: p.discarded, reason: p.reason, screenState: o.screenState, model: MODELS.perception, tokens: pu ? pu.promptTokens + pu.completionTokens : 0, latencyMs: pu?.latencyMs || 0, cost: pu?.cost || 0 });
+      })
+      .catch((e) => emit("perceive", { ran: false, discarded: false, reason: `vision error — using last read (${String(e?.message || e).slice(0, 120)})`, screenState: o.screenState }));
+    // Gated (unchanged) reads resolve instantly → this race ends at once and the
+    // turn stays fast. A read that actually runs is worth waiting for (see above).
+    const winner = await Promise.race([pP, new Promise((r) => setTimeout(() => r("timeout"), PERCEIVE_BUDGET_MS))]);
+    if (winner === "timeout") perceptionPending = pP; // vision overran the budget → talk on last read now, ground the next turn
+  } else {
+    emit("perceive", { ran: false, discarded: false, reason: screenActive ? "no frame captured — using last read" : "not sharing", screenState: o.screenState });
+  }
+
+  // Thinking is OFF the hot path. Waiting for a fresh reasoning pass before every
+  // reply cost ~0.5–1s for little gain: "stuck / done" state persists across
+  // turns, so the talker grounds on the PREVIOUS turn's verdict — already carried
+  // in o.lastThink and baked into the compiled context below. This turn's pass
+  // runs in parallel, updates o.lastThink for the NEXT reply, and streams into the
+  // transcript as it lands; we await it only later, so its tokens are recorded.
+  // TALKER — grounded in the now-fresh blackboard (screen read, intent + last reasoning)
+  const compiled = compileContext(o, route, intentNow, userText, screenActive);
+  emit("context", { compiled, tokens: estTokens(compiled) });
+  emit("talkerStart", { model: MODELS.talker });
+  const sys = talkerSystem(o, voiceMode);
+  let tk;
+  try {
+    tk = await chatStream({ model: MODELS.talker, role: "talker", provider: PROVIDER.talker, messages: [{ role: "system", content: sys }, { role: "user", content: compiled }], maxTokens: voiceMode ? 140 : 200, temperature: voiceMode ? 0.65 : 0.5, mock: mockTalker, onDelta: (d) => emit("delta", { text: d }) });
+  } catch (e) {
+    // The talker failed or the client hung up mid-reply. Calls that already ran
+    // (vision, intent, thinking) were billed — count them toward the budget.
+    await Promise.allSettled([iP, kP, perceptionPending]);
+    addTokens(sess, "ours", usages);
+    throw e;
+  }
+  tk.text = sanitizeReply(stripLabel(tk.text));
+  if (!tk.text) tk.text = "Sorry — let me look again. What are you seeing on the screen right now?"; // reply was pure prompt-echo; never speak blank
+  usages.push(tk); remember(o, "assistant", tk.text); o.lastSpokeAt = Date.now(); pushBridge(sess, "ava", tk.text);
+  emit("talkerDone", { text: tk.text, model: MODELS.talker, prompt: tk.promptTokens, output: tk.completionTokens, tokens: tk.promptTokens + tk.completionTokens, latencyMs: tk.latencyMs, cost: tk.cost });
+  if (o.knowledgeUsed && o.knowledgeUsed.length) emit("knowledge", { count: o.knowledgeUsed.length, snippets: o.knowledgeUsed, source: o.platform ? o.platform.name : null });
+  if (o.screenState && !o.screenState.stale) o.lastTalkerScreen = `${o.screenState.app} · ${o.screenState.page}`;
+
+  await iP; // already caught — never throws
+  await kP; // thinking ran in parallel off the hot path — await here so its tokens/cost are recorded (already caught)
+  if (perceptionPending) await perceptionPending; // already caught — never throws
+
+  // Pivot detection: the user moved to a different app since the plan was made,
+  // or their message signals a topic switch → re-plan NOW, not two turns later.
+  const appNow = o.screenState && !o.screenState.stale ? o.screenState.app : null;
+  const appPivot = !!(appNow && o.planApp && appNow !== o.planApp);
+  // The user is stating a NEW thing to do → the current goal is stale, re-derive now.
+  const newTask = /\b(i (?:want|wanna|need|'?d like) to|i want|now (?:i|let'?s)|next,?\s|let'?s|help me|can you help|instead|switch(?:ing)? to|chang(?:e|ing) to|moved? (?:on|to)|actually,? let'?s|forget (?:that|it)|never ?mind|different (?:question|thing|topic)|new (?:question|topic|task))\b/i.test(userText);
+  // The previous task was confirmed done → whatever they say next is a fresh goal.
+  const afterDone = !!o.prevResolved;
+  const willPlan = route.willPlan || appPivot || newTask || afterDone;
+  if (appPivot || (newTask && appNow)) o.plan = []; // old plan was for the old task — don't let it steer anything
+
+  o.turnsSincePlan += 1;
+  if (willPlan) {
+    try {
+      const pl = await plan(o, usages); o.turnsSincePlan = 0;
+      emit("planner", { ran: true, goal: o.goal, understanding: o.understanding, plan: o.plan, guidance: o.guidance, model: MODELS.planner, tokens: pl.promptTokens + pl.completionTokens, latencyMs: pl.latencyMs, cost: pl.cost });
+    } catch (e) {
+      emit("planner", { ran: false, goal: o.goal, understanding: o.understanding, plan: o.plan, error: String(e?.message || e) });
+    }
+  } else {
+    emit("planner", { ran: false, goal: o.goal, understanding: o.understanding, plan: o.plan, turnsUntil: 2 - o.turnsSincePlan });
+  }
+
+  // workflow progress — build from the plan in flexible mode, then detect where
+  // the user actually is on the journey and push the updated tracker.
+  if (o.mode !== "onboarding" && (appPivot || newTask || afterDone)) { o.workflow = null; o.done = false; o.doneAnnounced = false; } // fresh task → fresh tracker + clear the done latch (onboarding journey is fixed)
+  buildWorkflowFromPlan(o);
+  if (o.workflow) { try { await trackWorkflow(o, usages); } catch {} }
+  emit("workflow", o.workflow ? workflowView(o) : null); // sync the tracker (null clears a stale one)
+
+  o.prevResolved = !!(o.lastThink && o.lastThink.resolved); // if this task is done, re-plan on the next message
+  const hot = record(sess, "ours", usages, tk.latencyMs); // hot latency = talker only now
+  emit("metrics", { goal: o.goal, perModel: usages.map((u) => ({ role: u.role, model: u.model, tokens: u.promptTokens + u.completionTokens, cost: u.cost, latencyMs: u.latencyMs })), hotLatencyMs: hot, session: scoreView(sess.score.ours) });
+  emit("done", {});
+}
+
+/* ---------- end-of-call summary (for the session report) ---------- */
+export async function sessionSummary(sess) {
+  const o = sess.ours; const usages = [];
+  const convo = o.history.slice(-30).map((t) => `${t.role}: ${t.text}`).join("\n") || "(no conversation)";
+  const acts = o.activity.map((a) => a.action).join("; ") || "—";
+  const messages = [
+    { role: "system", content: 'Summarize this live screen-share voice session for a recap card the user sees after the call. Warm, concise, specific. Output ONLY JSON: {"headline":"<one short line naming what they were doing>","summary":"<2-3 sentences: what happened, what was accomplished, any snag>","highlights":["<up to 4 short bullet moments, each a few words>"]}.' },
+    { role: "user", content: `GOAL: ${o.goal}\nSCREEN ACTIVITY (oldest first): ${acts}\nCONVERSATION:\n${convo}` },
+  ];
+  const ask = (model) => chat({ model, role: "planner", messages, maxTokens: 300, temperature: 0.4,
+    mock: () => JSON.stringify({ headline: o.goal && o.goal !== "—" ? o.goal : "A quick session with Ava", summary: "MOCK mode recap: add an OPENROUTER_API_KEY for a real AI summary of the call.", highlights: ["Ran in MOCK mode with canned replies"] }) });
+  // A recap is the last thing the customer sees — one flaky upstream call
+  // shouldn't blank it. Try the planner model, then the faster intent model,
+  // then fall back to a plain recap built from the session itself.
+  let out = null;
+  for (const model of [MODELS.planner, MODELS.intent]) {
+    try { out = await ask(model); usages.push(out); break; }
+    catch (e) { console.error("  [summary]", model, e?.message || e); }
+  }
+  addTokens(sess, "ours", usages);
+  const replies = o.history.filter((t) => t.role === "assistant").length;
+  const fallback = {
+    headline: o.goal && o.goal !== "—" ? o.goal : "Session complete",
+    summary: `A ${replies}-reply session with Ava${o.activity.length ? `, across ${o.activity.length} screen changes` : ""}.`,
+    highlights: [],
+  };
+  const p = out ? parseJSON(out.text, fallback) : fallback;
+  return { headline: p.headline || o.goal, summary: p.summary || "", highlights: Array.isArray(p.highlights) ? p.highlights.slice(0, 4) : [], goal: o.goal, session: scoreView(sess.score.ours) };
+}
+
+/* ---------- barge-in truncation ---------- */
+// The user interrupted Ava mid-reply. Rewrite her last history entry to what
+// was ACTUALLY heard, so her memory matches the user's ears — otherwise she
+// keeps building on sentences the user never got.
+export function truncateAssistant(sess, heard) {
+  const h = sess.ours.history;
+  for (let i = h.length - 1; i >= 0; i--) {
+    if (h[i].role === "assistant") {
+      h[i].text = heard && heard.trim()
+        ? heard.trim() + " …(the user interrupted here — the rest was never heard)"
+        : "(started to answer but the user interrupted immediately — they heard none of it)";
+      break;
+    }
+  }
+  return { ok: true };
+}
+
+/* ---------- continuous observe (background): keep fresh + optional proactive ---------- */
+// Mark the screen as no longer shared (called when the user stops sharing).
+export function screenOff(sess) {
+  const o = sess.ours;
+  if (o.screenState) o.screenState = { ...o.screenState, stale: true };
+  o.lastTalkerScreen = ""; o.lastProactive = 0;
+  return { screenState: o.screenState, session: scoreView(sess.score.ours) };
+}
+
+// Keep perception fresh (silent). Frequent; never speaks. `force` means the
+// client's detector (hash + pixel diff) already decided this is a change —
+// don't let the coarser server hash gate discard a text-level change like a
+// tab switch inside the same modal.
+export async function observeUpdate(sess, frameDataUrl, frameHash, force = false) {
+  const o = sess.ours; const usages = [];
+  const prev = o.screenState && !o.screenState.stale ? `${o.screenState.app} · ${o.screenState.page}` : null;
+  const percept = await perceive(o, frameDataUrl, true, frameHash, "", usages, force);
+  const nowScreen = o.screenState ? `${o.screenState.app} · ${o.screenState.page}` : null;
+  const navChanged = !!(nowScreen && nowScreen !== prev); // real navigation, not just a scroll
+  // A reversal or a problem (closed a modal, cancelled, hit an error) is the
+  // moment a person watching would say something — flag it for a fast nudge.
+  const salient = /clos(e|ed|ing)|cancel|dismiss|abandon|error|fail|went back|reverted|unchanged/i.test(percept.activity || "");
+  // Real-time workflow tracking: when the user navigates to a new page, re-detect
+  // where they are on the journey so the tracker advances (or regresses) live.
+  let stepChanged = false;
+  if (navChanged && o.workflow) { try { o.workflow.changed = false; await trackWorkflow(o, usages); stepChanged = !!o.workflow.changed; } catch {} }
+  addTokens(sess, "ours", usages);
+  return { ran: percept.ran, discarded: percept.discarded, reason: percept.reason, navChanged, stepChanged, salient, activity: percept.activity || "", screenState: o.screenState, workflow: o.workflow ? workflowView(o) : null, session: scoreView(sess.score.ours) };
+}
+
+/* ---------- human handoff ---------- */
+// Prototype handoff: flag that the user wants a real person, move through a
+// believable connecting → waiting state. (No live agent backend here.)
+export function requestHandoff(sess) {
+  const o = sess.ours;
+  if (!o.handoff.requested) o.handoff = { requested: true, state: "connecting", at: Date.now() };
+  return { handoff: o.handoff, specialistKey: mintSpecialistKey(sess), workflow: o.workflow ? workflowView(o) : null };
+}
+export function handoffStatus(sess) {
+  const o = sess.ours;
+  if (o.handoff && o.handoff.state === "connecting" && Date.now() - (o.handoff.at || 0) > 2500) o.handoff.state = "waiting";
+  return { handoff: o.handoff, workflow: o.workflow ? workflowView(o) : null };
+}
+export function cancelHandoff(sess) {
+  sess.ours.handoff = { requested: false, state: "none" };
+  sess.ours.bridge.specialist = false;
+  revokeSpecialistKey(sess); // the shared link stops working
+  return { handoff: sess.ours.handoff, workflow: sess.ours.workflow ? workflowView(sess.ours) : null };
+}
+
+/* ---------- live bridge: a shared conversation the specialist can join ---------- */
+// Append a line both the user and the specialist can see. Roles: user | ava | specialist | system.
+export function pushBridge(sess, role, text) {
+  const b = sess.ours.bridge; if (!b || !text) return;
+  b.log.push({ seq: ++b.seq, role, text: String(text).slice(0, 2000), at: Date.now() });
+  if (b.log.length > 300) b.log.shift();
+}
+// Everything the specialist needs to arrive with full context (no cold start).
+function bridgeContext(sess) {
+  const o = sess.ours;
+  const ss = o.screenState && !o.screenState.stale ? o.screenState : null;
+  return {
+    platform: o.platform ? { name: o.platform.name, url: o.platform.url } : null,
+    mode: o.mode, goal: o.goal,
+    screen: ss ? { app: ss.app, page: ss.page, state: ss.state || "", elements: ss.elements || [] } : null,
+    workflow: o.workflow ? workflowView(o) : null,
+    reasoning: o.lastThink || null,
+    handoff: o.handoff,
+    specialist: o.bridge.specialist,
+  };
+}
+export function bridgePoll(sess, since = 0) {
+  const b = sess.ours.bridge;
+  return { seq: b.seq, events: b.log.filter((e) => e.seq > since), context: bridgeContext(sess) };
+}
+export function specialistJoin(sess) {
+  const o = sess.ours;
+  if (!o.handoff.requested) return null; // the user hasn't asked for a person
+  o.bridge.specialist = true;
+  o.handoff = { requested: true, state: "joined", at: Date.now() };
+  pushBridge(sess, "system", "A specialist joined the call and can see your screen and progress.");
+  return bridgePoll(sess, 0);
+}
+export function specialistSay(sess, text) {
+  pushBridge(sess, "specialist", text);
+  return { ok: true, seq: sess.ours.bridge.seq };
+}
+export function specialistLeave(sess) {
+  const o = sess.ours;
+  o.bridge.specialist = false;
+  o.handoff = { requested: false, state: "none" };
+  revokeSpecialistKey(sess);
+  pushBridge(sess, "system", "The specialist left — Ava is back with you.");
+  return bridgePoll(sess, 0);
+}
+// The user speaks while a specialist is present → goes to the specialist, not the LLM.
+export function userSayToBridge(sess, text) {
+  pushBridge(sess, "user", text);
+  return { ok: true, seq: sess.ours.bridge.seq };
+}
+
+// Generate ONE proactive line about the CURRENT screen (client calls this after the
+// screen settles and only when Ava isn't already speaking → no overlap/flooding).
+/* Silent-browsing intention guesser: watches the screen journey (activity
+   stream) and infers what the user is probably TRYING to do, so the goal
+   exists even when they never type or speak — and the talker has something
+   real to engage with instead of narrating screens. The deep planner still
+   overrides this whenever a real turn runs. */
+async function guessIntention(o, usages) {
+  const acts = o.activity.slice(-6).map((a) => a.action).join("; ") || "—";
+  const messages = [
+    { role: "system", content: 'From a user\'s screen journey, infer what they are most likely TRYING TO DO overall — a concrete task, not a description of where they are. Output ONLY JSON: {"goal":"<one concrete line, e.g. \'top up their OpenRouter credits\'>","understanding":"<one line: where they are in that journey>","confidence":<0..1>}. Ambiguous journey → confidence below 0.5.' },
+    { role: "user", content: `Screens/actions (oldest first): ${acts}\nCurrent screen: ${screenLine(o, true)}\nPrevious guess: ${o.goal}` },
+  ];
+  const out = await chat({ model: MODELS.intent, role: "intent", messages, maxTokens: 90, temperature: 0.3, mock: () => JSON.stringify({ goal: "top up their OpenRouter credits", understanding: "circling the billing pages", confidence: 0.8 }) });
+  usages.push(out);
+  o.lastGuessAt = Date.now();
+  const p = parseJSON(out.text, null);
+  if (p && p.goal && (p.confidence == null || p.confidence >= 0.5)) {
+    o.goal = p.goal; o.understanding = p.understanding || o.understanding; o.goalGuessed = true;
+    o.planApp = o.screenState && !o.screenState.stale ? o.screenState.app : o.planApp; // so it goes stale if they change apps
+    return p;
+  }
+  return null;
+}
+
+export async function proactiveNudge(sess) {
+  const o = sess.ours; const usages = [];
+  const ss = o.screenState;
+  const empty = { text: null, goal: o.goal, session: scoreView(sess.score.ours) };
+  if (!ss || ss.stale) return empty;                        // nothing shared → never invent
+  if (Date.now() - o.lastProactive < 1500) return empty;    // just enough breath to not talk over herself
+  if (o.done && o.doneAnnounced) return empty;              // task finished and already wrapped up → stay quiet, stop volunteering
+  // No goal yet (or a stale guess) while they browse → infer one from the journey
+  let guessedNow = null;
+  if (o.activity.length >= 2 && (o.goal === "—" || (o.goalGuessed && Date.now() - (o.lastGuessAt || 0) > 15000))) {
+    guessedNow = await guessIntention(o, usages);
+  }
+  const recentMine = o.history.slice(-6).filter((t) => t.role === "assistant").map((t) => t.text);
+  const planLine = o.plan.length ? o.plan.map((p, i) => `${i + 1}) ${p}`).join("  ") : "—";
+  const since = o.lastSpokeAt ? Math.round((Date.now() - o.lastSpokeAt) / 1000) + "s ago" : "a while ago";
+  // Ava's own vision agent flagged a reversal (they closed/cancelled/abandoned
+  // something you were helping with) → do not let her SKIP that moment.
+  const lastAct = (o.activity.at(-1) || {}).action || "";
+  const reversal = /clos(e|ed)|cancel|dismiss|abandon|remov|delet|went back|revert|error|fail/i.test(lastAct);
+  const directive = o.done
+    ? "\nTHEY JUST FINISHED — the whole task is COMPLETE and confirmed on screen. Say ONE short, warm congratulations that they're all set, then STOP. Do NOT give another step, suggest extra chores, or ask what's next."
+    : reversal
+    ? "\nHEADS UP: they just closed/cancelled/abandoned something you were engaged with. Follow up like a person would — do NOT reply SKIP. React (empathy or curiosity) and offer the next move."
+    : "";
+  // Once the task is done, drop the onboarding "give the next step" pressure —
+  // the done directive above is a wrap-up, not a nudge to keep guiding.
+  const momentSys = MOMENT_SYS + (!o.done && o.mode === "onboarding" && o.platform ? ONBOARDING_MOMENT : "");
+  const messages = [
+    { role: "system", content: momentSys },
+    { role: "user", content: `SCREEN NOW: ${screenLine(o, true)}\nGOAL${o.goalGuessed ? " (your inference from their journey — engage with it, confirm it naturally when useful)" : ""}: ${o.goal}\nPLAN: ${planLine}\nRECENT ACTIVITY (newest last — this is what just happened):\n${activityLine(o)}\nYOU LAST SPOKE: ${since}. Your recent lines (never repeat these): ${recentMine.join(" / ") || "—"}${directive}` },
+  ];
+  const out = await chat({ model: MODELS.talker, role: "talker", provider: PROVIDER.talker, messages, maxTokens: 60, temperature: 0.7, mock: () => "Want a hand with anything here?" });
+  usages.push(out); addTokens(sess, "ours", usages);
+  const t = sanitizeReply(stripLabel(out.text));
+  const base = { goal: o.goal, understanding: o.understanding, goalGuessedNow: !!guessedNow, workflow: o.workflow ? workflowView(o) : null, session: scoreView(sess.score.ours) };
+  if (!t || /^skip\b/i.test(t)) return { ...base, text: null };
+  const repeatGate = (o.mode === "onboarding" && o.platform) ? 0.8 : 0.6; // onboarding guidance reuses step language; only block near-duplicates
+  if (recentMine.some((l) => similar(l, t) > repeatGate)) return { ...base, text: null };
+  o.lastProactive = Date.now(); o.lastSpokeAt = Date.now(); remember(o, "assistant", t); pushBridge(sess, "ava", t);
+  if (o.done) o.doneAnnounced = true; // celebrated the finish once → go quiet from here
+  return { ...base, text: t };
+}