browserzap 0.5.5 → 0.6.1

package/bridge-server/resolvers.js

@@ -0,0 +1,287 @@
+'use strict';
+
+const { LIMITS } = require('./limits');
+
+/**
+ * Resolver engine — the registry (0.6.0, D-37).
+ *
+ * Pure: no I/O, no page access, no timers, no clocks. Given a failed (or
+ * ineffective) workflow step and the envelope the extension returned, say what
+ * the step is blocked on and what would clear it. The runner then waits for
+ * that condition as an ordinary `wait_for_state` call and retries the same
+ * step — so every wait and every retry still goes through the normal tool path
+ * and extension policy.
+ *
+ * Design: docs/NEXT_RELEASE_SCOPE_0.6.md (§3 of the 0.5 doc);
+ * the wait kinds it relies on: docs/ADR/ADR-007-waiting-and-timeouts.md.
+ *
+ * Adding a resolver is one entry here plus a fixture that fails without it.
+ * The validation rules at the bottom are checked by tests/resolvers.test.mjs.
+ */
+
+/** A change here that alters behaviour resets learned demotions (step profile). */
+const REGISTRY_VERSION = 1;
+
+/**
+ * Codes that are never auto-resolved: a person, a policy, or a unique target is
+ * needed. A resolver that claimed one of these would be guessing.
+ */
+const FORBIDDEN_CODES = Object.freeze([
+  'USER_CONFIRMATION_REQUIRED',
+  'USER_ACTION_REQUIRED',
+  'POLICY_BLOCKED',
+  'TARGET_AMBIGUOUS',
+]);
+
+/** Risks that must never be repeated in place (audit AU-08). */
+const CONSEQUENTIAL_RISKS = new Set(['external_side_effect', 'destructive', 'financial']);
+
+/** Tools a resolver may retry in place. A read-only tool is never a workflow step. */
+const RETRYABLE_TOOLS = new Set([
+  'browser_navigate', 'element_click', 'field_fill', 'select_option', 'wait_for_state', 'browser_press_key',
+]);
+
+/**
+ * Failures that prove the action never ran: the target was missing, unusable or
+ * a stale ref. Only these may be retried for a click or a key press; anything
+ * else may already have submitted something (AU-08).
+ */
+const ACTION_DID_NOT_RUN_CODES = new Set(['TARGET_NOT_FOUND', 'TARGET_NOT_INTERACTABLE', 'STALE_SNAPSHOT']);
+
+/**
+ * Failures a resolver may act on: the page has not got there yet. Anything else
+ * — a bad argument, a Pro gate, a missing workflow, a cancelled run — is
+ * deterministic, and waiting for the page cannot change it (ADR-007: only
+ * failures that can clear up are waited on). A successful call that changed
+ * nothing has no code at all and is classified by its evidence.
+ */
+const TRANSIENT_CODES = Object.freeze([
+  'TIMEOUT', 'TARGET_NOT_FOUND', 'TARGET_NOT_INTERACTABLE', 'STALE_SNAPSHOT',
+  'NAVIGATION_FAILED', 'BRIDGE_DISCONNECTED', 'POSTCONDITION_NOT_MET', 'SITE_ERROR',
+]);
+
+/** The wait kinds the extension understands (registered in doWaitFor). */
+const WAIT_KINDS = Object.freeze(['urlContains', 'text', 'target', 'targetGone', 'actionable', 'indicatorGone', 'networkQuiet', 'requestDone']);
+
+/**
+ * Ordered: the more specific answer wins. The condition hierarchy follows the
+ * design — the step's own expectation, then actionability, then a specific
+ * request, then a UI signal, then global network quiet (as a fallback only).
+ */
+const RESOLVERS = Object.freeze([
+  {
+    id: 'expectation_unmet',
+    safety: 'retry_reversible',
+    then: 'retry_step',
+    // About what the step produced, so it can never be a pre-wait: an
+    // expectation cannot be there before the step that produces it runs.
+    promotable: false,
+    budgetMs: { floor: 500, default: 5000, ceiling: 30000 },
+    matches: ({ evidence, step }) => Boolean(step.expect) && evidence.expectationMet === false,
+    wait: ({ step }) => waitForRecordedExpectation(step.expect),
+  },
+  {
+    id: 'click_no_effect',
+    safety: 'retry_reversible',
+    then: 'retry_step',
+    budgetMs: { floor: 500, default: 3000, ceiling: 10000 },
+    // The narrow AU-08 exception: reversible, nothing visible changed, and no
+    // request went out. A click that started a request is waited on instead.
+    matches: ({ evidence, step }) => step.tool === 'element_click'
+      && evidence.noObservableChange === true
+      && evidence.risk === 'reversible'
+      && Number(evidence.requestsStarted ?? 0) === 0,
+    wait: ({ step }) => ({ actionable: step.args.target, networkQuiet: true }),
+  },
+  {
+    id: 'target_not_ready',
+    safety: 'retry_reversible',
+    then: 'retry_step',
+    budgetMs: { floor: 500, default: 5000, ceiling: 20000 },
+    matches: ({ code }) => code === 'TARGET_NOT_INTERACTABLE',
+    wait: ({ step }) => ({ actionable: step.args.target }),
+  },
+  {
+    id: 'target_late',
+    safety: 'retry_reversible',
+    then: 'retry_step',
+    budgetMs: { floor: 500, default: 8000, ceiling: 30000 },
+    matches: ({ code, evidence }) => code === 'TARGET_NOT_FOUND'
+      && (Number(evidence.pendingRequests ?? 0) > 0 || Boolean(evidence.busyIndicator)),
+    wait: ({ step }) => ({ target: step.args.target }),
+  },
+  {
+    id: 'api_pending',
+    safety: 'retry_reversible',
+    then: 'retry_step',
+    budgetMs: { floor: 1000, default: 15000, ceiling: 45000 },
+    matches: ({ evidence }) => evidence.likelyCause === 'server_slow'
+      || Number(evidence.pendingRequests ?? 0) > 0
+      || Boolean(evidence.slowestRequest),
+    // The step's own recorded request is the strongest signal; global quiet is
+    // only the capped fallback.
+    wait: ({ step }) => (step.expect && step.expect.request
+      ? { requestDone: step.expect.request }
+      : { networkQuiet: true }),
+  },
+  {
+    id: 'still_rendering',
+    safety: 'retry_reversible',
+    then: 'retry_step',
+    budgetMs: { floor: 500, default: 10000, ceiling: 30000 },
+    matches: ({ evidence }) => Boolean(evidence.busyIndicator) || evidence.likelyCause === 'still_rendering',
+    wait: () => ({ indicatorGone: true }),
+  },
+  {
+    id: 'site_error',
+    safety: 'group',
+    then: 'retry_group',
+    budgetMs: { floor: 0, default: 0, ceiling: 0 },
+    matches: ({ code, evidence }) => code === 'SITE_ERROR' || evidence.likelyCause === 'site_error',
+    wait: () => null,
+  },
+  {
+    id: 'context_lost',
+    safety: 'group',
+    then: 'retry_group',
+    budgetMs: { floor: 0, default: 0, ceiling: 0 },
+    matches: ({ evidence }) => evidence.contextLost === true,
+    wait: () => null,
+  },
+]);
+
+/** The wait args for a recorded expectation (`appears` and `request` can combine). */
+function waitForRecordedExpectation(expect) {
+  if (!expect) return null;
+  const args = {};
+  if (expect.appears) args.target = expect.appears;
+  if (expect.request && expect.request.pathContains) args.requestDone = expect.request;
+  return Object.keys(args).length > 0 ? args : null;
+}
+
+/**
+ * How long the recorded-expectation wait may look for its evidence: the
+ * person's `maxWaitMs` when set, otherwise the settle the recorder measured
+ * (the learned pace for that step), otherwise the default expectation timeout.
+ * It is the budget of a bounded poll that ends the moment the evidence is
+ * there — never a pause (A6-10). Clamped to the shared limits.
+ */
+function expectBudgetMs(expect, maxWaitMs = null) {
+  const asked = Number.isFinite(maxWaitMs) && maxWaitMs > 0 ? maxWaitMs : null;
+  const recorded = Number.isFinite(expect?.settleMs) && expect.settleMs > 0 ? expect.settleMs : null;
+  const ms = asked ?? recorded ?? LIMITS.DEFAULT_EXPECT_TIMEOUT_MS;
+  return Math.max(LIMITS.SETTLE_QUIET_MS, Math.min(ms, LIMITS.MAX_WAIT_MS));
+}
+
+/** The failure a classifier works from, normalised from either envelope shape. */
+function normalise(env) {
+  return {
+    code: env?.error?.code ?? env?.code ?? null,
+    evidence: env?.evidence ?? {},
+    state: env?.state ?? (env?.ok === false ? 'failed' : 'completed'),
+  };
+}
+
+/**
+ * What is this step blocked on? Returns `{ id, safety, then, wait, budgetMs }`,
+ * or null when nothing safe could clear it (a person, a policy, ambiguity, or
+ * an unknown failure). A resolver whose `wait` is null only selects the
+ * existing group-recovery path.
+ */
+function classify(env, step, options = {}) {
+  const failure = normalise(env);
+  if (!step || !RETRYABLE_TOOLS.has(step.tool)) return null;
+  if (failure.code && FORBIDDEN_CODES.includes(failure.code)) return null;
+  if (failure.code && !TRANSIENT_CODES.includes(failure.code)) return null;
+  const demoted = Array.isArray(options.demoted) ? options.demoted : [];
+  for (const resolver of RESOLVERS) {
+    if (demoted.includes(resolver.id)) continue;
+    if (!resolver.matches({ ...failure, step })) continue;
+    const wait = resolver.wait({ step, evidence: failure.evidence });
+    if (resolver.then === 'retry_step' && !wait) return null;
+    return {
+      id: resolver.id,
+      safety: resolver.safety,
+      then: resolver.then,
+      wait,
+      budgetMs: resolveBudget(resolver, options),
+    };
+  }
+  return null;
+}
+
+/** One resolver by id, for a step profile that learned to pre-wait. */
+function resolverById(id) {
+  return RESOLVERS.find((resolver) => resolver.id === id && resolver.then === 'retry_step') ?? null;
+}
+
+/** The wait args for a resolver id applied to this step (promotion from the step profile). */
+function waitArgsFor(id, step) {
+  const resolver = resolverById(id);
+  return resolver ? resolver.wait({ step, evidence: {} }) : null;
+}
+
+/**
+ * May a step profile wait for this blocker *before* acting? Only a blocker about
+ * what the step is waiting on — never one about what it produces.
+ */
+function promotable(id) {
+  const resolver = resolverById(id);
+  return Boolean(resolver) && resolver.promotable !== false;
+}
+
+/**
+ * How long to wait for this resolver, in this order: the resolver's own default,
+ * the step's learned p95 × 1.5 (once it has ≥ 3 runs), the person's patience,
+ * an explicit cap, then the resolver's floor/ceiling.
+ */
+function resolveBudget(resolver, { learnedMs = null, patience = 'normal', maxWaitMs = null } = {}) {
+  const { floor, default: fallback, ceiling } = resolver.budgetMs;
+  let ms = fallback;
+  if (Number.isFinite(learnedMs) && learnedMs > 0) ms = Math.round(learnedMs * 1.5);
+  const factor = patience === 'fast' ? 0.5 : patience === 'patient' ? 3 : 1;
+  ms = Math.round(ms * factor);
+  if (Number.isFinite(maxWaitMs) && maxWaitMs > 0) ms = Math.min(ms, maxWaitMs);
+  return Math.max(floor, Math.min(ms, ceiling));
+}
+
+/**
+ * May this step be retried in place under AU-08?
+ *
+ * - the resolver must actually retry the step;
+ * - its tool must be one a workflow may repeat;
+ * - a consequential step is never repeated, whatever the failure code;
+ * - a click or key press is repeated only when the action provably did not run,
+ *   or under the click_no_effect resolver's own narrow rule;
+ * - everything else (fills, selects, navigations, waits) is safe to repeat.
+ */
+function mayRetryInPlace(resolver, env, step) {
+  if (!resolver || resolver.then !== 'retry_step') return false;
+  if (!step || !RETRYABLE_TOOLS.has(step.tool)) return false;
+  const { code, evidence } = normalise(env);
+  if (CONSEQUENTIAL_RISKS.has(evidence.risk)) return false;
+  if (resolver.id === 'click_no_effect') return true;
+  if (step.tool === 'element_click' || step.tool === 'browser_press_key') {
+    return ACTION_DID_NOT_RUN_CODES.has(code);
+  }
+  return true;
+}
+
+module.exports = {
+  REGISTRY_VERSION,
+  FORBIDDEN_CODES,
+  CONSEQUENTIAL_RISKS,
+  RETRYABLE_TOOLS,
+  ACTION_DID_NOT_RUN_CODES,
+  TRANSIENT_CODES,
+  WAIT_KINDS,
+  RESOLVERS,
+  classify,
+  resolveBudget,
+  mayRetryInPlace,
+  resolverById,
+  promotable,
+  waitArgsFor,
+  waitForRecordedExpectation,
+  expectBudgetMs,
+};

