@framers/agentos-ext-browser-automation 0.1.0 → 0.2.1

package/dist/attach/AttachController.js

@@ -0,0 +1,286 @@
+/**
+ * @fileoverview AttachController — the one object allowed to touch an attached
+ * (user-owned, already-running) browser.
+ *
+ * Non-negotiable contract, enforced here rather than by convention:
+ *
+ *  1. ATTACH-ONLY. The controller can never launch a browser. When the target
+ *     is missing or fails identity verification it ABORTS with a structured
+ *     error — it must not "helpfully" spawn Chrome (Codex spec review F9).
+ *  2. NON-DESTRUCTIVE DETACH. `detach()` tears down only OUR transport
+ *     connection. The backend interface deliberately has no close/quit surface,
+ *     so no code path can call `Browser.close()`/`Page.close()` on the user's
+ *     browser (Codex F10 — wunderland's `BrowserSession.disconnect()` calls
+ *     `browser.close()` and is exactly the hazard this replaces).
+ *  3. MARKER-TAB BOUND. Every operation targets the single agent tab the
+ *     controller claimed; other tabs/windows are out of reach by construction.
+ *  4. LEASED. All operations require the cross-process lease nonce acquired at
+ *     `claim()` (F3), and run under the no-replay state machine with deadlines
+ *     (F14) plus the deny-by-default URL policy (F12).
+ *
+ * @module browser-automation/attach/AttachController
+ */
+import { AttachError, toStructuredError } from './errors.js';
+import { acquireLease, releaseLease, requireLease } from './lease.js';
+import { AttachStateMachine, withDeadline } from './state.js';
+import { isNavigationAllowed, revalidateRedirect } from './url-policy.js';
+/**
+ * Orchestrates one attach session end to end. One controller instance = one
+ * lease = one agent tab.
+ */
+export class AttachController {
+    backend;
+    opts;
+    machine = new AttachStateMachine();
+    lease;
+    tab;
+    lastError;
+    paused = false;
+    dryRun;
+    navigations = 0;
+    lastUrl;
+    constructor(opts) {
+        this.backend = opts.backend;
+        this.opts = opts;
+        this.dryRun = !!opts.dryRun;
+    }
+    get deadline() {
+        return this.opts.deadlineMs ?? 45_000;
+    }
+    /** Non-throwing status snapshot. */
+    status() {
+        return {
+            transport: this.lease ? this.backend.kind : 'none',
+            state: this.machine.state,
+            leaseHeld: !!this.lease,
+            agentTab: this.tab,
+            lastError: this.lastError,
+            paused: this.paused,
+            dryRun: this.dryRun,
+            navigations: this.navigations,
+            lastUrl: this.lastUrl,
+        };
+    }
+    /** Pause the session — navigation/read refuse until {@link resume}. */
+    pause() {
+        this.paused = true;
+    }
+    /** Resume a paused session. */
+    resume() {
+        this.paused = false;
+    }
+    /** Toggle dry-run at runtime (simulate navigation/reads, don't perform them). */
+    setDryRun(on) {
+        this.dryRun = on;
+    }
+    /**
+     * Acquire the lease, open the transport, verify profile identity, and claim
+     * the marker agent tab. Aborts (never launches) on any verification failure.
+     */
+    async claim() {
+        this.machine.to('connecting');
+        try {
+            this.lease = acquireLease({ file: this.opts.leaseFile });
+            await withDeadline(this.backend.connect(), this.deadline, 'connect');
+            const identity = await withDeadline(this.backend.probeIdentity(), this.deadline, 'probeIdentity');
+            if (!identity.includes(this.opts.expectedIdentity)) {
+                throw new AttachError('PROFILE_MISMATCH', `attached browser did not present the expected profile identity (looked for "${this.opts.expectedIdentity}")`);
+            }
+            this.tab = await withDeadline(this.backend.claimAgentTab(), this.deadline, 'claimAgentTab');
+            this.machine.to('ready');
+            return this.status();
+        }
+        catch (err) {
+            this.lastError = toStructuredError(err);
+            this.machine.to('failed');
+            await this.safeReleaseOnFailure();
+            throw err;
+        }
+    }
+    /** Navigate the agent tab (policy-checked, HITL-gated, redirect-revalidated). */
+    async goto(url) {
+        this.requireReady();
+        const verdict = isNavigationAllowed(url, this.opts.urlPolicy);
+        if (!verdict.allowed) {
+            throw new AttachError('POLICY_BLOCKED', `navigation to "${url}" rejected: ${verdict.reason}`);
+        }
+        // HITL gate: after the policy passes, an approver may still block the page.
+        if (this.opts.onNavigate) {
+            const decision = await this.opts.onNavigate(url);
+            const approved = typeof decision === 'boolean' ? decision : decision.approved;
+            if (!approved) {
+                const reason = typeof decision === 'object' && decision.reason ? decision.reason : 'operator denied';
+                throw new AttachError('POLICY_BLOCKED', `navigation to "${url}" denied by approver: ${reason}`);
+            }
+        }
+        requireLease(this.opts.leaseFile, this.lease.nonce);
+        // Dry-run: report the URL as the landed target without touching the browser.
+        if (this.dryRun) {
+            this.navigations += 1;
+            this.lastUrl = url;
+            return url;
+        }
+        this.machine.to('navigating');
+        try {
+            const landed = await withDeadline(this.backend.gotoTab(this.tab, url), this.deadline, 'goto');
+            this.navigations += 1;
+            this.lastUrl = landed;
+            const landedVerdict = revalidateRedirect(landed, this.opts.urlPolicy);
+            if (!landedVerdict.allowed) {
+                this.machine.to('ready');
+                throw new AttachError('POLICY_BLOCKED', `redirect landed on a blocked target: ${landedVerdict.reason}`);
+            }
+            this.machine.to('ready');
+            return landed;
+        }
+        catch (err) {
+            if (this.machine.state === 'navigating')
+                this.machine.to('failed');
+            this.lastError = toStructuredError(err);
+            throw err;
+        }
+    }
+    /** Read text from the agent tab (size-capped by the backend). */
+    async read(selector, maxChars) {
+        this.requireReady();
+        requireLease(this.opts.leaseFile, this.lease.nonce);
+        if (this.dryRun)
+            return '[dry-run] read skipped';
+        this.machine.to('reading');
+        try {
+            const text = await withDeadline(this.backend.readTab(this.tab, selector, maxChars), this.deadline, 'read');
+            this.machine.to('ready');
+            return text;
+        }
+        catch (err) {
+            if (this.machine.state === 'reading')
+                this.machine.to('failed');
+            this.lastError = toStructuredError(err);
+            throw err;
+        }
+    }
+    /** Fixed, parameterized extraction expression: the selector map is data, never code. */
+    static extractExpression(fields) {
+        const spec = JSON.stringify(fields ?? {});
+        return `(() => {
+      const fields = ${spec};
+      const grab = (sel) => [...document.querySelectorAll(sel)].map((e) => (e.textContent || '').trim()).filter(Boolean);
+      if (Object.keys(fields).length) {
+        const out = {};
+        for (const [name, sel] of Object.entries(fields)) out[name] = grab(sel).slice(0, 200);
+        return out;
+      }
+      return {
+        url: location.href,
+        title: document.title,
+        heading: (document.querySelector('h1,h2') || {}).textContent?.trim() || '',
+        links: [...document.querySelectorAll('a[href]')].map((a) => ({ href: a.href, text: (a.textContent || '').trim().slice(0, 60) })).slice(0, 500),
+        text: (document.body.innerText || '').replace(/\\s+/g, ' ').slice(0, 4000),
+      };
+    })()`;
+    }
+    /** The backend's optional eval primitive, or a structured refusal. */
+    requireEval() {
+        const fn = this.backend.evalInTab?.bind(this.backend);
+        if (!fn) {
+            throw new AttachError('UNSUPPORTED_OP', `${this.backend.kind} backend has no page-evaluation capability`);
+        }
+        return fn;
+    }
+    /**
+     * Structured extraction over a fixed, parameterized expression: for each
+     * `name: cssSelector` pair, trimmed textContent lists; with no fields, a
+     * default page summary (url/title/heading/links/text). No caller-supplied
+     * code ever reaches the page — selectors are data.
+     */
+    async extract(fields) {
+        this.requireReady();
+        const evalFn = this.requireEval();
+        requireLease(this.opts.leaseFile, this.lease.nonce);
+        if (this.dryRun)
+            return { dryRun: true };
+        this.machine.to('reading');
+        try {
+            const out = await withDeadline(evalFn(this.tab, AttachController.extractExpression(fields)), this.deadline, 'extract');
+            this.machine.to('ready');
+            return out;
+        }
+        catch (err) {
+            if (this.machine.state === 'reading')
+                this.machine.to('failed');
+            this.lastError = toStructuredError(err);
+            throw err;
+        }
+    }
+    /**
+     * Arbitrary page evaluation. USER LANE ONLY: reachable through the daemon
+     * protocol's `eval` op and the JS client; no agent tool maps to it and the
+     * tool-facing surface has no eval member.
+     */
+    async evaluate(expression, timeoutMs) {
+        this.requireReady();
+        const evalFn = this.requireEval();
+        requireLease(this.opts.leaseFile, this.lease.nonce);
+        if (this.dryRun)
+            return '[dry-run] evaluate skipped';
+        this.machine.to('reading');
+        try {
+            const out = await withDeadline(evalFn(this.tab, expression, timeoutMs), Math.max(this.deadline, (timeoutMs ?? 0) + 5_000), 'evaluate');
+            this.machine.to('ready');
+            return out;
+        }
+        catch (err) {
+            if (this.machine.state === 'reading')
+                this.machine.to('failed');
+            this.lastError = toStructuredError(err);
+            throw err;
+        }
+    }
+    /**
+     * Release the session: park is the CALLER's responsibility (navigate to
+     * about:blank first if desired), then this closes only our transport and
+     * releases the lease. There is no code path to close browser/tabs.
+     */
+    async detach() {
+        try {
+            await this.backend.disconnectTransport();
+        }
+        finally {
+            if (this.lease)
+                releaseLease(this.opts.leaseFile, this.lease.nonce);
+            this.lease = undefined;
+            this.tab = undefined;
+            if (this.machine.state !== 'disconnected') {
+                if (this.machine.state !== 'failed')
+                    this.machine.to('failed');
+                this.machine.to('disconnected');
+            }
+        }
+    }
+    requireReady() {
+        if (this.paused) {
+            throw new AttachError('UNKNOWN', 'attach session is paused — call resume() before further operations');
+        }
+        if (this.machine.state !== 'ready' || !this.tab || !this.lease) {
+            throw new AttachError('UNKNOWN', `attach session not ready (state=${this.machine.state}) — call claim() first`);
+        }
+    }
+    async safeReleaseOnFailure() {
+        try {
+            await this.backend.disconnectTransport();
+        }
+        catch {
+            /* transport already dead */
+        }
+        if (this.lease) {
+            try {
+                releaseLease(this.opts.leaseFile, this.lease.nonce);
+            }
+            catch {
+                /* foreign lease — leave it */
+            }
+            this.lease = undefined;
+        }
+    }
+}
+//# sourceMappingURL=AttachController.js.map

