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

package/dist/attach/daemon/protocol.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HEARTBEAT_STALE_MS = exports.STALE_FILE_MS = exports.DEFAULT_PID_FILE = exports.DEFAULT_IPC_DIR = void 0;
+exports.resolveIpcDir = resolveIpcDir;
+exports.newCmdId = newCmdId;
+exports.cmdPath = cmdPath;
+exports.respPath = respPath;
+exports.statusPath = statusPath;
+exports.writeAtomicJson = writeAtomicJson;
+exports.readJson = readJson;
+exports.listPendingCmds = listPendingCmds;
+exports.gcStale = gcStale;
+/**
+ * @fileoverview File-queue IPC protocol for the attach daemon.
+ *
+ * One file per command (`cmd-<id>.json`), one per response (`resp-<id>.json`),
+ * plus an atomically maintained `status.json` heartbeat. All writes are
+ * write-then-rename so a poller can never observe a torn body. Ids are STRINGS:
+ * numeric ids at `time_ns` scale exceed JS 2^53 integer precision and fail the
+ * round-trip match (proven by the reference driver).
+ *
+ * Only the daemon process ever touches the network; every consumer of this
+ * module reads and writes local files, so no caller can trigger the per-process
+ * macOS Local Network prompt.
+ *
+ * @module browser-automation/attach/daemon/protocol
+ */
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const node_crypto_1 = require("node:crypto");
+/** Default IPC directory (created 0700). */
+exports.DEFAULT_IPC_DIR = (0, node_path_1.join)((0, node_os_1.homedir)(), '.wunderland', 'attach', 'ipc');
+/** Default daemon pidfile. */
+exports.DEFAULT_PID_FILE = (0, node_path_1.join)((0, node_os_1.homedir)(), '.wunderland', 'attach', 'daemon.pid');
+/** cmd/resp files older than this are garbage-collected. */
+exports.STALE_FILE_MS = 10 * 60000;
+/** status.json heartbeats older than this mark the daemon stale. */
+exports.HEARTBEAT_STALE_MS = 30000;
+/** Resolve the IPC dir from an explicit override or env, ensuring it exists 0700. */
+function resolveIpcDir(override, env = process.env) {
+    const dir = override?.trim() || env.WUNDERLAND_ATTACH_IPC_DIR?.trim() || exports.DEFAULT_IPC_DIR;
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true, mode: 0o700 });
+    return dir;
+}
+/** New string command id: `<client>-<epochMs>-<random8>`. */
+function newCmdId(client) {
+    return `${client}-${Date.now()}-${(0, node_crypto_1.randomUUID)().slice(0, 8)}`;
+}
+/** Path of a command file. */
+function cmdPath(dir, id) {
+    return (0, node_path_1.join)(dir, `cmd-${id}.json`);
+}
+/** Path of a response file. */
+function respPath(dir, id) {
+    return (0, node_path_1.join)(dir, `resp-${id}.json`);
+}
+/** Path of the daemon heartbeat file. */
+function statusPath(dir) {
+    return (0, node_path_1.join)(dir, 'status.json');
+}
+/** Write JSON via tmp-then-rename so readers never see a torn body. */
+function writeAtomicJson(file, value) {
+    const tmp = `${file}.${process.pid}.tmp`;
+    (0, node_fs_1.writeFileSync)(tmp, JSON.stringify(value), { mode: 0o600 });
+    (0, node_fs_1.renameSync)(tmp, file);
+}
+/** Read+parse JSON; undefined when missing or torn. */
+function readJson(file) {
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)(file, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Pending command files, oldest first (mtime, then name for determinism). */
+function listPendingCmds(dir) {
+    const out = [];
+    for (const name of (0, node_fs_1.readdirSync)(dir)) {
+        if (!name.startsWith('cmd-') || !name.endsWith('.json'))
+            continue;
+        const path = (0, node_path_1.join)(dir, name);
+        try {
+            out.push({ id: name.slice(4, -5), path, mtimeMs: (0, node_fs_1.statSync)(path).mtimeMs });
+        }
+        catch {
+            /* raced with GC or the consumer */
+        }
+    }
+    return out.sort((a, b) => a.mtimeMs - b.mtimeMs || (a.id < b.id ? -1 : 1));
+}
+/** Delete cmd/resp files older than {@link STALE_FILE_MS} (pass `now` = Infinity to sweep all). */
+function gcStale(dir, now = Date.now()) {
+    for (const name of (0, node_fs_1.readdirSync)(dir)) {
+        if (!/^(cmd|resp)-.*\.json$/.test(name))
+            continue;
+        const path = (0, node_path_1.join)(dir, name);
+        try {
+            if (now - (0, node_fs_1.statSync)(path).mtimeMs > exports.STALE_FILE_MS)
+                (0, node_fs_1.unlinkSync)(path);
+        }
+        catch {
+            /* raced with the consumer */
+        }
+    }
+}
+//# sourceMappingURL=protocol.js.map

package/dist/attach/daemon/protocol.js.map

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

package/dist/attach/daemon/runner.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @fileoverview Declarative attach runs: a parsed steps object, no control flow.
+ *
+ * Allowed ops: goto | read | extract | wait. NO eval — the JS lane
+ * (`attach run script.mjs`) covers everything needing logic. The runner
+ * claims before the first step and releases in a finally block, so a failed
+ * run never strands the session until the ttl. Consumes a parsed JS object;
+ * YAML parsing happens in the wunderland CLI (`yaml` is a wunderland dep).
+ *
+ * @module browser-automation/attach/daemon/runner
+ */
+import type { AttachDaemonClient } from './client.js';
+/** One declarative step. */
+export type AttachRunStep = {
+    op: 'goto';
+    url: string;
+    settle?: number;
+    out?: string;
+} | {
+    op: 'read';
+    selector?: string;
+    maxChars?: number;
+    out?: string;
+} | {
+    op: 'extract';
+    fields?: Record<string, string>;
+    out?: string;
+} | {
+    op: 'wait';
+    ms: number;
+    out?: string;
+};
+/** A parsed declarative plan. */
+export interface AttachRunPlan {
+    name: string;
+    claim?: {
+        ttlMs?: number;
+    };
+    steps: AttachRunStep[];
+}
+/** Run result: per-step records plus keyed captures. */
+export interface AttachRunResult {
+    name: string;
+    startedAt: number;
+    ok: boolean;
+    failedStep?: number;
+    error?: {
+        code?: string;
+        message: string;
+    };
+    steps: Array<{
+        op: string;
+        ok: boolean;
+        out?: string;
+    }>;
+    results: Record<string, unknown>;
+}
+/**
+ * Execute `plan` against a live daemon via `client`. Validates the op
+ * whitelist up front (an eval step is a hard error, not a skipped step),
+ * aborts on the first failing step, and always releases the claim.
+ */
+export declare function runAttachScript(plan: AttachRunPlan, client: AttachDaemonClient): Promise<AttachRunResult>;
+//# sourceMappingURL=runner.d.ts.map

package/dist/attach/daemon/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../../src/attach/daemon/runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,4BAA4B;AAC5B,MAAM,MAAM,aAAa,GACrB;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1D;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAClE;IAAE,EAAE,EAAE,SAAS,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAChE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7C,iCAAiC;AACjC,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3B,KAAK,EAAE,aAAa,EAAE,CAAC;CACxB;AAED,wDAAwD;AACxD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,EAAE,EAAE,OAAO,CAAC;IACZ,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,KAAK,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,OAAO,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAID;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,CAAC,CAyC/G"}

package/dist/attach/daemon/runner.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAttachScript = runAttachScript;
+const ALLOWED = new Set(['goto', 'read', 'extract', 'wait']);
+/**
+ * Execute `plan` against a live daemon via `client`. Validates the op
+ * whitelist up front (an eval step is a hard error, not a skipped step),
+ * aborts on the first failing step, and always releases the claim.
+ */
+async function runAttachScript(plan, client) {
+    if (!plan || !Array.isArray(plan.steps))
+        throw new Error('attach run plan needs a steps array');
+    for (const [i, s] of plan.steps.entries()) {
+        const opName = s.op ?? '(missing)';
+        if (!ALLOWED.has(opName)) {
+            throw new Error(`step ${i}: ${opName} is not a declarative op (eval is not a declarative op; use the JS lane)`);
+        }
+    }
+    const result = {
+        name: plan.name ?? 'attach-run',
+        startedAt: Date.now(),
+        ok: true,
+        steps: [],
+        results: {},
+    };
+    await client.claim(plan.claim?.ttlMs);
+    try {
+        for (const [i, step] of plan.steps.entries()) {
+            try {
+                let data;
+                if (step.op === 'goto')
+                    data = await client.goto(step.url, { settle: step.settle });
+                else if (step.op === 'read')
+                    data = await client.read({ selector: step.selector, maxChars: step.maxChars });
+                else if (step.op === 'extract')
+                    data = await client.extract(step.fields);
+                else
+                    await new Promise((r) => setTimeout(r, step.ms));
+                result.steps.push({ op: step.op, ok: true, out: step.out });
+                if (step.out !== undefined)
+                    result.results[step.out] = data;
+            }
+            catch (err) {
+                const e = err;
+                result.ok = false;
+                result.failedStep = i;
+                result.error = { code: e.code, message: e.message ?? String(err) };
+                result.steps.push({ op: step.op, ok: false, out: step.out });
+                break;
+            }
+        }
+        return result;
+    }
+    finally {
+        await client.release().catch(() => {
+            /* claim may have expired or the run never claimed successfully */
+        });
+    }
+}
+//# sourceMappingURL=runner.js.map

package/dist/attach/daemon/runner.js.map

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

package/dist/attach/daemon/surface.d.ts

@@ -0,0 +1,31 @@
+import type { AttachSurface } from '../AttachController.js';
+/** Options for {@link DaemonAttachSurface}. */
+export interface DaemonAttachSurfaceOptions {
+    ipcDir?: string;
+    /** Spawn the daemon entry ONCE if none is alive (default false). Never retries. */
+    autostart?: boolean;
+    /** Env for an autostarted daemon (defaults to process.env). */
+    env?: Record<string, string | undefined>;
+}
+/** See fileoverview. */
+export declare class DaemonAttachSurface implements AttachSurface {
+    private readonly client;
+    private readonly opts;
+    private autostartAttempted;
+    constructor(opts?: DaemonAttachSurfaceOptions);
+    /** Synchronous snapshot from status.json (tools call status() sync). */
+    status(): unknown;
+    /** Acquire driving rights; optionally autostart the daemon exactly once. */
+    claim(): Promise<unknown>;
+    /** Navigate the agent tab (policy enforced daemon-side). */
+    goto(url: string): Promise<string>;
+    /** Read visible text from the agent tab. */
+    read(selector?: string, maxChars?: number): Promise<string>;
+    /** Give up driving rights; the daemon keeps its held session. */
+    detach(): Promise<void>;
+    pause(): void;
+    resume(): void;
+    setDryRun(on: boolean): void;
+    private spawnDaemonOnce;
+}
+//# sourceMappingURL=surface.d.ts.map

package/dist/attach/daemon/surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface.d.ts","sourceRoot":"","sources":["../../../src/attach/daemon/surface.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAI5D,+CAA+C;AAC/C,MAAM,WAAW,0BAA0B;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mFAAmF;IACnF,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CAC1C;AAID,wBAAwB;AACxB,qBAAa,mBAAoB,YAAW,aAAa;IACvD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA6B;IAClD,OAAO,CAAC,kBAAkB,CAAS;gBAEvB,IAAI,GAAE,0BAA+B;IAKjD,wEAAwE;IACxE,MAAM,IAAI,OAAO;IAKjB,4EAA4E;IACtE,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC;IAQ/B,4DAA4D;IACtD,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIxC,4CAA4C;IACtC,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIjE,iEAAiE;IAC3D,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAM7B,KAAK,IAAI,IAAI;IAMb,MAAM,IAAI,IAAI;IAMd,SAAS,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI;YAMd,eAAe;CAmB9B"}

package/dist/attach/daemon/surface.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DaemonAttachSurface = void 0;
+/**
+ * @fileoverview Daemon-backed implementation of the tool-facing AttachSurface.
+ *
+ * `browser_attach_*` tools built over this class drive the persistent daemon's
+ * held session instead of opening their own transport, so a mission process
+ * never touches the network (no per-process macOS prompt). `detach()` maps to
+ * the daemon `release` op: the agent gives up driving rights; the daemon keeps
+ * its session. No eval member exists here by contract.
+ *
+ * @module browser-automation/attach/daemon/surface
+ */
+const node_child_process_1 = require("node:child_process");
+const node_url_1 = require("node:url");
+const errors_js_1 = require("../errors.js");
+const client_js_1 = require("./client.js");
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** See fileoverview. */
+class DaemonAttachSurface {
+    constructor(opts = {}) {
+        this.autostartAttempted = false;
+        this.opts = opts;
+        this.client = new client_js_1.AttachDaemonClient({ ipcDir: opts.ipcDir, client: 'agent-tools' });
+    }
+    /** Synchronous snapshot from status.json (tools call status() sync). */
+    status() {
+        const s = this.client.statusFile();
+        return s ?? { state: 'unavailable', hint: 'run `wunderland attach start`' };
+    }
+    /** Acquire driving rights; optionally autostart the daemon exactly once. */
+    async claim() {
+        if (!this.client.daemonLooksAlive() && this.opts.autostart && !this.autostartAttempted) {
+            this.autostartAttempted = true; // exactly one attempt per process, NEVER a retry loop
+            await this.spawnDaemonOnce();
+        }
+        return this.client.claim();
+    }
+    /** Navigate the agent tab (policy enforced daemon-side). */
+    async goto(url) {
+        return (await this.client.goto(url)).url;
+    }
+    /** Read visible text from the agent tab. */
+    async read(selector, maxChars) {
+        return (await this.client.read({ selector, maxChars })).text;
+    }
+    /** Give up driving rights; the daemon keeps its held session. */
+    async detach() {
+        await this.client.release();
+    }
+    // Control ops are fire-and-forget over the queue; tools return the file
+    // snapshot, which reflects the change within one daemon tick.
+    pause() {
+        void this.client.control('pause').catch(() => {
+            /* surfaced on the next driving op */
+        });
+    }
+    resume() {
+        void this.client.control('resume').catch(() => {
+            /* surfaced on the next driving op */
+        });
+    }
+    setDryRun(on) {
+        void this.client.control(on ? 'dry_run_on' : 'dry_run_off').catch(() => {
+            /* surfaced on the next driving op */
+        });
+    }
+    async spawnDaemonOnce() {
+        const entry = (0, node_url_1.fileURLToPath)(new URL('./daemon-main.js', import.meta.url));
+        (0, node_child_process_1.spawn)(process.execPath, [entry], {
+            detached: true,
+            stdio: 'ignore',
+            env: { ...(this.opts.env ?? process.env) },
+        }).unref();
+        for (let i = 0; i < 50; i++) {
+            // wait up to ~20s for connected
+            await sleep(400);
+            const s = this.client.statusFile();
+            if (s?.state === 'connected')
+                return;
+            if (s?.state === 'failed')
+                break;
+        }
+        throw new errors_js_1.AttachError('DAEMON_UNAVAILABLE', `autostart did not reach connected: ${this.client.statusFile()?.lastError ?? 'no status'}`);
+    }
+}
+exports.DaemonAttachSurface = DaemonAttachSurface;
+//# sourceMappingURL=surface.js.map

package/dist/attach/daemon/surface.js.map

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

package/dist/attach/devtools-port.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @fileoverview Parser for Chrome's `DevToolsActivePort` discovery file.
+ *
+ * When Chrome runs with remote debugging enabled it writes a two-line file at
+ * the root of its user-data directory:
+ *
+ * ```
+ * 9222
+ * /devtools/browser/07797f92-4fc3-432a-91dd-0e982e1a3bc0
+ * ```
+ *
+ * Line 1 is the listening port, line 2 the browser-target WebSocket path. The
+ * GUID rotates every browser boot, so callers MUST re-read this file per
+ * connection attempt — a cached ws URL goes stale the moment Chrome restarts.
+ *
+ * @module browser-automation/attach/devtools-port
+ */
+/** Parsed contents of a `DevToolsActivePort` file. */
+export interface DevToolsEndpoint {
+    /** TCP port the DevTools server listens on (loopback only). */
+    port: number;
+    /** Browser-target WebSocket path, e.g. `/devtools/browser/<guid>`. */
+    wsPath: string;
+    /** Full loopback WebSocket URL (`ws://localhost:…` — the host Chrome's DNS-rebinding guard accepts). */
+    wsUrl: string;
+}
+/**
+ * Parse the raw text of a `DevToolsActivePort` file.
+ *
+ * @param text Raw file contents (two newline-separated lines).
+ * @returns The parsed endpoint.
+ * @throws {Error} When the file is malformed: fewer than two non-empty lines,
+ *   a non-numeric/out-of-range port, or a ws path that is not a
+ *   `/devtools/browser/…` browser-target path.
+ */
+export declare function parseDevToolsActivePort(text: string): DevToolsEndpoint;
+//# sourceMappingURL=devtools-port.d.ts.map

package/dist/attach/devtools-port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"devtools-port.d.ts","sourceRoot":"","sources":["../../src/attach/devtools-port.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,sDAAsD;AACtD,MAAM,WAAW,gBAAgB;IAC/B,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC;IACf,wGAAwG;IACxG,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAmBtE"}

package/dist/attach/devtools-port.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * @fileoverview Parser for Chrome's `DevToolsActivePort` discovery file.
+ *
+ * When Chrome runs with remote debugging enabled it writes a two-line file at
+ * the root of its user-data directory:
+ *
+ * ```
+ * 9222
+ * /devtools/browser/07797f92-4fc3-432a-91dd-0e982e1a3bc0
+ * ```
+ *
+ * Line 1 is the listening port, line 2 the browser-target WebSocket path. The
+ * GUID rotates every browser boot, so callers MUST re-read this file per
+ * connection attempt — a cached ws URL goes stale the moment Chrome restarts.
+ *
+ * @module browser-automation/attach/devtools-port
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDevToolsActivePort = parseDevToolsActivePort;
+/**
+ * Parse the raw text of a `DevToolsActivePort` file.
+ *
+ * @param text Raw file contents (two newline-separated lines).
+ * @returns The parsed endpoint.
+ * @throws {Error} When the file is malformed: fewer than two non-empty lines,
+ *   a non-numeric/out-of-range port, or a ws path that is not a
+ *   `/devtools/browser/…` browser-target path.
+ */
+function parseDevToolsActivePort(text) {
+    const lines = String(text)
+        .split('\n')
+        .map((l) => l.trim())
+        .filter(Boolean);
+    if (lines.length < 2) {
+        throw new Error('DevToolsActivePort malformed: expected "<port>\\n<wsPath>"');
+    }
+    const port = Number(lines[0]);
+    if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+        throw new Error(`DevToolsActivePort malformed: invalid port "${lines[0]}"`);
+    }
+    const wsPath = lines[1];
+    if (!wsPath.startsWith('/devtools/browser/')) {
+        throw new Error(`DevToolsActivePort malformed: unexpected ws path "${wsPath}"`);
+    }
+    // Host MUST be `localhost`: Chrome's DNS-rebinding guard 403s the literal
+    // `127.0.0.1` form on the ws upgrade (proven live 2026-07-21).
+    return { port, wsPath, wsUrl: `ws://localhost:${port}${wsPath}` };
+}
+//# sourceMappingURL=devtools-port.js.map