package/bridge-server/tools.js

@@ -48,6 +48,18 @@ const EXPECT = {
 
 const TIMEOUT = { type: 'integer', minimum: 100, maximum: LIMITS.MAX_WAIT_MS, description: `Milliseconds (max ${LIMITS.MAX_WAIT_MS}).` };
 
+/** A request to wait for: method and a fragment of its path. Query strings are never matched. */
+const REQUEST_PATTERN = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['pathContains'],
+  description: 'A request to wait for, by method and a fragment of its path (no query strings).',
+  properties: {
+    method: { type: 'string', maxLength: 16, description: 'HTTP method, e.g. GET. Any method when omitted.' },
+    pathContains: { type: 'string', minLength: 1, maxLength: 200, description: 'A fragment of the request path, e.g. /api/accounts.' },
+  },
+};
+
 /** A saved step's own pacing: a deliberate pause the person set, never added by BrowserZap. */
 const PACING = {
   type: 'integer', minimum: 0, maximum: LIMITS.MAX_STEP_PACING_MS,
@@ -201,8 +213,10 @@ const MCP_TOOLS = [
   {
     name: 'wait_for_state',
     description:
-      'Wait (bounded) until the URL contains a string, some text appears, or an element appears/disappears. ' +
-      'Use instead of fixed sleeps.',
+      'Wait (bounded, polled) until the page reaches a state: the URL contains a string, text appears, an element appears ' +
+      'or disappears, an element becomes actionable (visible, enabled, uncovered and stable), a spinner goes away, ' +
+      'the network goes quiet, or a specific request answers. Use instead of fixed sleeps. With several conditions, ' +
+      'all must hold at once.',
     inputSchema: {
       type: 'object',
       additionalProperties: false,
@@ -212,6 +226,10 @@ const MCP_TOOLS = [
         text: { type: 'string', maxLength: 500 },
         target: TARGET,
         targetGone: TARGET,
+        actionable: { ...TARGET, description: 'An element that must be visible, enabled, uncovered and not moving.' },
+        indicatorGone: { type: 'boolean', description: 'Wait until no visible spinner, progress bar or "Loading…" indicator remains.' },
+        networkQuiet: { type: 'boolean', description: 'Wait until no tracked request is in flight and the page has been quiet for a moment.' },
+        requestDone: REQUEST_PATTERN,
         timeoutMs: TIMEOUT,
       },
     },
@@ -383,8 +401,9 @@ const MCP_TOOLS = [
       'Save a workflow from explicit steps. Each step is { tool, args } with tool one of browser_navigate, element_click, ' +
       'field_fill, select_option, wait_for_state, browser_press_key, browser_scroll and args exactly as that tool takes them ' +
       '(no refs, no approvalId). Use "{{param}}" inside strings for values given at run time. A step may also carry ' +
-      'waitBeforeMs (give a slow site that long before this step) and retry (repeat a group of steps on failure); ' +
-      'pace.waitBeforeMs is the workflow-wide default. Pacing is only ever what the person set — never added automatically.',
+      'waitBeforeMs (give a slow site that long before this step), retry (repeat a group of steps on failure), ' +
+      'patience or maxWaitMs (how long to wait for a blocker), and pace.waitBeforeMs is the workflow-wide default. ' +
+      'Pacing is only ever what the person set — never added automatically.',
     inputSchema: {
       type: 'object',
       additionalProperties: false,
@@ -414,6 +433,26 @@ const MCP_TOOLS = [
               note: { type: 'string', maxLength: 200 },
               waitBeforeMs: PACING,
               retry: RETRY,
+              patience: {
+                type: 'string',
+                enum: ['fast', 'normal', 'patient'],
+                description: 'How long this step gives a blocker it waits on: half, the default, or three times the learned budget. Never a fixed sleep.',
+              },
+              maxWaitMs: {
+                type: 'integer', minimum: 100, maximum: LIMITS.MAX_WAIT_MS,
+                description: `An explicit cap on one resolver wait for this step (100–${LIMITS.MAX_WAIT_MS}).`,
+              },
+              expect: {
+                type: 'object',
+                additionalProperties: false,
+                minProperties: 1,
+                description: 'What this step produces. Replay waits for it before calling the step done; no values.',
+                properties: {
+                  appears: { ...TARGET, description: 'An element (usually a dialog) that appears after this step.' },
+                  request: REQUEST_PATTERN,
+                  settleMs: { type: 'integer', minimum: 0, maximum: LIMITS.MAX_STEP_PACING_MS },
+                },
+              },
               onFail: {
                 type: 'string',
                 enum: ['stop', 'skip'],