package/dist/attach/AttachController.js.map

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

package/dist/attach/backends/jxa.d.ts

@@ -0,0 +1,39 @@
+import type { AttachBackend } from '../AttachController.js';
+/** Options for {@link JxaBackend}. */
+export interface JxaBackendOptions {
+    /** Chrome profile root (defaults to the macOS default profile root). */
+    profileRoot?: string;
+    /** Identity probe URL (a page whose title reveals the signed-in account). */
+    identityProbeUrl?: string;
+    /** Per-exec timeout ms (default 40s). */
+    execTimeoutMs?: number;
+}
+/**
+ * Build the exact osascript argv for a driver invocation. Pure + exported for
+ * unit tests: arguments pass as argv (never shell-interpolated). The driver
+ * receives `profileRoot` as its first arg, then the command and its args.
+ */
+export declare function buildJxaArgs(script: string, profileRoot: string, cmd: string, args: string[]): string[];
+/** The embedded JXA driver source (written to a temp file at first use). */
+export declare const JXA_DRIVER_SOURCE = "ObjC.import('Foundation');\nfunction chromePid(root) {\n  const dest = $.NSFileManager.defaultManager.destinationOfSymbolicLinkAtPathError(root + '/SingletonLock', null);\n  if (!dest || !dest.js) throw new Error('SingletonLock unreadable');\n  return parseInt(dest.js.match(/-(\\d+)$/)[1], 10);\n}\nfunction run(argv) {\n  const root = argv[0], cmd = argv[1];\n  const c = Application(chromePid(root));\n  c.includeStandardAdditions = false;\n  const MARKER = '__agentos_attach_tab_v1__';\n  if (cmd === 'claim') {\n    for (const w of c.windows()) {\n      for (const t of w.tabs()) {\n        if (t.url() === 'about:blank') {\n          try { c.execute(t, { javascript: 'window.name=' + JSON.stringify(MARKER) }); } catch (e) {}\n          return w.id() + ' ' + t.id();\n        }\n      }\n    }\n    throw new Error('NO_BLANK_TAB: open a fresh tab (about:blank) in the target profile first');\n  }\n  const wid = argv[2], tid = argv[3];\n  const w = c.windows().find((x) => String(x.id()) === String(wid));\n  if (!w) throw new Error('window ' + wid + ' not found');\n  const t = w.tabs().find((x) => String(x.id()) === String(tid));\n  if (!t) throw new Error('tab ' + tid + ' not found in window ' + wid);\n  if (cmd === 'goto') {\n    t.url = argv[4];\n    for (let i = 0; i < 80; i++) { delay(0.5); try { if (t.loading() === false) break; } catch (e) { break; } }\n    delay(1);\n    return t.url();\n  }\n  if (cmd === 'url') return t.url() + '\\n' + t.title();\n  if (cmd === 'read') {\n    const sel = argv[4] || 'body';\n    const max = parseInt(argv[5] || '6000', 10);\n    const js = '(document.querySelector(' + JSON.stringify(sel) + ')||document.body).innerText.slice(0,' + max + ')';\n    const r = c.execute(t, { javascript: js });\n    return typeof r === 'string' ? r : JSON.stringify(r);\n  }\n  throw new Error('unknown cmd ' + cmd);\n}\n";
+/** macOS JXA transport backend. */
+export declare class JxaBackend implements AttachBackend {
+    readonly kind: "jxa";
+    private readonly profileRoot;
+    private readonly identityProbeUrl;
+    private readonly execTimeoutMs;
+    private driverPath?;
+    private claimed?;
+    constructor(opts?: JxaBackendOptions);
+    /** Verify the SingletonLock resolves (Chrome is running) — no side effects. */
+    connect(): Promise<void>;
+    /** Nothing persistent to tear down: each op is a discrete osascript exec. */
+    disconnectTransport(): Promise<void>;
+    private driver;
+    private exec;
+    claimAgentTab(): Promise<string>;
+    probeIdentity(): Promise<string>;
+    gotoTab(tab: string, url: string): Promise<string>;
+    readTab(tab: string, selector?: string, maxChars?: number): Promise<string>;
+}
+//# sourceMappingURL=jxa.d.ts.map

