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

package/dist/attach/AttachController.d.ts

@@ -0,0 +1,183 @@
+/**
+ * @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 { type StructuredAttachError } from './errors.js';
+import { type UrlPolicyOptions } from './url-policy.js';
+/**
+ * Transport backend contract. INTENTIONALLY has no `closeBrowser`/`closeTab`
+ * surface: the strongest guarantee that a detach can never destroy user state
+ * is that the API cannot express it.
+ */
+export interface AttachBackend {
+    /** Transport id for status/reporting. */
+    readonly kind: 'cdp' | 'jxa';
+    /** Open the transport (e.g. CDP socket). Must NOT create or focus tabs. */
+    connect(): Promise<void>;
+    /** Close ONLY our transport connection. Must not touch browser state. */
+    disconnectTransport(): Promise<void>;
+    /** Claim (or create) the marker agent tab; returns an opaque tab handle. */
+    claimAgentTab(): Promise<string>;
+    /** Read a lightweight identity probe: current profile evidence (e.g. a known tab title). */
+    probeIdentity(): Promise<string>;
+    /** Navigate the agent tab. Returns the URL actually landed on. */
+    gotoTab(tab: string, url: string): Promise<string>;
+    /** Read innerText (optionally scoped by selector) from the agent tab. */
+    readTab(tab: string, selector?: string, maxChars?: number): Promise<string>;
+    /**
+     * OPTIONAL: evaluate an expression in the agent tab (returnByValue).
+     * Absent on backends without a safe eval primitive; callers surface
+     * `UNSUPPORTED_OP` when missing. Never exposed on the agent tool surface.
+     */
+    evalInTab?(tab: string, expression: string, timeoutMs?: number): Promise<unknown>;
+}
+/**
+ * What `createAttachTools` needs: satisfied in-process by {@link AttachController}
+ * (jxa transport) and over IPC by the daemon proxy surface (cdp transport).
+ * Deliberately NO eval and NO extract — the agent tool surface stays no-eval.
+ */
+export interface AttachSurface {
+    status(): unknown;
+    claim(): Promise<unknown>;
+    goto(url: string): Promise<string>;
+    read(selector?: string, maxChars?: number): Promise<string>;
+    detach(): Promise<void>;
+    pause(): void;
+    resume(): void;
+    setDryRun(on: boolean): void;
+}
+/**
+ * Human-in-the-loop navigation decision. Called before every `goto` (after the
+ * URL clears the deny-by-default policy). Return `false`/`{ approved: false }`
+ * to block the navigation with a `POLICY_BLOCKED` result. Async so a caller can
+ * prompt a real operator.
+ */
+export type NavigationApprover = (url: string) => boolean | {
+    approved: boolean;
+    reason?: string;
+} | Promise<boolean | {
+    approved: boolean;
+    reason?: string;
+}>;
+/** Controller configuration. */
+export interface AttachControllerOptions {
+    backend: AttachBackend;
+    /** Lease file path (one per machine/user). */
+    leaseFile: string;
+    /**
+     * Expected profile identity substring (e.g. the account email). Claim ABORTS
+     * with PROFILE_MISMATCH when the probe does not contain it. Required: an
+     * attach client must never guess which profile it is driving (F9).
+     */
+    expectedIdentity: string;
+    /** URL policy options (host allowlist etc.). */
+    urlPolicy?: UrlPolicyOptions;
+    /** Per-operation deadline in ms (default 45s). */
+    deadlineMs?: number;
+    /**
+     * Dry-run: navigation and reads are validated and reported but NOT performed
+     * against the browser. Lets a mission preview its plan (or run in CI) without
+     * touching the live session.
+     */
+    dryRun?: boolean;
+    /**
+     * HITL gate on navigation. Runs after the URL policy passes; a denial blocks
+     * the goto. Use to require operator approval for each page an assistant opens.
+     */
+    onNavigate?: NavigationApprover;
+}
+/** Status snapshot returned by {@link AttachController.status}. */
+export interface AttachStatus {
+    transport: 'cdp' | 'jxa' | 'none';
+    state: string;
+    leaseHeld: boolean;
+    agentTab?: string;
+    lastError?: StructuredAttachError;
+    /** Session paused — operations are refused until resume(). */
+    paused: boolean;
+    /** Dry-run mode — navigation/reads are simulated, not performed. */
+    dryRun: boolean;
+    /** Count of navigations performed this session. */
+    navigations: number;
+    /** Last URL the agent tab navigated to. */
+    lastUrl?: string;
+}
+/**
+ * Orchestrates one attach session end to end. One controller instance = one
+ * lease = one agent tab.
+ */
+export declare class AttachController {
+    private readonly backend;
+    private readonly opts;
+    private readonly machine;
+    private lease?;
+    private tab?;
+    private lastError?;
+    private paused;
+    private dryRun;
+    private navigations;
+    private lastUrl?;
+    constructor(opts: AttachControllerOptions);
+    private get deadline();
+    /** Non-throwing status snapshot. */
+    status(): AttachStatus;
+    /** Pause the session — navigation/read refuse until {@link resume}. */
+    pause(): void;
+    /** Resume a paused session. */
+    resume(): void;
+    /** Toggle dry-run at runtime (simulate navigation/reads, don't perform them). */
+    setDryRun(on: boolean): void;
+    /**
+     * Acquire the lease, open the transport, verify profile identity, and claim
+     * the marker agent tab. Aborts (never launches) on any verification failure.
+     */
+    claim(): Promise<AttachStatus>;
+    /** Navigate the agent tab (policy-checked, HITL-gated, redirect-revalidated). */
+    goto(url: string): Promise<string>;
+    /** Read text from the agent tab (size-capped by the backend). */
+    read(selector?: string, maxChars?: number): Promise<string>;
+    /** Fixed, parameterized extraction expression: the selector map is data, never code. */
+    private static extractExpression;
+    /** The backend's optional eval primitive, or a structured refusal. */
+    private requireEval;
+    /**
+     * 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.
+     */
+    extract(fields?: Record<string, string>): Promise<unknown>;
+    /**
+     * 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.
+     */
+    evaluate(expression: string, timeoutMs?: number): Promise<unknown>;
+    /**
+     * 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.
+     */
+    detach(): Promise<void>;
+    private requireReady;
+    private safeReleaseOnFailure;
+}
+//# sourceMappingURL=AttachController.d.ts.map

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

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