package/dist/attach/devtools-port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"devtools-port.js","sourceRoot":"","sources":["../../src/attach/devtools-port.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;;AAqBH,0DAmBC;AA5BD;;;;;;;;GAQG;AACH,SAAgB,uBAAuB,CAAC,IAAY;IAClD,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC;SACvB,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,OAAO,CAAC,CAAC;IACnB,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;IAChF,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,IAAI,GAAG,KAAK,EAAE,CAAC;QACzD,MAAM,IAAI,KAAK,CAAC,+CAA+C,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC9E,CAAC;IACD,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACxB,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,oBAAoB,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CAAC,qDAAqD,MAAM,GAAG,CAAC,CAAC;IAClF,CAAC;IACD,0EAA0E;IAC1E,+DAA+D;IAC/D,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,IAAI,GAAG,MAAM,EAAE,EAAE,CAAC;AACpE,CAAC"}

package/dist/attach/errors.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview Structured errors + diagnostic redaction for the attach lane.
+ *
+ * Attach operations run inside the user's AUTHENTICATED browser, so raw error
+ * text can carry session URLs, tokens, or account identifiers. Everything that
+ * leaves the attach layer is (a) mapped to a stable machine-readable code and
+ * (b) redacted of credential-class substrings before it can reach a report or
+ * a model prompt (Codex spec review F13/F14).
+ *
+ * @module browser-automation/attach/errors
+ */
+/** Stable failure codes for every attach-lane operation. */
+export type AttachErrorCode = 'CDP_TIMEOUT' | 'CDP_UNAVAILABLE' | 'JS_DISABLED' | 'ACCESSIBILITY_DENIED' | 'PROFILE_MISMATCH' | 'TAB_CLOSED' | 'NAV_TIMEOUT' | 'POLICY_BLOCKED' | 'LEASE_DENIED' | 'STALE_PORT_FILE' | 'DAEMON_UNAVAILABLE' | 'DAEMON_RUNNING' | 'NOT_CLAIMANT' | 'UNSUPPORTED_OP' | 'UNKNOWN';
+/** Structured attach error surfaced to tools/callers. */
+export interface StructuredAttachError {
+    code: AttachErrorCode;
+    /** Redacted, human-readable diagnostic. Never verbatim page/session text. */
+    message: string;
+}
+/** Error subclass carrying a structured code through throw sites. */
+export declare class AttachError extends Error {
+    readonly code: AttachErrorCode;
+    constructor(code: AttachErrorCode, message: string);
+}
+/**
+ * Redact credential-class substrings from a diagnostic string.
+ *
+ * @param text Raw diagnostic text.
+ * @returns The text with tokens/keys/secrets masked.
+ */
+export declare function redactDiagnostic(text: string): string;
+/**
+ * Map any thrown value to a {@link StructuredAttachError} with a redacted
+ * message. An {@link AttachError} keeps its explicit code; everything else is
+ * classified by message pattern, defaulting to `UNKNOWN`.
+ */
+export declare function toStructuredError(err: unknown): StructuredAttachError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/attach/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/attach/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,4DAA4D;AAC5D,MAAM,MAAM,eAAe,GACvB,aAAa,GACb,iBAAiB,GACjB,aAAa,GACb,sBAAsB,GACtB,kBAAkB,GAClB,YAAY,GACZ,aAAa,GACb,gBAAgB,GAChB,cAAc,GACd,iBAAiB,GACjB,oBAAoB,GACpB,gBAAgB,GAChB,cAAc,GACd,gBAAgB,GAChB,SAAS,CAAC;AAEd,yDAAyD;AACzD,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,eAAe,CAAC;IACtB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qEAAqE;AACrE,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;gBACnB,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM;CAKnD;AASD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIrD;AAeD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,qBAAqB,CASrE"}

