browserzap 0.5.5 → 0.6.1

package/bridge-server/workflows.js

@@ -31,7 +31,8 @@ const path = require('path');
 
 const { configDir } = require('./secret');
 const { MCP_TOOLS, validateArguments } = require('./tools');
-const { LIMITS, RUN_DEADLINE_MS } = require('./limits');
+const { LIMITS, RUN_DEADLINE_MS, MAX_STEP_RESOLVE_MS, MAX_RESOLVER_ATTEMPTS, MAX_INPLACE_CLICK_RETRIES } = require('./limits');
+const { classify, mayRetryInPlace, resolveBudget, resolverById, promotable, waitArgsFor, waitForRecordedExpectation, expectBudgetMs } = require('./resolvers');
 
 const SCHEMA_VERSION = 1;
 const NAME_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/;
@@ -85,6 +86,12 @@ const RETRY_DELAYS_MS = [2000, 5000];
 const TIMEOUT_TOOLS = new Set(['browser_navigate', 'element_click', 'field_fill', 'select_option', 'wait_for_state']);
 /** Durations kept per step for learning how fast a site is (run history). */
 const HISTORY_RUNS = 20;
+/** Step-profile thresholds (0.6.0): learn after this many runs, promote a blocker seen this often, demote one never cleared. */
+const PROFILE_MIN_RUNS = 3;
+const PROFILE_PROMOTE_RATE = 0.6;
+const PROFILE_DEMOTE_MISSES = 3;
+/** How many runs the promotion rule looks at: a blocker that stops happening stops being promoted (A6-07). */
+const PROFILE_WINDOW_RUNS = 10;
 
 /** Tools a workflow step may call: the ones that change or wait on the page. */
 const STEP_TOOLS = new Set([
@@ -290,7 +297,7 @@ function originOf(url) {
 }
 
 /** Fields a saved step may carry. `retry` is not allowed inside a cleanup step: no retries within retries. */
-const STEP_FIELDS = ['tool', 'args', 'expectChange', 'note', 'waitBeforeMs', 'retry', 'onFail'];
+const STEP_FIELDS = ['tool', 'args', 'expectChange', 'note', 'waitBeforeMs', 'retry', 'onFail', 'patience', 'maxWaitMs', 'expect'];
 const CLEANUP_STEP_FIELDS = ['tool', 'args', 'expectChange', 'note'];
 
 /**
@@ -325,6 +332,69 @@ function canonicalStep(step, at, allowed = STEP_FIELDS) {
   const out = { tool: step.tool, args };
   if (step.expectChange === true) out.expectChange = true;
   if (typeof step.note === 'string' && step.note) out.note = step.note.slice(0, 200);
+  // How patient this step is with a blocker (0.6.0): a multiplier, never a hidden pause.
+  if (step.patience !== undefined) {
+    if (!['fast', 'normal', 'patient'].includes(step.patience)) {
+      throw new WorkflowError('INVALID_ARGUMENT', `${at}.patience must be "fast", "normal" or "patient".`);
+    }
+    out.patience = step.patience;
+  }
+  if (step.maxWaitMs !== undefined) {
+    if (!Number.isInteger(step.maxWaitMs) || step.maxWaitMs < 100 || step.maxWaitMs > MAX_STEP_TIMEOUT_MS) {
+      throw new WorkflowError('INVALID_ARGUMENT', `${at}.maxWaitMs must be an integer from 100 to ${MAX_STEP_TIMEOUT_MS}.`);
+    }
+    out.maxWaitMs = step.maxWaitMs;
+  }
+  if (step.expect !== undefined) out.expect = canonicalExpect(step.expect, `${at}.expect`);
+  return out;
+}
+
+/**
+ * What a step produced when it was recorded (0.6.0): a dialog that appeared, a
+ * request it started (method + path fragment, ids templated), and how long the
+ * page took to settle. Replay waits for this before calling the step done.
+ */
+function canonicalExpect(expect, at) {
+  if (!expect || typeof expect !== 'object' || Array.isArray(expect)) throw new WorkflowError('INVALID_ARGUMENT', `${at} must be an object.`);
+  const allowed = ['appears', 'request', 'settleMs'];
+  for (const key of Object.keys(expect)) {
+    if (!allowed.includes(key)) throw new WorkflowError('INVALID_ARGUMENT', `${at}.${key} is not a known expectation field.`);
+  }
+  const out = {};
+  if (expect.appears !== undefined) {
+    if (!expect.appears || typeof expect.appears !== 'object' || Array.isArray(expect.appears)) {
+      throw new WorkflowError('INVALID_ARGUMENT', `${at}.appears must be a target object.`);
+    }
+    if (hasRef({ target: expect.appears })) {
+      throw new WorkflowError('INVALID_ARGUMENT', `${at}.appears: refs only live as long as one page; use role + name, label or text.`);
+    }
+    out.appears = expect.appears;
+  }
+  if (expect.request !== undefined) {
+    const request = expect.request;
+    if (!request || typeof request !== 'object' || Array.isArray(request)) {
+      throw new WorkflowError('INVALID_ARGUMENT', `${at}.request must be an object.`);
+    }
+    const normalized = {};
+    if (request.method !== undefined) {
+      if (typeof request.method !== 'string' || !request.method || request.method.length > 16) {
+        throw new WorkflowError('INVALID_ARGUMENT', `${at}.request.method must be a short HTTP method.`);
+      }
+      normalized.method = request.method.toUpperCase();
+    }
+    if (typeof request.pathContains !== 'string' || !request.pathContains || request.pathContains.length > 200) {
+      throw new WorkflowError('INVALID_ARGUMENT', `${at}.request.pathContains must be a path fragment (1–200 characters).`);
+    }
+    normalized.pathContains = request.pathContains;
+    out.request = normalized;
+  }
+  if (expect.settleMs !== undefined) {
+    if (!Number.isInteger(expect.settleMs) || expect.settleMs < 0 || expect.settleMs > MAX_PACING_MS) {
+      throw new WorkflowError('INVALID_ARGUMENT', `${at}.settleMs must be an integer from 0 to ${MAX_PACING_MS}.`);
+    }
+    out.settleMs = expect.settleMs;
+  }
+  if (Object.keys(out).length === 0) throw new WorkflowError('INVALID_ARGUMENT', `${at} needs appears, request or settleMs.`);
   return out;
 }
 
@@ -595,7 +665,22 @@ async function run(wf, {
   const paceDefault = wf.pace?.waitBeforeMs ?? 0;
   let groupAttempts = 0;
   let pendingRecovery = null;
-  const base = { workflow: wf.name, version: wf.version, startAt, totalSteps: wf.steps.length, origins };
+  /** Steps a resolver cleared in place (0.6.0). */
+  let resolvedInPlace = 0;
+  // What earlier runs learned about these steps: hints for the person, and a
+  // blocker frequent enough to wait for before acting (never a hidden change).
+  const hints = [];
+  if (history?.profile) {
+    for (let i = 0; i < wf.steps.length; i++) {
+      const learned = history.profile(i);
+      if (learned.promotedId) hints.push({ index: i, hint: `often blocked on ${learned.promotedId}; this run waits for it before acting` });
+      for (const id of learned.demoted) hints.push({ index: i, hint: `${id} never cleared in ${learned.blockers[id].seen} runs; skipped for this step` });
+    }
+  }
+  const base = {
+    workflow: wf.name, version: wf.version, startAt, totalSteps: wf.steps.length, origins,
+    ...(hints.length ? { hints } : {}),
+  };
 
   for (let i = startAt; i < wf.steps.length; i++) {
     if (signal?.aborted) return stopped('CANCELLED', `Cancelled before step ${i + 1}.`, i, null);
@@ -624,6 +709,21 @@ async function run(wf, {
       const learned = Math.min(LIMITS.MAX_WAIT_MS, Math.round(usualMs * 3));
       if (learned > (args.timeoutMs ?? 0) && learned > DEFAULT_STEP_TIMEOUT_MS) args.timeoutMs = learned;
     }
+    const profile = history?.profile ? history.profile(i) : null;
+    // A blocker this step hit often in earlier runs is waited for before
+    // acting — the same condition, just earlier, so no failed attempt first.
+    if (profile?.promotedId && step.onFail !== 'skip') {
+      const preResolver = resolverById(profile.promotedId);
+      const preArgs = waitArgsFor(profile.promotedId, step);
+      const budget = preResolver
+        ? resolveBudget(preResolver, { learnedMs: profile.p95Ms, patience: step.patience, maxWaitMs: step.maxWaitMs })
+        : 0;
+      if (preArgs && budget >= 250 && activeMs() + budget < deadlineMs) {
+        onStep({ index: i, tool: step.tool, preWait: profile.promotedId });
+        const pre = await execute('wait_for_state', { ...preArgs, timeoutMs: budget }, { allowedOrigins: origins, signal, index: i });
+        personMs += Number(pre.evidence?.waitedForPersonMs) || 0;
+      }
+    }
     onStep({ index: i, tool: step.tool, waitBeforeMs: waitBefore });
     const stepStarted = now();
     let env = await execute(step.tool, args, { allowedOrigins: origins, signal, index: i });
@@ -640,6 +740,73 @@ async function run(wf, {
       personMs += Number(env.evidence?.waitedForPersonMs) || 0;
       if (CONFIRMATION_RISKS.has(env.evidence?.risk)) unsafe.set(i, `step ${i + 1} (${step.tool}) needed the user's approval`);
     }
+    // ── Resolver engine (0.6.0, D-37) ────────────────────────────────────────
+    // A step that failed, or a click that landed but changed nothing, asks the
+    // registry what it is blocked on. The wait runs as a normal tool call, then
+    // the SAME step is retried in place — never a group, never a blind repeat.
+    // A recorded expectation is checked first: the step is done when what it
+    // produced is there, not merely when the click landed.
+    if (env.ok && step.expect) {
+      const expected = waitForRecordedExpectation(step.expect);
+      if (expected) {
+        // `maxWaitMs` when the person set one, else the settle the recorder
+        // measured for this step, else the default — the budget of a bounded
+        // poll, never a pause (A6-10).
+        const budget = expectBudgetMs(step.expect, step.maxWaitMs);
+        const met = await execute('wait_for_state', { ...expected, timeoutMs: budget }, { allowedOrigins: origins, signal, index: i });
+        personMs += Number(met.evidence?.waitedForPersonMs) || 0;
+        if (met.ok) {
+          env = { ...env, evidence: { ...env.evidence, expectationMet: true, ...(met.evidence?.elapsedMs ? { expectationWaitedMs: met.evidence.elapsedMs } : {}) } };
+        } else {
+          // The step's own summary describes a success; the failure has to say
+          // what was missing, or the run report tells the person the step worked.
+          const message = `The step ran, but what it produced did not appear: ${met.summary}`;
+          env = {
+            ...env,
+            ok: false,
+            state: 'failed',
+            summary: message,
+            error: { code: 'POSTCONDITION_NOT_MET', message },
+            evidence: { ...env.evidence, expectationMet: false, ...(met.evidence?.notReady ? { notReady: met.evidence.notReady } : {}) },
+          };
+        }
+      }
+    }
+    const resolver = { by: null, attempts: 0, waitedMs: 0, spentMs: 0 };
+    if (step.onFail !== 'skip' && !unsafe.has(i)) {
+      for (let attempt = 1; attempt <= MAX_RESOLVER_ATTEMPTS; attempt++) {
+        if (signal?.aborted) break;
+        const ineffective = step.tool === 'element_click' && env.ok && env.evidence?.noObservableChange === true;
+        if (env.ok && !ineffective) break;
+        const hit = classify(env, step, {
+          learnedMs: usualMs,
+          patience: step.patience,
+          maxWaitMs: step.maxWaitMs,
+          demoted: profile?.demoted ?? [],
+        });
+        if (!hit || hit.then !== 'retry_step' || !mayRetryInPlace(hit, env, step)) break;
+        if (hit.id === 'click_no_effect' && resolver.attempts >= MAX_INPLACE_CLICK_RETRIES) break;
+        const budget = Math.min(hit.budgetMs, MAX_STEP_RESOLVE_MS - resolver.spentMs);
+        if (budget < 250 || activeMs() + budget >= deadlineMs) break;
+        resolver.by = hit.id;
+        resolver.attempts += 1;
+        onStep({ index: i, tool: step.tool, retry: resolver.attempts, resolving: hit.id });
+        const waited = await execute('wait_for_state', { ...hit.wait, timeoutMs: budget }, { allowedOrigins: origins, signal, index: i });
+        personMs += Number(waited.evidence?.waitedForPersonMs) || 0;
+        // `waitedMs` is the time the resolver waited (what a report shows);
+        // `spentMs` also counts the retried step, so it bounds the resolve budget.
+        const waitedMs = Number(waited.evidence?.elapsedMs) || 0;
+        resolver.waitedMs += waitedMs;
+        resolver.spentMs += waitedMs;
+        // The blocker did not clear: keep the step's own failure, and say what it was waiting on.
+        if (!waited.ok) break;
+        const retryStarted = Date.now();
+        env = await execute(step.tool, args, { allowedOrigins: origins, signal, index: i });
+        personMs += Number(env.evidence?.waitedForPersonMs) || 0;
+        resolver.spentMs += Date.now() - retryStarted;
+        if (CONFIRMATION_RISKS.has(env.evidence?.risk)) unsafe.set(i, `step ${i + 1} (${step.tool}) needed the user's approval`);
+      }
+    }
     const record = {
       index: i,
       tool: step.tool,
@@ -652,7 +819,19 @@ async function run(wf, {
     const target = describeTarget(step.tool, step.args);
     if (target) record.target = target;
     if (retries) record.retries = retries;
+    if (resolver.by) {
+      const cleared = env.ok && !(step.expectChange && env.evidence?.noObservableChange);
+      if (cleared) {
+        record.resolved = { by: resolver.by, attempt: resolver.attempts, waitedMs: resolver.waitedMs };
+        resolvedInPlace += 1;
+      } else {
+        // Tried, but the condition never cleared: keep the step's own failure and
+        // say which blocker it was, so the report can explain it.
+        record.blocker = { by: resolver.by, attempt: resolver.attempts };
+      }
+    }
     if (env.evidence?.likelyCause) record.likelyCause = env.evidence.likelyCause;
+    if (env.evidence?.expectationMet !== undefined) record.expectationMet = env.evidence.expectationMet;
     // The status only: the error page's own text is page content.
     if (env.evidence?.siteError?.status) record.siteErrorStatus = env.evidence.siteError.status;
     if (pendingRecovery && i === pendingRecovery.from) {
@@ -660,6 +839,13 @@ async function run(wf, {
       pendingRecovery = null;
     }
     steps.push(record);
+    history?.recordProfile?.(i, {
+      settleMs: env.evidence?.waitedForSettleMs,
+      blocker: record.resolved?.by ?? record.blocker?.by ?? null,
+      cleared: Boolean(record.resolved),
+      resolved: Boolean(record.resolved),
+      ok: env.ok && !(step.expectChange && env.evidence?.noObservableChange),
+    });
     if (env.ok) {
       completed.add(i);
       if (env.evidence?.navigated || env.evidence?.domChanged) pageChanged.add(i);
@@ -751,13 +937,14 @@ async function run(wf, {
     ? ` Slower than usual: ${slowSteps.map((s) => `step ${s.index + 1} took ${Math.round(s.ms / 1000)} s (usually ${Math.round(s.usualMs / 1000)} s)`).join('; ')}.`
     : '';
   const recoveryNote = recoveries.length ? ` Recovered ${recoveries.length} time(s).` : '';
+  const resolvedNote = resolvedInPlace ? ` Resolved ${resolvedInPlace} step(s) in place.` : '';
   const skipNote = skipped.length
     ? ` Done with ${skipped.length} optional step(s) skipped (${skipped.map((s) => `step ${s.index + 1}`).join(', ')}).`
     : '';
   return {
     ok: true,
     state: 'completed',
-    summary: `Ran "${wf.name}" v${wf.version}: ${completed.size} step(s)${skipped.length ? ' verified' : ', all verified'}.${skipNote}${recoveryNote}${slowNote}`,
+    summary: `Ran "${wf.name}" v${wf.version}: ${completed.size} step(s)${skipped.length ? ' verified' : ', all verified'}.${skipNote}${recoveryNote}${resolvedNote}${slowNote}`,
     nextAction: null,
     error: null,
     evidence: {
@@ -961,15 +1148,61 @@ function runHistory(wf) {
   return {
     /** The 95th-percentile duration of a step, once it has run at least three times. */
     typicalMs(index) {
-      const list = Array.isArray(data.steps[index]) ? data.steps[index].filter((n) => Number.isFinite(n)) : [];
-      if (list.length < 3) return null;
-      const sorted = [...list].sort((a, b) => a - b);
-      return sorted[Math.min(sorted.length - 1, Math.ceil(sorted.length * 0.95) - 1)];
+      return p95(profileOf(data, index).ms);
     },
     record(index, ms) {
-      const list = Array.isArray(data.steps[index]) ? data.steps[index] : [];
-      list.push(Math.max(0, Math.round(ms)));
-      data.steps[index] = list.slice(-HISTORY_RUNS);
+      const profile = profileOf(data, index);
+      profile.ms.push(Math.max(0, Math.round(ms)));
+      writeProfile(data, index, profile);
+    },
+    /**
+     * What this step learned (0.6.0): a learned budget, a blocker frequent
+     * enough to wait for before acting, and blockers that never cleared. Ids,
+     * counts and milliseconds only.
+     *
+     * Promotion looks at the last PROFILE_WINDOW_RUNS runs (the blockerRuns
+     * ring), never at lifetime counts: a blocker that stopped happening is no
+     * longer waited for (A6-07).
+     */
+    profile(index) {
+      const profile = profileOf(data, index);
+      const runs = profile.ms.length;
+      const window = profile.blockerRuns.slice(-PROFILE_WINDOW_RUNS);
+      const recent = {};
+      for (const id of window) if (id) recent[id] = (recent[id] ?? 0) + 1;
+      const blockers = {};
+      let promotedId = null;
+      const demoted = [];
+      for (const [id, raw] of Object.entries(profile.blockers)) {
+        const seen = Number(raw?.seen) || 0;
+        const cleared = Number(raw?.cleared) || 0;
+        blockers[id] = { seen, cleared, recent: recent[id] ?? 0 };
+        if (window.length >= PROFILE_MIN_RUNS && (recent[id] ?? 0) / window.length >= PROFILE_PROMOTE_RATE
+          && cleared > 0 && promotable(id) && !promotedId) promotedId = id;
+        if (seen >= PROFILE_DEMOTE_MISSES && cleared === 0) demoted.push(id);
+      }
+      return {
+        runs, window: window.length, p95Ms: p95(profile.ms), settleP95Ms: p95(profile.settleMs),
+        blockers, promotedId, demoted, outcomes: { ...profile.outcomes },
+      };
+    },
+    /** One step's outcome. Milliseconds and blocker ids; no targets, text or values. */
+    recordProfile(index, { settleMs, blocker, cleared, resolved, ok } = {}) {
+      const profile = profileOf(data, index);
+      if (Number.isFinite(settleMs) && settleMs >= 0) profile.settleMs.push(Math.round(settleMs));
+      // One entry per run, even when nothing blocked it: the ring is the
+      // denominator of the promotion rate.
+      profile.blockerRuns.push(blocker ?? null);
+      if (blocker) {
+        const entry = profile.blockers[blocker] ?? { seen: 0, cleared: 0 };
+        entry.seen += 1;
+        if (cleared) entry.cleared += 1;
+        profile.blockers[blocker] = { seen: entry.seen, cleared: entry.cleared };
+      }
+      if (resolved) profile.outcomes.ok_after_resolve += 1;
+      else if (ok) profile.outcomes.ok += 1;
+      else profile.outcomes.failed += 1;
+      writeProfile(data, index, profile);
     },
     save() {
       try {
@@ -979,6 +1212,42 @@ function runHistory(wf) {
   };
 }
 
+/**
+ * A step's stored profile, upgrading the old shapes: an array of durations
+ * (0.5.x), or an object without the blockerRuns ring (0.6.0 before A6-07). An
+ * old profile loads as empty history for the ring — the durations it holds are
+ * still used — never as an error and never by rewriting the workflow.
+ */
+function profileOf(data, index) {
+  const empty = () => ({ ms: [], settleMs: [], blockers: {}, blockerRuns: [], outcomes: { ok: 0, ok_after_resolve: 0, failed: 0 } });
+  const raw = data.steps[index];
+  if (Array.isArray(raw)) return { ...empty(), ms: raw.filter(Number.isFinite) };
+  if (!raw || typeof raw !== 'object') return empty();
+  return {
+    ms: Array.isArray(raw.ms) ? raw.ms.filter(Number.isFinite) : [],
+    settleMs: Array.isArray(raw.settleMs) ? raw.settleMs.filter(Number.isFinite) : [],
+    blockers: raw.blockers && typeof raw.blockers === 'object' ? raw.blockers : {},
+    blockerRuns: Array.isArray(raw.blockerRuns) ? raw.blockerRuns.filter((id) => id === null || typeof id === 'string') : [],
+    outcomes: { ok: 0, ok_after_resolve: 0, failed: 0, ...(raw.outcomes && typeof raw.outcomes === 'object' ? raw.outcomes : {}) },
+  };
+}
+
+function writeProfile(data, index, profile) {
+  data.steps[index] = {
+    ms: profile.ms.slice(-HISTORY_RUNS),
+    settleMs: profile.settleMs.slice(-HISTORY_RUNS),
+    blockers: profile.blockers,
+    blockerRuns: profile.blockerRuns.slice(-PROFILE_WINDOW_RUNS),
+    outcomes: profile.outcomes,
+  };
+}
+
+function p95(list) {
+  if (list.length < 3) return null;
+  const sorted = [...list].sort((a, b) => a - b);
+  return sorted[Math.min(sorted.length - 1, Math.ceil(sorted.length * 0.95) - 1)];
+}
+
 // ─── Recorder ────────────────────────────────────────────────────────────────
 
 function slug(text, fallback) {
@@ -1108,6 +1377,24 @@ class Recorder {
         } catch { /* keep without */ }
       }
     }
+    // What this step produced, so replay waits for it before calling the step
+    // done (0.6.0): a dialog that appeared, the request it started (method +
+    // a path with ids templated), and how long the page took to settle. No
+    // values, no query strings, no page text.
+    const produced = {};
+    if (env.evidence?.appeared?.name) {
+      produced.appears = { role: env.evidence.appeared.role || 'dialog', name: env.evidence.appeared.name };
+    }
+    if (env.evidence?.requestStarted?.pathContains) {
+      produced.request = {
+        ...(env.evidence.requestStarted.method ? { method: env.evidence.requestStarted.method } : {}),
+        pathContains: env.evidence.requestStarted.pathContains,
+      };
+    }
+    if (Number.isFinite(env.evidence?.waitedForSettleMs) && env.evidence.waitedForSettleMs > 0) {
+      produced.settleMs = Math.round(env.evidence.waitedForSettleMs);
+    }
+    if (Object.keys(produced).length) step.expect = produced;
     this.steps.push(step);
   }