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

package/dist/attach/daemon/__tests__/harness.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fakeBackend = fakeBackend;
+exports.daemonUnderTest = daemonUnderTest;
+exports.op = op;
+/**
+ * @fileoverview Shared test harness for daemon-lane suites: a recording fake
+ * backend, an in-process daemon over real queue files, and a raw file-level op
+ * driver mirroring the client contract (responses are deleted after reading).
+ */
+const node_fs_1 = require("node:fs");
+const node_fs_2 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const AttachController_js_1 = require("../../AttachController.js");
+const daemon_js_1 = require("../daemon.js");
+const protocol_js_1 = require("../protocol.js");
+/** Recording fake backend satisfying AttachBackend + evalInTab. */
+function fakeBackend() {
+    const calls = [];
+    const backend = {
+        calls,
+        kind: 'cdp',
+        onUnexpectedClose: null,
+        async connect() {
+            calls.push('connect');
+        },
+        async disconnectTransport() {
+            calls.push('disconnect');
+        },
+        async claimAgentTab() {
+            calls.push('claim');
+            return 'tab-1';
+        },
+        async probeIdentity() {
+            calls.push('probe');
+            return 'Inbox - user@gmail.com - Gmail';
+        },
+        async gotoTab(_t, url) {
+            calls.push(`goto:${url}`);
+            return url;
+        },
+        async readTab() {
+            calls.push('read');
+            return 'PAGE TEXT';
+        },
+        async evalInTab(_t, expression) {
+            calls.push('eval');
+            return expression.includes('querySelectorAll') || expression.includes('location.href')
+                ? { extracted: true }
+                : 'evaluated';
+        },
+    };
+    return backend;
+}
+/** An in-process daemon over a fresh temp dir; caller owns cleanup + `await run`. */
+function daemonUnderTest(opts = {}) {
+    const dir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), 'attach-daemon-'));
+    const backend = fakeBackend();
+    const controller = new AttachController_js_1.AttachController({
+        backend,
+        leaseFile: (0, node_path_1.join)(dir, 'lease'),
+        expectedIdentity: 'user@gmail.com',
+    });
+    const daemon = new daemon_js_1.AttachDaemon({
+        controller,
+        backend,
+        ipcDir: (0, node_path_1.join)(dir, 'ipc'),
+        pidFile: (0, node_path_1.join)(dir, 'daemon.pid'),
+        pollMs: 25,
+        claimTtlMs: opts.claimTtlMs ?? 60000,
+    });
+    const run = daemon.run();
+    return { dir, backend, controller, daemon, run };
+}
+/** Raw file-level op driver; deletes the response after reading (client contract). */
+async function op(dir, client, opName, args) {
+    const ipc = (0, node_path_1.join)(dir, 'ipc');
+    const id = (0, protocol_js_1.newCmdId)(client);
+    (0, protocol_js_1.writeAtomicJson)((0, protocol_js_1.cmdPath)(ipc, id), { id, client, op: opName, args });
+    for (let i = 0; i < 400; i++) {
+        await new Promise((r) => setTimeout(r, 25));
+        const resp = (0, protocol_js_1.readJson)((0, protocol_js_1.respPath)(ipc, id));
+        if (resp) {
+            try {
+                (0, node_fs_2.unlinkSync)((0, protocol_js_1.respPath)(ipc, id));
+            }
+            catch {
+                /* raced */
+            }
+            return resp;
+        }
+    }
+    throw new Error(`no response to ${opName}`);
+}
+//# sourceMappingURL=harness.js.map

package/dist/attach/daemon/__tests__/harness.js.map

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

package/dist/attach/daemon/__tests__/protocol.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=protocol.test.d.ts.map

package/dist/attach/daemon/__tests__/protocol.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.test.d.ts","sourceRoot":"","sources":["../../../../src/attach/daemon/__tests__/protocol.test.ts"],"names":[],"mappings":""}