package/dist/attach/errors.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * @fileoverview Structured errors + diagnostic redaction for the attach lane.
+ *
+ * Attach operations run inside the user's AUTHENTICATED browser, so raw error
+ * text can carry session URLs, tokens, or account identifiers. Everything that
+ * leaves the attach layer is (a) mapped to a stable machine-readable code and
+ * (b) redacted of credential-class substrings before it can reach a report or
+ * a model prompt (Codex spec review F13/F14).
+ *
+ * @module browser-automation/attach/errors
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AttachError = void 0;
+exports.redactDiagnostic = redactDiagnostic;
+exports.toStructuredError = toStructuredError;
+/** Error subclass carrying a structured code through throw sites. */
+class AttachError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.name = 'AttachError';
+        this.code = code;
+    }
+}
+exports.AttachError = AttachError;
+const CREDENTIAL_PATTERNS = [
+    [/(token|secret|password|passwd|apikey|api_key|auth|bearer|session|cookie)(["']?\s*[:=]\s*["']?)[^\s"'&;]+/gi, '$1$2[redacted]'],
+    [/eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{4,}/g, '[redacted-jwt]'],
+    [/\b(sk|pk|rk|ak)-[A-Za-z0-9_-]{12,}\b/g, '[redacted-key]'],
+    [/[?&](code|state|id_token|access_token|refresh_token)=[^\s&"']+/gi, '?[redacted-param]'],
+];
+/**
+ * Redact credential-class substrings from a diagnostic string.
+ *
+ * @param text Raw diagnostic text.
+ * @returns The text with tokens/keys/secrets masked.
+ */
+function redactDiagnostic(text) {
+    let out = String(text ?? '');
+    for (const [re, rep] of CREDENTIAL_PATTERNS)
+        out = out.replace(re, rep);
+    return out;
+}
+const CODE_MATCHERS = [
+    [/timeout.*connectovercdp|connectovercdp.*timeout|cdp.*timeout/i, 'CDP_TIMEOUT'],
+    [/econnrefused|ws error|socket hang up|cdp.*unavailable/i, 'CDP_UNAVAILABLE'],
+    [/javascript through applescript is turned off/i, 'JS_DISABLED'],
+    [/not authorized to send apple events|accessibility/i, 'ACCESSIBILITY_DENIED'],
+    [/profile.*mismatch|wrong profile/i, 'PROFILE_MISMATCH'],
+    [/tab .* not found|window .* not found|target closed/i, 'TAB_CLOSED'],
+    [/navigation.*timeout|nav.*timeout|net::err_timed_out/i, 'NAV_TIMEOUT'],
+    [/policy|blocked|not allowed/i, 'POLICY_BLOCKED'],
+    [/lease/i, 'LEASE_DENIED'],
+    [/devtoolsactiveport.*malformed|stale.*port/i, 'STALE_PORT_FILE'],
+];
+/**
+ * Map any thrown value to a {@link StructuredAttachError} with a redacted
+ * message. An {@link AttachError} keeps its explicit code; everything else is
+ * classified by message pattern, defaulting to `UNKNOWN`.
+ */
+function toStructuredError(err) {
+    if (err instanceof AttachError) {
+        return { code: err.code, message: redactDiagnostic(err.message) };
+    }
+    const msg = err instanceof Error ? err.message : String(err);
+    for (const [re, code] of CODE_MATCHERS) {
+        if (re.test(msg))
+            return { code, message: redactDiagnostic(msg) };
+    }
+    return { code: 'UNKNOWN', message: redactDiagnostic(msg) };
+}
+//# sourceMappingURL=errors.js.map

package/dist/attach/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/attach/errors.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AAkDH,4CAIC;AAoBD,8CASC;AAxDD,qEAAqE;AACrE,MAAa,WAAY,SAAQ,KAAK;IAEpC,YAAY,IAAqB,EAAE,OAAe;QAChD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAPD,kCAOC;AAED,MAAM,mBAAmB,GAA4B;IACnD,CAAC,4GAA4G,EAAE,gBAAgB,CAAC;IAChI,CAAC,6DAA6D,EAAE,gBAAgB,CAAC;IACjF,CAAC,uCAAuC,EAAE,gBAAgB,CAAC;IAC3D,CAAC,kEAAkE,EAAE,mBAAmB,CAAC;CAC1F,CAAC;AAEF;;;;;GAKG;AACH,SAAgB,gBAAgB,CAAC,IAAY;IAC3C,IAAI,GAAG,GAAG,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;IAC7B,KAAK,MAAM,CAAC,EAAE,EAAE,GAAG,CAAC,IAAI,mBAAmB;QAAE,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;IACxE,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,aAAa,GAAqC;IACtD,CAAC,+DAA+D,EAAE,aAAa,CAAC;IAChF,CAAC,wDAAwD,EAAE,iBAAiB,CAAC;IAC7E,CAAC,+CAA+C,EAAE,aAAa,CAAC;IAChE,CAAC,oDAAoD,EAAE,sBAAsB,CAAC;IAC9E,CAAC,kCAAkC,EAAE,kBAAkB,CAAC;IACxD,CAAC,qDAAqD,EAAE,YAAY,CAAC;IACrE,CAAC,sDAAsD,EAAE,aAAa,CAAC;IACvE,CAAC,6BAA6B,EAAE,gBAAgB,CAAC;IACjD,CAAC,QAAQ,EAAE,cAAc,CAAC;IAC1B,CAAC,4CAA4C,EAAE,iBAAiB,CAAC;CAClE,CAAC;AAEF;;;;GAIG;AACH,SAAgB,iBAAiB,CAAC,GAAY;IAC5C,IAAI,GAAG,YAAY,WAAW,EAAE,CAAC;QAC/B,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,gBAAgB,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;IACpE,CAAC;IACD,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC7D,KAAK,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,IAAI,aAAa,EAAE,CAAC;QACvC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC;YAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC;IACpE,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC;AAC7D,CAAC"}

package/dist/attach/lease.d.ts

@@ -0,0 +1,43 @@
+/** On-disk lease record. */
+export interface AttachLease {
+    /** PID of the holding process. */
+    pid: number;
+    /** Random per-lease nonce every operation must present. */
+    nonce: string;
+    /** Epoch ms when the lease was acquired. */
+    acquiredAt: number;
+    /** Epoch ms after which the lease is reclaimable regardless of liveness. */
+    expiresAt: number;
+}
+/** Options for {@link acquireLease}. */
+export interface LeaseOptions {
+    /** Lease file path. */
+    file: string;
+    /** TTL in ms (default 10 minutes). */
+    ttlMs?: number;
+    /** Injectable clock for tests. */
+    now?: () => number;
+    /** Injectable liveness probe for tests (default: `process.kill(pid, 0)`). */
+    isPidAlive?: (pid: number) => boolean;
+    /** Acquiring process id (default `process.pid`). */
+    pid?: number;
+}
+/**
+ * Acquire the exclusive attach lease.
+ *
+ * @returns The acquired lease (persist the nonce; ops require it).
+ * @throws {AttachError} `LEASE_DENIED` when a live, unexpired lease exists.
+ */
+export declare function acquireLease(opts: LeaseOptions): AttachLease;
+/**
+ * Assert `nonce` matches the current lease.
+ * @throws {AttachError} `LEASE_DENIED` on missing lease or nonce mismatch.
+ */
+export declare function requireLease(file: string, nonce: string): AttachLease;
+/**
+ * Release the lease. Only the holder (matching nonce) may release; releasing a
+ * missing lease is a no-op.
+ * @throws {AttachError} `LEASE_DENIED` when the nonce does not match.
+ */
+export declare function releaseLease(file: string, nonce: string): void;
+//# sourceMappingURL=lease.d.ts.map

package/dist/attach/lease.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease.d.ts","sourceRoot":"","sources":["../../src/attach/lease.ts"],"names":[],"mappings":"AAkBA,4BAA4B;AAC5B,MAAM,WAAW,WAAW;IAC1B,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wCAAwC;AACxC,MAAM,WAAW,YAAY;IAC3B,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACtC,oDAAoD;IACpD,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAqBD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,YAAY,GAAG,WAAW,CAsB5D;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,CAMrE;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAO9D"}