jev-cdp 0.1.3 → 0.1.5

package/README.md

@@ -27,8 +27,8 @@ This is an early experimental port. See [NOTICE.md](NOTICE.md) for source attrib
 Run the published CLI without adding it to a project. Bun must be installed for either command:
 
 ```bash
-bunx jev-cdp@0.1.3 help run
-npx -y jev-cdp@0.1.3 help run
+bunx jev-cdp@0.1.5 help run
+npx -y jev-cdp@0.1.5 help run
 ```
 
 Chrome with a CDP endpoint and `TYPESAFE_API_KEY` are required for browser runs. FFmpeg is required for `--recording`.
@@ -98,7 +98,11 @@ bun run run -- run \
 
 `--recording` captures Chrome's compositor screencast stream for the full goal and renders an H.264 MP4. Because Chrome's native pointer is not part of that stream, the adapter draws a high-contrast cursor that starts at the viewport center, glides to each target, and pulses on clicks. `--interaction-pauses` adds a deterministic delay after opening or loading a page, switching to an attached tab, or changing the URL within a page. Jev chooses during that delay, and the adapter waits only for any time left before acting. The same flag also pauses after moving to a click target and before pressing the mouse. Jev does not choose or observe these delays. `--screenshot` saves the final viewport after the goal stops; when recording is also enabled, it reuses the final screencast frame.
 
-`--final-state` adds an AI-oriented semantic snapshot to the final JSON on standard output. It includes the final URL, title, visible text, viewport, scroll state, actionable elements, accessible labels, and control state such as `pressed`, `checked`, `selected`, and `expanded`. Progress remains on standard error, so a coding agent can parse standard output as one JSON object and choose the next bounded goal without another browser observation.
+`jev-cdp run` writes JSON Lines to standard output: one `type:"action"` object per executed action, followed by one `type:"result"` object with the final status and action budget. Action objects include elapsed execution time, the operation, page and tab URLs, the viewport, and a CSS selector, role, name, frame, and coordinates for the element. Fill actions include the entered text; password fields and `--field-value-env` values are redacted and must be supplied separately for replay. Select and scroll actions include their option value or wheel delta. The CSS selector and page URL can be used as Playwright replay targets, with the coordinates as a fallback at the recorded viewport size. `--final-state` adds the final semantic page snapshot: a frame tree with URLs and loading state, actionable elements with frame identity, screen bounds, nearby text, region, clickability, and any element covering the click point, plus new-tab and redirect transitions. Automatic navigation and embedded-content waits use `--wait-budget-ms` (15 seconds by default) and do not consume `--max-steps`; a timeout returns `wait_timeout`, its pending condition and elapsed wait time, and the latest semantic state. Runtime failures emit a `type:"result"` object with `status:"error"`; diagnostic text uses standard error.
+
+Each action object includes `consoleErrors` observed during that step. The result object includes `initialConsoleErrors` already present when attaching to the tab and `consoleErrors` for the full run. These fields include browser console errors, uncaught exceptions, and error-level DevTools log entries from the page and its frames. Review them alongside the semantic state; a console error does not by itself establish that the goal failed.
+
+The snapshot includes visible controls in nested iframes, including cross-origin frames. Clicking a link there uses its frame coordinates and checks that the observed control is still current. If that click opens a new tab, Jev switches to it, returns its target ID for the next goal, and keeps the recording and 1120×780 viewport consistent across the switch.
 
 ## Supply known field values without another LLM
 

package/dist/cli.js

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "jev-cdp",
-  version: "0.1.3",
+  version: "0.1.5",
   description: "A small Jev-powered bridge to Chrome through the Chrome DevTools Protocol.",
   type: "module",
   license: "MIT",
@@ -207,8 +207,15 @@ var snapshot_default = `// Ported from browser-use/jev-ultrafast at commit 452c1
     const r=e.getBoundingClientRect(), x=r.x+r.width/2, y=r.y+r.height/2, rname=role(e);
     if (!rname || r.width<=0 || r.height<=0 || x<0 || y<0 || x>=innerWidth || y>=innerHeight) continue;
     if (rname==='gridcell' && e.querySelector('button,[role="button"]')) continue;
+    const hit=document.elementFromPoint(x,y);
+    const coveredBy=hit && !e.contains(hit) && !hit.contains(e) ?
+      {tag:hit.tagName.toLowerCase(),text:(hit.innerText||hit.getAttribute('aria-label')||'').trim().slice(0,160),role:hit.getAttribute('role')} : null;
+    const region=e.closest('form,dialog,[role="dialog"],article,section,li,tr,[role="row"],main,nav,header,footer');
+    const nearbyText=(region?.innerText||e.parentElement?.innerText||'').trim().replace(/\\s+/g,' ').slice(0,240);
     const base={node:identity(e),role:rname,label:name(e)||rname,...(sensitive(e)?{sensitive:true}:{}),
-      rect:{x:r.x,y:r.y,w:r.width,h:r.height}};
+      rect:{x:r.x,y:r.y,w:r.width,h:r.height},frameUrl:location.href,
+      nearbyText,region:region?.getAttribute('aria-label')||region?.getAttribute('role')||region?.tagName.toLowerCase()||'',
+      clickable:!coveredBy,coveredBy};
     for (const key of ['checked','selected','expanded','pressed']) {
       const value=e.getAttribute('aria-'+key);
       if (value!==null) base[key]=value;
@@ -228,14 +235,20 @@ var snapshot_default = `// Ported from browser-use/jev-ultrafast at commit 452c1
       if (editable) actions.push({...base,kind:'click',value,label:'Open '+base.label});
     }
   }
