browserzap 0.5.5 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # Changelog
 
+## 0.6.1 (2026-10-30)
+
+The changes from three real-Chrome runs in the owner's own browser (docs/REVIEW_LATER.md, K-7…K-10). Checked in the
+owner's Chrome: `npm run check:chrome` 9/9, approval through the page card, the test tab closed at session end.
+
+- **No more tabs left behind.** The tab group is the contract: while the agent is connected its tabs stay open in the
+  BrowserZap group, and when the session ends **every tab still in that group closes — including the one on screen**.
+  Before this the active tab of the focused window was kept and ungrouped, so every run left a duplicate tab and
+  repeated runs piled them up (K-7). A tab you drag **out of** the group is yours and stays open. The one other
+  exception is a hand-off you were actually typing in (or a page that moved while it was open): that page is kept,
+  ungrouped, and closed never.
+- **A note instead of silence.** On a tab kept that way, a short dismissal note says *"The agent finished — this tab is
+  yours."* It goes on its own after a few seconds (K-10).
+- **Approve on the page.** A consequential action now draws an **Approve once** / **Deny** card beside the element it
+  marks, so the side panel never has to be opened by hand — Chrome will not open it on its own, which is why the ringed
+  button looked like the thing to press (K-8). The card, like the Stop pill and Done, acts only on a real click, is out
+  of the tab order and out of the agent's reach (it steps aside when the agent's own click is due to land there), and
+  the extension re-checks the approval is still pending for that session and tab. The toolbar icon is badged while a
+  decision or a hand-off waits, and cleared after. The side panel's **Approve once** still works.
+- **The "Your turn" card says what happens next.** It now reads *type here, then press Done — don't submit the form; the
+  agent continues after you press Done*. If the page moves while the hand-off is open (a login redirect, or you submit
+  the form yourself), the card on the new page says the page changed and **Done** still hands control back (K-9).
+- `npm run check:chrome` puts every instruction on the page it is about, not only in the terminal, and says explicitly
+  to press **Approve once** on the card next to the button — or in the side panel — and not the page's own button.
+
+## 0.6.0 (2026-10-30)
+
+A replay now waits for what the step is actually blocked on, and retries that step instead of going back.
+
+- **The resolver engine.** When a step fails, or a click lands but changes nothing, BrowserZap works out what it is
+  waiting for — a slow request, a spinner, a target that is not usable yet, a target that has not appeared — waits for
+  exactly that, then retries the **same step**. Up to twice per step and 45 seconds of waiting, inside the run's own
+  limit. A failed step is never replayed from step 1 unless that is where it failed.
+- **Clicks are still never repeated blindly.** A consequential click (submit, pay, delete, or one that needed your
+  approval) is never retried. A click is retried only when it provably did not happen, or when it was reversible,
+  changed nothing at all **and started no request**. A click that started a request is never clicked again.
+- **New wait conditions:** an element is usable (visible, enabled, uncovered and not moving), a spinner or "Loading…"
+  is gone, the page's network is quiet, or a specific request has answered. A 4xx/5xx answers at once instead of
+  waiting. A dashboard that refreshes itself every few seconds no longer looks busy forever, and analytics traffic is
+  ignored.
+- **Learns each step.** After three runs a step's wait budget comes from what it usually needs; a blocker it hit in
+  at least 60 % of its **last 10 runs** is waited for *before* acting, and one that stops happening stops being waited
+  for, so a site that was fixed is not slowed down; a wait that never helps is skipped there. You can override with
+  `patience` (`fast`/`normal`/`patient`) or `maxWaitMs` on a step. The saved workflow is never changed automatically;
+  hints appear in the run result.
+- **Remembers what a step produced.** The recorder saves the dialog that appeared, the request the step started
+  (method plus a path with ids replaced by `*`) and how long the page took to settle. On replay a step is done when
+  that is there, waiting at most the settle the recording measured (or your `maxWaitMs`) — a bounded check that ends
+  as soon as the evidence appears, never a pause. Never a value, a query string or page text.
+- **Re-run failed resumes at the step that failed** when the page has not moved since the last verified step;
+  otherwise at the nearest earlier page load. It first checks, with a short bounded wait, that the failed step's
+  target is really on the page now — a page that moved goes back to the page load, and a workflow with no page load
+  of its own fails that set with `RESUME_UNVERIFIED` rather than acting on a page nobody checked. The batch summary
+  says how many sets resumed.
+- No new tools and no new permission: still 34 tools, and the bridge stays loopback-only and authenticated.
+
 ## 0.5.5 (2026-10-30)
 
 Comment mode, debugging tools, files, Edge and WSL, a much better doctor, and the Chrome Web Store build. Known items to review are listed in docs/REVIEW_LATER.md (upload approval visibility, a file the person picks themselves, a download re-test, wider Comment screenshots, a calmer side panel).

