@cairnvibe/sdk 0.2.6 → 0.2.8

package/src/index.tsx

@@ -3,6 +3,8 @@
 import { useEffect, useRef, useState } from "react";
 import { usePathname, useRouter } from "next/navigation";
 import {
+  ChevronDown,
+  ChevronUp,
   Loader2,
   Mic,
   MicOff,
@@ -14,10 +16,12 @@ import {
   VolumeX,
   X,
 } from "lucide-react";
-import type { HistoryTurn as HistoryEntry, TourStep } from "@cairnvibe/core";
+import { TERMINAL_VERBS, safeParseVerbResponse, type HistoryTurn as HistoryEntry, type TourStep } from "@cairnvibe/core";
 import { collectVisible } from "./context-collector";
 import { findElement, highlightElement, logMiss, type MissContext } from "./element-ladder";
-import { executeVerbResponse } from "./verb-executor";
+import { createLiveElementRegistry } from "./runtime-scan";
+import { discoverWebMcpTools } from "./webmcp-client";
+import { executeToolStep, executeVerbResponse } from "./verb-executor";
 
 export interface CopilotProps {
   /** Reserved for a future client-side manifest fetch. Not required — the server handler owns the manifest. */
@@ -63,8 +67,24 @@ export function Copilot({
   persona = "Cairn",
 }: CopilotProps) {
   const pathname = usePathname() ?? "/";
+  // Mirrors `pathname` for use inside long-lived closures (a realtime
+  // session's handlers are all created once, when the connection opens —
+  // same staleness reason runTour tracks its own `currentRoute` locally
+  // rather than trusting its closure's `pathname` after a mid-tour
+  // navigation).
+  const pathnameRef = useRef(pathname);
+  useEffect(() => {
+    pathnameRef.current = pathname;
+    void sendFreshContext(); // no-op if no realtime session is open
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [pathname]);
   const router = useRouter();
   const [open, setOpen] = useState(false);
+  // Collapsed by default so the panel only ever shows the current exchange
+  // — the full archived transcript (built up over a long conversation)
+  // stays out of the way behind an explicit toggle instead of always being
+  // visible inline, which made the panel grow uncomfortably tall.
+  const [historyExpanded, setHistoryExpanded] = useState(false);
   const [question, setQuestion] = useState("");
   const [answer, setAnswer] = useState<string | null>(null);
   const [status, setStatus] = useState<Status>("idle");
@@ -118,6 +138,20 @@ export function Copilot({
   // already stateful).
   const historyRef = useRef<HistoryEntry[]>([]);
 
+  // A background scanner that keeps a live inventory of what's actually
+  // clickable on screen right now (runtime-scan.ts) — running continuously
+  // via a MutationObserver so there's never a pause to "go look at the
+  // page" right when a verb needs to click something. `liveMapRef` freezes
+  // one snapshot of it per turn (set alongside every context/question send,
+  // below) so a background rescan landing mid-flight can't shift what an id
+  // resolves to between when a request went out and its response came back.
+  const liveRegistryRef = useRef(createLiveElementRegistry());
+  const liveMapRef = useRef<Map<string, HTMLElement>>(new Map());
+  useEffect(() => {
+    liveRegistryRef.current.start();
+    return () => liveRegistryRef.current.stop();
+  }, []);
+
   const mediaRecorderRef = useRef<MediaRecorder | null>(null);
   const audioChunksRef = useRef<Blob[]>([]);
   const transcribeInFlightRef = useRef(false);
@@ -213,6 +247,36 @@ export function Copilot({
     setStatus(next);
   }
 
+  /**
+   * Refreshes the server's picture of route/visible/liveElements over an
+   * already-open realtime connection. Beyond the initial connect, called
+   * on every route change and whenever the mic is about to start listening
+   * again — a real, pre-existing gap this closes as a side effect: the
+   * server's context previously updated only once, at connection open, so
+   * navigating mid-call (via a "navigate" verb, or the user clicking
+   * around) left the server answering every later turn as if the user were
+   * still on the original page. Reads pathnameRef, not the closure's
+   * `pathname`, so it's correct even called from a handler created once at
+   * connection-open time.
+   */
+  async function sendFreshContext() {
+    const ws = rtSocketRef.current;
+    if (!ws || ws.readyState !== WebSocket.OPEN) return;
+    const liveScan = liveRegistryRef.current.getSnapshot();
+    liveMapRef.current = liveScan.byId;
+    const webMcpTools = await discoverWebMcpTools();
+    if (ws.readyState !== WebSocket.OPEN) return; // may have closed while awaiting discovery
+    ws.send(
+      JSON.stringify({
+        type: "context",
+        route: pathnameRef.current,
+        visible: collectVisible(),
+        liveElements: liveScan.elements,
+        webMcpTools,
+      }),
+    );
+  }
+
   function reportMiss(context: MissContext) {
     logMiss(context);
     if (reportMissesEndpoint) {
@@ -235,6 +299,7 @@ export function Copilot({
       onDo,
       onTour: (steps) => void runTour(steps),
       registeredActions,
+      liveElements: liveMapRef.current,
     });
   }
 
@@ -297,9 +362,23 @@ export function Copilot({
         }
 
         if (step.target) {
-          const el = findElement(step.target);
-          if (el) highlightElement(el);
-          else reportMiss({ attempted: step.target, route: currentRoute });
+          // A fresh scan, not the tour's starting liveMapRef snapshot — a
+          // step after a mid-tour navigation targets elements on a page
+          // that didn't exist when the tour began.
+          const liveScan = liveRegistryRef.current.getSnapshot();
+          const el = findElement(step.target, liveScan.byId);
+          if (el) {
+            highlightElement(el);
+            if (step.click) {
+              el.click();
+              // Give whatever the click reveals (a detail view, an expanded
+              // row) a moment to actually render before narrating it.
+              await new Promise((resolve) => setTimeout(resolve, 400));
+              if (tourGenerationRef.current !== myGeneration) return;
+            }
+          } else {
+            reportMiss({ attempted: step.target, route: currentRoute });
+          }
         }
 
         if (wasRealtimeListening && rtSocketRef.current?.readyState === WebSocket.OPEN) {
@@ -337,27 +416,85 @@ export function Copilot({
     setLastQuestion(q);
     setQuestion("");
     try {
+      await runTypedAgentLoop(q);
+    } catch {
+      setAnswer("Something went wrong reaching the help service — try again in a moment.");
+    } finally {
+      setStatus("idle");
+    }
+  }
+
+  const MAX_LOOP_ITERATIONS = 6; // a hard cap, not a target — see runTypedAgentLoop
+
+  /**
+   * Drives the agent loop over the stateless HTTP path: ask the server,
+   * and if it comes back with a continuing step (click/fill/read/
+   * call_tool — TERMINAL_VERBS in @cairnvibe/core says which verbs end a
+   * turn), execute that step for real, fold the real result into this
+   * turn's own working history, and ask again — repeat until a terminal
+   * verb or the iteration cap, instead of the old one-call-one-answer
+   * shape. `question` stays the original ask on every call; only
+   * `history` grows with each step's real trace, so the model always
+   * still knows what it was actually asked. `historyRef` (the
+   * conversation's real memory) is only ever committed once, at the end —
+   * a turn that hits the cap mid-loop doesn't leave partial noise in it.
+   */
+  async function runTypedAgentLoop(q: string): Promise<void> {
+    let loopHistory = historyRef.current;
+    const webMcpTools = await discoverWebMcpTools();
+
+    for (let i = 0; i < MAX_LOOP_ITERATIONS; i++) {
+      const liveScan = liveRegistryRef.current.getSnapshot();
+      liveMapRef.current = liveScan.byId;
       const res = await fetch(endpoint, {
         method: "POST",
         headers: { "content-type": "application/json" },
-        body: JSON.stringify({ route: pathname, question: q, visible: collectVisible(), history: historyRef.current }),
+        body: JSON.stringify({
+          route: pathname,
+          question: q,
+          visible: collectVisible(),
+          history: loopHistory,
+          liveElements: liveScan.elements,
+          webMcpTools,
+        }),
       });
       const data = await res.json().catch(() => null);
-      handleVerb(data);
-      // Unlike the realtime relay (one persistent connection, memory lives
-      // server-side), each of these POSTs is stateless — the widget itself
-      // is what remembers, and resends it above so the model has context
-      // for "the first one" / "do that instead" on the next question.
-      historyRef.current = [
-        ...historyRef.current,
-        { role: "user", text: q } satisfies HistoryEntry,
-        { role: "assistant", text: summarizeVerbForHistory(data) } satisfies HistoryEntry,
+      const parsed = safeParseVerbResponse(data);
+
+      if (!parsed || TERMINAL_VERBS.has(parsed.verb)) {
+        handleVerb(data);
+        // Unlike the realtime relay (one persistent connection, memory
+        // lives server-side), each of these POSTs is stateless — the
+        // widget itself is what remembers, and resends it above so the
+        // model has context for "the first one" / "do that instead" on
+        // the next question.
+        historyRef.current = [
+          ...loopHistory,
+          { role: "user", text: q } satisfies HistoryEntry,
+          { role: "assistant", text: summarizeVerbForHistory(data) } satisfies HistoryEntry,
+        ].slice(-MAX_HISTORY_TURNS);
+        return;
+      }
+
+      // A continuing step — show it happening, execute it for real, and
+      // go around again with the real result instead of ending the turn.
+      setAnswer(summarizeVerbForHistory(data));
+      const stepResult = await executeToolStep(data, pathname, liveMapRef.current);
+      loopHistory = [
+        ...loopHistory,
+        {
+          role: "assistant",
+          text: `${summarizeVerbForHistory(data)}. Result: ${stepResult?.observation ?? "no result"}`,
+        } satisfies HistoryEntry,
       ].slice(-MAX_HISTORY_TURNS);
-    } catch {
-      setAnswer("Something went wrong reaching the help service — try again in a moment.");
-    } finally {
-      setStatus("idle");
     }
+
+    setAnswer("I wasn't able to finish that — try asking again or breaking it into smaller steps.");
+    historyRef.current = [
+      ...loopHistory,
+      { role: "user", text: q } satisfies HistoryEntry,
+      { role: "assistant", text: "(gave up after too many steps)" } satisfies HistoryEntry,
+    ].slice(-MAX_HISTORY_TURNS);
   }
 
   /**
@@ -614,6 +751,7 @@ export function Copilot({
         }
         setRtStatus("rt-listening");
         setCaption("");
+        void sendFreshContext(); // refresh before the user starts talking again, not after
       }
 
       function disarmThinkingWatchdog() {
@@ -674,7 +812,7 @@ export function Copilot({
       }
 
       ws.onopen = () => {
-        ws.send(JSON.stringify({ type: "context", route: pathname, visible: collectVisible() }));
+        sendFreshContext();
         setRtStatus("rt-listening");
         rtStartingRef.current = false;
       };
@@ -690,6 +828,25 @@ export function Copilot({
           setRtStatus("rt-thinking");
           armThinkingWatchdog();
         } else if (msg.type === "verb") {
+          const parsedStep = safeParseVerbResponse(msg.verb);
+          if (parsedStep && !TERMINAL_VERBS.has(parsedStep.verb)) {
+            // A continuing agent-loop step (click/fill/read/call_tool) —
+            // the turn isn't over: execute it for real and report the
+            // result back so the server can decide the next step, instead
+            // of treating this like a normal answer (no
+            // disarmThinkingWatchdog/handleVerb — those are for when a
+            // turn actually ends). Shown visually so a multi-step turn
+            // reads as visible progress, not a silent pause; never spoken
+            // — the server's loop stays quiet between steps on purpose,
+            // to keep it fast.
+            setAnswer(summarizeVerbForHistory(msg.verb));
+            void executeToolStep(msg.verb, pathnameRef.current, liveMapRef.current).then((result) => {
+              if (ws.readyState === WebSocket.OPEN) {
+                ws.send(JSON.stringify({ type: "tool_result", observation: result?.observation ?? "no result" }));
+              }
+            });
+            return;
+          }
           disarmThinkingWatchdog();
           handleVerb(msg.verb);
         } else if (msg.type === "speaking_start") {
@@ -843,14 +1000,26 @@ export function Copilot({
 
           {(transcript.length > 0 || userCaption || answer || busy) && (
             <div className="cairn-stack">
-              {transcript.map((entry) => (
-                <div
-                  className={entry.role === "user" ? "cairn-bubble cairn-bubble-user cairn-bubble-past" : "cairn-bubble cairn-bubble-agent cairn-bubble-past"}
-                  key={entry.id}
+              {transcript.length > 0 && (
+                <button
+                  type="button"
+                  className="cairn-history-toggle"
+                  onClick={() => setHistoryExpanded((v) => !v)}
+                  aria-expanded={historyExpanded}
                 >
-                  {entry.role === "agent" ? <span className="cairn-bubble-text">{entry.text}</span> : entry.text}
-                </div>
-              ))}
+                  {historyExpanded ? <ChevronUp size={12} /> : <ChevronDown size={12} />}
+                  {historyExpanded ? "Hide earlier" : `${transcript.length} earlier`}
+                </button>
+              )}
+              {historyExpanded &&
+                transcript.map((entry) => (
+                  <div
+                    className={entry.role === "user" ? "cairn-bubble cairn-bubble-user cairn-bubble-past" : "cairn-bubble cairn-bubble-agent cairn-bubble-past"}
+                    key={entry.id}
+                  >
+                    {entry.role === "agent" ? <span className="cairn-bubble-text">{entry.text}</span> : entry.text}
+                  </div>
+                ))}
               {userCaption && (
                 <div className="cairn-bubble cairn-bubble-user" key={`u-${userCaption}`}>
                   {userCaption}
@@ -981,6 +1150,14 @@ function summarizeVerbForHistory(raw: unknown): string {
       return `(ran ${String(v.action)}${v.target ? ` on ${String(v.target)}` : ""})`;
     case "tour":
       return Array.isArray(v.steps) ? v.steps.map((s: { text?: string }) => s.text ?? "").join(" ") : "(tour)";
+    case "click":
+      return `(clicked ${String(v.target)})`;
+    case "fill":
+      return `(typed "${String(v.value)}" into ${String(v.target)})`;
+    case "read":
+      return `(read ${String(v.target)})`;
+    case "call_tool":
+      return `(called ${String(v.name)})`;
     default:
       return "(no response)";
   }
@@ -1220,6 +1397,26 @@ const COPILOT_STYLES = `
   text-transform: uppercase;
   color: rgba(11, 13, 18, 0.48);
 }
+.cairn-history-toggle {
+  align-self: center;
+  display: inline-flex;
+  align-items: center;
+  gap: 3px;
+  border: none;
+  background: none;
+  padding: 2px 8px;
+  font: inherit;
+  font-size: 11px;
+  font-weight: 600;
+  color: rgba(11, 13, 18, 0.4);
+  cursor: pointer;
+  border-radius: 999px;
+  transition: background 0.15s ease, color 0.15s ease;
+}
+.cairn-history-toggle:hover {
+  background: rgba(11, 13, 18, 0.05);
+  color: rgba(11, 13, 18, 0.6);
+}
 .cairn-thinking {
   display: inline-flex;
   gap: 4px;

package/src/realtime-server.ts

@@ -27,7 +27,7 @@
 
 import http from "node:http";
 import { WebSocket, WebSocketServer } from "ws";
-import type { HistoryTurn, Manifest, VerbResponse } from "@cairnvibe/core";
+import { TERMINAL_VERBS, type HistoryTurn, type LiveElement, type Manifest, type VerbResponse, type WebMcpTool } from "@cairnvibe/core";
 import { buildSystemPrompt, createVerbLLM, resolveVerb, type CapabilityTier, type CreateCopilotHandlerOptions } from "./server";
 import { DeepgramSpeakStream } from "./tts-stream";
 
@@ -107,14 +107,29 @@ export interface ConnectionDeps {
 }
 
 const MAX_HISTORY_TURNS = 8; // 4 exchanges — enough for "the first one"/"do that instead" without growing the prompt unbounded over a long call
+const MAX_LOOP_ITERATIONS = 6; // a hard cap on one turn's agent-loop steps, not a target — see finalizeTurn
 
 async function handleConnection(client: WebSocket, deps: ConnectionDeps): Promise<void> {
-  let context = { route: "/", visible: [] as string[] };
+  // liveElements/webMcpTools refresh on every "context" resend (the client
+  // sends one on route changes and each time it's about to start listening
+  // again), so a live scan from several turns ago never lingers into a
+  // later one.
+  let context: { route: string; visible: string[]; liveElements: LiveElement[]; webMcpTools: WebMcpTool[] } = {
+    route: "/",
+    visible: [],
+    liveElements: [],
+    webMcpTools: [],
+  };
   // Unlike the stateless HTTP path (which needs the client to resend
   // history every request), a realtime connection is already stateful —
   // one WebSocket per call — so this is accumulated here directly rather
   // than round-tripped through the client.
   const history: HistoryTurn[] = [];
+  // Resolves the agent loop's in-flight waitForToolResult() call once the
+  // client reports back what a click/fill/read/call_tool step actually
+  // did — same "a mutable pending-callback slot, resolved when the right
+  // message arrives" pattern onCurrentTurnFlushed already uses below.
+  let pendingToolResultResolve: ((observation: string) => void) | null = null;
 
   const dgUrl =
     `${DEEPGRAM_LIVE_URL}?model=${encodeURIComponent(deps.sttModel)}` +
@@ -202,13 +217,33 @@ async function handleConnection(client: WebSocket, deps: ConnectionDeps): Promis
     });
   }
 
+  /**
+   * Pauses the agent loop (finalizeTurn, below) until the client reports
+   * back the real result of a click/fill/read/call_tool step it just sent
+   * out — the server can't execute a DOM action itself, so every
+   * continuing step needs a real round trip to the browser and back. A
+   * real timeout, not a hang: a client that never answers (closed tab,
+   * dropped connection) can't leave a turn stuck forever.
+   */
+  function waitForToolResult(): Promise<string> {
+    return new Promise((resolve) => {
+      pendingToolResultResolve = resolve;
+      setTimeout(() => {
+        if (pendingToolResultResolve === resolve) {
+          pendingToolResultResolve = null;
+          resolve("(no result — timed out waiting for the browser)");
+        }
+      }, 15000);
+    });
+  }
+
   // Accumulates Deepgram "Results" transcript segments across one utterance
   // — see handleDeepgramMessage for why this can't just react to every
   // is_final.
   const turnState = { buffer: "" };
 
   dg.on("message", (data) => {
-    void handleDeepgramMessage(data.toString(), client, deps, () => context, speakStreamed, history, turnState, () => generation);
+    void handleDeepgramMessage(data.toString(), client, deps, () => context, speakStreamed, history, turnState, () => generation, waitForToolResult);
   });
 
   dg.on("error", (err) => {
@@ -226,7 +261,18 @@ async function handleConnection(client: WebSocket, deps: ConnectionDeps): Promis
     try {
       const msg = JSON.parse(data.toString());
       if (msg.type === "context") {
-        context = { route: String(msg.route ?? "/"), visible: Array.isArray(msg.visible) ? msg.visible : [] };
+        context = {
+          route: String(msg.route ?? "/"),
+          visible: Array.isArray(msg.visible) ? msg.visible : [],
+          liveElements: parseLiveElements(msg.liveElements),
+          webMcpTools: parseWebMcpTools(msg.webMcpTools),
+        };
+      } else if (msg.type === "tool_result" && typeof msg.observation === "string") {
+        // The client finished executing a click/fill/read/call_tool step
+        // the agent loop sent it — this is what finalizeTurn's
+        // waitForToolResult() below is paused on.
+        pendingToolResultResolve?.(msg.observation);
+        pendingToolResultResolve = null;
       } else if (msg.type === "end") {
         client.close();
       } else if (msg.type === "barge_in") {
@@ -272,11 +318,12 @@ export async function handleDeepgramMessage(
   raw: string,
   client: WebSocket,
   deps: ConnectionDeps,
-  getContext: () => { route: string; visible: string[] },
+  getContext: () => { route: string; visible: string[]; liveElements: LiveElement[]; webMcpTools: WebMcpTool[] },
   speakStreamed: (text: string) => Promise<void>,
   history: HistoryTurn[],
   turnState: { buffer: string },
   getGeneration: () => number,
+  waitForToolResult: () => Promise<string>,
 ): Promise<void> {
   let msg: any;
   try {
@@ -290,7 +337,7 @@ export async function handleDeepgramMessage(
     // after utterance_end_ms of silence — a safety net for the rare case a
     // Results message never carries speech_final:true, so a turn can't get
     // permanently stuck with real transcript sitting in the buffer forever.
-    if (turnState.buffer) await finalizeTurn(turnState, client, deps, getContext, speakStreamed, history, getGeneration);
+    if (turnState.buffer) await finalizeTurn(turnState, client, deps, getContext, speakStreamed, history, getGeneration, waitForToolResult);
     return;
   }
 
@@ -319,7 +366,7 @@ export async function handleDeepgramMessage(
     return;
   }
 
-  await finalizeTurn(turnState, client, deps, getContext, speakStreamed, history, getGeneration);
+  await finalizeTurn(turnState, client, deps, getContext, speakStreamed, history, getGeneration, waitForToolResult);
 }
 
 /**
@@ -338,49 +385,88 @@ export async function handleDeepgramMessage(
  * happens while this turn is still "thinking" bumps the generation, and
  * without this check the now-stale response would still land on the
  * client after the user had already moved on to a new question.
+ *
+ * A continuing verb (click/fill/read/call_tool — TERMINAL_VERBS says which
+ * ones aren't) doesn't end the turn here: the server can't execute a DOM
+ * action itself, so it sends the step to the client, awaits its real
+ * result over waitForToolResult(), folds that into a *local* working copy
+ * of history, and calls resolveVerb again — repeat up to
+ * MAX_LOOP_ITERATIONS. The connection's real `history` only gets the
+ * user's real question plus the turn's final answer, committed once at
+ * the end — a turn that hits the cap mid-loop doesn't leave partial tool
+ * noise in the conversation's real memory, same discipline the HTTP
+ * path's runTypedAgentLoop (index.tsx) follows.
  */
 async function finalizeTurn(
   turnState: { buffer: string },
   client: WebSocket,
   deps: ConnectionDeps,
-  getContext: () => { route: string; visible: string[] },
+  getContext: () => { route: string; visible: string[]; liveElements: LiveElement[]; webMcpTools: WebMcpTool[] },
   speakStreamed: (text: string) => Promise<void>,
   history: HistoryTurn[],
   getGeneration: () => number,
+  waitForToolResult: () => Promise<string>,
 ): Promise<void> {
   const transcript = turnState.buffer;
   turnState.buffer = "";
   const myGeneration = getGeneration();
   safeSend(client, { type: "final", text: transcript });
 
-  try {
-    const { route, visible } = getContext();
-    const verb = await resolveVerb(deps.llm, deps.systemPrompt, deps.manifest, deps.registeredActions, deps.capability, {
-      route,
-      question: transcript,
-      visible,
-      history,
-    });
+  let loopHistory = history;
 
-    if (myGeneration !== getGeneration()) return; // superseded by a barge-in while this turn was resolving
+  try {
+    for (let i = 0; i < MAX_LOOP_ITERATIONS; i++) {
+      const { route, visible, liveElements, webMcpTools } = getContext();
+      const verb = await resolveVerb(deps.llm, deps.systemPrompt, deps.manifest, deps.registeredActions, deps.capability, {
+        route,
+        question: transcript,
+        visible,
+        liveElements,
+        webMcpTools,
+        history: loopHistory,
+      });
 
-    // Sent immediately — before speech synthesis even starts — so
-    // highlight/navigate/do execute in the browser right away instead of
-    // waiting on audio. The agent visibly acts while it's still about to
-    // speak, not after.
-    safeSend(client, { type: "verb", verb });
+      if (myGeneration !== getGeneration()) return; // superseded by a barge-in while this turn was resolving
+
+      // Sent immediately — before speech synthesis even starts — so
+      // highlight/navigate/do execute in the browser right away instead of
+      // waiting on audio. The agent visibly acts while it's still about to
+      // speak, not after.
+      safeSend(client, { type: "verb", verb });
+
+      if (!TERMINAL_VERBS.has(verb.verb)) {
+        // A continuing step — no speech for it (keeps the loop fast;
+        // the client still shows it visually) — wait for its real result
+        // and go around again instead of ending the turn.
+        const observation = await waitForToolResult();
+        if (myGeneration !== getGeneration()) return;
+        loopHistory = [
+          ...loopHistory,
+          { role: "assistant" as const, text: `${summarizeVerbForHistory(verb)}. Result: ${observation}` },
+        ].slice(-MAX_HISTORY_TURNS);
+        continue;
+      }
 
-    history.push({ role: "user", text: transcript }, { role: "assistant", text: summarizeVerbForHistory(verb) });
-    history.splice(0, Math.max(0, history.length - MAX_HISTORY_TURNS));
+      history.push({ role: "user", text: transcript }, { role: "assistant", text: summarizeVerbForHistory(verb) });
+      history.splice(0, Math.max(0, history.length - MAX_HISTORY_TURNS));
 
-    // A verb with no spoken text (highlight/navigate/do often have none)
-    // still needs to unstick the client's "thinking" state and let the mic
-    // resume — turn_complete covers that with no audio path involved.
-    if ("text" in verb && verb.text) {
-      await speakStreamed(verb.text);
-    } else {
-      safeSend(client, { type: "turn_complete" });
+      // A verb with no spoken text (highlight/navigate/do often have none)
+      // still needs to unstick the client's "thinking" state and let the mic
+      // resume — turn_complete covers that with no audio path involved.
+      if ("text" in verb && verb.text) {
+        await speakStreamed(verb.text);
+      } else {
+        safeSend(client, { type: "turn_complete" });
+      }
+      return;
     }
+
+    // Iteration cap hit with no terminal verb — degrade honestly instead
+    // of leaving the client waiting forever.
+    history.push({ role: "user", text: transcript }, { role: "assistant", text: "(gave up after too many steps)" });
+    history.splice(0, Math.max(0, history.length - MAX_HISTORY_TURNS));
+    safeSend(client, { type: "verb", verb: { verb: "explain", text: "I wasn't able to finish that — try asking again or breaking it into smaller steps." } });
+    await speakStreamed("I wasn't able to finish that — try asking again or breaking it into smaller steps.");
   } catch (err) {
     console.error("[cairn realtime] failed to resolve/speak this turn:", err);
     if (myGeneration === getGeneration()) {
@@ -395,6 +481,42 @@ function safeSend(client: WebSocket, message: ServerMessage): void {
   client.send(JSON.stringify(message));
 }
 
+/** Defensive parse for the client's self-reported live DOM scan — same
+ * untrusted-input treatment `visible` already gets on this control-message
+ * path (no CopilotRequestSchema here, unlike the HTTP handler), just
+ * shaped-checked so a malformed entry can't reach the LLM prompt oddly. */
+function parseLiveElements(raw: unknown): LiveElement[] {
+  if (!Array.isArray(raw)) return [];
+  const elements: LiveElement[] = [];
+  for (const entry of raw) {
+    if (
+      entry &&
+      typeof entry === "object" &&
+      typeof (entry as any).id === "string" &&
+      typeof (entry as any).role === "string" &&
+      typeof (entry as any).label === "string"
+    ) {
+      elements.push({ id: (entry as any).id, role: (entry as any).role, label: (entry as any).label });
+    }
+    if (elements.length >= 60) break;
+  }
+  return elements;
+}
+
+/** Same defensive shape-check as parseLiveElements, for the client's
+ * self-reported WebMCP tool list. */
+function parseWebMcpTools(raw: unknown): WebMcpTool[] {
+  if (!Array.isArray(raw)) return [];
+  const tools: WebMcpTool[] = [];
+  for (const entry of raw) {
+    if (entry && typeof entry === "object" && typeof (entry as any).name === "string" && typeof (entry as any).description === "string") {
+      tools.push({ name: (entry as any).name, description: (entry as any).description, inputSchema: (entry as any).inputSchema });
+    }
+    if (tools.length >= 30) break;
+  }
+  return tools;
+}
+
 /** A short text form of any verb for the history log — not shown to the
  * user, just fed back to the model on later turns so it knows what it
  * already did/said. */
@@ -410,6 +532,14 @@ function summarizeVerbForHistory(verb: VerbResponse): string {
       return `(ran ${verb.action}${verb.target ? ` on ${verb.target}` : ""})`;
     case "tour":
       return verb.steps.map((s) => s.text).join(" ");
+    case "click":
+      return `(clicked ${verb.target})`;
+    case "fill":
+      return `(typed "${verb.value}" into ${verb.target})`;
+    case "read":
+      return `(read ${verb.target})`;
+    case "call_tool":
+      return `(called ${verb.name})`;
     default:
       return "(no response)";
   }