-  const words=[], walker=document.createTreeWalker(document.body,NodeFilter.SHOW_TEXT);
-  const range=document.createRange(); let node,length=0;
-  while ((node=walker.nextNode()) && length<6000) {
-    const value=node.textContent.trim(), parent=node.parentElement;
-    if (!value || !parent || parent.closest('script,style,noscript,template') || !visible(parent)) continue;
-    range.selectNodeContents(node); const r=range.getBoundingClientRect();
-    if (r.width>0 && r.height>0 && r.bottom>0 && r.top<innerHeight && r.right>0 && r.left<innerWidth) {
-      words.push(value); length+=value.length;
+  const roots=[document.body], shadowRoots=[];
+  for (const root of roots) for (const e of root.querySelectorAll('*')) {
+    if (e.shadowRoot) { roots.push(e.shadowRoot); shadowRoots.push(e.shadowRoot); }
+  }
+  const words=[], range=document.createRange(); let length=0;
+  for (const root of [...shadowRoots,document.body]) {
+    const walker=document.createTreeWalker(root,NodeFilter.SHOW_TEXT); let node;
+    while ((node=walker.nextNode()) && length<6000) {
+      const value=node.textContent.trim(), parent=node.parentElement;
+      if (!value || !parent || parent.closest('script,style,noscript,template') || !visible(parent)) continue;
+      range.selectNodeContents(node); const r=range.getBoundingClientRect();
+      if (r.width>0 && r.height>0 && r.bottom>0 && r.top<innerHeight && r.right>0 && r.left<innerWidth) {
+        words.push(value); length+=value.length;
+      }
     }
   }
   const text=words.join('\\n').slice(0,6000), height=document.documentElement.scrollHeight;
@@ -249,7 +262,6 @@ var snapshot_default = `// Ported from browser-use/jev-ultrafast at commit 452c1
   actions.forEach((a,i)=>a.id='e'+(i+1));
   if (scrollY+innerHeight<height-2) actions.push({id:'scroll_down',kind:'scroll',label:'Scroll down',delta:560});
   if (scrollY>0) actions.push({id:'scroll_up',kind:'scroll',label:'Scroll up',delta:-560});
-  actions.push({id:'wait',kind:'wait',label:'Wait for the page to update'});
   return {url:location.href,title:document.title,w:innerWidth,h:innerHeight,text,
     scroll:{y:scrollY,height},actions,marker,page_key,guards,omitted_actions};
 })()
@@ -278,6 +290,18 @@ var RECORDING_CURSOR_INIT = `(() => {
 
 class StalePageError extends Error {
 }
+
+class WaitTimeoutError extends Error {
+  elapsedMs;
+  pendingCondition;
+  state;
+  constructor(elapsedMs, pendingCondition, state) {
+    super(`Wait timed out after ${elapsedMs}ms: ${pendingCondition}`);
+    this.elapsedMs = elapsedMs;
+    this.pendingCondition = pendingCondition;
+    this.state = state;
+  }
+}
 function stableValue(value) {
   if (Array.isArray(value))
     return value.map(stableValue);
@@ -317,8 +341,26 @@ class Browser {
   #pageLoadPromise = null;
   #resolvePageLoad;
   #pauseUntil = 0;
+  #frameSessions = new Map;
+  #frameContexts = new Map;
+  #knownTargets = new Set;
+  #openedTabs = [];
+  #cdpUrl;
+  #switchOnPopup = false;
+  #loadingFrames = new Set;
+  #waitBudgetMs;
+  #waitSpentMs = 0;
+  #transitions = [];
+  #origin = null;
+  #changeListeners = new Set;
+  #targetUrls = new Map;
+  #newTargets = new Set;
+  #popupListeners = new Set;
+  #consoleErrors = [];
+  #watchedConsoleSessions = new Set;
   constructor(cdp, sessionId, targetId, ownsTarget, browserContextId, options) {
     this.#cdp = cdp;
+    this.#cdpUrl = options.cdpUrl;
     this.#sessionId = sessionId;
     this.#targetId = targetId;
     this.#ownsTarget = ownsTarget;
@@ -326,6 +368,7 @@ class Browser {
     this.#keepOpen = options.keepOpen ?? false;
     this.#screenshots = options.screenshots ?? false;
     this.#interactionPauses = options.interactionPauses ?? 0;
+    this.#waitBudgetMs = options.waitBudgetMs ?? 15000;
     this.#recordingPath = options.recordingPath ? resolve(options.recordingPath) : undefined;
     this.#screenshotPath = options.screenshotPath ? resolve(options.screenshotPath) : undefined;
   }
@@ -376,7 +419,41 @@ class Browser {
       flatten: true
     });
     const browser = new Browser(cdp, attached.sessionId, targetId, ownsTarget, browserContextId, options);
+    browser.#knownTargets = new Set((await listChromeTargets(options.cdpUrl)).map((target) => target.id));
     try {
+      const recordTargetUrl = (params) => {
+        const info = params.targetInfo;
+        if (info?.type === "page" && info.targetId && !browser.#knownTargets.has(info.targetId)) {
+          browser.#newTargets.add(info.targetId);
+          for (const listener of browser.#popupListeners)
+            listener();
+        }
+        if (!info?.targetId || !info.url || info.url === "about:blank")
+          return;
+        const urls = browser.#targetUrls.get(info.targetId) ?? [];
+        if (urls.at(-1) !== info.url)
+          urls.push(info.url);
+        browser.#targetUrls.set(info.targetId, urls);
+      };
+      browser.#stopPageEvents.push(cdp.on("Target.targetCreated", "", recordTargetUrl), cdp.on("Target.targetInfoChanged", "", recordTargetUrl));
+      await cdp.command("Target.setDiscoverTargets", { discover: true });
+      browser.#stopPageEvents.push(cdp.on("Target.attachedToTarget", browser.#sessionId, (params) => {
+        const info = params.targetInfo;
+        if (info?.type === "iframe" && info.targetId && typeof params.sessionId === "string") {
+          browser.#frameSessions.set(info.targetId, params.sessionId);
+          browser.watchConsole(params.sessionId, info.targetId).catch(() => {
+            return;
+          });
+        }
+      }));
+      browser.#stopPageEvents.push(cdp.on("Page.frameNavigated", browser.#sessionId, (params) => {
+        const frame = params.frame;
+        if (frame?.id)
+          browser.#frameContexts.delete(frame.id);
+      }));
+      await browser.call("Target.setAutoAttach", { autoAttach: true, waitForDebuggerOnStart: false, flatten: true });
+      await browser.watchConsole();
+      await browser.call("Page.enable");
       await browser.call("Emulation.setDeviceMetricsOverride", {
         width: 1120,
         height: 780,
@@ -392,7 +469,9 @@ class Browser {
       await browser.startRecording();
       return browser;
     } catch (error) {
-      await browser.close();
+      await browser.close().catch(() => {
+        return;
+      });
       throw error;
     }
   }
@@ -402,13 +481,65 @@ class Browser {
   get targetId() {
     return this.#targetId;
   }
-  async watchPageLoads() {
-    if (!this.#interactionPauses)
+  takeConsoleErrors() {
+    return this.#consoleErrors.splice(0);
+  }
+  pendingConsoleErrors() {
+    return [...this.#consoleErrors];
+  }
+  async watchConsole(sessionId = this.#sessionId, targetId = this.#targetId) {
+    if (this.#watchedConsoleSessions.has(sessionId))
       return;
+    this.#watchedConsoleSessions.add(sessionId);
+    const record = (source, message, url, timestamp) => {
+      if (!message.trim())
+        return;
+      this.#consoleErrors.push({
+        source,
+        message: message.slice(0, 4000),
+        ...url ? { url } : {},
+        ...timestamp !== undefined ? { timestamp } : {},
+        targetId
+      });
+    };
+    this.#stopPageEvents.push(this.#cdp.on("Runtime.consoleAPICalled", sessionId, (params) => {
+      if (params.type !== "error")
+        return;
+      const args = params.args;
+      const message = args?.map((arg) => String(arg.value ?? arg.description ?? "")).join(" ") ?? "";
+      const frame = params.stackTrace?.callFrames?.[0];
+      record("console", message, frame?.url, typeof params.timestamp === "number" ? params.timestamp : undefined);
+    }), this.#cdp.on("Runtime.exceptionThrown", sessionId, (params) => {
+      const details = params.exceptionDetails;
+      record("exception", details?.exception?.description ?? details?.text ?? "Uncaught exception", details?.url, typeof params.timestamp === "number" ? params.timestamp : undefined);
+    }), this.#cdp.on("Log.entryAdded", sessionId, (params) => {
+      const entry = params.entry;
+      if (entry?.level === "error")
+        record("log", entry.text ?? "", entry.url, entry.timestamp);
+    }));
+    await this.#cdp.command("Runtime.enable", {}, sessionId);
+    await this.#cdp.command("Log.enable", {}, sessionId);
+  }
+  async watchPageLoads() {
     await this.call("Page.enable");
     const tree = await this.call("Page.getFrameTree");
     this.#mainFrameId = tree.frameTree.frame.id;
+    await this.call("Runtime.addBinding", { name: "__jevDomChanged" });
+    const observeDom = `(() => {
+      if (window.__jevDomWatching) return;
+      window.__jevDomWatching = true;
+      const start = () => new MutationObserver(() => window.__jevDomChanged?.('change'))
+        .observe(document, {subtree:true, childList:true, attributes:true, characterData:true});
+      if (document.documentElement) start(); else document.addEventListener('DOMContentLoaded', start, {once:true});
+    })()`;
+    await this.call("Page.addScriptToEvaluateOnNewDocument", { source: observeDom });
+    await this.evaluate(observeDom).catch(() => {
+      return;
+    });
     const loading = (params) => {
+      if (typeof params.frameId === "string")
+        this.#loadingFrames.add(params.frameId);
+      this.signalChange();
       if (params.frameId !== this.#mainFrameId || this.#pageLoadPromise)
         return;
       this.#pageLoadPromise = new Promise((resolve2) => {
@@ -416,6 +547,9 @@ class Browser {
       });
     };
     const loaded = () => {
+      if (this.#mainFrameId)
+        this.#loadingFrames.delete(this.#mainFrameId);
+      this.signalChange();
       if (!this.#pageLoadPromise)
         return;
       this.#pauseUntil = performance.now() + this.#interactionPauses;
@@ -425,34 +559,69 @@ class Browser {
     };
     this.#stopPageEvents.push(this.#cdp.on("Page.frameStartedLoading", this.#sessionId, loading), this.#cdp.on("Page.frameNavigated", this.#sessionId, (params) => {
       const frame = params.frame;
+      this.signalChange();
       if (frame && frame.id === this.#mainFrameId && !frame.parentId)
         loading({ frameId: frame.id });
     }), this.#cdp.on("Page.loadEventFired", this.#sessionId, loaded), this.#cdp.on("Page.frameStoppedLoading", this.#sessionId, (params) => {
+      if (typeof params.frameId === "string")
+        this.#loadingFrames.delete(params.frameId);
+      this.signalChange();
       if (params.frameId === this.#mainFrameId)
         loaded();
     }), this.#cdp.on("Page.navigatedWithinDocument", this.#sessionId, (params) => {
+      this.signalChange();
       if (params.frameId === this.#mainFrameId) {
         this.#pauseUntil = performance.now() + this.#interactionPauses;
         this.resetRecordingCursor().catch(() => {
           return;
         });
       }
-    }));
+    }), this.#cdp.on("Page.frameAttached", this.#sessionId, () => this.signalChange()), this.#cdp.on("Page.frameDetached", this.#sessionId, () => this.signalChange()), this.#cdp.on("Runtime.bindingCalled", this.#sessionId, () => this.signalChange()));
+  }
+  signalChange() {
+    for (const listener of this.#changeListeners)
+      listener();
+  }
+  async waitForChange(ms) {
+    await new Promise((resolve2) => {
+      const done = () => {
+        clearTimeout(timer);
+        this.#changeListeners.delete(done);
+        resolve2();
+      };
+      const timer = setTimeout(done, Math.min(ms, 150));
+      this.#changeListeners.add(done);
+    });
+  }
+  async waitForNewTarget(ms) {
+    if (this.#newTargets.size)
+      return;
+    await new Promise((resolve2) => {
+      const done = () => {
+        clearTimeout(timer);
+        this.#popupListeners.delete(done);
+        resolve2();
+      };
+      const timer = setTimeout(done, ms);
+      this.#popupListeners.add(done);
+    });
   }
   async waitForInteractionPause() {
     if (!this.#interactionPauses)
       return;
+    const waitStarted = performance.now();
     while (true) {
       const pageLoad = this.#pageLoadPromise;
       if (pageLoad) {
-        await Promise.race([
-          pageLoad,
-          Bun.sleep(15000).then(() => {
-            throw new Error("Page did not finish loading within 15 seconds");
-          })
-        ]);
+        const remainingBudget = this.#waitBudgetMs - this.#waitSpentMs - (performance.now() - waitStarted);
+        if (remainingBudget <= 0)
+          throw new WaitTimeoutError(Math.round(this.#waitSpentMs + performance.now() - waitStarted), "main document loading", null);
+        await Promise.race([pageLoad, Bun.sleep(remainingBudget).then(() => {
+          throw new WaitTimeoutError(Math.round(this.#waitSpentMs + performance.now() - waitStarted), "main document loading", null);
+        })]);
         continue;
       }
+      this.#waitSpentMs += performance.now() - waitStarted;
       const remaining = this.#pauseUntil - performance.now();
       if (remaining <= 0)
         return;
@@ -464,7 +633,9 @@ class Browser {
       return;
     if (!Bun.which("ffmpeg"))
       throw new Error("--recording requires ffmpeg on PATH");
-    this.#recordingDirectory = await mkdtemp(join(tmpdir(), "jev-cdp-recording-"));
+    const firstSegment = !this.#recordingDirectory;
+    if (firstSegment)
+      this.#recordingDirectory = await mkdtemp(join(tmpdir(), "jev-cdp-recording-"));
     await this.call("Page.enable");
     await this.call("Page.addScriptToEvaluateOnNewDocument", { source: RECORDING_CURSOR_INIT });
     const viewport = await this.evaluate("({width: innerWidth, height: innerHeight})");
@@ -472,11 +643,11 @@ class Browser {
       throw new Error("Could not read the recording viewport");
     await this.animateCursor(viewport.width / 2, viewport.height / 2);
     const initial = await this.call("Page.captureScreenshot", { format: "jpeg", quality: 70 });
-    const initialPath = join(this.#recordingDirectory, "000000.jpg");
+    const initialPath = join(this.#recordingDirectory, `${String(this.#recordingSequence++).padStart(6, "0")}.jpg`);
     await Bun.write(initialPath, Buffer.from(initial.data, "base64"));
-    this.#recordingFrames.push({ path: initialPath, elapsedMs: 0 });
-    this.#recordingSequence = 1;
-    this.#recordingStartedAt = performance.now();
+    if (firstSegment)
+      this.#recordingStartedAt = performance.now();
+    this.#recordingFrames.push({ path: initialPath, elapsedMs: firstSegment ? 0 : performance.now() - this.#recordingStartedAt });
     this.#stopRecordingEvents = this.#cdp.on("Page.screencastFrame", this.#sessionId, (params) => {
       const frame = params;
       this.call("Page.screencastFrameAck", { sessionId: frame.sessionId }).catch(() => {
@@ -590,18 +761,52 @@ class Browser {
     })()`);
   }
   async waitForReady() {
-    const deadline = Date.now() + 15000;
-    while (Date.now() < deadline) {
+    const started = performance.now();
+    const deadline = started + this.#waitBudgetMs - this.#waitSpentMs;
+    while (performance.now() < deadline) {
       try {
-        if (!this.#pageLoadPromise && await this.evaluate("document.readyState") === "complete")
+        if (!this.#pageLoadPromise && await this.evaluate("document.readyState") === "complete") {
+          this.#waitSpentMs += performance.now() - started;
           return;
+        }
+      } catch (error) {
+        if (!(error instanceof StalePageError))
+          throw error;
+      }
+      await this.waitForChange(Math.max(1, deadline - performance.now()));
+    }
+    this.#waitSpentMs += performance.now() - started;
+    const state = await this.observe(false).catch(() => null);
+    throw new WaitTimeoutError(Math.round(this.#waitSpentMs), "main document loading", state);
+  }
+  async waitForSemanticReady(initial, screenshot = this.#screenshots) {
+    const started = performance.now();
+    const spentAtStart = this.#waitSpentMs;
+    const deadline = started + Math.max(0, this.#waitBudgetMs - this.#waitSpentMs);
+    const accountWait = () => {
+      this.#waitSpentMs += Math.max(0, performance.now() - started - (this.#waitSpentMs - spentAtStart));
+    };
+    let state = initial;
+    while (true) {
+      const pending = state.frames.find((frame) => frame.loading || frame.readyState !== "complete");
+      const loadingText = state.frames.length > 1 && !state.actions.some((action) => action.frameId) && /(?:^|\n)loading(?:\.{0,3}|\s)/i.test(state.text);
+      if (!pending && !loadingText) {
+        accountWait();
+        return state;
+      }
+      const condition = pending ? `frame ${pending.url || pending.id} loading` : "embedded content loading";
+      if (performance.now() >= deadline) {
+        accountWait();
+        throw new WaitTimeoutError(Math.round(this.#waitSpentMs), condition, state);
+      }
+      await this.waitForChange(Math.max(1, deadline - performance.now()));
+      try {
+        state = await this.observe(screenshot);
       } catch (error) {
         if (!(error instanceof StalePageError))
           throw error;
       }
-      await Bun.sleep(20);
     }
-    throw new Error("Page did not finish loading within 15 seconds");
   }
   async evaluate(expression, awaitPromise = false) {
     const response = await this.call("Runtime.evaluate", { expression, returnByValue: true, awaitPromise }, awaitPromise ? 15000 : undefined);
@@ -609,6 +814,125 @@ class Browser {
       throw new StalePageError("Document changed during evaluation");
     return response.result?.value;
   }
+  async evaluateFrame(frameId, expression) {
+    const session = this.#frameSessions.get(frameId);
+    let contextId = this.#frameContexts.get(frameId);
+    if (!session && !contextId) {
+      const context = await this.call("Page.createIsolatedWorld", { frameId });
+      contextId = context.executionContextId;
+      this.#frameContexts.set(frameId, contextId);
+    }
+    const response = await this.#cdp.command("Runtime.evaluate", { expression, returnByValue: true, ...contextId ? { contextId } : {} }, session ?? this.#sessionId);
+    if (response.exceptionDetails)
+      throw new StalePageError("Frame changed during evaluation");
+    return response.result?.value;
+  }
+  async frameOffset(frameId, parentId = null) {
+    const session = parentId ? this.#frameSessions.get(parentId) ?? this.#sessionId : this.#sessionId;
+    const owner = await this.#cdp.command("DOM.getFrameOwner", { frameId }, session);
+    const box = await this.#cdp.command("DOM.getBoxModel", { backendNodeId: owner.backendNodeId }, session);
+    return { x: box.model.content[0], y: box.model.content[1] };
+  }
+  async frameScreenOffset(frameId, frames) {
+    const states = frames ?? await this.frameStates();
+    let id = frameId;
+    let x = 0, y = 0;
+    while (id) {
+      const frame = states.find((item) => item.id === id);
+      if (!frame?.parentId)
+        break;
+      const offset = await this.frameOffset(id, frame.parentId);
+      x += offset.x;
+      y += offset.y;
+      id = frame.parentId;
+    }
+    return { x, y };
+  }
+  async frameStates() {
+    const tree = await this.call("Page.getFrameTree");
+    const frames = [];
+    const visit = async (node, parentId) => {
+      const { id, url = "" } = node.frame;
+      let readyState = null;
+      try {
+        readyState = id === this.#mainFrameId ? await this.evaluate("document.readyState") ?? null : await this.evaluateFrame(id, "document.readyState") ?? null;
+      } catch {}
+      frames.push({
+        id,
+        parentId,
+        url,
+        readyState,
+        loading: this.#loadingFrames.has(id) || readyState !== "complete"
+      });
+      for (const child of node.childFrames ?? [])
+        await visit(child, id);
+    };
+    await visit(tree.frameTree, null);
+    return frames;
+  }
+  async discoverTabs() {
+    if (!this.#switchOnPopup)
+      return;
+    for (const target of await listChromeTargets(this.#cdpUrl)) {
+      if (target.type !== "page" || this.#knownTargets.has(target.id))
+        continue;
+      this.#knownTargets.add(target.id);
+      this.#newTargets.delete(target.id);
+      const attached = await this.#cdp.command("Target.attachToTarget", { targetId: target.id, flatten: true });
+      try {
+        await this.#cdp.command("Emulation.setDeviceMetricsOverride", {
+          width: 1120,
+          height: 780,
+          deviceScaleFactor: 1,
+          mobile: false
+        }, attached.sessionId);
+      } finally {
+        if (this.#switchOnPopup) {
+          if (this.#recordingPath) {
+            await this.call("Page.stopScreencast").catch(() => {
+              return;
+            });
+            this.#stopRecordingEvents?.();
+            this.#stopRecordingEvents = undefined;
+            await this.#recordingWrites;
+          }
+          this.#sessionId = attached.sessionId;
+          this.#targetId = target.id;
+          this.#loadingFrames.clear();
+          await this.watchConsole();
+          await this.watchPageLoads();
+          this.#switchOnPopup = false;
+          await this.startRecording();
+        } else {
+          await this.#cdp.command("Target.detachFromTarget", { sessionId: attached.sessionId });
+        }
+      }
+      this.#openedTabs.push({ id: target.id, url: target.url, title: target.title });
+      if (this.#origin)
+        this.#transitions.push({
+          kind: "new_tab",
+          control: this.#origin.control,
+          fromTargetId: this.#origin.targetId,
+          targetId: target.id,
+          fromUrl: this.#origin.url,
+          destinationUrl: target.url,
+          settled: false
+        });
+      const urls = this.#targetUrls.get(target.id) ?? [];
+      const requested = this.#origin?.href ?? urls[0];
+      if (this.#origin && requested && requested !== target.url)
+        this.#transitions.push({
+          kind: "redirect",
+          control: this.#origin.control,
+          fromTargetId: this.#origin.targetId,
+          targetId: target.id,
+          fromUrl: requested,
+          destinationUrl: target.url,
+          settled: false
+        });
+    }
+    this.#switchOnPopup = false;
+  }
   async settleAfterInput() {
     const action = this.#afterInput;
     this.#afterInput = null;
@@ -644,21 +968,116 @@ class Browser {
   }
   async observe(screenshot = this.#screenshots) {
     await this.settleAfterInput();
+    await this.discoverTabs();
     let info;
-    for (let attempt = 0;attempt < 10; attempt++) {
+    const waitStarted = performance.now();
+    const deadline = waitStarted + Math.max(0, this.#waitBudgetMs - this.#waitSpentMs);
+    let waited = false;
+    while (true) {
       try {
         info = await this.evaluate(snapshot_default);
         if (info)
           break;
       } catch (error) {
-        if (!(error instanceof StalePageError) || attempt === 9)
+        if (!(error instanceof StalePageError))
           throw error;
       }
-      await Bun.sleep(20);
+      if (performance.now() >= deadline) {
+        this.#waitSpentMs += performance.now() - waitStarted;
+        throw new WaitTimeoutError(Math.round(this.#waitSpentMs), "document navigating", null);
+      }
+      waited = true;
+      await this.waitForChange(Math.max(1, deadline - performance.now()));
+    }
+    if (waited)
+      this.#waitSpentMs += performance.now() - waitStarted;
+    if (this.#openedTabs.length) {
+      const targets2 = await listChromeTargets(this.#cdpUrl);
+      this.#openedTabs = this.#openedTabs.map((tab) => {
+        const current = targets2.find((target) => target.id === tab.id);
+        return current ? { ...tab, url: current.url, title: current.title } : tab;
+      });
+      info.text = `${info.text}
+${this.#openedTabs.map((tab) => `Opened new tab: ${tab.title} ${tab.url} (target ${tab.id})`).join(`
+`)}`;
+    }
+    const frames = await this.frameStates();
+    for (const frame of frames.filter((frame2) => frame2.parentId !== null)) {
+      const frameId = frame.id;
+      try {
+        const offset = await this.frameScreenOffset(frameId, frames);
+        const child = await this.evaluateFrame(frameId, snapshot_default);
+        if (!child)
+          continue;
+        info.text = `${info.text}
+${child.text}`.slice(0, 6000);
+        for (const action of child.actions) {
+          if (!action.node || !action.rect)
+            continue;
+          const rect = { ...action.rect, x: action.rect.x + offset.x, y: action.rect.y + offset.y };
+          if (rect.x < 0 || rect.y < 0 || rect.x >= info.w || rect.y >= info.h)
+            continue;
+          const covering = await this.evaluate(`(() => {
+            const e=document.elementFromPoint(${rect.x + rect.w / 2},${rect.y + rect.h / 2});
+            if (!e || e.tagName==='IFRAME') return null;
+            return {tag:e.tagName.toLowerCase(),text:(e.innerText||e.getAttribute('aria-label')||'').trim().slice(0,160),role:e.getAttribute('role')};
+          })()`);
+          info.actions.push({
+            ...action,
+            frameId,
+            rect,
+            id: `e${info.actions.length + 1}`,
+            clickable: action.clickable && !covering,
+            coveredBy: covering ?? action.coveredBy
+          });
+          info.guards[`${frameId}:${action.node}`] = child.guards[String(action.node)];
+        }
+        info.marker = [info.marker, frameId, child.marker];
+      } catch {}
     }
-    if (!info)
-      throw new StalePageError("Document is navigating");
-    const page = { ...info, fingerprint: fingerprint(info) };
+    if (this.#origin && this.#targetId === this.#origin.targetId && info.url !== this.#origin.url && !this.#transitions.some((transition) => transition.control === this.#origin.control && transition.fromUrl === this.#origin.url && transition.targetId === this.#targetId)) {
+      this.#transitions.push({
+        kind: "navigation",
+        control: this.#origin.control,
+        fromTargetId: this.#origin.targetId,
+        targetId: this.#targetId,
+        fromUrl: this.#origin.url,
+        destinationUrl: info.url,
+        settled: false
+      });
+      if (this.#origin.href && this.#origin.href !== info.url)
+        this.#transitions.push({
+          kind: "redirect",
+          control: this.#origin.control,
+          fromTargetId: this.#origin.targetId,
+          targetId: this.#targetId,
+          fromUrl: this.#origin.href,
+          destinationUrl: info.url,
+          settled: false
+        });
+    }
+    const targets = this.#transitions.length ? await listChromeTargets(this.#cdpUrl) : [];
+    for (const transition of this.#transitions) {
+      const target = targets.find((item) => item.id === transition.targetId);
+      if (target)
+        transition.destinationUrl = target.url;
+      transition.settled = frames.every((frame) => !frame.loading);
+    }
+    if (this.#origin?.href)
+      for (const transition of this.#transitions.filter((item) => item.kind === "new_tab" && item.control === this.#origin.control)) {
+        if (transition.destinationUrl !== this.#origin.href && !this.#transitions.some((item) => item.kind === "redirect" && item.targetId === transition.targetId && item.fromUrl === this.#origin.href)) {
+          this.#transitions.push({
+            kind: "redirect",
+            control: transition.control,
+            fromTargetId: transition.fromTargetId,
+            targetId: transition.targetId,
+            fromUrl: this.#origin.href,
+            destinationUrl: transition.destinationUrl,
+            settled: transition.settled
+          });
+        }
+      }
+    const page = { ...info, frames, transitions: [...this.#transitions], fingerprint: fingerprint(info) };
     if (screenshot) {
       const capture = await this.call("Page.captureScreenshot", { format: "jpeg", quality: 72 });
       page.screenshot = capture.data;
@@ -666,6 +1085,12 @@ class Browser {
     return page;
   }
   async fresh(page, action) {
+    if (action?.frameId && typeof action.node === "number") {
+      const current = await this.evaluateFrame(action.frameId, `(() => {
+        const c=window.__jevFast; return c ? c.guard(c.nodes.get(${action.node})) : null;
+      })()`);
+      return stableStringify(current) === stableStringify(page.guards[`${action.frameId}:${action.node}`]);
+    }
     if (action && (action.kind === "click" || action.kind === "select")) {
       if (typeof action.node !== "number")
         return false;
@@ -675,15 +1100,49 @@ class Browser {
       })()`);
       return stableStringify(current) === stableStringify([page.page_key, page.guards[String(action.node)]]);
     }
-    const marker = await this.evaluate(MARKER);
+    let marker = await this.evaluate(MARKER);
+    for (const frame of (await this.frameStates()).filter((item) => item.parentId !== null)) {
+      try {
+        const childMarker = await this.evaluateFrame(frame.id, MARKER);
+        if (childMarker !== undefined)
+          marker = [marker ?? null, frame.id, childMarker];
+      } catch {
+        return false;
+      }
+    }
     return stableStringify(marker) === stableStringify(page.marker);
   }
+  async describeElement(action) {
+    const expression = `(node => {
+      const e = window.__jevFast?.nodes.get(node);
+      if (!e?.isConnected) return null;
+      const path = [];
+      for (let current = e; current; current = current.parentElement) {
+        if (current.id && document.querySelectorAll('#' + CSS.escape(current.id)).length === 1) {
+          path.unshift('#' + CSS.escape(current.id));
+          break;
+        }
+        let position = 1;
+        for (let sibling = current.previousElementSibling; sibling; sibling = sibling.previousElementSibling) {
+          if (sibling.tagName === current.tagName) position++;
+        }
+        path.unshift(current.tagName.toLowerCase() + ':nth-of-type(' + position + ')');
+      }
+      return {css:path.join(' > '),tag:e.tagName.toLowerCase(),
+        href:typeof e.href === 'string' ? e.href : e.getAttribute('href'),
+        inputType:e.getAttribute('type'),frameUrl:location.href,target:e.getAttribute('target')};
+    })(${action.node})`;
+    const details = action.frameId ? await this.evaluateFrame(action.frameId, expression) : await this.evaluate(expression);
+    if (!details)
+      throw new StalePageError("Target changed before replay details were captured");
+    return details;
+  }
   async act(action, page, text) {
     if (!await this.fresh(page, action))
       throw new StalePageError("Page changed since this decision");
     if (action.kind === "wait") {
       await Bun.sleep(100);
-      return;
+      return { element: null, performedAt: performance.now() };
     }
     if (action.kind === "scroll") {
       await this.animateCursor(550, 650);
@@ -694,11 +1153,25 @@ class Browser {
         deltaX: 0,
         deltaY: action.delta ?? 0
       });
-      return;
+      return { element: null, performedAt: performance.now() };
     }
     if (typeof action.node !== "number")
       throw new Error("Invalid observed node");
-    const target = await this.evaluate(`(action => {
+    const details = await this.describeElement(action);
+    if (action.kind === "click")
+      this.#origin = {
+        control: action.label,
+        targetId: this.#targetId,
+        url: page.url,
+        href: details.href
+      };
+    const target = await (action.frameId ? this.evaluateFrame(action.frameId, `(action => {
+      const e=window.__jevFast?.nodes.get(action.node);
+      if (!e?.isConnected || !e.checkVisibility({checkOpacity:true,checkVisibilityCSS:true})) return null;
+      const r=e.getBoundingClientRect(), x=r.x+r.width/2, y=r.y+r.height/2;
+      if (!e.contains(document.elementFromPoint(x,y))) return null;
+      return {x,y};
+    })(${JSON.stringify(action)})`) : this.evaluate(`(action => {
       const e=window.__jevFast?.nodes.get(action.node);
       if (!e?.isConnected || e.matches(':disabled') || e.closest('[aria-disabled="true"],[inert]') ||
           !e.checkVisibility({checkOpacity:true,checkVisibilityCSS:true})) return null;
@@ -714,12 +1187,43 @@ class Browser {
         e.dispatchEvent(new Event('change',{bubbles:true}));
       }
       return {x,y};
-    })(${JSON.stringify(action)})`);
+    })(${JSON.stringify(action)})`));
     if (!target) {
       if (action.kind === "select")
         throw new Error("Dropdown execution was not confirmed");
       throw new StalePageError("Target changed or is covered");
     }
+    let performedAt = action.kind === "select" ? performance.now() : 0;
+    if (action.frameId) {
+      const offset = await this.frameScreenOffset(action.frameId);
+      target.x += offset.x;
+      target.y += offset.y;
+      const covered = await this.evaluate(`(() => {
+        const e=document.elementFromPoint(${target.x},${target.y});
+        return !e || e.tagName!=='IFRAME';
+      })()`);
+      if (covered)
+        throw new StalePageError("Target is covered in the parent page");
+    }
+    let frame = null;
+    if (action.frameId) {
+      const frames = await this.frameStates();
+      const parentId = frames.find((item) => item.id === action.frameId)?.parentId ?? null;
+      const index = frames.filter((item) => item.parentId === parentId).findIndex((item) => item.id === action.frameId);
+      if (index < 0)
+        throw new StalePageError("Target frame changed before input");
+      frame = { id: action.frameId, parentId, url: details.frameUrl, index };
+    }
+    const element = {
+      css: details.css,
+      role: action.role ?? null,
+      name: action.label,
+      tag: details.tag,
+      href: details.href,
+      inputType: details.inputType,
+      point: { x: target.x, y: target.y },
+      frame
+    };
     await this.animateCursor(target.x, target.y);
     if (action.kind !== "select") {
       if (action.kind === "click" && this.#interactionPauses > 0) {
@@ -741,6 +1245,7 @@ class Browser {
         if (type === "mousePressed")
           await this.animateCursor(target.x, target.y, true);
       }
+      performedAt = performance.now();
       if (action.kind === "fill") {
         const modifiers = process.platform === "darwin" ? 4 : 2;
         await this.call("Input.dispatchKeyEvent", {
@@ -757,9 +1262,15 @@ class Browser {
           modifiers
         });
         await this.call("Input.insertText", { text: text ?? "" });
+        performedAt = performance.now();
       }
     }
     this.#afterInput = action;
+    if (action.kind === "click") {
+      this.#switchOnPopup = true;
+      await this.waitForNewTarget(details.target === "_blank" ? 650 : 100);
+    }
+    return { element, performedAt };
   }
   async close() {
     if (this.#closed)
@@ -808,9 +1319,9 @@ its matching autocomplete suggestion selected. For date pickers, CLICK the field
 Set every requested filter/control; a matching result alone does not prove a requested filter was set.
 Do not toggle a checkbox, switch, or radio already in the requested state.
 Submit populated search fields before opening a result; a populated field alone is not an applied search.
-WAIT only when the needed control is absent/disabled, or submitted results are still loading.
 If Search/Submit is visible and the required fields are ready, CLICK it immediately.
-Recent WAIT actions are not evidence of loading. Prefer a useful visible control over WAIT.
+Loading and frame readiness are handled by the browser adapter before this decision.
+Use frame URL, nearby text, bounds, and clickability to distinguish repeated labels.
 DONE requires visible evidence that ALL requirements are satisfied. If asked to open a result,
 a matching link is not enough. BLOCKED means no supported operation can make progress.`;
 var TARGET = `Choose the best observed target if the next operation is the one specified in this question.
@@ -882,13 +1393,21 @@ function actionSpace(actions) {
     }
     if (typeof action.node !== "number")
       continue;
-    if (!indices.has(action.node)) {
+    const identity = `${action.frameId ?? "main"}:${action.node}`;
+    if (!indices.has(identity)) {
       const index2 = String(elements.length + 1);
-      indices.set(action.node, index2);
+      indices.set(identity, index2);
       const element2 = {
         index: index2,
         label: action.label.split(" \u2192 ")[0] ?? action.label,
-        operations: []
+        operations: [],
+        frameId: action.frameId ?? null,
+        frameUrl: action.frameUrl ?? null,
+        bounds: action.rect ?? null,
+        nearbyText: action.nearbyText ?? "",
+        region: action.region ?? "",
+        clickable: action.clickable ?? true,
+        coveredBy: action.coveredBy ?? null
       };
       for (const key of ["role", "value", "checked", "selected", "expanded", "pressed", "sensitive"]) {
         if (action[key] !== undefined)
@@ -900,7 +1419,9 @@ function actionSpace(actions) {
       }
       elements.push(element2);
     }
-    const index = indices.get(action.node);
+    const index = indices.get(identity);
+    if (action.clickable === false)
+      continue;
     const group = targets[operation] ??= {};
     const element = elements[Number(index) - 1];
     if (!element.operations.includes(operation))
@@ -939,6 +1460,13 @@ async function choose(page, goal, history, providedFields = []) {
       type: "choice",
       criteria: Object.fromEntries(Object.entries(candidates).map(([index, action]) => [index, {
         element: `[${index}] ${action.label}`,
+        frame_id: action.frameId ?? null,
+        frame: action.frameUrl ?? page.url,
+        region: action.region ?? "",
+        nearby_text: action.nearbyText ?? "",
+        bounds: action.rect ?? null,
+        clickable: action.clickable ?? true,
+        covered_by: action.coveredBy ?? null,
         current_value: action.current_value ?? action.value ?? "",
         ...Object.fromEntries(["role", "checked", "selected", "expanded", "pressed", "sensitive"].filter((name) => action[name] !== undefined).map((name) => [name, action[name]]))
       }])),
@@ -1118,12 +1646,23 @@ function fieldText(context) {
 }
 
 // src/agent.ts
+function redactConsoleErrors(errors, secrets) {
+  const redact = (text) => secrets.reduce((value, secret) => value.replaceAll(secret, "[redacted]"), text);
+  return errors.map((error) => ({
+    ...error,
+    message: redact(error.message),
+    ...error.url ? { url: redact(error.url) } : {}
+  }));
+}
+
 class Agent {
   #browser;
   #goal;
   #maxSteps;
   #screenshots;
   #fieldValues;
+  #sensitiveFieldLabels;
+  #secretValues;
   #page;
   #decision = null;
   #history = [];
@@ -1132,6 +1671,8 @@ class Agent {
   #status = "ready";
   #startedAt = null;
   #pendingText = null;
+  #waitTimeout;
+  #initialConsoleErrors = [];
   constructor(browser, page, options) {
     this.#browser = browser;
     this.#page = page;
@@ -1139,6 +1680,9 @@ class Agent {
     this.#maxSteps = options.maxSteps;
     this.#screenshots = options.screenshots ?? false;
     this.#fieldValues = options.fieldValues ?? {};
+    this.#sensitiveFieldLabels = new Set(options.sensitiveFieldLabels ?? []);
+    this.#secretValues = Object.entries(this.#fieldValues).filter(([label, value]) => this.#sensitiveFieldLabels.has(label) && value.length > 0).map(([, value]) => value);
+    this.#startedAt = performance.now();
   }
   static async create(options) {
     if (!options.goal.trim())
@@ -1156,12 +1700,24 @@ class Agent {
       recordingPath: options.recordingPath,
       screenshotPath: options.screenshotPath,
       freshContext: options.freshContext,
-      interactionPauses: options.interactionPauses
+      interactionPauses: options.interactionPauses,
+      waitBudgetMs: options.waitBudgetMs
     });
     try {
-      return new Agent(browser, await browser.observe(options.screenshots), options);
+      const agent = new Agent(browser, await browser.observe(options.screenshots), options);
+      try {
+        await agent.waitForReadiness();
+      } catch (error) {
+        if (!(error instanceof WaitTimeoutError))
+          throw error;
+        agent.recordWaitTimeout(error);
+      }
+      agent.#initialConsoleErrors = redactConsoleErrors(browser.takeConsoleErrors(), agent.#secretValues);
+      return agent;
     } catch (error) {
-      await browser.close();
+      await browser.close().catch(() => {
+        return;
+      });
       throw error;
     }
   }
@@ -1176,7 +1732,14 @@ class Agent {
       status: this.#status,
       elapsedMs: this.elapsedMs(),
       maxSteps: this.#maxSteps,
-      elements: actionSpace(this.#page.actions).elements
+      elements: actionSpace(this.#page.actions).elements,
+      initialConsoleErrors: [...this.#initialConsoleErrors],
+      consoleErrors: [
+        ...this.#initialConsoleErrors,
+        ...this.#history.flatMap((entry) => entry.consoleErrors),
+        ...redactConsoleErrors(this.#browser.pendingConsoleErrors(), this.#secretValues)
+      ],
+      ...this.#waitTimeout ? { waitTimeout: this.#waitTimeout } : {}
     };
   }
   get targetId() {
@@ -1190,15 +1753,12 @@ class Agent {
       this.#startedAt = performance.now();
     if (!await this.#browser.fresh(this.#page)) {
       this.#page = await this.#browser.observe(this.#screenshots);
+      await this.waitForReadiness();
     }
     this.#decision = null;
-    if (["done", "blocked", "budget_exhausted"].includes(this.#status)) {
+    if (["done", "blocked", "budget_exhausted", "wait_timeout"].includes(this.#status)) {
       throw new Error("This run has stopped");
     }
-    if (this.#decisions.length >= this.#maxSteps * 2) {
-      this.#status = "budget_exhausted";
-      return;
-    }
     this.#decision = await choose(this.#page, this.#goal, this.#history, Object.keys(this.#fieldValues));
     this.#decisions.push(this.#decision);
     this.#status = "predicted";
@@ -1239,7 +1799,7 @@ class Agent {
       if (provided !== undefined) {
         text = provided;
         helper = { model: "provided-field-value", provider: "caller", latency_ms: 0, usage: {} };
-        this.#textCalls.push({ ...helper, field: action.label, value: action.sensitive ? "[redacted]" : text });
+        this.#textCalls.push({ ...helper, field: action.label, value: action.sensitive || this.#sensitiveFieldLabels.has(action.label) ? "[redacted]" : text });
       } else if (this.#pendingText?.contextKey === contextKey) {
         ({ text, helper } = this.#pendingText);
       } else {
@@ -1249,7 +1809,8 @@ class Agent {
       }
     }
     await this.#browser.waitForInteractionPause();
-    await this.#browser.act(action, page, text ?? undefined);
+    const fromTargetId = this.#browser.targetId;
+    const { element, performedAt } = await this.#browser.act(action, page, text ?? undefined);
     this.#pendingText = null;
     const entry = {
       step: this.#history.length + 1,
@@ -1259,21 +1820,33 @@ class Agent {
       probability: decision.probabilities[selected] ?? 0,
       confidence: decision.confidence,
       latency_ms: decision.latency_ms,
-      text: action.sensitive && text !== null ? "[redacted]" : text,
+      text: (action.sensitive || this.#sensitiveFieldLabels.has(action.label)) && text !== null ? "[redacted]" : text,
       text_helper: helper?.model ?? null,
       text_latency_ms: helper?.latency_ms ?? 0,
       operation: decision.operation,
       target: decision.target,
       page_changed: null,
+      from_url: page.url,
       url: page.url,
+      viewport: { width: page.w, height: page.h },
+      from_target_id: fromTargetId,
+      target_id: this.#browser.targetId,
+      element,
+      value: action.kind === "select" ? action.value ?? null : null,
+      delta_y: action.kind === "scroll" ? action.delta ?? 0 : null,
+      redacted: action.kind === "fill" && (Boolean(action.sensitive) || this.#sensitiveFieldLabels.has(action.label)),
       usage: decision.usage,
-      executed_ms: this.elapsedMs(),
-      elapsed_ms: this.elapsedMs()
+      executed_ms: Math.round(performedAt - this.#startedAt),
+      elapsed_ms: this.elapsedMs(),
+      consoleErrors: []
     };
     this.#history.push(entry);
     this.#page = await this.#browser.observe(this.#screenshots);
+    await this.waitForReadiness();
+    entry.consoleErrors = redactConsoleErrors(this.#browser.takeConsoleErrors(), this.#secretValues);
     entry.page_changed = this.#page.fingerprint !== page.fingerprint;
     entry.url = this.#page.url;
+    entry.target_id = this.#browser.targetId;
     entry.elapsed_ms = this.elapsedMs();
     this.#status = "ready";
   }
@@ -1282,21 +1855,41 @@ class Agent {
       await this.predict();
       await this.act();
     } catch (error) {
+      if (error instanceof WaitTimeoutError) {
+        this.recordWaitTimeout(error);
+        return this.snapshot();
+      }
       if (!(error instanceof StalePageError))
         throw error;
       this.#decision = null;
       this.#status = "ready";
       this.#page = await this.#browser.observe(this.#screenshots);
+      try {
+        await this.waitForReadiness();
+      } catch (waitError) {
+        if (!(waitError instanceof WaitTimeoutError))
+          throw waitError;
+        this.recordWaitTimeout(waitError);
+      }
     }
     return this.snapshot();
   }
   async run(onStep) {
-    while (!["done", "blocked", "budget_exhausted"].includes(this.#status)) {
+    while (!["done", "blocked", "budget_exhausted", "wait_timeout"].includes(this.#status)) {
       const state = await this.tick();
       onStep?.(state);
     }
     return this.snapshot();
   }
+  async waitForReadiness() {
+    this.#page = await this.#browser.waitForSemanticReady(this.#page, this.#screenshots);
+  }
+  recordWaitTimeout(error) {
+    this.#status = "wait_timeout";
+    this.#waitTimeout = { elapsedMs: error.elapsedMs, pendingCondition: error.pendingCondition };
+    if (error.state)
+      this.#page = error.state;
+  }
   close() {
     return this.#browser.close();
   }
@@ -1372,6 +1965,8 @@ Goal control:
   --goal <text>                  One bounded browser goal. Required.
   --max-steps <number>           Maximum executed browser actions.
                                  [env: JEV_MAX_STEPS] [default: 12]
+  --wait-budget-ms <number>      Total wall-clock budget for page and frame readiness.
+                                 [default: 15000]
 
 Browser behavior:
   --visible                      Activate the controlled tab.
@@ -1395,12 +1990,15 @@ Evidence and output:
   -h, --help                     Show this help and exit.
 
 Output:
-  The final result is one JSON object on stdout. Progress and diagnostics use stderr.
+  Stdout is JSON Lines: one object per executed action, then one result object.
+  Each action includes new console errors observed during that step. The result
+  includes initial errors and all errors observed during the run.
+  Errors and diagnostics use stderr.
 
 Exit codes:
   0  Jev reported the goal complete.
   1  Invalid configuration or runtime failure.
-  2  Jev reported that it was blocked.
+  2  Jev was blocked or the wait budget timed out.
   3  The maximum browser-step budget was exhausted.
 
 Examples:
@@ -1483,6 +2081,7 @@ function addFieldValue(options, assignment, fromEnvironment) {
     if (!supplied)
       throw new CliError(`Environment variable is missing or empty: ${environmentName}`);
     options.fieldValues[label] = supplied;
+    options.sensitiveFieldLabels.push(label);
   } else {
     options.fieldValues[label] = assignment.slice(separator + 1);
   }
@@ -1492,10 +2091,12 @@ function parseRunOptions(args) {
     cdpUrl: process.env.CHROME_CDP_URL ?? DEFAULT_CDP_URL,
     maxSteps: parsePositiveInteger(process.env.JEV_MAX_STEPS ?? "12", "JEV_MAX_STEPS"),
     interactionPauses: 0,
+    waitBudgetMs: 15000,
     visible: enabled(process.env.JEV_BROWSER_VISIBLE),
     keepOpen: enabled(process.env.JEV_BROWSER_KEEP_OPEN),
     finalState: false,
     fieldValues: {},
+    sensitiveFieldLabels: [],
     freshContext: enabled(process.env.JEV_BROWSER_FRESH_CONTEXT)
   };
   for (let index = 0;index < args.length; index++) {
@@ -1512,6 +2113,8 @@ function parseRunOptions(args) {
       options.maxSteps = parsePositiveInteger(nextValue(args, index++, argument), argument);
     else if (argument === "--interaction-pauses")
       options.interactionPauses = parseNonNegativeInteger(nextValue(args, index++, argument), argument);
+    else if (argument === "--wait-budget-ms")
+      options.waitBudgetMs = parsePositiveInteger(nextValue(args, index++, argument), argument);
     else if (argument === "--recording")
       options.recordingPath = nextValue(args, index++, argument);
     else if (argument === "--screenshot")
@@ -1559,17 +2162,45 @@ function parseCommonOptions(args, help) {
   }
   return options;
 }
-function latencyStats(values) {
+function actionEvent(entry, maxSteps) {
+  return {
+    type: "action",
+    status: "executed",
+    step: entry.step,
+    elapsedMs: entry.executed_ms,
+    budget: { used: entry.step, max: maxSteps, remaining: maxSteps - entry.step },
+    page: { before: entry.from_url, after: entry.url, changed: entry.page_changed, viewport: entry.viewport },
+    tab: { before: entry.from_target_id, after: entry.target_id },
+    consoleErrors: entry.consoleErrors,
+    action: {
+      kind: entry.kind,
+      label: entry.action,
+      element: entry.element,
+      ...entry.kind === "fill" ? { text: entry.text, redacted: entry.redacted } : {},
+      ...entry.kind === "select" ? { optionValue: entry.value } : {},
+      ...entry.kind === "scroll" ? { deltaY: entry.delta_y, point: { x: 550, y: 650 } } : {},
+      ...entry.kind === "wait" ? { durationMs: 100 } : {}
+    }
+  };
+}
+function semanticState(page, elements) {
+  const frameTree = (parentId) => page.frames.filter((frame) => frame.parentId === parentId).map((frame) => ({ ...frame, children: frameTree(frame.id) }));
   return {
-    count: values.length,
-    totalMs: values.reduce((sum, value) => sum + value, 0),
-    averageMs: values.length ? Math.round(values.reduce((sum, value) => sum + value, 0) / values.length) : null,
-    maxMs: values.length ? Math.max(...values) : null
+    url: page.url,
+    title: page.title,
+    text: page.text,
+    viewport: { width: page.w, height: page.h },
+    scroll: page.scroll,
+    elements,
+    frameTree: frameTree(null),
+    transitions: page.transitions,
+    omittedActions: page.omitted_actions
   };
 }
 async function runGoal(args) {
   const options = parseRunOptions(args);
   let agent;
+  let reportedActions = 0;
   try {
     agent = await Agent.create({
       url: options.url,
@@ -1578,50 +2209,65 @@ async function runGoal(args) {
       cdpUrl: options.cdpUrl,
       maxSteps: options.maxSteps,
       interactionPauses: options.interactionPauses,
+      waitBudgetMs: options.waitBudgetMs,
       visible: options.visible,
       keepOpen: options.keepOpen,
       recordingPath: options.recordingPath,
       screenshotPath: options.screenshotPath,
       fieldValues: options.fieldValues,
+      sensitiveFieldLabels: options.sensitiveFieldLabels,
       freshContext: options.freshContext
     });
-    let reportedActions = 0;
-    const result = await agent.run((state) => {
+    await agent.run((state) => {
       const action = state.history.length > reportedActions ? state.history.at(-1) : undefined;
-      const decision = state.decisions.at(-1);
       reportedActions = state.history.length;
-      const operation = action?.operation ?? decision?.operation ?? "none";
-      const jevLatency = action?.latency_ms ?? decision?.latency_ms;
-      const helper = action?.text_helper ? ` text=${action.text_helper}:${action.text_latency_ms}ms` : "";
-      console.error(`elapsed=${state.elapsedMs}ms actions=${state.history.length}/${state.maxSteps} status=${state.status} operation=${operation} jev=${jevLatency ?? 0}ms${helper}`);
+      if (action)
+        console.log(JSON.stringify(actionEvent(action, state.maxSteps)));
     });
+    await agent.close();
+    const result = agent.snapshot();
     console.log(JSON.stringify({
+      type: "result",
       status: result.status,
       targetId: agent.targetId,
       url: result.page.url,
       actions: result.history.length,
       maxSteps: result.maxSteps,
+      budget: { used: result.history.length, max: result.maxSteps, remaining: result.maxSteps - result.history.length },
       elapsedMs: result.elapsedMs,
       textCalls: result.textCalls.length,
-      latency: {
-        jev: latencyStats(result.decisions.map((decision) => decision.latency_ms)),
-        textHelper: latencyStats(result.textCalls.map((call) => call.latency_ms))
-      },
+      initialConsoleErrors: result.initialConsoleErrors,
+      consoleErrors: result.consoleErrors,
+      ...result.waitTimeout ? { waitTimeout: result.waitTimeout } : {},
       ...options.recordingPath ? { recording: options.recordingPath } : {},
       ...options.screenshotPath ? { screenshot: options.screenshotPath } : {},
-      ...options.finalState ? {
-        finalState: {
-          url: result.page.url,
-          title: result.page.title,
-          text: result.page.text,
-          viewport: { width: result.page.w, height: result.page.h },
-          scroll: result.page.scroll,
-          elements: result.elements,
-          omittedActions: result.page.omitted_actions
-        }
+      ...options.finalState || result.status === "wait_timeout" ? {
+        finalState: semanticState(result.page, result.elements)
       } : {}
     }));
     return result.status === "done" ? 0 : result.status === "budget_exhausted" ? 3 : 2;
+  } catch (error) {
+    const state = agent?.snapshot();
+    for (const action of state?.history.slice(reportedActions) ?? []) {
+      console.log(JSON.stringify(actionEvent(action, options.maxSteps)));
+    }
+    console.log(JSON.stringify({
+      type: "result",
+      status: error instanceof WaitTimeoutError ? "wait_timeout" : "error",
+      targetId: agent?.targetId ?? null,
+      url: state?.page.url ?? (error instanceof WaitTimeoutError ? error.state?.url ?? null : null),
+      actions: state?.history.length ?? 0,
+      maxSteps: options.maxSteps,
+      budget: { used: state?.history.length ?? 0, max: options.maxSteps, remaining: options.maxSteps - (state?.history.length ?? 0) },
+      elapsedMs: state?.elapsedMs ?? 0,
+      initialConsoleErrors: state?.initialConsoleErrors ?? [],
+      consoleErrors: state?.consoleErrors ?? [],
+      ...error instanceof WaitTimeoutError ? { waitTimeout: { elapsedMs: error.elapsedMs, pendingCondition: error.pendingCondition } } : {},
+      ...state ? { finalState: semanticState(state.page, state.elements) } : error instanceof WaitTimeoutError && error.state ? { finalState: semanticState(error.state, actionSpace(error.state.actions).elements) } : {}
+    }));
+    if (error instanceof WaitTimeoutError)
+      return 2;
+    throw error;
   } finally {
     await agent?.close();
   }
@@ -1729,5 +2375,6 @@ async function main(args = Bun.argv.slice(2)) {
 if (import.meta.main)
   process.exitCode = await main();
 export {
+  actionEvent,
   main
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jev-cdp",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "A small Jev-powered bridge to Chrome through the Chrome DevTools Protocol.",
   "type": "module",
   "license": "MIT",