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

package/README.md

@@ -39,10 +39,29 @@ Installs the `bad` command, downloads Chromium, adds PATH. Requires Node.js 20+.
 Or via npm:
 
 ```bash
-npm i -g @tangle-network/browser-agent-driver
+npm install -g @tangle-network/browser-agent-driver
 npx playwright install chromium
 ```
 
+Do not install the unscoped `bad` package from npm. It is unrelated to Tangle. The `bad` command is installed by `@tangle-network/browser-agent-driver`.
+
+## Agent Discovery
+
+Agents should read the product manifest before generating Browser Agent integration code:
+
+- Manifest: https://tangle.tools/.well-known/tangle-browser-agent.json
+- Product page: https://tangle.tools/services/browser-agent
+- Scoped npm package: `@tangle-network/browser-agent-driver`
+- CLI binary: `bad`
+
+Safe discovery commands:
+
+```bash
+bad --help
+bad run --help
+bad snapshot --help
+```
+
 ### As a library
 
 ```bash
@@ -488,6 +507,28 @@ bad view audit-results/stripe.com-1775502457141
 
 Web UI with per-turn screenshots, action JSON, reasoning, element highlights. Pair with `--show-cursor` for animated cursor recordings.
 
+### Shareable run videos
+
+A run's `report.json` is a complete trace — per-turn screenshot, action, and reasoning — so it renders directly into a shareable video via [`run-capsule`](https://github.com/tangle-network/run-capsule), no extra capture step:
+
+```bash
+npx run-capsule --playwright agent-results/report.json --no-upload
+# → screen.mp4  (real product frames, each captioned with the agent's 💭 reasoning + action + URL)
+# → replay.mp4  (the unified storyboard)
+```
+
+For the **animated cursor**, run with `--show-cursor` (bakes the cursor + reasoning overlay into the run's own `recording.webm`) and hand that recording to `run-capsule` as the screen capsule — it's reused as-is rather than rebuilt, so the real cursor motion survives, with the reasoning storyboard rendered from the trace alongside:
+
+```bash
+bad run --goal "…" --url https://… --show-cursor
+npx run-capsule --playwright agent-results/report.json \
+  --video agent-results/cli-task/recording.webm --no-upload
+# → screen.mp4  (the real run recording — animated cursor + overlay)
+# → replay.mp4  (reasoning storyboard from the trace)
+```
+
+Needs a `run-capsule` whose Playwright adapter understands this driver's suite-shaped `report.json` ([tangle-network/run-capsule#4](https://github.com/tangle-network/run-capsule/pull/4); earlier versions read a bare `TestResult` and render an empty capsule for a suite) and, for `--video`, the recording-ingest path ([#5](https://github.com/tangle-network/run-capsule/pull/5)). Without `--video`, the `screen` capsule replays the per-turn screenshots — real frames only when the run captured them (vision is on by default unless you pass `--no-vision` or a vision-off benchmark profile, which blocks images for speed). Drop `--no-upload` for a temporary public link.
+
 ## Guides
 
 - [Configuration Reference](./docs/guides/configuration.md)

package/discovery/llms.txt

@@ -0,0 +1,27 @@
+# Tangle Browser Agent
+
+Tangle Browser Agent is the `@tangle-network/browser-agent-driver` package and `bad` CLI for agentic browser automation, UI testing, wallet flows, extraction, and evidence capture.
+
+## Canonical discovery
+
+- Live manifest: https://tangle.tools/.well-known/tangle-browser-agent.json
+- Product page: https://tangle.tools/services/browser-agent
+- Source: https://github.com/tangle-network/browser-agent-driver
+- npm: https://www.npmjs.com/package/@tangle-network/browser-agent-driver
+
+## Install
+
+```bash
+npm install -g @tangle-network/browser-agent-driver
+npx playwright install chromium
+```
+
+Do not install the unscoped `bad` package from npm. It is unrelated to Tangle.
+
+## Safe discovery commands
+
+```bash
+bad --help
+bad run --help
+bad snapshot --help
+```

package/discovery/tangle-agent.json

@@ -0,0 +1,36 @@
+{
+  "schema_version": "2026-06-16",
+  "name": "Tangle Browser Agent",
+  "description": "Browser automation driver and bad CLI for agentic web tasks, UI regression testing, wallet flows, and evidence capture.",
+  "homepage": "https://tangle.tools/services/browser-agent",
+  "manifest": "https://tangle.tools/.well-known/tangle-browser-agent.json",
+  "llms": "https://tangle.tools/llms.txt",
+  "repo": "https://github.com/tangle-network/browser-agent-driver",
+  "npm": "@tangle-network/browser-agent-driver",
+  "install": [
+    "npm install -g @tangle-network/browser-agent-driver",
+    "npx playwright install chromium"
+  ],
+  "cli": {
+    "bin": "bad",
+    "safe_discovery_commands": [
+      "bad --help",
+      "bad run --help",
+      "bad snapshot --help"
+    ]
+  },
+  "sdk": {
+    "package": "@tangle-network/browser-agent-driver",
+    "exports": [
+      "BrowserAgent",
+      "PlaywrightDriver"
+    ],
+    "peer_dependency": "playwright"
+  },
+  "environment": {
+    "openai_key": "OPENAI_API_KEY",
+    "anthropic_key": "ANTHROPIC_API_KEY",
+    "google_key": "GOOGLE_GENERATIVE_AI_API_KEY",
+    "proxy_url": "BAD_PROXY_URL"
+  }
+}

package/dist/brain/action-parse.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Action parsing + runtime validation for LLM-emitted action JSON.
+ *
+ * Pure functions, no shared state — `parseNextActions` takes the valid-action
+ * set as a parameter so it stays decoupled from the Brain class.
+ */
+import type { Action } from '../types.js';
+declare function parseNextActions(parsed: Record<string, unknown>, validActions: Set<string>): Action[] | undefined;
+/**
+ * Runtime validation of LLM-parsed action objects.
+ * Ensures required fields are present and correctly typed per action variant.
+ * Throws on missing/invalid fields so the caller can abort gracefully.
+ */
+declare function validateAction(actionType: string, data: Record<string, unknown>): Action;
+export { parseNextActions, validateAction };
+//# sourceMappingURL=action-parse.d.ts.map

package/dist/brain/action-parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-parse.d.ts","sourceRoot":"","sources":["../../src/brain/action-parse.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,iBAAS,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,GAAG,SAAS,CAmB1G;AAED;;;;GAIG;AACH,iBAAS,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAiJjF;AAWD,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,CAAC"}

package/dist/brain/action-parse.js

@@ -0,0 +1,191 @@
+/**
+ * Action parsing + runtime validation for LLM-emitted action JSON.
+ *
+ * Pure functions, no shared state — `parseNextActions` takes the valid-action
+ * set as a parameter so it stays decoupled from the Brain class.
+ */
+function parseNextActions(parsed, validActions) {
+    if (!Array.isArray(parsed.nextActions)) {
+        return undefined;
+    }
+    const nextActions = [];
+    for (const entry of parsed.nextActions.slice(0, 3)) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const rawEntry = entry;
+        const actionType = typeof rawEntry.action === 'string' ? rawEntry.action : undefined;
+        if (!actionType || !validActions.has(actionType))
+            continue;
+        try {
+            nextActions.push(validateAction(actionType, rawEntry));
+        }
+        catch {
+            // Best effort: ignore malformed follow-up action.
+        }
+    }
+    return nextActions.length > 0 ? nextActions : undefined;
+}
+/**
+ * Runtime validation of LLM-parsed action objects.
+ * Ensures required fields are present and correctly typed per action variant.
+ * Throws on missing/invalid fields so the caller can abort gracefully.
+ */
+function validateAction(actionType, data) {
+    const requireStr = (field) => {
+        const v = data[field];
+        if (typeof v !== 'string' || !v)
+            throw new Error(`${actionType} action requires "${field}" (string)`);
+        return v;
+    };
+    const optStr = (field) => {
+        const v = data[field];
+        return typeof v === 'string' ? v : '';
+    };
+    const num = (v, fallback) => (typeof v === 'number' ? v : fallback);
+    switch (actionType) {
+        case 'click':
+            return { action: 'click', selector: requireStr('selector') };
+        case 'type':
+            return { action: 'type', selector: requireStr('selector'), text: optStr('text') };
+        case 'press':
+            return { action: 'press', selector: requireStr('selector'), key: requireStr('key') };
+        case 'hover':
+            return { action: 'hover', selector: requireStr('selector') };
+        case 'select':
+            return { action: 'select', selector: requireStr('selector'), value: optStr('value') };
+        case 'scroll':
+            return {
+                action: 'scroll',
+                direction: data.direction === 'up' ? 'up' : 'down',
+                ...(data.amount != null ? { amount: num(data.amount, 500) } : {}),
+            };
+        case 'navigate':
+            return { action: 'navigate', url: requireStr('url') };
+        case 'wait':
+            return { action: 'wait', ms: num(data.ms, 1000) };
+        case 'evaluate':
+            return { action: 'evaluate', criteria: optStr('criteria') };
+        case 'runScript':
+            return { action: 'runScript', script: requireStr('script') };
+        case 'extractWithIndex': {
+            const query = requireStr('query');
+            const contains = typeof data.contains === 'string' ? data.contains : '';
+            return {
+                action: 'extractWithIndex',
+                query,
+                ...(contains ? { contains } : {}),
+            };
+        }
+        case 'verifyPreview':
+            return { action: 'verifyPreview' };
+        case 'complete':
+            return { action: 'complete', result: optStr('result') };
+        case 'abort':
+            return { action: 'abort', reason: optStr('reason') || 'No reason provided' };
+        case 'fill': {
+            // Multi-field batch fill — at least one of fields/selects/checks must be non-empty
+            const fields = isStringRecord(data.fields) ? data.fields : undefined;
+            const selects = isStringRecord(data.selects) ? data.selects : undefined;
+            const checks = Array.isArray(data.checks) && data.checks.every((c) => typeof c === 'string')
+                ? data.checks
+                : undefined;
+            const fieldCount = (fields ? Object.keys(fields).length : 0)
+                + (selects ? Object.keys(selects).length : 0)
+                + (checks ? checks.length : 0);
+            if (fieldCount === 0) {
+                throw new Error('fill action requires at least one of "fields" (object), "selects" (object), or "checks" (string[])');
+            }
+            return {
+                action: 'fill',
+                ...(fields ? { fields } : {}),
+                ...(selects ? { selects } : {}),
+                ...(checks ? { checks } : {}),
+            };
+        }
+        case 'clickSequence': {
+            const refs = Array.isArray(data.refs) && data.refs.every((r) => typeof r === 'string')
+                ? data.refs
+                : null;
+            if (!refs || refs.length === 0) {
+                throw new Error('clickSequence action requires "refs" (string[]) with at least one entry');
+            }
+            return {
+                action: 'clickSequence',
+                refs,
+                ...(typeof data.intervalMs === 'number' ? { intervalMs: data.intervalMs } : {}),
+            };
+        }
+        // Vision-first coordinate actions.
+        case 'clickAt':
+            return { action: 'clickAt', x: num(data.x, 0), y: num(data.y, 0) };
+        case 'typeAt':
+            return { action: 'typeAt', x: num(data.x, 0), y: num(data.y, 0), text: optStr('text') };
+        // Set-of-Marks label-based actions.
+        case 'clickLabel':
+            return { action: 'clickLabel', label: num(data.label, 0) };
+        case 'typeLabel':
+            return { action: 'typeLabel', label: num(data.label, 0), text: optStr('text') };
+        // Macro invocation. The driver validates the name and required args at
+        // execute time; macros without params may omit args.
+        case 'macro': {
+            const args = {};
+            if (data.args && typeof data.args === 'object' && !Array.isArray(data.args)) {
+                for (const [k, v] of Object.entries(data.args)) {
+                    if (typeof v === 'string')
+                        args[k] = v;
+                }
+            }
+            return {
+                action: 'macro',
+                name: requireStr('name'),
+                ...(Object.keys(args).length > 0 ? { args } : {}),
+            };
+        }
+        case 'fanOut': {
+            // Accept either explicit subGoals[] or the shorthand
+            // baseUrl+goalTemplate+items trio. resolveSubGoals() in
+            // runner/fan-out.ts expands shorthand → subGoals at execute time.
+            const subGoals = Array.isArray(data.subGoals)
+                ? data.subGoals
+                    .filter((s) => s && typeof s === 'object')
+                    .map((s) => ({
+                    url: typeof s.url === 'string' ? s.url : '',
+                    goal: typeof s.goal === 'string' ? s.goal : '',
+                    ...(typeof s.label === 'string' ? { label: s.label } : {}),
+                    ...(typeof s.maxTurns === 'number' ? { maxTurns: s.maxTurns } : {}),
+                }))
+                    .filter((s) => s.url && s.goal)
+                : undefined;
+            const baseUrl = typeof data.baseUrl === 'string' ? data.baseUrl : undefined;
+            const goalTemplate = typeof data.goalTemplate === 'string' ? data.goalTemplate : undefined;
+            const items = Array.isArray(data.items) && data.items.every((i) => typeof i === 'string')
+                ? data.items
+                : undefined;
+            const hasExplicit = subGoals && subGoals.length > 0;
+            const hasShorthand = baseUrl && goalTemplate && items && items.length > 0;
+            if (!hasExplicit && !hasShorthand) {
+                throw new Error('fanOut action requires either "subGoals" (array of {url,goal}) or the shorthand trio "baseUrl" + "goalTemplate" + "items" (non-empty string[])');
+            }
+            return {
+                action: 'fanOut',
+                ...(hasExplicit ? { subGoals } : {}),
+                ...(hasShorthand ? { baseUrl, goalTemplate, items } : {}),
+                ...(typeof data.summarize === 'string' ? { summarize: data.summarize } : {}),
+            };
+        }
+        default:
+            throw new Error(`Unknown action type: ${actionType}`);
+    }
+}
+/** Type guard: value is a Record<string, string> */
+function isStringRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    for (const v of Object.values(value)) {
+        if (typeof v !== 'string')
+            return false;
+    }
+    return true;
+}
+export { parseNextActions, validateAction };
+//# sourceMappingURL=action-parse.js.map

package/dist/brain/action-parse.js.map

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

package/dist/brain/decide.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The hot-loop decision methods for the Brain engine: the DOM-first `decide`
+ * path, the vision-first / hybrid `decideVision` path, the navigation-model
+ * routing classifier they share, and the tolerant JSON decision parser.
+ *
+ * Extracted from brain/index.ts via the delegate + host-interface pattern.
+ * The Brain class keeps thin delegators (`decide`, `decideVision`, `parse`);
+ * these free functions hold the method bodies verbatim and read/write Brain
+ * state through {@link BrainDecideHost}, which Brain `implements` so tsc proves
+ * the host surface is complete. Behavior is byte-identical to the inlined
+ * versions — same ordering, thresholds, retries, and prompt text.
+ */
+import type { ModelMessage, SystemModelMessage } from 'ai';
+import type { PageState } from '../types.js';
+import type { BrainDecision, UserContent } from './types.js';
+import type { BrainProvider, ModelSelection, GenerateResult } from './model-client.js';
+/**
+ * The slice of Brain state the decision hot loop reads/writes. Brain declares
+ * `implements BrainDecideHost`, so a missing or mistyped member is a compile
+ * error — this interface IS the safety gate for the extraction. All members
+ * are public on Brain by construction.
+ */
+export interface BrainDecideHost {
+    provider: BrainProvider;
+    modelName: string;
+    navProvider?: BrainProvider;
+    navModelName?: string;
+    adaptiveModelRouting: boolean;
+    observationMode: 'dom' | 'vision' | 'hybrid';
+    visionStrategy: 'always' | 'never' | 'auto';
+    compactFirstTurn: boolean;
+    lastDecisionUrl?: string;
+    history: ModelMessage[];
+    maxHistoryTurns: number;
+    debug: boolean;
+    baseUrl?: string;
+    buildUserContent(text: string, screenshot?: string, forceVision?: boolean): UserContent;
+    buildSystemForDecide(goal: string, state: PageState, turn: number, providerName: BrainProvider): string | SystemModelMessage[];
+    generate(system: string | SystemModelMessage[], messages: ModelMessage[], selection?: ModelSelection, maxOutputTokens?: number): Promise<GenerateResult>;
+}
+export declare function decideImpl(self: BrainDecideHost, goal: string, state: PageState, extraContext?: string, turnInfo?: {
+    current: number;
+    max: number;
+}, options?: {
+    forceVision?: boolean;
+}): Promise<BrainDecision>;
+/**
+ * Vision-first decision path. The screenshot is the primary
+ * observation; DOM snapshot is minimal context (URL, title only in pure
+ * vision mode, or compact DOM in hybrid mode). The LLM outputs
+ * coordinate-based actions (clickAt, typeAt) in 1024×768 virtual space.
+ */
+export declare function decideVisionImpl(self: BrainDecideHost, goal: string, state: PageState, extraContext?: string, turnInfo?: {
+    current: number;
+    max: number;
+}): Promise<BrainDecision>;
+export declare function parseDecision(raw: string): Omit<BrainDecision, 'raw' | 'tokensUsed'>;
+//# sourceMappingURL=decide.d.ts.map

package/dist/brain/decide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decide.d.ts","sourceRoot":"","sources":["../../src/brain/decide.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,IAAI,CAAC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAS7C,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEvF;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,aAAa,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,aAAa,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oBAAoB,EAAE,OAAO,CAAC;IAC9B,eAAe,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC7C,cAAc,EAAE,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;IAC5C,gBAAgB,EAAE,OAAO,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,OAAO,GAAG,WAAW,CAAC;IACxF,oBAAoB,CAClB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,aAAa,GAC1B,MAAM,GAAG,kBAAkB,EAAE,CAAC;IACjC,QAAQ,CACN,MAAM,EAAE,MAAM,GAAG,kBAAkB,EAAE,EACrC,QAAQ,EAAE,YAAY,EAAE,EACxB,SAAS,CAAC,EAAE,cAAc,EAC1B,eAAe,CAAC,EAAE,MAAM,GACvB,OAAO,CAAC,cAAc,CAAC,CAAC;CAC5B;AA4BD,wBAAsB,UAAU,CAC9B,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,SAAS,EAChB,YAAY,CAAC,EAAE,MAAM,EACrB,QAAQ,CAAC,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EAC3C,OAAO,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,GAClC,OAAO,CAAC,aAAa,CAAC,CAkMxB;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,SAAS,EAChB,YAAY,CAAC,EAAE,MAAM,EACrB,QAAQ,CAAC,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC1C,OAAO,CAAC,aAAa,CAAC,CA6HxB;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,YAAY,CAAC,CAoFpF"}