package/dist/attach/backends/jxa.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jxa.d.ts","sourceRoot":"","sources":["../../../src/attach/backends/jxa.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAI5D,sCAAsC;AACtC,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,yCAAyC;IACzC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAEvG;AAED,4EAA4E;AAC5E,eAAO,MAAM,iBAAiB,00DA2C7B,CAAC;AAEF,mCAAmC;AACnC,qBAAa,UAAW,YAAW,aAAa;IAC9C,QAAQ,CAAC,IAAI,EAAG,KAAK,CAAU;IAC/B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,UAAU,CAAC,CAAS;IAC5B,OAAO,CAAC,OAAO,CAAC,CAA+B;gBAEnC,IAAI,GAAE,iBAAsB;IAMxC,+EAA+E;IACzE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAU9B,6EAA6E;IACvE,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;YAI5B,MAAM;YAWN,IAAI;IAeZ,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC;IAQhC,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC;IAQhC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKlD,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAIlF"}

package/dist/attach/backends/jxa.js

@@ -0,0 +1,155 @@
+/**
+ * @fileoverview JXA (macOS) attach backend.
+ *
+ * Drives the user's RUNNING Chrome through `osascript -l JavaScript`,
+ * addressing the application BY PID resolved from the profile root's
+ * `SingletonLock` symlink — bundle-name addressing is ambiguous when more than
+ * one Chrome instance runs (e.g. a devtools-mcp cache instance) and MUST NOT
+ * be used. Navigation and reads work on background tabs; nothing here focuses,
+ * creates windows beyond the agent tab, or closes anything.
+ *
+ * The embedded driver mirrors the field-proven `vca-jxa.js` contract:
+ * claim (marker-binds an about:blank tab), goto (poll `loading`), url, and a
+ * selector-scoped innerText read. Raw arbitrary page JS is deliberately NOT
+ * exposed (Codex spec review F2).
+ *
+ * @module browser-automation/attach/backends/jxa
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { readlinkSync } from 'node:fs';
+import { pidFromSingletonLock } from '../singleton-lock.js';
+import { AttachError } from '../errors.js';
+const pExecFile = promisify(execFile);
+/**
+ * Build the exact osascript argv for a driver invocation. Pure + exported for
+ * unit tests: arguments pass as argv (never shell-interpolated). The driver
+ * receives `profileRoot` as its first arg, then the command and its args.
+ */
+export function buildJxaArgs(script, profileRoot, cmd, args) {
+    return ['-l', 'JavaScript', script, profileRoot, cmd, ...args];
+}
+/** The embedded JXA driver source (written to a temp file at first use). */
+export const JXA_DRIVER_SOURCE = `ObjC.import('Foundation');
+function chromePid(root) {
+  const dest = $.NSFileManager.defaultManager.destinationOfSymbolicLinkAtPathError(root + '/SingletonLock', null);
+  if (!dest || !dest.js) throw new Error('SingletonLock unreadable');
+  return parseInt(dest.js.match(/-(\\d+)$/)[1], 10);
+}
+function run(argv) {
+  const root = argv[0], cmd = argv[1];
+  const c = Application(chromePid(root));
+  c.includeStandardAdditions = false;
+  const MARKER = '__agentos_attach_tab_v1__';
+  if (cmd === 'claim') {
+    for (const w of c.windows()) {
+      for (const t of w.tabs()) {
+        if (t.url() === 'about:blank') {
+          try { c.execute(t, { javascript: 'window.name=' + JSON.stringify(MARKER) }); } catch (e) {}
+          return w.id() + ' ' + t.id();
+        }
+      }
+    }
+    throw new Error('NO_BLANK_TAB: open a fresh tab (about:blank) in the target profile first');
+  }
+  const wid = argv[2], tid = argv[3];
+  const w = c.windows().find((x) => String(x.id()) === String(wid));
+  if (!w) throw new Error('window ' + wid + ' not found');
+  const t = w.tabs().find((x) => String(x.id()) === String(tid));
+  if (!t) throw new Error('tab ' + tid + ' not found in window ' + wid);
+  if (cmd === 'goto') {
+    t.url = argv[4];
+    for (let i = 0; i < 80; i++) { delay(0.5); try { if (t.loading() === false) break; } catch (e) { break; } }
+    delay(1);
+    return t.url();
+  }
+  if (cmd === 'url') return t.url() + '\\n' + t.title();
+  if (cmd === 'read') {
+    const sel = argv[4] || 'body';
+    const max = parseInt(argv[5] || '6000', 10);
+    const js = '(document.querySelector(' + JSON.stringify(sel) + ')||document.body).innerText.slice(0,' + max + ')';
+    const r = c.execute(t, { javascript: js });
+    return typeof r === 'string' ? r : JSON.stringify(r);
+  }
+  throw new Error('unknown cmd ' + cmd);
+}
+`;
+/** macOS JXA transport backend. */
+export class JxaBackend {
+    kind = 'jxa';
+    profileRoot;
+    identityProbeUrl;
+    execTimeoutMs;
+    driverPath;
+    claimed;
+    constructor(opts = {}) {
+        this.profileRoot = opts.profileRoot ?? join(homedir(), 'Library/Application Support/Google/Chrome');
+        this.identityProbeUrl = opts.identityProbeUrl ?? 'https://mail.google.com/mail/u/0/';
+        this.execTimeoutMs = opts.execTimeoutMs ?? 40_000;
+    }
+    /** Verify the SingletonLock resolves (Chrome is running) — no side effects. */
+    async connect() {
+        let target;
+        try {
+            target = readlinkSync(join(this.profileRoot, 'SingletonLock'));
+        }
+        catch {
+            throw new AttachError('CDP_UNAVAILABLE', 'no running Chrome found for the target profile root (SingletonLock absent)');
+        }
+        pidFromSingletonLock(target); // throws on malformed
+    }
+    /** Nothing persistent to tear down: each op is a discrete osascript exec. */
+    async disconnectTransport() {
+        this.claimed = undefined;
+    }
+    async driver() {
+        if (this.driverPath)
+            return this.driverPath;
+        const { mkdtempSync, writeFileSync } = await import('node:fs');
+        const { tmpdir } = await import('node:os');
+        const dir = mkdtempSync(join(tmpdir(), 'attach-jxa-'));
+        const file = join(dir, 'driver.js');
+        writeFileSync(file, JXA_DRIVER_SOURCE);
+        this.driverPath = file;
+        return file;
+    }
+    async exec(cmd, args) {
+        const script = await this.driver();
+        const argv = buildJxaArgs(script, this.profileRoot, cmd, args);
+        try {
+            const { stdout } = await pExecFile('osascript', argv, { timeout: this.execTimeoutMs });
+            return stdout.trim();
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new AttachError(/turned off/i.test(msg) ? 'JS_DISABLED' : /not authorized/i.test(msg) ? 'ACCESSIBILITY_DENIED' : 'UNKNOWN', msg);
+        }
+    }
+    async claimAgentTab() {
+        const out = await this.exec('claim', []);
+        const [wid, tid] = out.split(/\s+/);
+        if (!wid || !tid)
+            throw new AttachError('TAB_CLOSED', `claim returned malformed ids: "${out}"`);
+        this.claimed = { wid, tid };
+        return `${wid} ${tid}`;
+    }
+    async probeIdentity() {
+        // Claim first if needed so the probe never touches a user tab.
+        if (!this.claimed)
+            await this.claimAgentTab();
+        const { wid, tid } = this.claimed;
+        await this.exec('goto', [wid, tid, this.identityProbeUrl]);
+        return this.exec('url', [wid, tid]);
+    }
+    async gotoTab(tab, url) {
+        const [wid, tid] = tab.split(/\s+/);
+        return this.exec('goto', [wid, tid, url]);
+    }
+    async readTab(tab, selector, maxChars) {
+        const [wid, tid] = tab.split(/\s+/);
+        return this.exec('read', [wid, tid, selector ?? 'body', String(maxChars ?? 6000)]);
+    }
+}
+//# sourceMappingURL=jxa.js.map