package/dist/attach/daemon/__tests__/protocol.test.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const protocol_js_1 = require("../protocol.js");
+const dirs = [];
+const tdir = () => {
+    const d = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), 'attach-ipc-'));
+    dirs.push(d);
+    return d;
+};
+(0, vitest_1.afterEach)(() => {
+    for (const d of dirs.splice(0))
+        (0, node_fs_1.rmSync)(d, { recursive: true, force: true });
+});
+(0, vitest_1.describe)('protocol', () => {
+    (0, vitest_1.it)('ids are strings and survive a JSON round trip at time_ns scale', () => {
+        const id = (0, protocol_js_1.newCmdId)('cli');
+        (0, vitest_1.expect)(typeof id).toBe('string');
+        (0, vitest_1.expect)(id.startsWith('cli-')).toBe(true);
+        // the historical bug: 1753112793123456789 > 2^53 rounds as a JS number
+        const echoed = JSON.parse(JSON.stringify({ id: 'cli-1753112793123456789-x' }));
+        (0, vitest_1.expect)(echoed.id).toBe('cli-1753112793123456789-x');
+    });
+    (0, vitest_1.it)('writeAtomicJson leaves no .tmp behind and readJson round-trips', () => {
+        const d = tdir();
+        const f = (0, node_path_1.join)(d, 'x.json');
+        (0, protocol_js_1.writeAtomicJson)(f, { a: 1 });
+        (0, vitest_1.expect)((0, protocol_js_1.readJson)(f)).toEqual({ a: 1 });
+        (0, vitest_1.expect)((0, node_fs_1.readdirSync)(d).filter((n) => n.includes('.tmp'))).toEqual([]);
+    });
+    (0, vitest_1.it)('readJson returns undefined for missing or torn files', () => {
+        const d = tdir();
+        (0, vitest_1.expect)((0, protocol_js_1.readJson)((0, node_path_1.join)(d, 'missing.json'))).toBeUndefined();
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(d, 'torn.json'), '{not json');
+        (0, vitest_1.expect)((0, protocol_js_1.readJson)((0, node_path_1.join)(d, 'torn.json'))).toBeUndefined();
+    });
+    (0, vitest_1.it)('listPendingCmds returns cmd-* files oldest-first and ignores responses and temp files', () => {
+        const d = tdir();
+        (0, protocol_js_1.writeAtomicJson)((0, protocol_js_1.cmdPath)(d, 'b'), { id: 'b' });
+        (0, protocol_js_1.writeAtomicJson)((0, protocol_js_1.cmdPath)(d, 'a'), { id: 'a' });
+        (0, protocol_js_1.writeAtomicJson)((0, protocol_js_1.respPath)(d, 'zzz'), { id: 'zzz' });
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(d, 'cmd-torn.json.tmp'), '{');
+        const past = new Date(Date.now() - 5000);
+        (0, node_fs_1.utimesSync)((0, protocol_js_1.cmdPath)(d, 'b'), past, past);
+        (0, vitest_1.expect)((0, protocol_js_1.listPendingCmds)(d).map((c) => c.id)).toEqual(['b', 'a']);
+    });
+    (0, vitest_1.it)('gcStale removes cmd/resp files older than STALE_FILE_MS and keeps fresh ones', () => {
+        const d = tdir();
+        (0, protocol_js_1.writeAtomicJson)((0, protocol_js_1.cmdPath)(d, 'old'), { id: 'old' });
+        (0, protocol_js_1.writeAtomicJson)((0, protocol_js_1.respPath)(d, 'old'), { id: 'old' });
+        (0, protocol_js_1.writeAtomicJson)((0, protocol_js_1.cmdPath)(d, 'new'), { id: 'new' });
+        const past = new Date(Date.now() - protocol_js_1.STALE_FILE_MS - 1000);
+        (0, node_fs_1.utimesSync)((0, protocol_js_1.cmdPath)(d, 'old'), past, past);
+        (0, node_fs_1.utimesSync)((0, protocol_js_1.respPath)(d, 'old'), past, past);
+        (0, protocol_js_1.gcStale)(d);
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)((0, protocol_js_1.cmdPath)(d, 'old'))).toBe(false);
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)((0, protocol_js_1.respPath)(d, 'old'))).toBe(false);
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)((0, protocol_js_1.cmdPath)(d, 'new'))).toBe(true);
+    });
+    (0, vitest_1.it)('gcStale with now=Infinity sweeps every queue file regardless of age', () => {
+        const d = tdir();
+        (0, protocol_js_1.writeAtomicJson)((0, protocol_js_1.cmdPath)(d, 'x'), { id: 'x' });
+        (0, protocol_js_1.writeAtomicJson)((0, protocol_js_1.respPath)(d, 'y'), { id: 'y' });
+        (0, protocol_js_1.gcStale)(d, Number.POSITIVE_INFINITY);
+        (0, vitest_1.expect)((0, node_fs_1.readdirSync)(d).filter((n) => n.startsWith('cmd-') || n.startsWith('resp-'))).toEqual([]);
+    });
+});
+//# sourceMappingURL=protocol.test.js.map

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

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

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=runner.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runner.test.d.ts","sourceRoot":"","sources":["../../../../src/attach/daemon/__tests__/runner.test.ts"],"names":[],"mappings":""}

