@cairnvibe/sdk 0.2.13 → 0.3.0

package/src/skill-store.ts

@@ -0,0 +1,88 @@
+// Architecture Pillar 3 (Skill half) — real, persistent storage for
+// self-authored Skills (packages/core/src/skills.ts), scoped by whatever
+// opaque `scopeId` string the caller passes — same discipline as
+// memory-sqlite.ts's own MemoryStore, but for a DIFFERENT axis of scope on
+// purpose: a MemoryStore scopeId is per-user/session (today's usage,
+// unchanged), while a SkillStore scopeId is meant to be per-DEPLOYMENT
+// (the whole app, shared across every user who talks to it — the same
+// scope ui-manifest.json itself already has). Nothing in this file
+// enforces that distinction; it's the caller's own choice of scopeId that
+// makes it true, exactly as MemoryStore's own doc comment already
+// establishes for its scope.
+//
+// A dedicated table (not reusing memory-sqlite's facts table with a
+// JSON-blob value) specifically so `listSkillSummaries` can select just
+// id/name/description/pattern at the SQL level — the real mechanism
+// behind "progressive disclosure stays cheap": a deployment with many
+// learned Skills never pays to load every Skill's full instructions just
+// to list what's available, only the one a caller actually requests via
+// getSkill.
+
+import fs from "node:fs";
+import path from "node:path";
+import Database from "better-sqlite3";
+import type { Skill, SkillSummary } from "@cairnvibe/core";
+
+const SKILLS_TABLE = "cairn_skills";
+
+export interface SkillStore {
+  /** Upserts by (scopeId, id) — a re-learned Skill for the same real capability replaces the old one, never accumulates duplicates. */
+  saveSkill(scopeId: string, skill: Skill): void;
+  /** Cheap: id/name/description/pattern only, never the full instructions — see this file's own doc comment. */
+  listSkillSummaries(scopeId: string): SkillSummary[];
+  /** The one Skill a caller actually matched — full instructions included. Null if this scope has no Skill with that id. */
+  getSkill(scopeId: string, id: string): Skill | null;
+}
+
+/**
+ * @param target Either a file path (opened/created, parent dir made if
+ * needed) or an already-open better-sqlite3 `Database` — pass an open
+ * connection to share it with your own tables (or memory-sqlite.ts's own
+ * store) instead of opening a second file.
+ */
+export function createSqliteSkillStore(target: string | Database.Database): SkillStore {
+  const db = typeof target === "string" ? openFile(target) : target;
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS ${SKILLS_TABLE} (
+      scope_id TEXT NOT NULL,
+      id TEXT NOT NULL,
+      name TEXT NOT NULL,
+      description TEXT NOT NULL,
+      instructions TEXT NOT NULL,
+      pattern TEXT,
+      created_at TEXT NOT NULL,
+      PRIMARY KEY (scope_id, id)
+    )
+  `);
+
+  const upsertSkill = db.prepare(`
+    INSERT INTO ${SKILLS_TABLE} (scope_id, id, name, description, instructions, pattern, created_at)
+    VALUES (@scopeId, @id, @name, @description, @instructions, @pattern, @createdAt)
+    ON CONFLICT(scope_id, id) DO UPDATE SET
+      name = excluded.name, description = excluded.description, instructions = excluded.instructions,
+      pattern = excluded.pattern, created_at = excluded.created_at
+  `);
+  const selectSummaries = db.prepare(`SELECT id, name, description, pattern FROM ${SKILLS_TABLE} WHERE scope_id = ?`);
+  const selectSkill = db.prepare(`SELECT id, name, description, instructions, pattern, created_at FROM ${SKILLS_TABLE} WHERE scope_id = ? AND id = ?`);
+
+  return {
+    saveSkill(scopeId, skill) {
+      upsertSkill.run({ scopeId, id: skill.id, name: skill.name, description: skill.description, instructions: skill.instructions, pattern: skill.pattern ?? null, createdAt: skill.createdAt });
+    },
+    listSkillSummaries(scopeId) {
+      const rows = selectSummaries.all(scopeId) as { id: string; name: string; description: string; pattern: string | null }[];
+      return rows.map((r) => ({ id: r.id, name: r.name, description: r.description, pattern: r.pattern ?? undefined }));
+    },
+    getSkill(scopeId, id) {
+      const row = selectSkill.get(scopeId, id) as { id: string; name: string; description: string; instructions: string; pattern: string | null; created_at: string } | undefined;
+      if (!row) return null;
+      return { id: row.id, name: row.name, description: row.description, instructions: row.instructions, pattern: row.pattern ?? undefined, createdAt: row.created_at };
+    },
+  };
+}
+
+function openFile(filePath: string): Database.Database {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  return new Database(filePath);
+}

package/src/tts-stream.ts

@@ -21,6 +21,36 @@ import { WebSocket } from "ws";
 
 const DEEPGRAM_SPEAK_WS_URL = "wss://api.deepgram.com/v1/speak";
 
+/**
+ * Phase 2 step 1 — the sentence-boundary detector behind true "LLM tokens
+ * streamed straight into TTS." `sendText`/`flush` below already support
+ * being called many times per turn (queue more, render what's queued so
+ * far) — the missing piece was WHEN to flush a growing buffer of
+ * streamed LLM text so audio starts before the whole answer finishes
+ * generating, without cutting off mid-word or (the real trap) mid-number
+ * ("3." from "3.5 dollars").
+ *
+ * Deliberately simple: a period/!/? followed by REAL whitespace that has
+ * already arrived — never a boundary at the current end of the buffer,
+ * even if it looks sentence-final ("...3." with nothing after it yet),
+ * because more streamed text (".5 dollars") could still be on the way.
+ * The caller flushes whatever's left in the buffer once the LLM stream
+ * itself ends, regardless of trailing punctuation — real content is
+ * never silently dropped, just possibly not maximally chunked. This is
+ * a real, accepted simplification, not NLP-grade sentence detection: an
+ * abbreviation like "Mr. Smith" flushes one beat early. That costs a
+ * little TTS naturalness, never correctness — nothing in the text is
+ * lost or reordered.
+ */
+export function splitFlushableSentences(buffer: string): { toFlush: string; remainder: string } {
+  const re = /[.!?]\s+/g;
+  let lastEnd = -1;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(buffer)) !== null) lastEnd = re.lastIndex;
+  if (lastEnd === -1) return { toFlush: "", remainder: buffer };
+  return { toFlush: buffer.slice(0, lastEnd).trimEnd(), remainder: buffer.slice(lastEnd) };
+}
+
 export type SpeakChunkCallback = (audio: Buffer) => void;
 
 export interface DeepgramSpeakStreamOptions {

package/src/vad.ts

@@ -0,0 +1,153 @@
+// A lightweight, dependency-free voice-activity heuristic for client-side
+// barge-in detection — replaces a bare RMS-amplitude threshold with a
+// two-feature (energy + zero-crossing rate) gate plus an adaptive ambient
+// noise floor, entirely in plain JS math over the same Float32Array PCM
+// samples the ScriptProcessorNode already delivers. No model, no WASM, no
+// added bundle weight — the real alternative to a neural VAD (e.g. Silero)
+// this session's own research flagged as carrying a genuine ~1-2MB/
+// 20-30x bundle-size cost for a widget meant to drop into a third-party
+// page (see DEVELOPMENT.md, Phase 2 step 2's Pending section) — this
+// avoids that tradeoff entirely rather than deciding it.
+//
+// Energy alone (the prior BARGE_IN_RMS_THRESHOLD design) fires on ANY
+// loud sound — a cough, a door slam, background music, a raised-volume
+// TV. Zero-crossing rate distinguishes broadly speech-plausible content
+// (voiced pitch + its harmonics, unvoiced fricatives) from the two
+// extremes most likely to false-trigger a bare energy gate: a low-
+// frequency hum/rumble (near-zero ZCR) and broadband hiss/static-like
+// noise (ZCR near its ceiling). The ZCR band below is deliberately wide
+// — it only rejects those two extremes, not a precise speech classifier
+// — and, like the original RMS threshold, is not calibrated against real
+// hardware in this environment (no live mic here); a reasonable starting
+// point, not a tuned production value.
+//
+// The adaptive noise floor is the other real improvement over a flat
+// threshold: instead of one fixed absolute RMS cutoff, the energy gate
+// tracks a slow-moving estimate of the room's own ambient level (updated
+// only on frames NOT classified as speech) and requires real speech to
+// clear a multiple of it — a noisy room raises the bar automatically
+// instead of the old constant threshold false-triggering on ambient
+// noise all the time.
+
+const ABSOLUTE_MIN_RMS = 0.02; // same floor as the original flat threshold — never MORE sensitive than before in a quiet room
+const NOISE_FLOOR_MULTIPLIER = 3; // real speech must clear 3x the ambient floor, not just the absolute minimum
+const NOISE_FLOOR_EMA_ALPHA = 0.05; // slow-moving — ~1.7s time constant at a 4096-sample/48kHz frame, so a rising voice isn't mistaken for a rising ambient floor
+const MIN_ZCR = 0.003; // rejects near-DC hum/rumble; well below any real voiced-speech fundamental's crossing rate
+const MAX_ZCR = 0.4; // rejects hiss/static-like broadband noise (pure white noise sits near 0.5)
+
+export interface VadFrameResult {
+  isSpeech: boolean;
+  rms: number;
+  zcr: number;
+  noiseFloor: number;
+}
+
+export interface VadDetector {
+  process(samples: Float32Array): VadFrameResult;
+  reset(): void;
+}
+
+export function computeRms(samples: Float32Array): number {
+  if (samples.length === 0) return 0;
+  let sumSquares = 0;
+  for (let i = 0; i < samples.length; i++) sumSquares += samples[i] * samples[i];
+  return Math.sqrt(sumSquares / samples.length);
+}
+
+// Fraction of adjacent-sample sign changes, in [0, 1] — a coarse
+// frequency-content proxy that needs no FFT: near 0 for a slow/DC-ish
+// signal, near 1 for a signal that changes sign every sample (Nyquist-
+// rate content, the discrete analogue of white noise/hiss).
+export function computeZcr(samples: Float32Array): number {
+  if (samples.length < 2) return 0;
+  let crossings = 0;
+  for (let i = 1; i < samples.length; i++) {
+    if (samples[i] >= 0 !== samples[i - 1] >= 0) crossings++;
+  }
+  return crossings / (samples.length - 1);
+}
+
+export function createVadDetector(): VadDetector {
+  let noiseFloor = 0;
+
+  return {
+    process(samples: Float32Array): VadFrameResult {
+      const rms = computeRms(samples);
+      const zcr = computeZcr(samples);
+
+      const energyThreshold = Math.max(ABSOLUTE_MIN_RMS, noiseFloor * NOISE_FLOOR_MULTIPLIER);
+      const isSpeech = rms > energyThreshold && zcr >= MIN_ZCR && zcr <= MAX_ZCR;
+
+      if (!isSpeech) noiseFloor = noiseFloor * (1 - NOISE_FLOOR_EMA_ALPHA) + rms * NOISE_FLOOR_EMA_ALPHA;
+
+      return { isSpeech, rms, zcr, noiseFloor };
+    },
+    reset() {
+      noiseFloor = 0;
+    },
+  };
+}
+
+// A live-reported bug traced this session (see DEVELOPMENT.md) to a
+// server-side "confirm-or-reverse" barge-in design that raced Deepgram's
+// own transcript against a fixed grace window — real, deliberate
+// interruptions routinely lost that race and got treated as false
+// positives. Removing that system fixed the false "resumes from the
+// top," but left barge-in firing on a SINGLE ~85-100ms VAD frame
+// (createVadDetector's own frame-classification granularity at the
+// 4096-sample ScriptProcessorNode buffer size in use) — a single cough
+// or door-slam frame that happens to pass the energy+ZCR gate still cuts
+// the agent off, permanently now, with no recovery at all.
+//
+// Real research into how production voice-agent platforms actually solve
+// this (Pipecat, LiveKit Agents, Vapi, Deepgram's own Voice Agent API —
+// see DEVELOPMENT.md for the full comparison) converges on the same
+// answer, independent of any STT-transcript race: gate the LOCAL VAD
+// trigger on SUSTAINED speech across a minimum duration, not a single
+// frame. Pipecat's own documented production spec cites a 250ms minimum
+// duration; Vapi's stopSpeakingPlan defaults its VAD-duration threshold
+// (voiceSeconds) to 0.2s specifically to "balance responsiveness and
+// avoid false triggers." This is the same idea, entirely client-side —
+// unlike the removed server-side design, it never waits on a network
+// round trip or Deepgram's own transcript timing, so it can't reintroduce
+// that exact race. A brief, real noise burst (a cough, a single loud
+// clack) essentially never sustains cleanly across multiple consecutive
+// frames at these energy/ZCR bands; genuine speech does.
+const BARGE_IN_MIN_SPEECH_MS = 200;
+
+export interface BargeInGate {
+  /** Feed one frame's VAD classification plus that frame's real duration
+   * (samples.length / sampleRate * 1000 — NOT assumed, since sample rate
+   * varies by device/browser). Returns true the instant accumulated
+   * consecutive speech crosses the minimum-duration threshold — fires
+   * exactly once per sustained speech onset. Any non-speech frame resets
+   * the accumulator immediately, so a genuine interruption still cuts in
+   * well under half a second, while an isolated noise burst (which
+   * essentially never sustains across consecutive frames) never fires at
+   * all. */
+  update(frame: VadFrameResult, frameDurationMs: number): boolean;
+  reset(): void;
+}
+
+export function createBargeInGate(minSpeechMs: number = BARGE_IN_MIN_SPEECH_MS): BargeInGate {
+  let accumulatedMs = 0;
+  let fired = false;
+
+  return {
+    update(frame, frameDurationMs) {
+      if (!frame.isSpeech) {
+        accumulatedMs = 0;
+        fired = false;
+        return false;
+      }
+      accumulatedMs += frameDurationMs;
+      if (fired || accumulatedMs < minSpeechMs) return false;
+      fired = true;
+      return true;
+    },
+    reset() {
+      accumulatedMs = 0;
+      fired = false;
+    },
+  };
+}

package/src/verb-executor.ts

@@ -6,36 +6,57 @@
 // enforces the same schema independently — never trust the client alone.
 
 import { VerbResponseSchema, type ApiCall, type BatchAction, type TourStep, type VerbResponse } from "@cairnvibe/core";
-import { findElement, fillElement, highlightElement, logMiss, readElement, type MissContext } from "./element-ladder";
+import { dragElement, findElement, findElementWithRetry, fillElement, highlightElement, logMiss, pressKey, readElement, selectOption, waitForDomSettle, type MissContext } from "./element-ladder";
 import { executeWebMcpTool } from "./webmcp-client";
 
-/** The real result of one agent-loop step (click/fill/read/call_tool, or a
- * batch of several) — fed back to the model as its next turn's
- * "observation" so it can decide what to do next instead of acting blind.
- * The loop that drives this lives on the caller's side, not here:
+/** The real result of one agent-loop step (click/fill/read/call_tool/
+ * navigate, or a batch of several) — fed back to the model as its next
+ * turn's "observation" so it can decide what to do next instead of acting
+ * blind. The loop that drives this lives on the caller's side, not here:
  * index.tsx's runTypedAgentLoop for the HTTP path, realtime-server.ts's
  * finalizeTurn for the realtime one — this module only ever executes one
  * step (or one batch of steps) at a time. */
 export interface ToolStepResult {
-  verb: "click" | "fill" | "read" | "call_tool" | "batch";
+  verb: "click" | "fill" | "read" | "call_tool" | "batch" | "navigate" | "drag" | "select" | "key" | "scroll" | "wait_for";
   target?: string;
   ok: boolean;
   observation: string;
 }
 
+// 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).
  */
-export function executeToolStep(raw: unknown, route: string, liveElements?: Map<string, HTMLElement>): Promise<ToolStepResult | null> {
+export function executeToolStep(
+  raw: unknown,
+  route: string,
+  liveElements?: Map<string, HTMLElement>,
+  onNavigate?: (route: string) => void,
+  onConfirmTool?: (tool: { name: string; description: string }) => Promise<boolean>,
+): Promise<ToolStepResult | null> {
   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
@@ -44,6 +65,8 @@ export function executeToolStep(raw: unknown, route: string, liveElements?: Map<
     executeVerbResponse(raw, route, {
       onExplain: () => {},
       liveElements,
+      onNavigate,
+      onConfirmTool,
       onToolStep: (result) => {
         clearTimeout(timer);
         resolve(result);
@@ -75,6 +98,15 @@ export interface VerbExecutorOptions {
    * saw. Absent entirely for a caller that hasn't wired up live scanning.
    */
   liveElements?: Map<string, HTMLElement>;
+  /**
+   * Architecture Pillar 6 (the safety layer) — real confirmation for a
+   * WebMCP tool whose own registration declared `riskTier: "confirm"`
+   * (webmcp-client.ts's own doc comment covers the enforcement point).
+   * Absent means every "confirm"-tier tool call is declined by default —
+   * the safe fallback for a host app that hasn't wired up a real
+   * confirmation UI, never an implicit yes.
+   */
+  onConfirmTool?: (tool: { name: string; description: string }) => Promise<boolean>;
 }
 
 const FALLBACK_TEXT = "I'm not sure — I couldn't understand that response. Try rephrasing your question.";
@@ -111,10 +143,34 @@ function dispatchVerb(verb: VerbResponse, route: string, options: VerbExecutorOp
       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 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 ?? [];
@@ -189,7 +245,14 @@ function dispatchVerb(verb: VerbResponse, route: string, options: VerbExecutorOp
       }
       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 waitForDomSettle().then(() => {
+        options.onToolStep?.({ verb: "click", target: verb.target, ok: true, observation: "Clicked it." });
+      });
       return;
     }
 
@@ -207,7 +270,13 @@ function dispatchVerb(verb: VerbResponse, route: string, options: VerbExecutorOp
         return;
       }
       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 waitForDomSettle().then(() => {
+        options.onToolStep?.({ verb: "fill", target: verb.target, ok: true, observation: `Typed "${verb.value}" into it.` });
+      });
       return;
     }
 
@@ -225,12 +294,99 @@ function dispatchVerb(verb: VerbResponse, route: string, options: VerbExecutorOp
 
     case "call_tool": {
       if (verb.text) options.onExplain(verb.text);
-      void executeWebMcpTool(verb.name, verb.args).then((result) => {
+      void 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 = findElement(verb.target, options.liveElements);
+      const to = from ? findElement(verb.to, options.liveElements) : null;
+      if (!from || !to) {
+        (options.onMiss ?? 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;
+      }
+      highlightElement(from);
+      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 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 = findElement(verb.target, options.liveElements);
+      if (!el || !selectOption(el, verb.value)) {
+        (options.onMiss ?? 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;
+      }
+      highlightElement(el);
+      void 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 ? findElement(verb.target, options.liveElements) : (document.activeElement as HTMLElement | null);
+      if (!el) {
+        if (verb.target) (options.onMiss ?? logMiss)({ attempted: verb.target, route });
+        options.onToolStep?.({ verb: "key", target: verb.target, ok: false, observation: "Could not find that element on the page." });
+        return;
+      }
+      pressKey(el, verb.key);
+      void 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 = findElement(verb.target, options.liveElements);
+      if (!el) {
+        (options.onMiss ?? 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.
+      highlightElement(el);
+      void 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 findElementWithRetry(verb.target, options.liveElements, WAIT_FOR_ATTEMPTS, WAIT_FOR_DELAY_MS).then((el) => {
+        if (!el) {
+          (options.onMiss ?? 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
@@ -257,26 +413,40 @@ async function executeBatchActions(
   const steps: string[] = [];
   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: BatchAction, route: string, options: VerbExecutorOptions): Promise<{ ok: boolean; observation: string }> {
   switch (action.verb) {
     case "click": {
-      const el = findElement(action.target, options.liveElements);
+      const el = await findElementWithRetry(action.target, options.liveElements);
       if (!el) {
         (options.onMiss ?? logMiss)({ attempted: action.target, route });
         return { ok: false, observation: "Could not find that element on the page." };
       }
       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 waitForDomSettle();
       return { ok: true, observation: "Clicked it." };
     }
     case "fill": {
-      const el = findElement(action.target, options.liveElements);
+      const el = await findElementWithRetry(action.target, options.liveElements);
       if (!el || !fillElement(el, action.value)) {
         (options.onMiss ?? logMiss)({ attempted: action.target, route });
         return {
@@ -285,10 +455,11 @@ async function executeOneBatchAction(action: BatchAction, route: string, options
         };
       }
       highlightElement(el);
+      await waitForDomSettle();
       return { ok: true, observation: `Typed "${action.value}" into it.` };
     }
     case "read": {
-      const el = findElement(action.target, options.liveElements);
+      const el = await findElementWithRetry(action.target, options.liveElements);
       if (!el) {
         (options.onMiss ?? logMiss)({ attempted: action.target, route });
         return { ok: false, observation: "Could not find that element on the page." };
@@ -296,9 +467,59 @@ async function executeOneBatchAction(action: BatchAction, route: string, options
       return { ok: true, observation: readElement(el) };
     }
     case "call_tool": {
-      const result = await executeWebMcpTool(action.name, action.args);
+      const result = await executeWebMcpTool(action.name, action.args, options.onConfirmTool);
       return { ok: result.ok, observation: result.observation };
     }
+    case "drag": {
+      const from = await findElementWithRetry(action.target, options.liveElements);
+      const to = from ? await findElementWithRetry(action.to, options.liveElements) : null;
+      if (!from || !to) {
+        (options.onMiss ?? 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." };
+      }
+      highlightElement(from);
+      dragElement(from, to);
+      await waitForDomSettle();
+      return { ok: true, observation: `Dragged it to ${action.to}.` };
+    }
+    case "select": {
+      const el = await findElementWithRetry(action.target, options.liveElements);
+      if (!el || !selectOption(el, action.value)) {
+        (options.onMiss ?? 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." };
+      }
+      highlightElement(el);
+      await waitForDomSettle();
+      return { ok: true, observation: `Selected "${action.value}".` };
+    }
+    case "key": {
+      const el = action.target ? await findElementWithRetry(action.target, options.liveElements) : (document.activeElement as HTMLElement | null);
+      if (!el) {
+        if (action.target) (options.onMiss ?? logMiss)({ attempted: action.target, route });
+        return { ok: false, observation: "Could not find that element on the page." };
+      }
+      pressKey(el, action.key);
+      await waitForDomSettle();
+      return { ok: true, observation: `Pressed ${action.key}.` };
+    }
+    case "scroll": {
+      const el = await findElementWithRetry(action.target, options.liveElements);
+      if (!el) {
+        (options.onMiss ?? logMiss)({ attempted: action.target, route });
+        return { ok: false, observation: "Could not find that element on the page." };
+      }
+      highlightElement(el);
+      await waitForDomSettle();
+      return { ok: true, observation: "Scrolled it into view." };
+    }
+    case "wait_for": {
+      const el = await findElementWithRetry(action.target, options.liveElements, WAIT_FOR_ATTEMPTS, WAIT_FOR_DELAY_MS);
+      if (!el) {
+        (options.onMiss ?? logMiss)({ attempted: action.target, route });
+        return { ok: false, observation: "It never appeared." };
+      }
+      return { ok: true, observation: "It appeared." };
+    }
   }
 }