package/dist/attach/backends/jxa.js.map

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

package/dist/attach/backends/raw-cdp.d.ts

@@ -0,0 +1,53 @@
+import type { AttachBackend } from '../AttachController.js';
+/** Options for {@link RawCdpBackend}. */
+export interface RawCdpBackendOptions {
+    /** Chrome profile root holding `DevToolsActivePort` (default: macOS default profile root). */
+    profileRoot?: string;
+    /** Identity probe: substring matched against page-target urls (default `mail.google.com`). */
+    identityProbeUrl?: string;
+    /** Post-navigation settle delay ms (default 1800; the daemon sets 0 and settles per op). */
+    settleMs?: number;
+    /** Per-CDP-command timeout ms (default 20000). */
+    commandTimeoutMs?: number;
+    /** ws open timeout ms (default 15000). */
+    connectTimeoutMs?: number;
+    /** Eval result size cap in serialized chars (default 512 * 1024). */
+    evalMaxChars?: number;
+}
+/**
+ * Raw single-target CDP backend (see fileoverview for the contract).
+ *
+ * Never sends `Browser.close`; `Target.closeTarget` is only ever issued for
+ * the tab this instance created.
+ */
+export declare class RawCdpBackend implements AttachBackend {
+    readonly kind: "cdp";
+    private readonly opts;
+    private ws;
+    private nextId;
+    private readonly pending;
+    private sessionId;
+    private createdTargetId;
+    /** Invoked once when the transport drops unexpectedly (daemon schedules backoff reconnect). */
+    onUnexpectedClose: ((err: Error) => void) | null;
+    constructor(options?: RawCdpBackendOptions);
+    /** Open the ws to the browser endpoint. Creates/focuses NOTHING. Idempotent while connected. */
+    connect(): Promise<void>;
+    /** Close ONLY our created tab (if any), then the ws. Never `Browser.close`. */
+    disconnectTransport(): Promise<void>;
+    /** Create the agent tab, attach flattened to it alone, enable Page/Runtime on that session only. */
+    claimAgentTab(): Promise<string>;
+    /** Metadata-only identity read: matching page targets' titles/urls. No attach, no navigation. */
+    probeIdentity(): Promise<string>;
+    /** Navigate the agent tab, settle, return the landed URL. */
+    gotoTab(tab: string, url: string): Promise<string>;
+    /** innerText read, optional selector scope, capped. */
+    readTab(tab: string, selector?: string, maxChars?: number): Promise<string>;
+    /** Runtime.evaluate in the agent tab (optional backend capability used by extract/evaluate). */
+    evalInTab(tab: string, expression: string, timeoutMs?: number): Promise<unknown>;
+    private requireTab;
+    private onMessage;
+    private failAllPending;
+    private send;
+}
+//# sourceMappingURL=raw-cdp.d.ts.map

