@cairnvibe/sdk 0.2.13 → 0.3.0

package/dist/verb-executor.js

@@ -11,19 +11,33 @@ exports.executeVerbResponse = executeVerbResponse;
 const core_1 = require("@cairnvibe/core");
 const element_ladder_1 = require("./element-ladder");
 const webmcp_client_1 = require("./webmcp-client");
+// wait_for's own real, bounded retry budget — longer than
+// findElementWithRetry's own default (2 attempts, 300ms apart, ~300ms
+// total), since this verb exists specifically for "I know something
+// async should show up" — a toast, a panel appearing after a click — not
+// the incidental transient-miss recovery findElementWithRetry's default
+// already covers for click/fill/batch steps.
+const WAIT_FOR_ATTEMPTS = 6;
+const WAIT_FOR_DELAY_MS = 500;
 /**
  * Promise wrapper around executeVerbResponse for a continuing verb
- * (click/fill/read/call_tool) — resolves once the real action has actually
- * finished (synchronously for click/fill/read, after a real await for
- * call_tool) with its real observation, instead of the fire-and-forget
- * callback shape every other verb uses. This is what a loop driver awaits
- * before deciding whether to call the model again.
+ * (click/fill/read/call_tool, or now a navigate marked `continueAfter` —
+ * see isTerminalVerb in @cairnvibe/core) — resolves once the real action
+ * has actually finished (synchronously for click/fill/read, after a real
+ * await for call_tool/navigate) with its real observation, instead of the
+ * fire-and-forget callback shape every other verb uses. This is what a
+ * loop driver awaits before deciding whether to call the model again.
+ * `onNavigate` is only needed for that new navigate-as-continuing-step
+ * case — every existing caller that never passes it keeps working
+ * unchanged (a continueAfter navigate with no onNavigate here would just
+ * never actually move the page; real callers always pass one, same as
+ * handleVerb's own options already do for the terminal case).
  */