package/bridge-server/background-runs.js

@@ -13,6 +13,8 @@
 'use strict';
 
 const crypto = require('crypto');
+const { LIMITS } = require('./limits');
+const { resolveParams, substitute } = require('./workflows');
 
 /** Finished runs kept for workflow_status and rerunFailed. */
 const MAX_KEPT = 10;
@@ -25,6 +27,85 @@ class RunError extends Error {
   }
 }
 
+/** Steps that only read the page: a resume may start at one without a probe. */
+const RESUME_WITHOUT_PROBE = new Set(['wait_for_state', 'page_inspect', 'screenshot_capture', 'page_console', 'page_network']);
+
+/** The nearest `browser_navigate` at or before `index`; -1 when there is none. */
+function navigationAnchor(wf, index) {
+  let found = -1;
+  for (let i = 0; i <= index && Array.isArray(wf?.steps) && i < wf.steps.length; i++) {
+    if (wf.steps[i].tool === 'browser_navigate') found = i;
+  }
+  return found;
+}
+
+/**
+ * Where a set that did not complete may resume (0.6.0). It stays at the failed
+ * step when the page has not navigated since the last verified step; otherwise
+ * it starts at the nearest navigation anchor at or before the failure. Never
+ * step 1 unless that is the anchor.
+ */
+function resumeAtFor(wf, run) {
+  if (!wf || !run || !Number.isInteger(run.stoppedAt)) return 0;
+  const checkpoint = Number.isInteger(run.checkpoint) ? run.checkpoint : -1;
+  const lastNavigation = navigationAnchor(wf, run.stoppedAt);
+  if (checkpoint >= 0 && checkpoint >= lastNavigation) return run.stoppedAt;
+  if (lastNavigation >= 0) return lastNavigation;
+  return 0;
+}
+
+/**
+ * A resume: where to start (`at`), the navigation anchor to fall back to when
+ * the page has moved (`anchor`, -1 when the workflow has none) and the failed
+ * step's own target (`target`), which is what a resume at that step must find
+ * actionable before it runs (A6-09). Values are not substituted here: the
+ * caller resolves them per parameter set.
+ */
+function resumePlan(wf, run) {
+  const at = resumeAtFor(wf, run);
+  const anchor = Number.isInteger(run?.stoppedAt) ? navigationAnchor(wf, run.stoppedAt) : -1;
+  const target = wf?.steps?.[at]?.args?.target;
+  return { at, anchor, target: at > 0 && target && typeof target === 'object' ? target : null };
+}
+
+/**
+ * Prove the page is still where a resume at the failed step expects it.
+ *
+ * A real `wait_for_state { actionable: <the step's target> }` through the
+ * normal tool path, bounded by LIMITS.RESUME_PROBE_MS (a poll that ends as
+ * soon as the target is ready, never a pause). When it does not hold, the set
+ * starts at its navigation anchor instead. With no anchor there is nothing
+ * safe to start from, so it throws RESUME_UNVERIFIED: a set is never resumed
+ * with a real click on a page nobody checked.
+ *
+ * Returns the step to start at.
+ */
+async function probeResume({ wf, plan, params = {}, execute, allowedOrigins = null, timeoutMs = LIMITS.RESUME_PROBE_MS }) {
+  const at = plan?.at ?? 0;
+  if (!(at > 0) || !execute) return at;
+  const tool = wf?.steps?.[at]?.tool;
+  let reason;
+  if (plan?.target) {
+    const target = substitute(plan.target, resolveParams(wf, params));
+    const env = await execute('wait_for_state', { actionable: target, timeoutMs }, { allowedOrigins, index: at });
+    if (env.ok) return at;
+    reason = env.error?.code ?? 'the probe did not hold';
+  } else if (tool === 'browser_navigate' || RESUME_WITHOUT_PROBE.has(tool)) {
+    return at;
+  } else {
+    // A key press with no target (Enter, say) acts on whatever has focus:
+    // there is nothing to probe, so it is never the first thing a resume does.
+    reason = 'the step has no target to check';
+  }
+  if (plan.anchor >= 0) return plan.anchor;
+  throw new RunError(
+    'RESUME_UNVERIFIED',
+    `The page is not where step ${at + 1} of "${wf.name}" expects it (${reason}), ` +
+    'and the workflow has no earlier page load to go back to, so nothing was run.',
+    'Open the page the workflow starts on, or save it with a browser_navigate first, then run it from the start.',
+  );
+}
+
 /**
  * @param {object} deps
  * @param {(job: object) => Promise<object>} deps.execute   runs the batch for a job; resolves with the bulk result
@@ -43,7 +124,7 @@ function createRunRegistry({ execute, onFinish = () => {}, now = Date.now }) {
    * Start a batch. `paramSets` and `labels` are kept in memory only.
    * Throws RunError(TAB_BUSY) while another run is going.
    */