package/dist/attach/backends/raw-cdp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"raw-cdp.d.ts","sourceRoot":"","sources":["../../../src/attach/backends/raw-cdp.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAI5D,yCAAyC;AACzC,MAAM,WAAW,oBAAoB;IACnC,8FAA8F;IAC9F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8FAA8F;IAC9F,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,0CAA0C;IAC1C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAWD;;;;;GAKG;AACH,qBAAa,aAAc,YAAW,aAAa;IACjD,QAAQ,CAAC,IAAI,EAAG,KAAK,CAAU;IAC/B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiC;IACtD,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;IAC7D,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,eAAe,CAAuB;IAC9C,+FAA+F;IAC/F,iBAAiB,EAAE,CAAC,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,IAAI,CAAQ;gBAE5C,OAAO,GAAE,oBAAyB;IAW9C,gGAAgG;IAC1F,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAqD9B,+EAA+E;IACzE,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB1C,oGAAoG;IAC9F,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC;IAatC,iGAAiG;IAC3F,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC;IAUtC,6DAA6D;IACvD,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAOxD,uDAAuD;IACjD,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,QAAQ,SAAO,GAAG,OAAO,CAAC,MAAM,CAAC;IAQ/E,gGAAgG;IAC1F,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAkBtF,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,SAAS;IAejB,OAAO,CAAC,cAAc;IActB,OAAO,CAAC,IAAI;CAoBb"}