-function executeToolStep(raw, route, liveElements) {
+function executeToolStep(raw, route, liveElements, onNavigate, onConfirmTool) {
     return new Promise((resolve) => {
         // executeVerbResponse only ever reaches onToolStep for a genuinely
         // continuing verb — callers are only expected to call this after
-        // already confirming (via TERMINAL_VERBS) that the parsed verb is one,
+        // already confirming (via isTerminalVerb) that the parsed verb is one,
         // so this should always fire; a real timeout (not an immediate
         // microtask — call_tool's own real network round trip needs the time)
         // is the safety net for the case where it somehow doesn't, so a loop
@@ -32,6 +46,8 @@ function executeToolStep(raw, route, liveElements) {
         executeVerbResponse(raw, route, {
             onExplain: () => { },
             liveElements,
+            onNavigate,
+            onConfirmTool,
             onToolStep: (result) => {
                 clearTimeout(timer);
                 resolve(result);
@@ -70,11 +86,36 @@ function dispatchVerb(verb, route, options) {
                 options.onExplain(verb.text);
             return;
         }
-        case "navigate":
+        case "navigate": {
+            // Real, live-reported gap this closes: navigate used to ALWAYS end
+            // the turn the instant it fired, even for a compound goal like "buy
+            // earbuds" that needs navigate, then search, then a real report
+            // back — see isTerminalVerb's own doc comment in @cairnvibe/core.
+            // `options.onToolStep` is only ever set by executeToolStep's own
+            // continuing-step wrapper — handleVerb's options never provide it —
+            // so this branch can only run when the caller already confirmed
+            // (via isTerminalVerb) that this navigate was genuinely marked
+            // continueAfter; the defensive `verb.continueAfter` check here is
+            // belt-and-suspenders, not the real gate.
+            if (verb.continueAfter && options.onToolStep) {
+                if (verb.text)
+                    options.onExplain(verb.text);
+                options.onNavigate?.(verb.route);
+                // A client-side route change is itself an async re-render (a new
+                // page's whole DOM mounting) — same real race waitForDomSettle
+                // already closes for fill/click, arguably more likely here. The
+                // NEXT resolveVerb call needs the settled new page's context, not
+                // whatever was on screen the instant router.push was called.
+                void (0, element_ladder_1.waitForDomSettle)(300, 200, 2000).then(() => {
+                    options.onToolStep?.({ verb: "navigate", target: verb.route, ok: true, observation: `Navigated to ${verb.route}.` });
+                });
+                return;
+            }
             options.onNavigate?.(verb.route);
             if (verb.text)
                 options.onExplain(verb.text);
             return;
+        }
         case "do": {
             const allowed = options.registeredActions ?? [];
             if (allowed.includes(verb.action)) {
@@ -149,7 +190,14 @@ function dispatchVerb(verb, route, options) {
             }
             (0, element_ladder_1.highlightElement)(el);
             el.click();
-            options.onToolStep?.({ verb: "click", target: verb.target, ok: true, observation: "Clicked it." });
+            // Real, live-found race this closes — see waitForDomSettle's own doc
+            // comment: a click can trigger an async re-render (a cart count
+            // updating, a filtered list refreshing) that hasn't happened yet the
+            // instant .click() returns. A subsequent read step in the same turn
+            // needs the SETTLED result, not whatever was on screen a moment ago.
+            void (0, element_ladder_1.waitForDomSettle)().then(() => {
+                options.onToolStep?.({ verb: "click", target: verb.target, ok: true, observation: "Clicked it." });
+            });
             return;
         }
         case "fill": {
@@ -167,7 +215,13 @@ function dispatchVerb(verb, route, options) {
                 return;
             }
             (0, element_ladder_1.highlightElement)(el);
-            options.onToolStep?.({ verb: "fill", target: verb.target, ok: true, observation: `Typed "${verb.value}" into it.` });
+            // See the click case's own comment — the exact real bug found live:
+            // typing into a search box, then reading the still-unfiltered
+            // results a moment later and reporting a match the real, since-
+            // filtered page never actually showed.
+            void (0, element_ladder_1.waitForDomSettle)().then(() => {
+                options.onToolStep?.({ verb: "fill", target: verb.target, ok: true, observation: `Typed "${verb.value}" into it.` });
+            });
             return;
         }
         case "read": {
@@ -185,11 +239,99 @@ function dispatchVerb(verb, route, options) {
         case "call_tool": {
             if (verb.text)
                 options.onExplain(verb.text);
-            void (0, webmcp_client_1.executeWebMcpTool)(verb.name, verb.args).then((result) => {
+            void (0, webmcp_client_1.executeWebMcpTool)(verb.name, verb.args, options.onConfirmTool).then((result) => {
                 options.onToolStep?.({ verb: "call_tool", target: verb.name, ok: result.ok, observation: result.observation });
             });
             return;
         }
+        case "drag": {
+            if (verb.text)
+                options.onExplain(verb.text);
+            const from = (0, element_ladder_1.findElement)(verb.target, options.liveElements);
+            const to = from ? (0, element_ladder_1.findElement)(verb.to, options.liveElements) : null;
+            if (!from || !to) {
+                (options.onMiss ?? element_ladder_1.logMiss)({ attempted: from ? verb.to : verb.target, route });
+                options.onToolStep?.({ verb: "drag", target: verb.target, ok: false, observation: from ? "Could not find the drop destination on the page." : "Could not find that element on the page." });
+                return;
+            }
+            (0, element_ladder_1.highlightElement)(from);
+            (0, element_ladder_1.dragElement)(from, to);
+            // Same real re-render race as click/fill — a drop can trigger an
+            // async re-render (a canvas connection line, a reordered list) that
+            // hasn't settled the instant the pointer sequence finishes.
+            void (0, element_ladder_1.waitForDomSettle)().then(() => {
+                options.onToolStep?.({ verb: "drag", target: verb.target, ok: true, observation: `Dragged it to ${verb.to}.` });
+            });
+            return;
+        }
+        case "select": {
+            if (verb.text)
+                options.onExplain(verb.text);
+            const el = (0, element_ladder_1.findElement)(verb.target, options.liveElements);
+            if (!el || !(0, element_ladder_1.selectOption)(el, verb.value)) {
+                (options.onMiss ?? element_ladder_1.logMiss)({ attempted: verb.target, route });
+                options.onToolStep?.({
+                    verb: "select",
+                    target: verb.target,
+                    ok: false,
+                    observation: el ? `Could not find an option matching "${verb.value}".` : "Could not find that element on the page.",
+                });
+                return;
+            }
+            (0, element_ladder_1.highlightElement)(el);
+            void (0, element_ladder_1.waitForDomSettle)().then(() => {
+                options.onToolStep?.({ verb: "select", target: verb.target, ok: true, observation: `Selected "${verb.value}".` });
+            });
+            return;
+        }
+        case "key": {
+            if (verb.text)
+                options.onExplain(verb.text);
+            const el = verb.target ? (0, element_ladder_1.findElement)(verb.target, options.liveElements) : document.activeElement;
+            if (!el) {
+                if (verb.target)
+                    (options.onMiss ?? element_ladder_1.logMiss)({ attempted: verb.target, route });
+                options.onToolStep?.({ verb: "key", target: verb.target, ok: false, observation: "Could not find that element on the page." });
+                return;
+            }
+            (0, element_ladder_1.pressKey)(el, verb.key);
+            void (0, element_ladder_1.waitForDomSettle)().then(() => {
+                options.onToolStep?.({ verb: "key", target: verb.target, ok: true, observation: `Pressed ${verb.key}.` });
+            });
+            return;
+        }
+        case "scroll": {
+            if (verb.text)
+                options.onExplain(verb.text);
+            const el = (0, element_ladder_1.findElement)(verb.target, options.liveElements);
+            if (!el) {
+                (options.onMiss ?? element_ladder_1.logMiss)({ attempted: verb.target, route });
+                options.onToolStep?.({ verb: "scroll", target: verb.target, ok: false, observation: "Could not find that element on the page." });
+                return;
+            }
+            // A real, already-known element (never a coordinate or something
+            // not yet discovered) — highlightElement's own scrollIntoView is
+            // exactly the real repositioning this verb exists for; the glow
+            // also gives the user a visible cue of where the agent just moved.
+            (0, element_ladder_1.highlightElement)(el);
+            void (0, element_ladder_1.waitForDomSettle)().then(() => {
+                options.onToolStep?.({ verb: "scroll", target: verb.target, ok: true, observation: "Scrolled it into view." });
+            });
+            return;
+        }
+        case "wait_for": {
+            if (verb.text)
+                options.onExplain(verb.text);
+            void (0, element_ladder_1.findElementWithRetry)(verb.target, options.liveElements, WAIT_FOR_ATTEMPTS, WAIT_FOR_DELAY_MS).then((el) => {
+                if (!el) {
+                    (options.onMiss ?? element_ladder_1.logMiss)({ attempted: verb.target, route });
+                    options.onToolStep?.({ verb: "wait_for", target: verb.target, ok: false, observation: "It never appeared." });
+                    return;
+                }
+                options.onToolStep?.({ verb: "wait_for", target: verb.target, ok: true, observation: "It appeared." });
+            });
+            return;
+        }
         // Several click/fill/read/call_tool steps in one round trip instead of
         // one each — server.ts's resolveVerb already validated every action's
         // target/name against real state before this ever arrived. Runs in
@@ -212,26 +354,40 @@ async function executeBatchActions(actions, route, options) {
     const steps = [];
     for (const action of actions) {
         const result = await executeOneBatchAction(action, route, options);
-        steps.push(`${action.verb} ${"target" in action ? action.target : action.name}: ${result.observation}`);
+        const label = ("target" in action && action.target) || ("name" in action && action.name) || "(focused element)";
+        steps.push(`${action.verb} ${label}: ${result.observation}`);
         if (!result.ok)
             return { ok: false, observation: steps.join(" | ") };
     }
     return { ok: true, observation: steps.join(" | ") };
 }
+// Phase 3 step 4 — real, bounded, LLM-free retry latitude for the
+// Executor's own lookups (CODA's own point: the Executor stays
+// opinion-free; anything requiring judgment escalates to the Critic,
+// which now genuinely exists as of step 3). Scoped to batch specifically,
+// per the plan's own build order — a batch's later steps are the ones
+// most likely to race a DOM update the batch's OWN earlier step just
+// triggered, which is exactly the "stale re-render" case this recovers
+// from; single-step click/fill/read stay unchanged (findElement, no
+// retry) rather than widening scope beyond what was actually planned.
 async function executeOneBatchAction(action, route, options) {
     switch (action.verb) {
         case "click": {
-            const el = (0, element_ladder_1.findElement)(action.target, options.liveElements);
+            const el = await (0, element_ladder_1.findElementWithRetry)(action.target, options.liveElements);
             if (!el) {
                 (options.onMiss ?? element_ladder_1.logMiss)({ attempted: action.target, route });
                 return { ok: false, observation: "Could not find that element on the page." };
             }
             (0, element_ladder_1.highlightElement)(el);
             el.click();
+            // Same real race as the single-step case (see waitForDomSettle's own
+            // doc comment) — arguably MORE likely here, since a batch's next
+            // step often deliberately reads what THIS step just changed.
+            await (0, element_ladder_1.waitForDomSettle)();
             return { ok: true, observation: "Clicked it." };
         }
         case "fill": {
-            const el = (0, element_ladder_1.findElement)(action.target, options.liveElements);
+            const el = await (0, element_ladder_1.findElementWithRetry)(action.target, options.liveElements);
             if (!el || !(0, element_ladder_1.fillElement)(el, action.value)) {
                 (options.onMiss ?? element_ladder_1.logMiss)({ attempted: action.target, route });
                 return {
@@ -240,10 +396,11 @@ async function executeOneBatchAction(action, route, options) {
                 };
             }
             (0, element_ladder_1.highlightElement)(el);
+            await (0, element_ladder_1.waitForDomSettle)();
             return { ok: true, observation: `Typed "${action.value}" into it.` };
         }
         case "read": {
-            const el = (0, element_ladder_1.findElement)(action.target, options.liveElements);
+            const el = await (0, element_ladder_1.findElementWithRetry)(action.target, options.liveElements);
             if (!el) {
                 (options.onMiss ?? element_ladder_1.logMiss)({ attempted: action.target, route });
                 return { ok: false, observation: "Could not find that element on the page." };
@@ -251,9 +408,60 @@ async function executeOneBatchAction(action, route, options) {
             return { ok: true, observation: (0, element_ladder_1.readElement)(el) };
         }
         case "call_tool": {
-            const result = await (0, webmcp_client_1.executeWebMcpTool)(action.name, action.args);
+            const result = await (0, webmcp_client_1.executeWebMcpTool)(action.name, action.args, options.onConfirmTool);
             return { ok: result.ok, observation: result.observation };
         }
+        case "drag": {
+            const from = await (0, element_ladder_1.findElementWithRetry)(action.target, options.liveElements);
+            const to = from ? await (0, element_ladder_1.findElementWithRetry)(action.to, options.liveElements) : null;
+            if (!from || !to) {
+                (options.onMiss ?? element_ladder_1.logMiss)({ attempted: from ? action.to : action.target, route });
+                return { ok: false, observation: from ? "Could not find the drop destination on the page." : "Could not find that element on the page." };
+            }
+            (0, element_ladder_1.highlightElement)(from);
+            (0, element_ladder_1.dragElement)(from, to);
+            await (0, element_ladder_1.waitForDomSettle)();
+            return { ok: true, observation: `Dragged it to ${action.to}.` };
+        }
+        case "select": {
+            const el = await (0, element_ladder_1.findElementWithRetry)(action.target, options.liveElements);
+            if (!el || !(0, element_ladder_1.selectOption)(el, action.value)) {
+                (options.onMiss ?? element_ladder_1.logMiss)({ attempted: action.target, route });
+                return { ok: false, observation: el ? `Could not find an option matching "${action.value}".` : "Could not find that element on the page." };
+            }
+            (0, element_ladder_1.highlightElement)(el);
+            await (0, element_ladder_1.waitForDomSettle)();
+            return { ok: true, observation: `Selected "${action.value}".` };
+        }
+        case "key": {
+            const el = action.target ? await (0, element_ladder_1.findElementWithRetry)(action.target, options.liveElements) : document.activeElement;
+            if (!el) {
+                if (action.target)
+                    (options.onMiss ?? element_ladder_1.logMiss)({ attempted: action.target, route });
+                return { ok: false, observation: "Could not find that element on the page." };
+            }
+            (0, element_ladder_1.pressKey)(el, action.key);
+            await (0, element_ladder_1.waitForDomSettle)();
+            return { ok: true, observation: `Pressed ${action.key}.` };
+        }
+        case "scroll": {
+            const el = await (0, element_ladder_1.findElementWithRetry)(action.target, options.liveElements);
+            if (!el) {
+                (options.onMiss ?? element_ladder_1.logMiss)({ attempted: action.target, route });
+                return { ok: false, observation: "Could not find that element on the page." };
+            }
+            (0, element_ladder_1.highlightElement)(el);
+            await (0, element_ladder_1.waitForDomSettle)();
+            return { ok: true, observation: "Scrolled it into view." };
+        }
+        case "wait_for": {
+            const el = await (0, element_ladder_1.findElementWithRetry)(action.target, options.liveElements, WAIT_FOR_ATTEMPTS, WAIT_FOR_DELAY_MS);
+            if (!el) {
+                (options.onMiss ?? element_ladder_1.logMiss)({ attempted: action.target, route });
+                return { ok: false, observation: "It never appeared." };
+            }
+            return { ok: true, observation: "It appeared." };
+        }
     }
 }
 /**

package/dist/webmcp-client.d.ts

@@ -6,8 +6,21 @@ export declare function discoverWebMcpTools(): Promise<WebMcpTool[]>;
  * exact request's own discoverWebMcpTools() call), never invented.
  * Returns a plain-text observation for the agent loop to reason about
  * next, the same shape a click/fill/read result already takes.
+ *
+ * Architecture Pillar 6 (the safety layer) — `confirmTool` is only ever
+ * consulted for a tool whose OWN registration declared `riskTier:
+ * "confirm"` (never something the model or this call site can widen) — a
+ * real-world-effect tool (a payment, a delete, anything hard to undo)
+ * that must get a genuine yes from the END USER before it runs, not just
+ * the model's own decision to call it. No `confirmTool` provided (a host
+ * app that hasn't wired up a confirmation UI) is treated as a decline,
+ * never as an implicit yes — the safe default when there's no real way
+ * to ask.
  */
-export declare function executeWebMcpTool(name: string, args: Record<string, unknown> | undefined): Promise<{
+export declare function executeWebMcpTool(name: string, args: Record<string, unknown> | undefined, confirmTool?: (tool: {
+    name: string;
+    description: string;
+}) => Promise<boolean>): Promise<{
     ok: boolean;
     observation: string;
 }>;

package/dist/webmcp-client.js

@@ -34,6 +34,11 @@ async function discoverWebMcpTools() {
             name: String(tool.name),
             description: String(tool.description ?? "").slice(0, MAX_DESCRIPTION_LENGTH),
             inputSchema: tool.inputSchema,
+            // Architecture Pillar 6 — passed through only when the page's own
+            // registration declared a real "confirm" tier; anything else
+            // (absent, or a value that isn't literally "confirm") stays
+            // undefined/"safe" — never invented, never widened by a typo.
+            riskTier: tool.riskTier === "confirm" ? "confirm" : undefined,
         }));
     }
     catch {
@@ -49,8 +54,18 @@ async function discoverWebMcpTools() {
  * exact request's own discoverWebMcpTools() call), never invented.
  * Returns a plain-text observation for the agent loop to reason about
  * next, the same shape a click/fill/read result already takes.
+ *
+ * Architecture Pillar 6 (the safety layer) — `confirmTool` is only ever
+ * consulted for a tool whose OWN registration declared `riskTier:
+ * "confirm"` (never something the model or this call site can widen) — a
+ * real-world-effect tool (a payment, a delete, anything hard to undo)
+ * that must get a genuine yes from the END USER before it runs, not just
+ * the model's own decision to call it. No `confirmTool` provided (a host
+ * app that hasn't wired up a confirmation UI) is treated as a decline,
+ * never as an implicit yes — the safe default when there's no real way
+ * to ask.
  */
-async function executeWebMcpTool(name, args) {
+async function executeWebMcpTool(name, args, confirmTool) {
     const modelContext = getModelContext();
     if (!modelContext?.getTools || !modelContext.executeTool) {
         return { ok: false, observation: "This page no longer has that tool available." };
@@ -60,6 +75,12 @@ async function executeWebMcpTool(name, args) {
         const tool = Array.isArray(tools) ? tools.find((t) => t.name === name) : undefined;
         if (!tool)
             return { ok: false, observation: `No tool named "${name}" is available on this page right now.` };
+        if (tool.riskTier === "confirm") {
+            const confirmed = confirmTool ? await confirmTool({ name: tool.name, description: tool.description ?? "" }) : false;
+            if (!confirmed) {
+                return { ok: false, observation: "This action needs the user's real confirmation before it can run, and it wasn't confirmed." };
+            }
+        }
         const result = await modelContext.executeTool(tool, args ?? {});
         const observation = typeof result === "string" ? result : JSON.stringify(result ?? null);
         return { ok: true, observation: observation.slice(0, 2000) };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cairnvibe/sdk",
-  "version": "0.2.13",
+  "version": "0.3.0",
   "description": "In-app AI copilot — <Copilot/> for React/Next.js, <cairn-widget> for any framework — plus the server handlers and realtime voice relay behind them.",
   "license": "MIT",
   "publishConfig": { "access": "public" },
@@ -23,6 +23,8 @@
     "./server": "./dist/server.js",
     "./dashboard": "./dist/dashboard.js",
     "./dashboard-sqlite": "./dist/dashboard-sqlite.js",
+    "./memory-sqlite": "./dist/memory-sqlite.js",
+    "./skill-store": "./dist/skill-store.js",
     "./transcribe-server": "./dist/transcribe-server.js",
     "./speak-server": "./dist/speak-server.js",
     "./realtime-server": "./dist/realtime-server.js",

package/src/agent-loop.ts

@@ -0,0 +1,222 @@
+// The shared skeleton behind both agent-loop drivers — index.tsx's
+// runTypedAgentLoop (HTTP/typed transport) and realtime-server.ts's
+// finalizeTurn (WebSocket/voice relay) independently re-implemented the
+// exact same "ask, check terminal, execute a continuing step for real,
+// fold the result into working history, ask again, up to a hard
+// iteration cap" shape — a real, live duplication risk (any future fix
+// to one had to be remembered and re-applied to the other by hand).
+// This module is the first step of the Phase 3 multi-agent redesign
+// (see DEVELOPMENT.md/the plan file's "Phase 3" entry): extract exactly
+// that shared shape, with ZERO behavior change, so Planner/Critic
+// wiring in later steps has one real place to attach to instead of two.
+//
+// Deliberately does NOT own transport-specific side effects — sending a
+// message to a client, speaking, committing to a connection's real
+// cross-turn memory, barge-in cancellation timing. Those stay in each
+// transport's own getNextStep/onStep/onStepResult/executeStep closures,
+// and in what the caller does with this function's return value, exactly
+// as before this extraction. Plain TypeScript only (no JSX, no Node
+// built-ins) — imported as raw source by index.tsx's browser bundle AND
+// compiled to dist/ for realtime-server.ts's Node build.
+
+import { isTerminalVerb, type AgentEvent, type CriticVerdict, type HistoryTurn, type VerbResponse } from "@cairnvibe/core";
+
+/** 4 exchanges — matches the cap both original drivers independently used. */
+export const MAX_HISTORY_TURNS = 8;
+
+/**
+ * Architecture Pillar 4 — a cheap, LOCAL signal for "this goal probably
+ * needs more than one real step," checked BEFORE the first step even
+ * runs, so a caller can start the Planner call in PARALLEL with the
+ * first getNextStep instead of only after that first step already came
+ * back non-terminal (the "lazy gate" the plan singles out for
+ * replacement — realtime-server.ts's own onStep used to build planPromise
+ * only once `!terminal && iteration === 0` was already true, one full
+ * model round trip later than it needed to be). Deliberately
+ * conservative, on purpose: a false negative here just falls back to
+ * that same lazy-after-step-1 behavior — unchanged, zero regression —
+ * while a false positive costs one Planner call that would have started
+ * a moment later anyway, never a wrong answer. Genuine UI-pattern-aware
+ * classification (Pillar 2, not built yet) can replace this heuristic
+ * later without changing what calls it. Lives here (not server.ts) so
+ * BOTH transports can use the exact same check: this file is plain,
+ * dependency-free TypeScript imported as raw source by index.tsx's
+ * browser bundle AND compiled for realtime-server.ts's Node build — a
+ * server-only file (server.ts imports the Anthropic/Groq SDKs) can never
+ * be imported from the client widget.
+ */
+const MULTI_STEP_SIGNAL = /\b(then|after that|once (you|it|that|i)|and then|next,|first[,.]? .*\bthen\b)\b/;
+export function looksMultiStep(question: string): boolean {
+  return MULTI_STEP_SIGNAL.test(question.toLowerCase());
+}
+
+export function summarizeVerbForHistory(verb: VerbResponse): string {
+  if ("text" in verb && verb.text) return verb.text;
+  switch (verb.verb) {
+    case "highlight":
+    case "open":
+      return `(highlighted ${verb.target})`;
+    case "navigate":
+      return `(navigated to ${verb.route})`;
+    case "do":
+      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})`;
+    case "drag":
+      return `(dragged ${verb.target} to ${verb.to})`;
+    case "select":
+      return `(selected "${verb.value}" in ${verb.target})`;
+    case "key":
+      return `(pressed ${verb.key}${verb.target ? ` on ${verb.target}` : ""})`;
+    case "batch":
+      return `(${verb.actions.length} steps: ${verb.actions.map((a) => a.verb).join(", ")})`;
+    default:
+      return "(no response)";
+  }
+}
+
+export interface AgentLoopStepEvent {
+  verb: VerbResponse;
+  /** 0-based. */
+  iteration: number;
+  /** True if isTerminalVerb(verb) says this ends the loop right after
+   * this hook returns (TERMINAL_VERBS membership, except a navigate
+   * marked continueAfter — see isTerminalVerb's own doc comment). Lets a
+   * caller act differently for a continuing vs. final step without
+   * re-deriving that check itself. */
+  terminal: boolean;
+}
+
+export interface AgentLoopStepResultEvent {
+  verb: VerbResponse;
+  iteration: number;
+  observation: string | null | undefined;
+}
+
+export interface AgentLoopDeps {
+  /** Resolve the next step given the CURRENT working history. Return
+   * `null` for a response that failed to parse/validate — the HTTP
+   * path's own real case (a raw fetch response might not conform);
+   * realtime's in-process resolveVerb never produces this, since it
+   * always returns a valid VerbResponse itself. A null return ends the
+   * loop immediately with outcome "unparseable". */
+  getNextStep(loopHistory: HistoryTurn[], iteration: number): Promise<VerbResponse | null>;
+  /** Fires immediately after getNextStep resolves, before the terminal/
+   * continuing branch is decided — the real-time side-effect point (send
+   * the verb to a client, trigger an ack on the first continuing step,
+   * check for a superseding barge-in). Returning true aborts the loop
+   * immediately: no further side effects, outcome "aborted". */
+  onStep?(event: AgentLoopStepEvent): boolean | Promise<boolean>;
+  /** Execute a continuing verb (click/fill/read/call_tool/batch) for
+   * real; return its observation text (or null/undefined for "no
+   * result", folded into history as "no result" exactly like both
+   * original drivers already did). */
+  executeStep(verb: VerbResponse, iteration: number): Promise<string | null | undefined>;
+  /** Fires after executeStep resolves, before folding the observation
+   * into working history — a second real-time abort checkpoint (e.g. a
+   * barge-in generation check after awaiting a real tool result, which
+   * can itself take a while). Returning true aborts the loop with
+   * outcome "aborted", discarding this step's observation. */
+  onStepResult?(event: AgentLoopStepResultEvent): boolean | Promise<boolean>;
+  /**
+   * Phase 3 step 3 — a genuinely separate pass over the step's REAL
+   * observation, decoupled from the Executor/model's own self-report
+   * (the direct fix for the diagnosed bug: a batch succeeded and the
+   * model kept looping instead of recognizing it). Fires after
+   * onStepResult/the history fold. Returning a "task_complete" or
+   * "give_up" verdict ends the loop right here — even though the
+   * model's own verb was never a TERMINAL_VERBS member — instead of
+   * asking the model again and hoping it notices. Returning "continue"
+   * (including after the caller's own closure has silently handled a
+   * "replan" by fetching a fresh Plan — driveAgentLoop itself has no
+   * concept of a Plan, only of "keep going or stop") keeps the loop
+   * going exactly as if this hook were absent. Returning null/undefined
+   * behaves the same as "continue" — a caller can choose not to run the
+   * Critic on a particular step without a special no-op verdict shape.
+   */
+  runCritic?(event: AgentLoopStepResultEvent): Promise<CriticVerdict | null | undefined>;
+  /**
+   * Phase 3 step 5 — a pure, fire-and-forget event consumer for a
+   * Talker-style narration layer ("Revisable by Design"'s pattern):
+   * never awaited, never able to affect control flow. driveAgentLoop
+   * itself emits "act" (right after a step's onStep/abort check passes —
+   * only for a verb that's actually going to execute, never a discarded
+   * one) and "obs" (right after onStepResult's own abort check passes),
+   * since it already has that data at exactly those points. A caller's
+   * own onStep/runCritic closures can call this SAME callback directly —
+   * it's just a plain reference they already have via the deps object
+   * they constructed — to emit "thk" (Critic reasoning) or "inj"
+   * (injected filler narration, e.g. a Talker ack phrase) events too;
+   * driveAgentLoop has no opinion on those.
+   */
+  onEvent?(event: AgentEvent): void;
+  /** Defaults to 6 — a hard cap, not a target, matching both original drivers. */
+  maxIterations?: number;
+}
+
+export type AgentLoopOutcome =
+  | { outcome: "terminal"; finalVerb: VerbResponse; workingHistory: HistoryTurn[] }
+  /** The Critic independently confirmed the (last) task's doneContract
+   * is satisfied — the real fix for the diagnosed bug. The caller
+   * synthesizes its own terminal-shaped response (e.g. `{verb: "explain",
+   * text: verdict.reasoning}`) from `verdict`, same as it would for a
+   * model-produced terminal verb. */
+  | { outcome: "critic-complete"; verdict: CriticVerdict; workingHistory: HistoryTurn[] }
+  /** The Critic (or the harness's own stall-count fail-safe, inside the
+   * caller's runCritic closure) decided continuing wouldn't help. */
+  | { outcome: "critic-give-up"; verdict: CriticVerdict; workingHistory: HistoryTurn[] }
+  | { outcome: "unparseable"; workingHistory: HistoryTurn[] }
+  | { outcome: "gave-up"; workingHistory: HistoryTurn[] }
+  | { outcome: "aborted"; workingHistory: HistoryTurn[] };
+
+export async function driveAgentLoop(initialHistory: HistoryTurn[], deps: AgentLoopDeps): Promise<AgentLoopOutcome> {
+  const maxIterations = deps.maxIterations ?? 6;
+  let loopHistory = initialHistory;
+
+  for (let i = 0; i < maxIterations; i++) {
+    const verb = await deps.getNextStep(loopHistory, i);
+    if (verb === null) return { outcome: "unparseable", workingHistory: loopHistory };
+
+    const terminal = isTerminalVerb(verb);
+    if (deps.onStep) {
+      const abort = await deps.onStep({ verb, iteration: i, terminal });
+      if (abort) return { outcome: "aborted", workingHistory: loopHistory };
+    }
+    deps.onEvent?.({ type: "act", verb, at: Date.now() });
+
+    if (terminal) {
+      return { outcome: "terminal", finalVerb: verb, workingHistory: loopHistory };
+    }
+
+    const observation = await deps.executeStep(verb, i);
+    if (deps.onStepResult) {
+      const abort = await deps.onStepResult({ verb, iteration: i, observation });
+      if (abort) return { outcome: "aborted", workingHistory: loopHistory };
+    }
+    deps.onEvent?.({ type: "obs", observation: observation ?? "no result", ok: observation !== null && observation !== undefined, at: Date.now() });
+
+    loopHistory = [
+      ...loopHistory,
+      { role: "assistant" as const, text: `${summarizeVerbForHistory(verb)}. Result: ${observation ?? "no result"}` },
+    ].slice(-MAX_HISTORY_TURNS);
+
+    if (deps.runCritic) {
+      const verdict = await deps.runCritic({ verb, iteration: i, observation });
+      if (verdict?.verdict === "task_complete") return { outcome: "critic-complete", verdict, workingHistory: loopHistory };
+      if (verdict?.verdict === "give_up") return { outcome: "critic-give-up", verdict, workingHistory: loopHistory };
+      // "continue", "replan" (already handled inside the caller's own
+      // runCritic closure — see this field's own doc comment), or no
+      // verdict at all: fall through and keep looping, unchanged.
+    }
+  }
+
+  return { outcome: "gave-up", workingHistory: loopHistory };
+}