-  function start({ wf, paramSets, labels = [], onError = 'continue' }) {
+  function start({ wf, paramSets, labels = [], onError = 'continue', resume = [] }) {
     const running = active();
     if (running) {
       throw new RunError('TAB_BUSY', `"${running.workflow}" is still running in the background (${running.runId}).`,
@@ -57,6 +138,7 @@ function createRunRegistry({ execute, onFinish = () => {}, now = Date.now }) {
       total: paramSets.length,
       paramSets,
       labels,
+      resume,
       wf,
       onError,
       state: 'running',
@@ -130,15 +212,19 @@ function createRunRegistry({ execute, onFinish = () => {}, now = Date.now }) {
       throw new RunError('TAB_BUSY', `"${job.workflow}" (${runId}) is still running.`, 'Wait for it to finish, or cancel it.');
     }
     const runs = job.result?.evidence?.runs ?? [];
-    const finished = new Map(runs.map((r) => [r.index, r.ok]));
+    const finished = new Map(runs.map((r) => [r.index, r]));
     const indexes = [];
-    for (let i = 0; i < job.total; i++) if (finished.get(i) !== true) indexes.push(i);
+    for (let i = 0; i < job.total; i++) if (finished.get(i)?.ok !== true) indexes.push(i);
     return {
       job,
       indexes,
       paramSets: indexes.map((i) => job.paramSets[i]),
       // A set keeps its name from the first run ("#3" stays "#3").
       labels: indexes.map((i) => job.labels[i] ?? `#${i + 1}`),
+      // Where each set may resume (0.6.0): the failed step, or the nearest
+      // navigation anchor when the page has moved since the last verified step.
+      // A resume at the failed step is probed first (probeResume, A6-09).
+      resume: indexes.map((i) => resumePlan(job.wf, finished.get(i))),
     };
   }
 
@@ -194,6 +280,7 @@ function compactBatch(result) {
     needAttention: ev.needAttention ?? attention.length,
     notRun: ev.notRun ?? 0,
     skippedSteps: (ev.runs ?? []).reduce((n, r) => n + (r.skipped?.length ?? 0), 0),
+    resolvedSteps: (ev.runs ?? []).reduce((n, r) => n + (r.resolvedSteps ?? 0), 0),
     recovered: (ev.runs ?? []).filter((r) => r.recoveries?.length).length,
     elapsedMs: ev.elapsedMs ?? null,
     report: ev.report ?? null,
@@ -201,4 +288,4 @@ function compactBatch(result) {
   };
 }
 
-module.exports = { createRunRegistry, compactBatch, RunError };
+module.exports = { createRunRegistry, compactBatch, resumeAtFor, resumePlan, navigationAnchor, probeResume, RunError };

package/bridge-server/cli-run.js

@@ -75,6 +75,8 @@ function describe(env) {
       `${f?.likelyCause ? `, ${f.likelyCause}` : ''}${f?.screenshot ? `\n    screenshot: ${f.screenshot}` : ''}`);
   }
   if (env.evidence?.report) lines.push(`Report: ${env.evidence.report} (browserzap --runs)`);
+  const resolved = runs.reduce((n, r) => n + (r.resolvedSteps ?? 0), 0);
+  if (resolved) lines.push(`  ${resolved} step(s) resolved in place (a wait, then the same step again).`);
   if (!runs.length && !env.ok && env.nextAction) lines.push(env.nextAction);
   return lines.join('\n');
 }

package/bridge-server/limits.js

@@ -26,6 +26,13 @@ const LIMITS = Object.freeze({
   SETTLE_QUIET_MS: 500,
   /** How long that settle waits for a busy page (it costs nothing on a quiet one). */
   SETTLE_MAX_MS: 5000,
+  /** A wait whose condition makes no progress for this long ends early: a page that is stuck does not get better. */
+  STALL_MS: 3000,
+  /**
+   * Before "Re-run failed" resumes at the step that failed, that step's target
+   * must be actionable within this. A bounded probe, not a pause (A6-09).
+   */
+  RESUME_PROBE_MS: 3000,
   /** Longest per-step pacing a person may set on a saved workflow step. */
   MAX_STEP_PACING_MS: 30000,
   /** A tab with no agent action for this long is detached, so Chrome's "debugging" bar goes away (D-35). */
@@ -60,6 +67,16 @@ const STATUS_DEADLINE_MS = 4_000;
  */
 const RUN_DEADLINE_MS = 600_000;
 
+/**
+ * Resolver engine bounds (`bridge-server/resolvers.js`, 0.6.0, D-37).
+ * A step may spend at most MAX_STEP_RESOLVE_MS resolving blockers in place,
+ * across at most MAX_RESOLVER_ATTEMPTS attempts, and a reversible click with
+ * no effect at all is repeated at most MAX_INPLACE_CLICK_RETRIES times (AU-08).
+ */
+const MAX_STEP_RESOLVE_MS = 45_000;
+const MAX_RESOLVER_ATTEMPTS = 2;
+const MAX_INPLACE_CLICK_RETRIES = 2;
+
 /**
  * How long the caller waits for the extension to answer one call: the sum of
  * every wait the call can do, plus a margin, and never less than
@@ -97,4 +114,13 @@ function callDeadlineMs(tool, args = {}) {
   return Math.max(CALL_DEADLINE_MS, waits + DEADLINE_MARGIN_MS);
 }
 
-module.exports = { LIMITS, CALL_DEADLINE_MS, STATUS_DEADLINE_MS, RUN_DEADLINE_MS, callDeadlineMs };
+module.exports = {
+  LIMITS,
+  CALL_DEADLINE_MS,
+  STATUS_DEADLINE_MS,
+  RUN_DEADLINE_MS,
+  MAX_STEP_RESOLVE_MS,
+  MAX_RESOLVER_ATTEMPTS,
+  MAX_INPLACE_CLICK_RETRIES,
+  callDeadlineMs,
+};

package/bridge-server/mcp-server.js

@@ -41,7 +41,7 @@ const workflows = require('./workflows');
 const screenshots = require('./screenshots');
 const feedback = require('./feedback');
 const downloads = require('./downloads');
-const { createRunRegistry, compactBatch, RunError } = require('./background-runs');
+const { createRunRegistry, compactBatch, probeResume, RunError } = require('./background-runs');
 
 const { WorkflowError, Recorder } = workflows;
 
@@ -929,7 +929,7 @@ async function runTool(requestId, traceId, args, progress) {
  * redaction as screenshot_capture).
  */
 async function runBatchOrOnce({
-  wf, params, paramSets, labels, onError, startAt = 0, approvalId, signal,
+  wf, params, paramSets, labels, onError, startAt = 0, approvalId, signal, resume = [],
   onCall = () => {}, onStep = () => {}, onSet = () => {}, onSetDone = () => {},
 }) {
   const execute = async (tool, stepArgs, { allowedOrigins }) => {
@@ -946,14 +946,14 @@ async function runBatchOrOnce({
     const { env } = await executeTool('screenshot_capture', {}, { allowedOrigins: ALLOWED_ORIGINS });
     return env.ok ? env.screenshotPath ?? null : null;
   };
-  const runOnce = async (setParams, first) => {
+  const runOnce = async (setParams, first, setStartAt = 0) => {
     const startedAt = new Date().toISOString();
     const history = workflows.runHistory(wf);
     const result = await workflows.run(wf, {
       history,
       onStep,
       params: setParams,
-      startAt: first ? startAt : 0,
+      startAt: setStartAt || (first ? startAt : 0),
       approvalId: first ? approvalId : undefined,
       execute,
       capture,
@@ -964,7 +964,7 @@ async function runBatchOrOnce({
     service.recordRun({ wf, result, params: setParams, startedAt });
     return result;
   };
-  if (paramSets === undefined) return runOnce(params, true);
+  if (paramSets === undefined) return runOnce(params, true, startAt);
   let first = true;
   return pro.runBulk({
     wf,
@@ -972,9 +972,22 @@ async function runBatchOrOnce({
     labels,
     onError,
     signal,
+    resume,
+    // A resume at the failed step is probed first, as a real wait_for_state
+    // through executeTool; the page has moved, so the set starts at the
+    // navigation anchor instead (A6-09). With no anchor it fails without acting.
+    resumeStart: ({ plan, params: setParams }) => probeResume({
+      wf, plan, params: setParams, execute, allowedOrigins: ALLOWED_ORIGINS,
+    }),
     onSet,
     onSetDone,
-    runOnce: (setParams) => { const r = runOnce(setParams, first); first = false; return r; },
+    // A re-run of the sets that failed resumes at the step that failed where
+    // the page allows it (0.6.0), instead of starting every set at step 1.
+    runOnce: (setParams, setStartAt) => {
+      const r = runOnce(setParams, first, setStartAt ?? 0);
+      first = false;
+      return r;
+    },
   });
 }
 
@@ -985,6 +998,7 @@ const backgroundRuns = createRunRegistry({
     paramSets: job.paramSets,
     labels: job.labels,
     onError: job.onError,
+    resume: job.resume,
     signal: job.controller.signal,
     onCall: (c) => { job.call = c; },
     onStep: ({ index }) => backgroundRuns.progress(job, { stepIndex: index }),
@@ -1040,14 +1054,16 @@ function statusOfRuns(traceId, args) {
 }
 
 function rerunFailedTool(traceId, args) {
-  const { job: previous, paramSets, labels } = backgroundRuns.failedSets(args.rerunFailed);
+  const { job: previous, paramSets, labels, resume } = backgroundRuns.failedSets(args.rerunFailed);
   if (previous.workflow !== args.name) {
     return errorEnvelope(traceId, 'INVALID_ARGUMENT', `${previous.runId} ran "${previous.workflow}", not "${args.name}".`);
   }
   if (paramSets.length === 0) return okEnvelope(traceId, `Every set of ${previous.runId} completed; nothing to run again.`);
-  const job = backgroundRuns.start({ wf: workflows.load(previous.workflow), paramSets, labels, onError: 'continue' });
+  const job = backgroundRuns.start({ wf: workflows.load(previous.workflow), paramSets, labels, onError: 'continue', resume });
+  const resumed = resume.filter((plan) => plan?.at > 0).length;
   return okEnvelope(traceId,
-    `Running the ${paramSets.length} set(s) of ${previous.runId} that did not complete, from the start, in the background (${job.runId}).`,
+    `Running the ${paramSets.length} set(s) of ${previous.runId} that did not complete` +
+    `${resumed ? `, ${resumed} from the step that failed` : ''}, in the background (${job.runId}).`,
     { runId: job.runId }, { paramSets: paramSets.length, rerunOf: previous.runId });
 }
 

package/bridge-server/panel.js

@@ -38,6 +38,7 @@ const { CALL_DEADLINE_MS } = require('./limits');
 const { createWorkflowService, checkStep, stepLogEntry } = require('./workflow-service');
 const { createSessionLog, describeResult } = require('./session-log');
 const { parseParamSets } = require('./param-sets');
+const { resumePlan, probeResume } = require('./background-runs');
 const screenshots = require('./screenshots');
 const feedback = require('./feedback');
 
@@ -218,7 +219,13 @@ function createPanelRunner({ deliver, toExtension, log = () => {} }) {
           if (ok) current.batch.done += 1;
           else current.batch.failed += 1;
         },
-        runOnce: (setParams) => runOnce(setParams, 0),
+        // "Re-run failed" probes the failed step's target before resuming there,
+        // as a real wait_for_state; a page that has moved starts at the
+        // navigation anchor, and with no anchor the set fails without acting (A6-09).
+        resumeStart: ({ plan, params: setParams }) => probeResume({
+          wf, plan, params: setParams, execute, allowedOrigins: wf.origins,
+        }),
+        runOnce: (setParams, setStartAt) => runOnce(setParams, setStartAt ?? 0),
       });
       const runs = result.evidence?.runs ?? [];
       lastBatch = {
@@ -226,6 +233,9 @@ function createPanelRunner({ deliver, toExtension, log = () => {} }) {
         paramSets: batch.paramSets,
         labels: batch.labels,
         unfinished: batch.paramSets.map((_, i) => i).filter((i) => !runs.some((r) => r.index === i && r.ok)),
+        // Where each set may resume when the person presses "Re-run failed" (0.6.0):
+        // the plan a probe proves before it is used (A6-09).
+        resumeByIndex: Object.fromEntries(runs.filter((r) => !r.ok).map((r) => [r.index, resumePlan(wf, r)])),
       };
       // What the person needs to find each problem: step, cause, screenshot. Never values.
       const attention = runs.filter((r) => !r.ok).map((r) => ({
@@ -241,7 +251,7 @@ function createPanelRunner({ deliver, toExtension, log = () => {} }) {
         status: result.ok ? 'completed' : controller.signal.aborted ? 'cancelled' : 'failed',
         summary: result.summary,
         code: result.error?.code ?? null,
-        nextAction: lastBatch.unfinished.length ? `${lastBatch.unfinished.length} set(s) did not complete. "Re-run failed" runs just those, from the start.` : null,
+        nextAction: lastBatch.unfinished.length ? `${lastBatch.unfinished.length} set(s) did not complete. "Re-run failed" runs just those, from the step that failed where the page allows it.` : null,
         canContinueFrom: null,
         batch: { ...current.batch, attention, report: result.evidence?.report ?? null, canRerun: lastBatch.unfinished.length > 0 },
         finishedAt: new Date().toISOString(),
@@ -396,7 +406,8 @@ function createPanelRunner({ deliver, toExtension, log = () => {} }) {
           const wf = workflows.load(lastBatch.workflow);
           const paramSets = lastBatch.unfinished.map((i) => lastBatch.paramSets[i]);
           const labels = lastBatch.unfinished.map((i) => lastBatch.labels[i] ?? `#${i + 1}`);
-          runWorkflow(wf, {}, 0, profile, { paramSets, labels }).catch((err) => log('panel_run_error', { message: err.message }));
+          const resume = lastBatch.unfinished.map((i) => lastBatch.resumeByIndex?.[i] ?? null);
+          runWorkflow(wf, {}, 0, profile, { paramSets, labels, resume }).catch((err) => log('panel_run_error', { message: err.message }));
           return { ok: true, data: { runId: current.runId, sets: paramSets.length } };
         }
         case 'run':