package/dist/attach/AttachController.js

@@ -0,0 +1,283 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AttachController = void 0;
+/**
+ * @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
+ */
+const errors_js_1 = require("./errors.js");
+const lease_js_1 = require("./lease.js");
+const state_js_1 = require("./state.js");
+const url_policy_js_1 = require("./url-policy.js");
+/**
+ * Orchestrates one attach session end to end. One controller instance = one
+ * lease = one agent tab.
+ */
+class AttachController {
+    constructor(opts) {
+        this.machine = new state_js_1.AttachStateMachine();
+        this.paused = false;
+        this.navigations = 0;
+        this.backend = opts.backend;
+        this.opts = opts;
+        this.dryRun = !!opts.dryRun;
+    }
+    get deadline() {
+        return this.opts.deadlineMs ?? 45000;
+    }
+    /** 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 = (0, lease_js_1.acquireLease)({ file: this.opts.leaseFile });
+            await (0, state_js_1.withDeadline)(this.backend.connect(), this.deadline, 'connect');
+            const identity = await (0, state_js_1.withDeadline)(this.backend.probeIdentity(), this.deadline, 'probeIdentity');
+            if (!identity.includes(this.opts.expectedIdentity)) {
+                throw new errors_js_1.AttachError('PROFILE_MISMATCH', `attached browser did not present the expected profile identity (looked for "${this.opts.expectedIdentity}")`);
+            }
+            this.tab = await (0, state_js_1.withDeadline)(this.backend.claimAgentTab(), this.deadline, 'claimAgentTab');
+            this.machine.to('ready');
+            return this.status();
+        }
+        catch (err) {
+            this.lastError = (0, errors_js_1.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 = (0, url_policy_js_1.isNavigationAllowed)(url, this.opts.urlPolicy);
+        if (!verdict.allowed) {
+            throw new errors_js_1.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 errors_js_1.AttachError('POLICY_BLOCKED', `navigation to "${url}" denied by approver: ${reason}`);
+            }
+        }
+        (0, lease_js_1.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 (0, state_js_1.withDeadline)(this.backend.gotoTab(this.tab, url), this.deadline, 'goto');
+            this.navigations += 1;
+            this.lastUrl = landed;
+            const landedVerdict = (0, url_policy_js_1.revalidateRedirect)(landed, this.opts.urlPolicy);
+            if (!landedVerdict.allowed) {
+                this.machine.to('ready');
+                throw new errors_js_1.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 = (0, errors_js_1.toStructuredError)(err);
+            throw err;
+        }
+    }
+    /** Read text from the agent tab (size-capped by the backend). */
+    async read(selector, maxChars) {
+        this.requireReady();
+        (0, lease_js_1.requireLease)(this.opts.leaseFile, this.lease.nonce);
+        if (this.dryRun)
+            return '[dry-run] read skipped';
+        this.machine.to('reading');
+        try {
+            const text = await (0, state_js_1.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 = (0, errors_js_1.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 errors_js_1.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();
+        (0, lease_js_1.requireLease)(this.opts.leaseFile, this.lease.nonce);
+        if (this.dryRun)
+            return { dryRun: true };
+        this.machine.to('reading');
+        try {
+            const out = await (0, state_js_1.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 = (0, errors_js_1.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();
+        (0, lease_js_1.requireLease)(this.opts.leaseFile, this.lease.nonce);
+        if (this.dryRun)
+            return '[dry-run] evaluate skipped';
+        this.machine.to('reading');
+        try {
+            const out = await (0, state_js_1.withDeadline)(evalFn(this.tab, expression, timeoutMs), Math.max(this.deadline, (timeoutMs ?? 0) + 5000), 'evaluate');
+            this.machine.to('ready');
+            return out;
+        }
+        catch (err) {
+            if (this.machine.state === 'reading')
+                this.machine.to('failed');
+            this.lastError = (0, errors_js_1.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)
+                (0, lease_js_1.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 errors_js_1.AttachError('UNKNOWN', 'attach session is paused — call resume() before further operations');
+        }
+        if (this.machine.state !== 'ready' || !this.tab || !this.lease) {
+            throw new errors_js_1.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 {
+                (0, lease_js_1.releaseLease)(this.opts.leaseFile, this.lease.nonce);
+            }
+            catch {
+                /* foreign lease — leave it */
+            }
+            this.lease = undefined;
+        }
+    }
+}
+exports.AttachController = AttachController;
+//# 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/__tests__/AttachController.test.d.ts

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

package/dist/attach/__tests__/AttachController.test.d.ts.map

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