package/dist/attach/daemon/__tests__/runner.test.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const runner_js_1 = require("../runner.js");
+const client_js_1 = require("../client.js");
+const harness_js_1 = require("./harness.js");
+const cleanups = [];
+(0, vitest_1.afterEach)(() => {
+    for (const f of cleanups.splice(0))
+        f();
+});
+(0, vitest_1.describe)('runAttachScript', () => {
+    (0, vitest_1.it)('runs goto/read/extract/wait steps, captures out keys untrusted-labeled, releases the claim', async () => {
+        const { dir, run } = (0, harness_js_1.daemonUnderTest)();
+        cleanups.push(() => (0, node_fs_1.rmSync)(dir, { recursive: true, force: true }));
+        const client = new client_js_1.AttachDaemonClient({ ipcDir: (0, node_path_1.join)(dir, 'ipc'), client: 'runner', pollMs: 25 });
+        const result = await (0, runner_js_1.runAttachScript)({
+            name: 'demo',
+            steps: [
+                { op: 'goto', url: 'https://example.com/', settle: 0 },
+                { op: 'read', out: 'page' },
+                { op: 'extract', fields: { perks: 'li' }, out: 'perks' },
+                { op: 'wait', ms: 10 },
+            ],
+        }, client);
+        (0, vitest_1.expect)(result.ok).toBe(true);
+        (0, vitest_1.expect)(result.results.page).toMatchObject({ untrusted: true });
+        (0, vitest_1.expect)(result.results.perks).toMatchObject({ untrusted: true });
+        (0, vitest_1.expect)(result.steps).toHaveLength(4);
+        (0, vitest_1.expect)(result.steps.every((s) => s.ok)).toBe(true);
+        // The claim was released: a different client can claim immediately.
+        const other = new client_js_1.AttachDaemonClient({ ipcDir: (0, node_path_1.join)(dir, 'ipc'), client: 'other', pollMs: 25 });
+        await (0, vitest_1.expect)(other.claim()).resolves.toBeTruthy();
+        await other.quit();
+        await run;
+    }, 60000);
+    (0, vitest_1.it)('rejects eval steps up front', async () => {
+        const { dir, run } = (0, harness_js_1.daemonUnderTest)();
+        cleanups.push(() => (0, node_fs_1.rmSync)(dir, { recursive: true, force: true }));
+        const client = new client_js_1.AttachDaemonClient({ ipcDir: (0, node_path_1.join)(dir, 'ipc'), client: 'runner', pollMs: 25 });
+        await (0, vitest_1.expect)((0, runner_js_1.runAttachScript)({ name: 'bad', steps: [{ op: 'eval', expression: '1' }] }, client)).rejects.toThrowError(/eval is not a declarative op/);
+        await client.quit();
+        await run;
+    }, 60000);
+    (0, vitest_1.it)('aborts on the first failing step with the step index and skips later steps', async () => {
+        const { dir, run } = (0, harness_js_1.daemonUnderTest)();
+        cleanups.push(() => (0, node_fs_1.rmSync)(dir, { recursive: true, force: true }));
+        const client = new client_js_1.AttachDaemonClient({ ipcDir: (0, node_path_1.join)(dir, 'ipc'), client: 'runner', pollMs: 25 });
+        const failed = await (0, runner_js_1.runAttachScript)({
+            name: 'abort',
+            steps: [
+                { op: 'goto', url: 'http://insecure.example/' },
+                { op: 'read', out: 'never' },
+            ],
+        }, client);
+        (0, vitest_1.expect)(failed.ok).toBe(false);
+        (0, vitest_1.expect)(failed.failedStep).toBe(0);
+        (0, vitest_1.expect)(failed.error?.code).toBe('POLICY_BLOCKED');
+        (0, vitest_1.expect)(failed.results.never).toBeUndefined();
+        (0, vitest_1.expect)(failed.steps).toHaveLength(1);
+        await client.quit();
+        await run;
+    }, 60000);
+});
+//# sourceMappingURL=runner.test.js.map

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

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

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

