@tangle-network/browser-agent-driver 0.33.2 → 0.34.0

package/dist/provider-defaults.js

@@ -1,3 +1,19 @@
+/** Runtime list of the `SupportedProvider` union — the single source of truth
+ *  for validating a user-supplied `--provider` string before it is cast. */
+export const SUPPORTED_PROVIDERS = [
+    'openai',
+    'anthropic',
+    'google',
+    'cli-bridge',
+    'codex-cli',
+    'claude-code',
+    'sandbox-backend',
+    'zai-coding-plan',
+];
+/** Narrow an arbitrary string to a `SupportedProvider`. */
+export function isSupportedProvider(value) {
+    return SUPPORTED_PROVIDERS.includes(value);
+}
 /**
  * Z.ai coding plan endpoints. The plan exposes two compatibility surfaces:
  *   - OpenAI-compatible at /api/coding/paas/v4 — works with glm-4.6 / glm-4.5
@@ -55,6 +71,23 @@ export function resolveProviderModelName(provider, requestedModel, options) {
     }
     return model || 'gpt-5.4';
 }
+/**
+ * Pick a default provider when the CLI passed none. Honours a present
+ * `OPENAI_API_KEY` (→ `'openai'`, which resolves to `gpt-5.4` + the OpenAI key)
+ * before falling back to the keyless `'claude-code'` engine. Mirrors the `run`
+ * command's `driverConfig.provider || 'openai'` precedent so design-audit no
+ * longer silently overrides a present OpenAI key with claude-code/sonnet.
+ *
+ * Fail-open offline: with no `OPENAI_API_KEY` the result is still
+ * `'claude-code'`, preserving the zero-key path the engine was designed to run
+ * on. Only the design-audit default site consumes this; explicit `--provider`
+ * still wins, so no other command's behaviour changes.
+ */
+export function resolveDefaultProvider(env = process.env) {
+    if (env.OPENAI_API_KEY)
+        return 'openai';
+    return 'claude-code';
+}
 export function resolveProviderApiKey(provider, explicitApiKey, env = process.env) {
     if (explicitApiKey)
         return explicitApiKey;

package/dist/provider-defaults.js.map

@@ -1 +1 @@
-{"version":3,"file":"provider-defaults.js","sourceRoot":"","sources":["../src/provider-defaults.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"provider-defaults.js","sourceRoot":"","sources":["../src/provider-defaults.ts"],"names":[],"mappings":"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"}

package/dist/runner/allowed-domains.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Allowed-domain helpers — registrable-root derivation used for first-party
+ * subdomain tolerance when enforcing a scenario's allowedDomains boundary.
+ */
+/**
+ * Reduce a hostname to its registrable root (last two labels) so that
+ * `news.example.com` and `example.com` compare equal. Hosts with two or
+ * fewer labels are returned unchanged.
+ */
+export declare function domainRoot(host: string): string;
+//# sourceMappingURL=allowed-domains.d.ts.map

package/dist/runner/allowed-domains.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"allowed-domains.d.ts","sourceRoot":"","sources":["../../src/runner/allowed-domains.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG/C"}

package/dist/runner/allowed-domains.js

@@ -0,0 +1,14 @@
+/**
+ * Allowed-domain helpers — registrable-root derivation used for first-party
+ * subdomain tolerance when enforcing a scenario's allowedDomains boundary.
+ */
+/**
+ * Reduce a hostname to its registrable root (last two labels) so that
+ * `news.example.com` and `example.com` compare equal. Hosts with two or
+ * fewer labels are returned unchanged.
+ */
+export function domainRoot(host) {
+    const parts = host.split('.').filter(Boolean);
+    return parts.length <= 2 ? host : parts.slice(-2).join('.');
+}
+//# sourceMappingURL=allowed-domains.js.map

package/dist/runner/allowed-domains.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"allowed-domains.js","sourceRoot":"","sources":["../../src/runner/allowed-domains.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC9C,OAAO,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC9D,CAAC"}

package/dist/runner/batch-fill.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Batch-fill opportunity detection — injects a "must batch next turn" hint
+ * when the agent starts filling a multi-field form one field at a time.
+ */
+import type { Turn, PageState } from '../types.js';
+/**
+ * Detect when the agent is filling a multi-field form one input at a time and
+ * inject a hint that demands a `fill` batch on the next turn.
+ *
+ * Trigger conditions (all must hold):
+ *   1. The agent's most recent action was a single-step `type` on the
+ *      current URL
+ *   2. The current snapshot has 2+ unused fillable refs (textbox /
+ *      searchbox / combobox) that the agent hasn't typed into yet
+ *   3. We haven't already injected this hint in the last turn (to avoid
+ *      hint loops if the agent ignores it)
+ *
+ * The detector fires after one type action when two or more unused fields
+ * remain, which catches common two-field-per-step forms before the agent
+ * burns extra turns.
+ *
+ * The hint is high-priority (100) so it survives ctxBudget truncation, and
+ * it explicitly lists the unused @refs from the current snapshot so the LLM
+ * doesn't have to guess. The injection is gated by BAD_BATCH_HINT=0 for
+ * rollback.
+ */
+export declare function detectBatchFillOpportunity(turns: Turn[], state: PageState): string | null;
+//# sourceMappingURL=batch-fill.d.ts.map

package/dist/runner/batch-fill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-fill.d.ts","sourceRoot":"","sources":["../../src/runner/batch-fill.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAElD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,CAiDzF"}

package/dist/runner/batch-fill.js

@@ -0,0 +1,80 @@
+/**
+ * Batch-fill opportunity detection — injects a "must batch next turn" hint
+ * when the agent starts filling a multi-field form one field at a time.
+ */
+/**
+ * Detect when the agent is filling a multi-field form one input at a time and
+ * inject a hint that demands a `fill` batch on the next turn.
+ *
+ * Trigger conditions (all must hold):
+ *   1. The agent's most recent action was a single-step `type` on the
+ *      current URL
+ *   2. The current snapshot has 2+ unused fillable refs (textbox /
+ *      searchbox / combobox) that the agent hasn't typed into yet
+ *   3. We haven't already injected this hint in the last turn (to avoid
+ *      hint loops if the agent ignores it)
+ *
+ * The detector fires after one type action when two or more unused fields
+ * remain, which catches common two-field-per-step forms before the agent
+ * burns extra turns.
+ *
+ * The hint is high-priority (100) so it survives ctxBudget truncation, and
+ * it explicitly lists the unused @refs from the current snapshot so the LLM
+ * doesn't have to guess. The injection is gated by BAD_BATCH_HINT=0 for
+ * rollback.
+ */
+export function detectBatchFillOpportunity(turns, state) {
+    if (turns.length === 0)
+        return null;
+    const lastTurn = turns[turns.length - 1];
+    // Last action must be a single-step type on the current URL
+    if (lastTurn.action.action !== 'type')
+        return null;
+    if (lastTurn.state.url !== state.url)
+        return null;
+    // Collect the @refs the agent has typed into across the ENTIRE run on
+    // the same URL. The detector should never ask the agent to re-fill a
+    // field it already filled, even if the earlier fill happened many
+    // turns ago.
+    const usedRefs = new Set();
+    for (const t of turns) {
+        if (t.state.url !== state.url)
+            continue;
+        const a = t.action;
+        if (a.action === 'type' && 'selector' in a && typeof a.selector === 'string') {
+            usedRefs.add(a.selector);
+        }
+        if (a.action === 'fill') {
+            for (const k of Object.keys(a.fields ?? {}))
+                usedRefs.add(k);
+            for (const k of Object.keys(a.selects ?? {}))
+                usedRefs.add(k);
+            for (const k of a.checks ?? [])
+                usedRefs.add(k);
+        }
+    }
+    // Find unused fillable refs in the current snapshot. We look for textbox,
+    // searchbox, combobox, and spinbutton roles — anything that takes text.
+    // Snapshot lines look like: `  - textbox "First name" [ref=t1f2a]`
+    const unusedRefs = [];
+    for (const line of state.snapshot.split('\n')) {
+        const match = line.match(/\b(textbox|searchbox|combobox|spinbutton)\b[^"]*"([^"]*)"[^[]*\[ref=([^\]]+)\]/i);
+        if (!match)
+            continue;
+        const role = match[1].toLowerCase();
+        const name = match[2];
+        const ref = `@${match[3]}`;
+        if (usedRefs.has(ref))
+            continue;
+        unusedRefs.push({ ref, name, role });
+    }
+    // Need at least 2 unused fields to make batching worthwhile
+    if (unusedRefs.length < 2)
+        return null;
+    const refList = unusedRefs
+        .slice(0, 12) // cap so we don't explode the prompt
+        .map((u) => `  - ${u.ref} (${u.role}: "${u.name}")`)
+        .join('\n');
+    return `\n[BATCH FILL REQUIRED]\nYou just typed into a single field, but ${unusedRefs.length} more fillable fields are visible on this same form. STOP. Your NEXT action MUST be a \`fill\` action that batches ALL remaining unused fields on this page in one turn. Do not emit another single-step \`type\` — emit \`fill\` with multiple entries.\n\nUnused fillable @refs from the current snapshot (use these in your \`fill.fields\` map):\n${refList}\n\nExample:\n{\"action\":\"fill\",\"fields\":{\"${unusedRefs[0].ref}\":\"value1\",\"${unusedRefs[1].ref}\":\"value2\"}}\n`;
+}
+//# sourceMappingURL=batch-fill.js.map

package/dist/runner/batch-fill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-fill.js","sourceRoot":"","sources":["../../src/runner/batch-fill.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,0BAA0B,CAAC,KAAa,EAAE,KAAgB;IACxE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IACnC,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IAExC,4DAA4D;IAC5D,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,KAAK,MAAM;QAAE,OAAO,IAAI,CAAA;IAClD,IAAI,QAAQ,CAAC,KAAK,CAAC,GAAG,KAAK,KAAK,CAAC,GAAG;QAAE,OAAO,IAAI,CAAA;IAEjD,sEAAsE;IACtE,qEAAqE;IACrE,kEAAkE;IAClE,aAAa;IACb,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAA;IAClC,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,KAAK,KAAK,CAAC,GAAG;YAAE,SAAQ;QACvC,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAA;QAClB,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,IAAI,UAAU,IAAI,CAAC,IAAI,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YAC7E,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAA;QAC1B,CAAC;QACD,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YACxB,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC;gBAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;YAC5D,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC;gBAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;YAC7D,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,IAAI,EAAE;gBAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;QACjD,CAAC;IACH,CAAC;IAED,0EAA0E;IAC1E,wEAAwE;IACxE,mEAAmE;IACnE,MAAM,UAAU,GAAuD,EAAE,CAAA;IACzE,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,iFAAiF,CAAC,CAAA;QAC3G,IAAI,CAAC,KAAK;YAAE,SAAQ;QACpB,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAA;QACnC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAA;QACrB,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAA;QAC1B,IAAI,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,SAAQ;QAC/B,UAAU,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;IACtC,CAAC;IAED,4DAA4D;IAC5D,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA;IAEtC,MAAM,OAAO,GAAG,UAAU;SACvB,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,qCAAqC;SAClD,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,IAAI,IAAI,CAAC;SACnD,IAAI,CAAC,IAAI,CAAC,CAAA;IAEb,OAAO,oEAAoE,UAAU,CAAC,MAAM,yVAAyV,OAAO,oDAAoD,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,mBAAmB,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,mBAAmB,CAAA;AAC1jB,CAAC"}

package/dist/runner/completion-policy.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Completion-result policy — decides whether a planner-emitted complete.result
+ * is a fabricated placeholder and whether runScript output is usable enough to
+ * auto-complete on. The plan executor and the per-action loop both consult these.
+ */
+/**
+ * Detect placeholder patterns in a planner-generated complete.result.
+ *
+ * The planner has to commit to its `complete.result` text BEFORE any prior
+ * runScript step actually runs, so on extraction tasks it fabricates
+ * placeholders. We detect those patterns and substitute the runScript
+ * output (deterministic, no extra LLM call).
+ *
+ * Patterns we catch:
+ *   - JSON `null` literals (e.g. `{"x": null, "y": null}`)
+ *   - "<from prior step>", "<placeholder>", "<value from ...>", "<extracted ...>", "<observed ...>"
+ *   - "{{...}}" template markers
+ *
+ * Conservative on purpose — we only substitute when the planner clearly
+ * didn't know real values at planning time. A complete.result that contains
+ * actual data (no nulls, no placeholder markers) passes through unchanged.
+ */
+export declare function hasPlaceholderPattern(text: string): boolean;
+/** Returns true only when runScript output contains usable extracted data. */
+export declare function isMeaningfulRunScriptOutput(output: string | null | undefined): boolean;
+//# sourceMappingURL=completion-policy.d.ts.map

package/dist/runner/completion-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion-policy.d.ts","sourceRoot":"","sources":["../../src/runner/completion-policy.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAgB3D;AAED,8EAA8E;AAC9E,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CA2BtF"}

package/dist/runner/completion-policy.js

@@ -0,0 +1,76 @@
+/**
+ * Completion-result policy — decides whether a planner-emitted complete.result
+ * is a fabricated placeholder and whether runScript output is usable enough to
+ * auto-complete on. The plan executor and the per-action loop both consult these.
+ */
+/**
+ * Detect placeholder patterns in a planner-generated complete.result.
+ *
+ * The planner has to commit to its `complete.result` text BEFORE any prior
+ * runScript step actually runs, so on extraction tasks it fabricates
+ * placeholders. We detect those patterns and substitute the runScript
+ * output (deterministic, no extra LLM call).
+ *
+ * Patterns we catch:
+ *   - JSON `null` literals (e.g. `{"x": null, "y": null}`)
+ *   - "<from prior step>", "<placeholder>", "<value from ...>", "<extracted ...>", "<observed ...>"
+ *   - "{{...}}" template markers
+ *
+ * Conservative on purpose — we only substitute when the planner clearly
+ * didn't know real values at planning time. A complete.result that contains
+ * actual data (no nulls, no placeholder markers) passes through unchanged.
+ */
+export function hasPlaceholderPattern(text) {
+    if (typeof text !== 'string' || text.length === 0)
+        return false;
+    if (/<from prior step>|<placeholder>|<value from|<extracted|<observed|<previous step|<runscript output>/i.test(text)) {
+        return true;
+    }
+    if (/\{\{[^}]+\}\}/.test(text)) {
+        return true;
+    }
+    // JSON-shape detection: a result that parses as JSON and contains null
+    // values is almost always a planner-fabricated extraction shell. Pure
+    // strings with the word "null" elsewhere don't match because we look
+    // for the JSON null literal pattern (`: null` or `[null`).
+    if (/:\s*null\b|\[\s*null\b/.test(text)) {
+        return true;
+    }
+    return false;
+}
+/** Returns true only when runScript output contains usable extracted data. */
+export function isMeaningfulRunScriptOutput(output) {
+    if (typeof output !== 'string')
+        return false;
+    const trimmed = output.trim();
+    if (trimmed.length === 0)
+        return false;
+    if (trimmed === 'null' || trimmed === 'undefined' || trimmed === '""' || trimmed === "''")
+        return false;
+    // Empty JSON shells: `{}`, `[]`, `{"x": null}`, `[null, null]`
+    if (trimmed === '{}' || trimmed === '[]')
+        return false;
+    if (hasPlaceholderPattern(trimmed))
+        return false;
+    // If the output parses as JSON and EVERY top-level value is null/empty,
+    // treat it as not meaningful. This catches `{"x": null, "y": ""}` even
+    // though the placeholder regex would already catch the null one.
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            const values = Object.values(parsed);
+            if (values.length > 0) {
+                const allEmpty = values.every((v) => v === null || v === undefined || v === '' || v === 0);
+                if (allEmpty)
+                    return false;
+            }
+        }
+        if (Array.isArray(parsed) && parsed.length === 0)
+            return false;
+    }
+    catch {
+        // Not JSON, that's fine — fall through to "meaningful" if we got here.
+    }
+    return true;
+}
+//# sourceMappingURL=completion-policy.js.map

package/dist/runner/completion-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion-policy.js","sourceRoot":"","sources":["../../src/runner/completion-policy.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IAC/D,IAAI,qGAAqG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACrH,OAAO,IAAI,CAAA;IACb,CAAC;IACD,IAAI,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/B,OAAO,IAAI,CAAA;IACb,CAAC;IACD,uEAAuE;IACvE,sEAAsE;IACtE,qEAAqE;IACrE,2DAA2D;IAC3D,IAAI,wBAAwB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACxC,OAAO,IAAI,CAAA;IACb,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,2BAA2B,CAAC,MAAiC;IAC3E,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAA;IAC5C,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,CAAA;IAC7B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IACtC,IAAI,OAAO,KAAK,MAAM,IAAI,OAAO,KAAK,WAAW,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,KAAK,CAAA;IACvG,+DAA+D;IAC/D,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,KAAK,CAAA;IACtD,IAAI,qBAAqB,CAAC,OAAO,CAAC;QAAE,OAAO,KAAK,CAAA;IAChD,wEAAwE;IACxE,uEAAuE;IACvE,iEAAiE;IACjE,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;QAClC,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YACnE,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;YACpC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACtB,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAC3B,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAC5D,CAAA;gBACD,IAAI,QAAQ;oBAAE,OAAO,KAAK,CAAA;YAC5B,CAAC;QACH,CAAC;QACD,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,KAAK,CAAA;IAChE,CAAC;IAAC,MAAM,CAAC;QACP,uEAAuE;IACzE,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/runner/constants.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Runner constants — defaults and thresholds the main loop and its helpers read.
+ */
+import type { SupervisorConfig } from '../types.js';
+export declare const DEFAULT_MAX_TURNS = 20;
+export declare const DEFAULT_RETRIES = 3;
+export declare const DEFAULT_RETRY_DELAY_MS = 1000;
+export declare const DEFAULT_MICRO_PLAN_ACTIONS = 2;
+export declare const SAFE_MICRO_ACTIONS: Set<"click" | "type" | "scroll" | "navigate" | "wait" | "complete" | "press" | "hover" | "select" | "evaluate" | "runScript" | "extractWithIndex" | "verifyPreview" | "abort" | "fill" | "clickSequence" | "clickAt" | "typeAt" | "clickLabel" | "typeLabel" | "macro" | "fanOut">;
+export declare const DEFAULT_SUPERVISOR: Required<Pick<SupervisorConfig, 'enabled' | 'useVision' | 'minTurnsBeforeInvoke' | 'cooldownTurns' | 'maxInterventions' | 'hardStallWindow'>>;
+export declare const EXTENSION_TURNS_GRANTED = 5;
+export declare const EXTENSION_HARD_CAP = 25;
+export declare const EXTENSION_PROGRESS_LOOKBACK = 3;
+//# sourceMappingURL=constants.d.ts.map

package/dist/runner/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/runner/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAU,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE5D,eAAO,MAAM,iBAAiB,KAAK,CAAC;AACpC,eAAO,MAAM,eAAe,IAAI,CAAC;AACjC,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAC3C,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAE5C,eAAO,MAAM,kBAAkB,oRAA6I,CAAC;AAC7K,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,IAAI,CAAC,gBAAgB,EAAE,SAAS,GAAG,WAAW,GAAG,sBAAsB,GAAG,eAAe,GAAG,kBAAkB,GAAG,iBAAiB,CAAC,CAO5K,CAAC;AAIF,eAAO,MAAM,uBAAuB,IAAI,CAAC;AACzC,eAAO,MAAM,kBAAkB,KAAK,CAAC;AACrC,eAAO,MAAM,2BAA2B,IAAI,CAAC"}

package/dist/runner/constants.js

@@ -0,0 +1,23 @@
+/**
+ * Runner constants — defaults and thresholds the main loop and its helpers read.
+ */
+export const DEFAULT_MAX_TURNS = 20;
+export const DEFAULT_RETRIES = 3;
+export const DEFAULT_RETRY_DELAY_MS = 1000;
+export const DEFAULT_MICRO_PLAN_ACTIONS = 2;
+// Safe action verbs for micro-plans emitted by the model.
+export const SAFE_MICRO_ACTIONS = new Set(['click', 'type', 'press', 'hover', 'select', 'scroll', 'wait', 'clickAt', 'typeAt', 'clickLabel', 'typeLabel']);
+export const DEFAULT_SUPERVISOR = {
+    enabled: true,
+    useVision: true,
+    minTurnsBeforeInvoke: 5,
+    cooldownTurns: 3,
+    maxInterventions: 2,
+    hardStallWindow: 4,
+};
+// One-time max-turns extension thresholds. An active run can receive a single
+// extension when it reaches the configured cap while still making page progress.
+export const EXTENSION_TURNS_GRANTED = 5;
+export const EXTENSION_HARD_CAP = 25;
+export const EXTENSION_PROGRESS_LOOKBACK = 3;
+//# sourceMappingURL=constants.js.map

package/dist/runner/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/runner/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC;AACpC,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC;AACjC,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,CAAC;AAC3C,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC;AAC5C,0DAA0D;AAC1D,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,EAAE,WAAW,CAAC,CAAC,CAAC;AAC7K,MAAM,CAAC,MAAM,kBAAkB,GAAkJ;IAC/K,OAAO,EAAE,IAAI;IACb,SAAS,EAAE,IAAI;IACf,oBAAoB,EAAE,CAAC;IACvB,aAAa,EAAE,CAAC;IAChB,gBAAgB,EAAE,CAAC;IACnB,eAAe,EAAE,CAAC;CACnB,CAAC;AAEF,8EAA8E;AAC9E,iFAAiF;AACjF,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC;AACzC,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAC;AACrC,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC"}

package/dist/runner/decision-screenshot.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Decision-time screenshot attachment: lazily captures a base64 screenshot and
+ * folds it into the PageState when vision is requested for a decide/scout turn.
+ *
+ * Extracted from runner.ts via the delegate + host-interface pattern. The
+ * BrowserAgent class keeps a thin delegator (`attachDecisionScreenshot`); this
+ * free function holds the method body verbatim and reads runner state through
+ * {@link RunnerDecisionScreenshotHost}, which BrowserAgent `implements` so tsc
+ * proves the host surface is complete. Behavior is byte-identical to the
+ * inlined version.
+ */
+import type { Driver } from '../drivers/types.js';
+import type { PageState } from '../types.js';
+/**
+ * The slice of runner state attachDecisionScreenshot reads. The BrowserAgent
+ * class declares `implements RunnerDecisionScreenshotHost`, so a missing or
+ * mistyped member is a compile error — this interface IS the safety gate for
+ * the extraction.
+ */
+export interface RunnerDecisionScreenshotHost {
+    driver: Driver;
+}
+export declare function attachDecisionScreenshotImpl(self: RunnerDecisionScreenshotHost, state: PageState): Promise<PageState>;
+//# sourceMappingURL=decision-screenshot.d.ts.map

package/dist/runner/decision-screenshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-screenshot.d.ts","sourceRoot":"","sources":["../../src/runner/decision-screenshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,WAAW,4BAA4B;IAC3C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAsB,4BAA4B,CAChD,IAAI,EAAE,4BAA4B,EAClC,KAAK,EAAE,SAAS,GACf,OAAO,CAAC,SAAS,CAAC,CAQpB"}

package/dist/runner/decision-screenshot.js

@@ -0,0 +1,23 @@
+/**
+ * Decision-time screenshot attachment: lazily captures a base64 screenshot and
+ * folds it into the PageState when vision is requested for a decide/scout turn.
+ *
+ * Extracted from runner.ts via the delegate + host-interface pattern. The
+ * BrowserAgent class keeps a thin delegator (`attachDecisionScreenshot`); this
+ * free function holds the method body verbatim and reads runner state through
+ * {@link RunnerDecisionScreenshotHost}, which BrowserAgent `implements` so tsc
+ * proves the host surface is complete. Behavior is byte-identical to the
+ * inlined version.
+ */
+export async function attachDecisionScreenshotImpl(self, state) {
+    if (state.screenshot || !self.driver.screenshot)
+        return state;
+    try {
+        const screenshot = await self.driver.screenshot();
+        return { ...state, screenshot: screenshot.toString('base64') };
+    }
+    catch {
+        return state;
+    }
+}
+//# sourceMappingURL=decision-screenshot.js.map

package/dist/runner/decision-screenshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-screenshot.js","sourceRoot":"","sources":["../../src/runner/decision-screenshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAeH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAChD,IAAkC,EAClC,KAAgB;IAEhB,IAAI,KAAK,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU;QAAE,OAAO,KAAK,CAAC;IAC9D,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;QAClD,OAAO,EAAE,GAAG,KAAK,EAAE,UAAU,EAAE,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;IACjE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/runner/domain-boundary.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Allowed-domain enforcement: filtering scout candidates to in-scope hosts,
+ * blocking disallowed search-result clicks before they fire, and snapping the
+ * agent back inside the allowed host set when navigation strays.
+ *
+ * Extracted from runner.ts via the delegate + host-interface pattern. The
+ * BrowserAgent class keeps thin delegators (`filterScoutCandidatesByAllowedDomains`,
+ * `inspectDisallowedSearchClick`, `enforceAllowedDomainBoundary`); these free
+ * functions hold the method bodies verbatim and read runner state through
+ * {@link RunnerDomainHost}, which BrowserAgent `implements` so tsc proves the
+ * host surface is complete. Behavior is byte-identical to the inlined versions
+ * — same ordering, subdomain tolerance, and message text.
+ */
+import type { Driver } from '../drivers/types.js';
+import type { Action, PageState, Scenario } from '../types.js';
+/**
+ * The slice of runner state the allowed-domain enforcement helpers read. The
+ * BrowserAgent class declares `implements RunnerDomainHost`, so a missing or
+ * mistyped member is a compile error — this interface IS the safety gate for
+ * the extraction.
+ */
+export interface RunnerDomainHost {
+    driver: Driver;
+}
+export declare function filterScoutCandidatesByAllowedDomainsImpl(self: RunnerDomainHost, candidates: Array<{
+    ref: string;
+    text: string;
+    score: number;
+}>, allowedDomains: string[] | undefined): Promise<Array<{
+    ref: string;
+    text: string;
+    score: number;
+}>>;
+export declare function inspectDisallowedSearchClickImpl(self: RunnerDomainHost, state: PageState, scenario: Scenario, action: Action): Promise<string | undefined>;
+export declare function enforceAllowedDomainBoundaryImpl(self: RunnerDomainHost, preActionState: PageState, scenario: Scenario): Promise<string | undefined>;
+//# sourceMappingURL=domain-boundary.d.ts.map

package/dist/runner/domain-boundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain-boundary.d.ts","sourceRoot":"","sources":["../../src/runner/domain-boundary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAM/D;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAsB,yCAAyC,CAC7D,IAAI,EAAE,gBAAgB,EACtB,UAAU,EAAE,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,EAC/D,cAAc,EAAE,MAAM,EAAE,GAAG,SAAS,GACnC,OAAO,CAAC,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAgB9D;AAED,wBAAsB,gCAAgC,CACpD,IAAI,EAAE,gBAAgB,EACtB,KAAK,EAAE,SAAS,EAChB,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAkB7B;AAED,wBAAsB,gCAAgC,CACpD,IAAI,EAAE,gBAAgB,EACtB,cAAc,EAAE,SAAS,EACzB,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAyB7B"}

package/dist/runner/domain-boundary.js

@@ -0,0 +1,81 @@
+/**
+ * Allowed-domain enforcement: filtering scout candidates to in-scope hosts,
+ * blocking disallowed search-result clicks before they fire, and snapping the
+ * agent back inside the allowed host set when navigation strays.
+ *
+ * Extracted from runner.ts via the delegate + host-interface pattern. The
+ * BrowserAgent class keeps thin delegators (`filterScoutCandidatesByAllowedDomains`,
+ * `inspectDisallowedSearchClick`, `enforceAllowedDomainBoundary`); these free
+ * functions hold the method bodies verbatim and read runner state through
+ * {@link RunnerDomainHost}, which BrowserAgent `implements` so tsc proves the
+ * host surface is complete. Behavior is byte-identical to the inlined versions
+ * — same ordering, subdomain tolerance, and message text.
+ */
+import { safeHostname } from './utils.js';
+import { buildSearchResultsGuidance } from './search-guidance.js';
+import { domainRoot } from './allowed-domains.js';
+export async function filterScoutCandidatesByAllowedDomainsImpl(self, candidates, allowedDomains) {
+    if (!allowedDomains || allowedDomains.length === 0 || !self.driver.inspectSelectorHref) {
+        return candidates;
+    }
+    const allowedHosts = new Set(allowedDomains.map((domain) => domain.toLowerCase()));
+    const resolved = await Promise.all(candidates.map(async (candidate) => {
+        const href = await self.driver.inspectSelectorHref(candidate.ref).catch(() => undefined);
+        const host = href ? safeHostname(href) : undefined;
+        return { candidate, host };
+    }));
+    return resolved
+        .filter(({ host }) => !host || allowedHosts.has(host))
+        .map(({ candidate }) => candidate);
+}
+export async function inspectDisallowedSearchClickImpl(self, state, scenario, action) {
+    if (action.action !== 'click')
+        return undefined;
+    if (!scenario.allowedDomains || scenario.allowedDomains.length === 0)
+        return undefined;
+    if (!buildSearchResultsGuidance(state, scenario.goal, scenario.allowedDomains))
+        return undefined;
+    if (!self.driver.inspectSelectorHref)
+        return undefined;
+    const href = await self.driver.inspectSelectorHref(action.selector);
+    const host = href ? safeHostname(href) : undefined;
+    if (!href || !host)
+        return undefined;
+    const allowedLower = scenario.allowedDomains.map((domain) => domain.toLowerCase());
+    if (allowedLower.includes(host))
+        return undefined;
+    // First-party subdomain tolerance
+    if (allowedLower.some((h) => domainRoot(h) === domainRoot(host)))
+        return undefined;
+    return [
+        `Blocked action: selector ${action.selector} resolves to ${href}, which is outside the allowed host set: ${scenario.allowedDomains.join(', ')}.`,
+        'Choose a result from an allowed host instead, even if the snippet text looks relevant.',
+    ].join(' ');
+}
+export async function enforceAllowedDomainBoundaryImpl(self, preActionState, scenario) {
+    if (!scenario.allowedDomains || scenario.allowedDomains.length === 0)
+        return undefined;
+    const currentUrl = self.driver.getUrl?.() ?? preActionState.url;
+    const currentHost = safeHostname(currentUrl);
+    if (!currentHost)
+        return undefined;
+    const allowedHosts = scenario.allowedDomains.map((domain) => domain.toLowerCase());
+    if (allowedHosts.includes(currentHost))
+        return undefined;
+    // First-party subdomain tolerance: allow navigation within the same registrable domain
+    const currentRoot = domainRoot(currentHost);
+    if (allowedHosts.some((h) => domainRoot(h) === currentRoot))
+        return undefined;
+    const previousHost = safeHostname(preActionState.url);
+    if (previousHost && allowedHosts.includes(previousHost)) {
+        await self.driver.execute({ action: 'navigate', url: preActionState.url }).catch(() => { });
+    }
+    else if (scenario.startUrl) {
+        await self.driver.execute({ action: 'navigate', url: scenario.startUrl }).catch(() => { });
+    }
+    return [
+        `Boundary violation: landed on ${currentUrl}, but the allowed host set is ${allowedHosts.join(', ')}.`,
+        'Return to an allowed host and continue from there; do not rely on disallowed subdomains even if their snippet looks relevant.',
+    ].join(' ');
+}
+//# sourceMappingURL=domain-boundary.js.map

package/dist/runner/domain-boundary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain-boundary.js","sourceRoot":"","sources":["../../src/runner/domain-boundary.ts"],"names":[],"mappings":"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"}

package/dist/runner/effect-verify.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Per-action effect verification: the helper the runner loop calls after each
+ * executed action to decide whether the expected effect actually landed.
+ *
+ * Extracted from runner.ts via the delegate + host-interface pattern. The
+ * BrowserAgent class keeps a thin delegator (`verifyEffect`); this free
+ * function holds the method body verbatim and reads runner state through
+ * {@link RunnerEffectVerifyHost}, which BrowserAgent `implements` so tsc proves
+ * the host surface is complete. Behavior is byte-identical to the inlined
+ * version — same settle-wait conditions, timing, and verifier call.
+ */
+import type { Driver } from '../drivers/types.js';
+import type { Action, PageState } from '../types.js';
+/**
+ * The slice of runner state the effect verifier reads. The BrowserAgent class
+ * declares `implements RunnerEffectVerifyHost`, so a missing or mistyped member
+ * is a compile error — this interface IS the safety gate for the extraction.
+ * All members are public on BrowserAgent by construction.
+ */
+export interface RunnerEffectVerifyHost {
+    driver: Driver;
+    cachedPostState: PageState | undefined;
+}
+export declare function verifyEffectImpl(self: RunnerEffectVerifyHost, expectedEffect: string, preActionState: PageState, actionType?: Action['action']): Promise<{
+    verified: boolean;
+    reason?: string;
+}>;
+//# sourceMappingURL=effect-verify.d.ts.map

package/dist/runner/effect-verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effect-verify.d.ts","sourceRoot":"","sources":["../../src/runner/effect-verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAIrD;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,SAAS,GAAG,SAAS,CAAC;CACxC;AAED,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,sBAAsB,EAC5B,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,SAAS,EACzB,UAAU,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,GAC5B,OAAO,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA4BjD"}