@@ -0,0 +1,64 @@
+import { type DaemonStatusFile } from './protocol.js';
+/** Client options. */
+export interface AttachDaemonClientOptions {
+    ipcDir?: string;
+    /** Client name prefix used in ids and claimant identity (default `client`). */
+    client?: string;
+    /** Response poll cadence ms (default 400). */
+    pollMs?: number;
+    /** Base per-op timeout ms before per-op margins (default 45000). */
+    opTimeoutMs?: number;
+}
+/** See fileoverview. All failures throw {@link AttachError} with a structured code. */
+export declare class AttachDaemonClient {
+    readonly ipcDir: string;
+    readonly client: string;
+    private readonly pollMs;
+    private readonly opTimeoutMs;
+    constructor(opts?: AttachDaemonClientOptions);
+    /** Fast, round-trip-free snapshot of status.json (undefined when absent). */
+    statusFile(): DaemonStatusFile | undefined;
+    /** True when status.json shows a fresh heartbeat or a live recorded pid. */
+    daemonLooksAlive(): boolean;
+    /** Liveness echo through the queue. */
+    ping(): Promise<{
+        pong: boolean;
+        pid: number;
+    }>;
+    /** Controller + daemon status snapshot via the queue. */
+    status(): Promise<Record<string, unknown>>;
+    /** Acquire driving rights (and trigger the controller claim on first use). */
+    claim(ttlMs?: number): Promise<Record<string, unknown>>;
+    /** Navigate the agent tab (daemon settles for `settle` ms, default 1800). */
+    goto(url: string, o?: {
+        settle?: number;
+    }): Promise<{
+        url: string;
+    }>;
+    /** Read visible text (untrusted page content). */
+    read(o?: {
+        selector?: string;
+        maxChars?: number;
+    }): Promise<{
+        untrusted: true;
+        text: string;
+    }>;
+    /** Structured extraction via a selector map (untrusted page content). */
+    extract(fields?: Record<string, string>): Promise<{
+        untrusted: true;
+        data: unknown;
+    }>;
+    /** USER LANE ONLY: arbitrary page evaluation for user-authored scripts. */
+    evaluate(expression: string, timeoutMs?: number): Promise<{
+        untrusted: true;
+        value: unknown;
+    }>;
+    /** Give up driving rights (daemon parks the tab; its session persists). */
+    release(): Promise<void>;
+    /** Runtime session controls. */
+    control(action: 'pause' | 'resume' | 'dry_run_on' | 'dry_run_off' | 'status'): Promise<Record<string, unknown>>;
+    /** Full daemon shutdown (parks tab, releases lease; Chrome untouched). */
+    quit(): Promise<void>;
+    private request;
+}
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/attach/daemon/client.ts"],"names":[],"mappings":"AAgBA,OAAO,EAWL,KAAK,gBAAgB,EACtB,MAAM,eAAe,CAAC;AAEvB,sBAAsB;AACtB,MAAM,WAAW,yBAAyB;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAID,uFAAuF;AACvF,qBAAa,kBAAkB;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAEzB,IAAI,GAAE,yBAA8B;IAOhD,6EAA6E;IAC7E,UAAU,IAAI,gBAAgB,GAAG,SAAS;IAI1C,4EAA4E;IAC5E,gBAAgB,IAAI,OAAO;IAY3B,uCAAuC;IACjC,IAAI,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAIrD,yDAAyD;IACnD,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAIhD,8EAA8E;IACxE,KAAK,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAI7D,6EAA6E;IACvE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAI9E,kDAAkD;IAC5C,IAAI,CAAC,CAAC,GAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,IAAI,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAIxG,yEAAyE;IACnE,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,IAAI,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC;IAI3F,2EAA2E;IACrE,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,IAAI,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC;IAOpG,2EAA2E;IACrE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAI9B,gCAAgC;IAC1B,OAAO,CAAC,MAAM,EAAE,OAAO,GAAG,QAAQ,GAAG,YAAY,GAAG,aAAa,GAAG,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAIrH,0EAA0E;IACpE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAIb,OAAO;CA6BtB"}

package/dist/attach/daemon/client.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AttachDaemonClient = void 0;
+/**
+ * @fileoverview Typed client for the attach daemon's file queue.
+ *
+ * No network, no child processes: writes `cmd-<id>.json`, polls for
+ * `resp-<id>.json`, deletes the response after reading. Used by user scripts
+ * (`wunderland attach run`), the declarative runner, and the tools'
+ * DaemonAttachSurface. `evaluate` is the user lane; no agent tool reaches it.
+ *
+ * Liveness: a daemon mid-op can miss heartbeats (the loop is serial), so
+ * {@link AttachDaemonClient.daemonLooksAlive} accepts a fresh heartbeat OR a
+ * live recorded pid.
+ *
+ * @module browser-automation/attach/daemon/client
+ */
+const node_fs_1 = require("node:fs");
+const errors_js_1 = require("../errors.js");
+const protocol_js_1 = require("./protocol.js");
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** See fileoverview. All failures throw {@link AttachError} with a structured code. */
+class AttachDaemonClient {
+    constructor(opts = {}) {
+        this.ipcDir = (0, protocol_js_1.resolveIpcDir)(opts.ipcDir);
+        this.client = `${opts.client ?? 'client'}-${process.pid}`;
+        this.pollMs = opts.pollMs ?? 400;
+        this.opTimeoutMs = opts.opTimeoutMs ?? 45000;
+    }
+    /** Fast, round-trip-free snapshot of status.json (undefined when absent). */
+    statusFile() {
+        return (0, protocol_js_1.readJson)((0, protocol_js_1.statusPath)(this.ipcDir));
+    }
+    /** True when status.json shows a fresh heartbeat or a live recorded pid. */
+    daemonLooksAlive() {
+        const s = this.statusFile();
+        if (!s || s.state === 'stopped' || s.state === 'failed')
+            return false;
+        if (Date.now() - s.t <= protocol_js_1.HEARTBEAT_STALE_MS)
+            return true;
+        try {
+            process.kill(s.pid, 0);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Liveness echo through the queue. */
+    async ping() {
+        return (await this.request('ping'));
+    }
+    /** Controller + daemon status snapshot via the queue. */
+    async status() {
+        return (await this.request('status'));
+    }
+    /** Acquire driving rights (and trigger the controller claim on first use). */
+    async claim(ttlMs) {
+        return (await this.request('claim', ttlMs ? { ttlMs } : {}));
+    }
+    /** Navigate the agent tab (daemon settles for `settle` ms, default 1800). */
+    async goto(url, o = {}) {
+        return (await this.request('goto', { url, ...o }, this.opTimeoutMs + (o.settle ?? 1800)));
+    }
+    /** Read visible text (untrusted page content). */
+    async read(o = {}) {
+        return (await this.request('read', o));
+    }
+    /** Structured extraction via a selector map (untrusted page content). */
+    async extract(fields) {
+        return (await this.request('extract', fields ? { fields } : {}));
+    }
+    /** USER LANE ONLY: arbitrary page evaluation for user-authored scripts. */
+    async evaluate(expression, timeoutMs) {
+        return (await this.request('eval', { expression, timeoutMs }, this.opTimeoutMs + (timeoutMs ?? 30000)));
+    }
+    /** Give up driving rights (daemon parks the tab; its session persists). */
+    async release() {
+        await this.request('release');
+    }
+    /** Runtime session controls. */
+    async control(action) {
+        return (await this.request('control', { action }));
+    }
+    /** Full daemon shutdown (parks tab, releases lease; Chrome untouched). */
+    async quit() {
+        await this.request('quit');
+    }
+    async request(op, args = {}, timeoutMs) {
+        if (!this.daemonLooksAlive()) {
+            throw new errors_js_1.AttachError('DAEMON_UNAVAILABLE', 'no live attach daemon behind this IPC dir; run `wunderland attach start`');
+        }
+        const id = (0, protocol_js_1.newCmdId)(this.client);
+        const cmdFile = (0, protocol_js_1.cmdPath)(this.ipcDir, id);
+        const respFile = (0, protocol_js_1.respPath)(this.ipcDir, id);
+        (0, protocol_js_1.writeAtomicJson)(cmdFile, { id, client: this.client, op, args });
+        const deadline = Date.now() + (timeoutMs ?? this.opTimeoutMs);
+        while (Date.now() < deadline) {
+            await sleep(this.pollMs);
+            const resp = (0, protocol_js_1.readJson)(respFile);
+            if (!resp)
+                continue;
+            try {
+                (0, node_fs_1.unlinkSync)(respFile);
+            }
+            catch {
+                /* raced with GC */
+            }
+            if (resp.ok)
+                return resp.data;
+            throw new errors_js_1.AttachError(resp.error.code, resp.error.message);
+        }
+        const consumed = !(0, node_fs_1.existsSync)(cmdFile);
+        throw new errors_js_1.AttachError(consumed ? 'CDP_TIMEOUT' : 'DAEMON_UNAVAILABLE', consumed
+            ? `${op} timed out awaiting the daemon's response`
+            : `${op} was never consumed — daemon gone; run \`wunderland attach start\``);
+    }
+}
+exports.AttachDaemonClient = AttachDaemonClient;
+//# sourceMappingURL=client.js.map

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

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

package/dist/attach/daemon/daemon-lock.d.ts

@@ -0,0 +1,19 @@
+/** A held daemon lock. */
+export interface DaemonLock {
+    /** Absolute pidfile path backing the lock. */
+    readonly pidFile: string;
+    /** Remove the pidfile iff this process still owns it. Never throws. */
+    release(): void;
+}
+/**
+ * Acquire the daemon singleton atomically.
+ *
+ * Creates `pidFile` with the `wx` flag (fails when it exists). On EEXIST the
+ * holder is inspected: a live pid refuses acquisition with `DAEMON_RUNNING`;
+ * a dead pid or an unreadable body reclaims the file once. Concurrent
+ * acquirers race safely on the atomic create — exactly one wins.
+ *
+ * @throws {AttachError} `DAEMON_RUNNING` when another live daemon holds the lock.
+ */
+export declare function acquireDaemonLock(pidFile: string): DaemonLock;
+//# sourceMappingURL=daemon-lock.d.ts.map

package/dist/attach/daemon/daemon-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon-lock.d.ts","sourceRoot":"","sources":["../../../src/attach/daemon/daemon-lock.ts"],"names":[],"mappings":"AAmBA,0BAA0B;AAC1B,MAAM,WAAW,UAAU;IACzB,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,OAAO,IAAI,IAAI,CAAC;CACjB;AAkBD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAsC7D"}

package/dist/attach/daemon/daemon-lock.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.acquireDaemonLock = acquireDaemonLock;
+/**
+ * @fileoverview Atomic daemon singleton via an O_EXCL pidfile.
+ *
+ * Mutual exclusion for the attach daemon: exactly one daemon may hold one
+ * Chrome session, or concurrent `attach start`s would open two CDP sockets
+ * and raise two macOS Local Network prompts. NOTE: `../singleton-lock.ts` is,
+ * despite its name, a parser for Chrome's own SingletonLock symlink (JXA pid
+ * addressing) and provides no locking — this module is the daemon's lock.
+ *
+ * Reclaim policy is pid-liveness, not age: a lock whose recorded pid is dead
+ * (or whose body is unreadable/torn) is reclaimed; a live pid refuses the
+ * acquisition no matter how old the file is.
+ *
+ * @module browser-automation/attach/daemon/daemon-lock
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const errors_js_1 = require("../errors.js");
+/** True when `pid` refers to a live process we may signal (EPERM counts as alive). */
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+/**
+ * Acquire the daemon singleton atomically.
+ *
+ * Creates `pidFile` with the `wx` flag (fails when it exists). On EEXIST the
+ * holder is inspected: a live pid refuses acquisition with `DAEMON_RUNNING`;
+ * a dead pid or an unreadable body reclaims the file once. Concurrent
+ * acquirers race safely on the atomic create — exactly one wins.
+ *
+ * @throws {AttachError} `DAEMON_RUNNING` when another live daemon holds the lock.
+ */
+function acquireDaemonLock(pidFile) {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(pidFile), { recursive: true, mode: 0o700 });
+    const body = { pid: process.pid, startedAt: Date.now() };
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const fd = (0, node_fs_1.openSync)(pidFile, 'wx', 0o600);
+            (0, node_fs_1.writeSync)(fd, JSON.stringify(body));
+            (0, node_fs_1.closeSync)(fd);
+            return {
+                pidFile,
+                release() {
+                    try {
+                        const cur = JSON.parse((0, node_fs_1.readFileSync)(pidFile, 'utf8'));
+                        if (cur.pid === process.pid)
+                            (0, node_fs_1.unlinkSync)(pidFile);
+                    }
+                    catch {
+                        /* released best-effort: file gone or owned by a newer daemon */
+                    }
+                },
+            };
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+            let holder;
+            try {
+                holder = JSON.parse((0, node_fs_1.readFileSync)(pidFile, 'utf8'));
+            }
+            catch {
+                /* torn or unreadable body: treat as reclaimable */
+            }
+            if (holder && pidAlive(holder.pid)) {
+                throw new errors_js_1.AttachError('DAEMON_RUNNING', `daemon already running (pid ${holder.pid})`);
+            }
+            try {
+                (0, node_fs_1.unlinkSync)(pidFile);
+            }
+            catch {
+                /* raced with another reclaimer; the retry create decides the winner */
+            }
+        }
+    }
+    throw new errors_js_1.AttachError('DAEMON_RUNNING', 'daemon lock contention: another process reclaimed the pidfile first');
+}
+//# sourceMappingURL=daemon-lock.js.map

package/dist/attach/daemon/daemon-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon-lock.js","sourceRoot":"","sources":["../../../src/attach/daemon/daemon-lock.ts"],"names":[],"mappings":";;AAqDA,8CAsCC;AA3FD;;;;;;;;;;;;;;GAcG;AACH,qCAA8F;AAC9F,yCAAoC;AACpC,4CAA2C;AAgB3C,sFAAsF;AACtF,SAAS,QAAQ,CAAC,GAAW;IAC3B,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAQ,GAA6B,CAAC,IAAI,KAAK,OAAO,CAAC;IACzD,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,iBAAiB,CAAC,OAAe;IAC/C,IAAA,mBAAS,EAAC,IAAA,mBAAO,EAAC,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC9D,MAAM,IAAI,GAAa,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;IACnE,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,CAAC,EAAE,OAAO,EAAE,EAAE,CAAC;QAC7C,IAAI,CAAC;YACH,MAAM,EAAE,GAAG,IAAA,kBAAQ,EAAC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;YAC1C,IAAA,mBAAS,EAAC,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;YACpC,IAAA,mBAAS,EAAC,EAAE,CAAC,CAAC;YACd,OAAO;gBACL,OAAO;gBACP,OAAO;oBACL,IAAI,CAAC;wBACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAA,sBAAY,EAAC,OAAO,EAAE,MAAM,CAAC,CAAa,CAAC;wBAClE,IAAI,GAAG,CAAC,GAAG,KAAK,OAAO,CAAC,GAAG;4BAAE,IAAA,oBAAU,EAAC,OAAO,CAAC,CAAC;oBACnD,CAAC;oBAAC,MAAM,CAAC;wBACP,gEAAgE;oBAClE,CAAC;gBACH,CAAC;aACF,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;gBAAE,MAAM,GAAG,CAAC;YAChE,IAAI,MAA4B,CAAC;YACjC,IAAI,CAAC;gBACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAA,sBAAY,EAAC,OAAO,EAAE,MAAM,CAAC,CAAa,CAAC;YACjE,CAAC;YAAC,MAAM,CAAC;gBACP,mDAAmD;YACrD,CAAC;YACD,IAAI,MAAM,IAAI,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;gBACnC,MAAM,IAAI,uBAAW,CAAC,gBAAgB,EAAE,+BAA+B,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC;YACxF,CAAC;YACD,IAAI,CAAC;gBACH,IAAA,oBAAU,EAAC,OAAO,CAAC,CAAC;YACtB,CAAC;YAAC,MAAM,CAAC;gBACP,uEAAuE;YACzE,CAAC;QACH,CAAC;IACH,CAAC;IACD,MAAM,IAAI,uBAAW,CAAC,gBAAgB,EAAE,qEAAqE,CAAC,CAAC;AACjH,CAAC"}

package/dist/attach/daemon/daemon-main.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Build and run the daemon from an environment map. Returns the process exit
+ * code (0 clean stop, 2 failure). Exported for tests and for the CLI.
+ */
+export declare function main(env?: Record<string, string | undefined>): Promise<number>;
+//# sourceMappingURL=daemon-main.d.ts.map

package/dist/attach/daemon/daemon-main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon-main.d.ts","sourceRoot":"","sources":["../../../src/attach/daemon/daemon-main.ts"],"names":[],"mappings":"AAiBA;;;GAGG;AACH,wBAAsB,IAAI,CAAC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAoDjG"}