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

package/dist/attach/evidence.js

@@ -0,0 +1,269 @@
+/**
+ * @fileoverview Where an attach session's screenshots are written: one
+ * evidence directory, and the checks that keep a write inside it.
+ *
+ * A screenshot's path comes from a tool argument, so it must not reach the
+ * rest of the disk or replace a file. It is read against the evidence
+ * directory, refused when it leaves it or passes through a link, and written
+ * to a new file only.
+ *
+ * The directory is private to this user, by the rules the media packs keep
+ * for the files they save (`imageFiles.ts`, `audioFiles.ts`). The evidence
+ * directory and each directory in it on the way to the file belong to this
+ * user and are writable by no one else. Each directory above the evidence
+ * directory belongs to this user or root and is writable by no one else
+ * unless it is sticky, as /tmp is. A user who could rename an entry on that
+ * path could swap a directory for a link between the checks and the write,
+ * and Node has no `openat` to create a file in a checked directory. On
+ * Windows, where Node reads no ACLs, only the directories' kind is checked.
+ *
+ * A page takes seconds to capture, so the directories are checked twice:
+ * before the capture, so that nothing is asked of the browser for a path
+ * that will be refused, and again around the creation of the file, before
+ * the image is written through its handle.
+ *
+ * @module browser-automation/attach/evidence
+ */
+import { constants as fsConstants } from 'node:fs';
+import { access, lstat, mkdir, open, realpath, unlink } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { AttachError } from './errors.js';
+/** The evidence directory when none is configured. */
+export const DEFAULT_EVIDENCE_DIR = join(homedir(), '.wunderland', 'attach-evidence');
+const blocked = (message) => new AttachError('POLICY_BLOCKED', message);
+/** A mode's permission bits as four octal digits. */
+const octal = (mode) => (mode & 4095n).toString(8).padStart(4, '0');
+/**
+ * The path inside `root` that `filePath` names when read against it, or
+ * `undefined` when it names `root` itself or a place outside it.
+ */
+function insideOf(root, filePath) {
+    const inside = relative(root, resolve(root, filePath));
+    return inside === '' || inside === '..' || inside.startsWith(`..${sep}`) || isAbsolute(inside) ? undefined : inside;
+}
+/**
+ * Refuses, by the text of the path alone, a path that names no file, and a
+ * relative path that leaves the evidence directory. A relative path reads the
+ * same against the directory however the directory is named, so it is settled
+ * here, before the disk is touched. An absolute path is settled by
+ * {@link nameInside}, once the directory's real path is known.
+ *
+ * @throws POLICY_BLOCKED
+ */
+function checkName(filePath, configured) {
+    if (typeof filePath !== 'string' ||
+        !filePath.trim() ||
+        filePath.includes('\0') ||
+        filePath.endsWith('/') ||
+        filePath.endsWith(sep)) {
+        throw blocked('screenshot path must name a file inside the evidence directory');
+    }
+    if (!isAbsolute(filePath) && insideOf(configured, filePath) === undefined) {
+        throw blocked(`screenshot path must stay inside the evidence directory (${configured})`);
+    }
+}
+/**
+ * The path inside the evidence directory that `filePath` names. An absolute
+ * path may name the directory by its real path (`root`), as a result of
+ * {@link prepareEvidenceFile} does, or as it is configured.
+ *
+ * @throws POLICY_BLOCKED when the path is outside the directory.
+ */
+function nameInside(filePath, configured, root) {
+    const inside = insideOf(root, filePath) ?? insideOf(configured, filePath);
+    if (inside === undefined) {
+        throw blocked(`screenshot path must stay inside the evidence directory (${root})`);
+    }
+    return inside;
+}
+/**
+ * `dir` as a directory private to this user: a directory, not a link, that
+ * this user owns and that neither its group nor others can write. Where the
+ * platform has no user ids (Windows) only the kind is checked.
+ *
+ * @throws POLICY_BLOCKED when it is anything else.
+ */
+async function privateDirectory(dir) {
+    const stat = await lstat(dir, { bigint: true });
+    if (!stat.isDirectory()) {
+        throw blocked(`screenshot path passes through ${dir}, which is not a directory (a link is refused)`);
+    }
+    if (typeof process.getuid === 'function' && (stat.uid !== BigInt(process.getuid()) || (stat.mode & 18n) !== 0n)) {
+        throw blocked(`${dir} must belong to this user and be writable by no one else (owner uid ${stat.uid}, mode ${octal(stat.mode)}): chmod 700 it, or set another evidence directory`);
+    }
+    return { path: dir, dev: stat.dev, ino: stat.ino };
+}
+/**
+ * Why another user could change a directory above `dir`, a real path, or
+ * `undefined` when none can: each directory above it must belong to this
+ * user or root and be writable by no one else, unless it is sticky, where
+ * only an entry's owner can rename it. Where the platform has no user ids
+ * (Windows) nothing is checked.
+ */
+async function changeableParent(dir) {
+    if (typeof process.getuid !== 'function')
+        return undefined;
+    const uid = BigInt(process.getuid());
+    for (let parent = dirname(dir);; parent = dirname(parent)) {
+        const stat = await lstat(parent, { bigint: true });
+        if (!stat.isDirectory())
+            return `${parent}, above it, is not a directory`;
+        if (stat.uid !== uid && stat.uid !== 0n) {
+            return `${parent}, above it, belongs to uid ${stat.uid} (mode ${octal(stat.mode)})`;
+        }
+        if ((stat.mode & 18n) !== 0n && (stat.mode & 512n) === 0n) {
+            return `${parent}, above it, can be written by others and is not sticky (owner uid ${stat.uid}, mode ${octal(stat.mode)})`;
+        }
+        if (dirname(parent) === parent)
+            return undefined;
+    }
+}
+/** Whether each checked directory is still that directory: the same device and inode, and not a link. */
+async function unchanged(directories) {
+    for (const checked of directories) {
+        const now = await lstat(checked.path, { bigint: true }).catch(() => undefined);
+        if (!now?.isDirectory() || now.dev !== checked.dev || now.ino !== checked.ino)
+            return false;
+    }
+    return true;
+}
+/**
+ * The path a screenshot at `filePath` would be written to, for a dry run:
+ * the same reading of the path as {@link prepareEvidenceFile}, with nothing
+ * made on the disk. The evidence directory is named by its real path when it
+ * exists, as a written screenshot's path is.
+ *
+ * @param evidenceDir - The configured evidence directory, or `undefined` for the default.
+ * @param filePath - The path asked for, relative to the directory or absolute inside it.
+ * @throws POLICY_BLOCKED when the path names no file or leaves the directory.
+ */
+export async function plannedEvidencePath(evidenceDir, filePath) {
+    const configured = resolve(evidenceDir ?? DEFAULT_EVIDENCE_DIR);
+    checkName(filePath, configured);
+    const root = await realpath(configured).catch(() => configured);
+    return join(root, nameInside(filePath, configured, root));
+}
+/**
+ * Prepares the file a screenshot is written to, before the page is captured.
+ * The evidence directory is made when missing (mode 0700) and read by its
+ * real path, so a link swapped in for it later moves nothing. Each directory
+ * from it to the file is made (mode 0700) or checked: a directory, not a
+ * link, private to this user, with no directory above the evidence directory
+ * that another user can change. A file already at the path is refused.
+ *
+ * @param evidenceDir - The configured evidence directory, or `undefined` for the default.
+ * @param filePath - The path asked for, relative to the directory or absolute inside it.
+ * @throws POLICY_BLOCKED for a path that names no file, leaves the directory,
+ *   passes through a link or a file, or names something that exists, and for
+ *   a directory that is not private to this user.
+ * @throws UNKNOWN when the directory cannot take a new file (its mode, or a
+ *   file system mounted read-only).
+ */
+export async function prepareEvidenceFile(evidenceDir, filePath) {
+    const configured = resolve(evidenceDir ?? DEFAULT_EVIDENCE_DIR);
+    checkName(filePath, configured);
+    await mkdir(configured, { recursive: true, mode: 0o700 });
+    const root = await realpath(configured);
+    const target = join(root, nameInside(filePath, configured, root));
+    const directories = [await privateDirectory(root)];
+    const changeable = await changeableParent(root);
+    if (changeable) {
+        throw blocked(`the evidence directory ${root} cannot be used: ${changeable}. Set one under directories that no other user can change`);
+    }
+    let dir = root;
+    for (const part of relative(root, dirname(target)).split(sep).filter(Boolean)) {
+        dir = join(dir, part);
+        await mkdir(dir, { mode: 0o700 }).catch((err) => {
+            // Something is there already: the check below says whether it will do.
+            if (err.code !== 'EEXIST')
+                throw err;
+        });
+        directories.push(await privateDirectory(dir));
+    }
+    if (await lstat(target).catch(() => undefined)) {
+        throw blocked(`a file is already at ${target}: a screenshot never replaces one`);
+    }
+    // A directory this user owns can still refuse a new file: asked now, not
+    // after the page is captured.
+    await access(dir, fsConstants.W_OK | fsConstants.X_OK).catch((err) => {
+        throw new AttachError('UNKNOWN', `${dir} cannot take a new file (${err.code ?? err.message})`);
+    });
+    return { target, directories };
+}
+/**
+ * Whether the opened file, by its `stat`, is the one at the prepared path,
+ * with no other name, in the directories as they were checked.
+ */
+async function inPlace(prepared, file) {
+    const named = await lstat(prepared.target, { bigint: true }).catch(() => undefined);
+    return (file.isFile() &&
+        named !== undefined &&
+        named.nlink === 1n &&
+        named.dev === file.dev &&
+        named.ino === file.ino &&
+        (await unchanged(prepared.directories)));
+}
+/**
+ * Removes what a failed write left. The bytes go through the handle, when it
+ * is still open (after a failed close it is not). The file itself goes only
+ * when its path can still be shown to reach it: nothing is removed by path
+ * alone, since by now the path may name another file.
+ */
+async function discard(prepared, handle, file) {
+    await handle.truncate(0).catch(() => { });
+    if (await inPlace(prepared, file))
+        await unlink(prepared.target).catch(() => { });
+}
+/**
+ * Creates the prepared file and writes `bytes` to it.
+ *
+ * The directories are checked to be the ones prepared, the file is created
+ * with flag `wx` (it never replaces a file, and a link at its name is not
+ * followed), and with the file open the directories are checked again and the
+ * file is checked to be the one at its path, with no other name. Only then
+ * are the bytes written, through the handle. Node has no `openat`, so this is
+ * the order that keeps an image out of a directory swapped in while the page
+ * was captured: a file created in the wrong place stays empty.
+ *
+ * A write that fails leaves no partial image: the file is emptied through
+ * its handle, and removed when it is still the file at its path. A close
+ * that reports the write failed is an error of the call too, and the file is
+ * removed by the same rule.
+ *
+ * @throws POLICY_BLOCKED when a file is already there or a directory changed.
+ */
+export async function writeEvidenceFile(prepared, bytes) {
+    const changed = () => blocked('the evidence directory changed while the page was captured; no image was written');
+    if (!(await unchanged(prepared.directories)))
+        throw changed();
+    let handle;
+    try {
+        handle = await open(prepared.target, 'wx', 0o600);
+    }
+    catch (err) {
+        throw err.code === 'EEXIST'
+            ? blocked(`a file is already at ${prepared.target}: a screenshot never replaces one`)
+            : err;
+    }
+    try {
+        const file = await handle.stat({ bigint: true });
+        if (!(await inPlace(prepared, file)))
+            throw changed();
+        try {
+            await handle.writeFile(bytes);
+            // Closed here, and its error kept: a file system may report a failed
+            // write only when the file is closed (NFS, a quota).
+            await handle.close();
+        }
+        catch (err) {
+            await discard(prepared, handle, file);
+            throw err;
+        }
+    }
+    finally {
+        // After a close above this does nothing.
+        await handle.close().catch(() => { });
+    }
+}
+//# sourceMappingURL=evidence.js.map

package/dist/attach/evidence.js.map

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

package/dist/attach/lease.js

@@ -1,8 +1,3 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.acquireLease = acquireLease;
-exports.requireLease = requireLease;
-exports.releaseLease = releaseLease;
 /**
  * @fileoverview Cross-process attach lease — exactly ONE session may drive the
  * user's browser at a time.
@@ -16,10 +11,10 @@ exports.releaseLease = releaseLease;
  *
  * @module browser-automation/attach/lease
  */
-const node_crypto_1 = require("node:crypto");
-const node_fs_1 = require("node:fs");
-const node_path_1 = require("node:path");
-const errors_js_1 = require("./errors.js");
+import { randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { AttachError } from './errors.js';
 const DEFAULT_TTL_MS = 10 * 60 * 1000;
 function defaultIsPidAlive(pid) {
     try {
@@ -32,7 +27,7 @@ function defaultIsPidAlive(pid) {
 }
 function readLease(file) {
     try {
-        return JSON.parse((0, node_fs_1.readFileSync)(file, 'utf8'));
+        return JSON.parse(readFileSync(file, 'utf8'));
     }
     catch {
         return undefined;
@@ -44,34 +39,34 @@ function readLease(file) {
  * @returns The acquired lease (persist the nonce; ops require it).
  * @throws {AttachError} `LEASE_DENIED` when a live, unexpired lease exists.
  */
-function acquireLease(opts) {
+export function acquireLease(opts) {
     const now = opts.now ?? Date.now;
     const alive = opts.isPidAlive ?? defaultIsPidAlive;
-    const existing = (0, node_fs_1.existsSync)(opts.file) ? readLease(opts.file) : undefined;
+    const existing = existsSync(opts.file) ? readLease(opts.file) : undefined;
     if (existing) {
         const fresh = existing.expiresAt > now();
         if (fresh && alive(existing.pid)) {
-            throw new errors_js_1.AttachError('LEASE_DENIED', `attach lease held by pid ${existing.pid} until ${new Date(existing.expiresAt).toISOString()}`);
+            throw new AttachError('LEASE_DENIED', `attach lease held by pid ${existing.pid} until ${new Date(existing.expiresAt).toISOString()}`);
         }
     }
     const lease = {
         pid: opts.pid ?? process.pid,
-        nonce: (0, node_crypto_1.randomBytes)(16).toString('hex'),
+        nonce: randomBytes(16).toString('hex'),
         acquiredAt: now(),
         expiresAt: now() + (opts.ttlMs ?? DEFAULT_TTL_MS),
     };
-    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(opts.file), { recursive: true });
-    (0, node_fs_1.writeFileSync)(opts.file, JSON.stringify(lease));
+    mkdirSync(dirname(opts.file), { recursive: true });
+    writeFileSync(opts.file, JSON.stringify(lease));
     return lease;
 }
 /**
  * Assert `nonce` matches the current lease.
  * @throws {AttachError} `LEASE_DENIED` on missing lease or nonce mismatch.
  */
-function requireLease(file, nonce) {
-    const lease = (0, node_fs_1.existsSync)(file) ? readLease(file) : undefined;
+export function requireLease(file, nonce) {
+    const lease = existsSync(file) ? readLease(file) : undefined;
     if (!lease || lease.nonce !== nonce) {
-        throw new errors_js_1.AttachError('LEASE_DENIED', 'operation presented a stale or unknown lease nonce');
+        throw new AttachError('LEASE_DENIED', 'operation presented a stale or unknown lease nonce');
     }
     return lease;
 }
@@ -80,13 +75,13 @@ function requireLease(file, nonce) {
  * missing lease is a no-op.
  * @throws {AttachError} `LEASE_DENIED` when the nonce does not match.
  */
-function releaseLease(file, nonce) {
-    const lease = (0, node_fs_1.existsSync)(file) ? readLease(file) : undefined;
+export function releaseLease(file, nonce) {
+    const lease = existsSync(file) ? readLease(file) : undefined;
     if (!lease)
         return;
     if (lease.nonce !== nonce) {
-        throw new errors_js_1.AttachError('LEASE_DENIED', 'refusing to release a lease held by another session');
+        throw new AttachError('LEASE_DENIED', 'refusing to release a lease held by another session');
     }
-    (0, node_fs_1.unlinkSync)(file);
+    unlinkSync(file);
 }
 //# sourceMappingURL=lease.js.map

package/dist/attach/lease.js.map

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

package/dist/attach/singleton-lock.js

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * @fileoverview Resolve the running Chrome's PID from its `SingletonLock`.
  *
@@ -11,8 +10,6 @@
  *
  * @module browser-automation/attach/singleton-lock
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.pidFromSingletonLock = pidFromSingletonLock;
 /**
  * Extract the owning PID from a `SingletonLock` symlink target.
  *
@@ -20,7 +17,7 @@ exports.pidFromSingletonLock = pidFromSingletonLock;
  * @returns The PID (e.g. `666`).
  * @throws {Error} When the target does not end in `-<digits>`.
  */
-function pidFromSingletonLock(symlinkTarget) {
+export function pidFromSingletonLock(symlinkTarget) {
     const m = /-(\d+)$/.exec(String(symlinkTarget).trim());
     if (!m) {
         throw new Error(`SingletonLock target malformed (expected "<host>-<pid>"): "${symlinkTarget}"`);

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

@@ -1 +1 @@
-{"version":3,"file":"singleton-lock.js","sourceRoot":"","sources":["../../src/attach/singleton-lock.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;AASH,oDAMC;AAbD;;;;;;GAMG;AACH,SAAgB,oBAAoB,CAAC,aAAqB;IACxD,MAAM,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACvD,IAAI,CAAC,CAAC,EAAE,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,8DAA8D,aAAa,GAAG,CAAC,CAAC;IAClG,CAAC;IACD,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACnC,CAAC"}
+{"version":3,"file":"singleton-lock.js","sourceRoot":"","sources":["../../src/attach/singleton-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,aAAqB;IACxD,MAAM,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACvD,IAAI,CAAC,CAAC,EAAE,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,8DAA8D,aAAa,GAAG,CAAC,CAAC;IAClG,CAAC;IACD,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACnC,CAAC"}

package/dist/attach/state.js

@@ -1,7 +1,3 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.AttachStateMachine = void 0;
-exports.withDeadline = withDeadline;
 /**
  * @fileoverview Attach-session state machine + operation deadlines.
  *
@@ -13,7 +9,7 @@ exports.withDeadline = withDeadline;
  *
  * @module browser-automation/attach/state
  */
-const errors_js_1 = require("./errors.js");
+import { AttachError } from './errors.js';
 const LEGAL = Object.freeze({
     disconnected: ['connecting'],
     connecting: ['ready', 'failed', 'disconnected'],
@@ -29,10 +25,8 @@ const LEGAL = Object.freeze({
  * `reading`, a failure lands in `failed` and the ONLY way forward is an
  * explicit `disconnected` reset by the owner — never a silent retry.
  */
-class AttachStateMachine {
-    constructor() {
-        this.current = 'disconnected';
-    }
+export class AttachStateMachine {
+    current = 'disconnected';
     /** The current state. */
     get state() {
         return this.current;
@@ -43,7 +37,7 @@ class AttachStateMachine {
      */
     to(next) {
         if (!LEGAL[this.current].includes(next)) {
-            throw new errors_js_1.AttachError('UNKNOWN', `illegal attach-state transition ${this.current} → ${next}`);
+            throw new AttachError('UNKNOWN', `illegal attach-state transition ${this.current} → ${next}`);
         }
         this.current = next;
         return this.current;
@@ -53,7 +47,6 @@ class AttachStateMachine {
         return this.current === 'connecting' || this.current === 'navigating' || this.current === 'reading';
     }
 }
-exports.AttachStateMachine = AttachStateMachine;
 /**
  * Bound a transport promise with a hard deadline.
  *
@@ -62,10 +55,10 @@ exports.AttachStateMachine = AttachStateMachine;
  * @param label     Operation label for the failure message.
  * @throws {AttachError} `NAV_TIMEOUT` when the deadline expires first.
  */
-async function withDeadline(p, ms, label) {
+export async function withDeadline(p, ms, label) {
     let timer;
     const gate = new Promise((_, reject) => {
-        timer = setTimeout(() => reject(new errors_js_1.AttachError('NAV_TIMEOUT', `${label} exceeded ${ms}ms deadline`)), ms);
+        timer = setTimeout(() => reject(new AttachError('NAV_TIMEOUT', `${label} exceeded ${ms}ms deadline`)), ms);
     });
     try {
         return await Promise.race([p, gate]);

package/dist/attach/state.js.map

@@ -1 +1 @@
-{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/attach/state.ts"],"names":[],"mappings":";;;AAwEA,oCAUC;AAlFD;;;;;;;;;;GAUG;AACH,2CAA0C;AAW1C,MAAM,KAAK,GAA0D,MAAM,CAAC,MAAM,CAAC;IACjF,YAAY,EAAE,CAAC,YAAY,CAAC;IAC5B,UAAU,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,cAAc,CAAC;IAC/C,KAAK,EAAE,CAAC,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,QAAQ,CAAC;IAC1D,UAAU,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC;IAC/B,OAAO,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC;IAC5B,MAAM,EAAE,CAAC,cAAc,CAAC;CACzB,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAa,kBAAkB;IAA/B;QACU,YAAO,GAAgB,cAAc,CAAC;IAuBhD,CAAC;IArBC,yBAAyB;IACzB,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED;;;OAGG;IACH,EAAE,CAAC,IAAiB;QAClB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACxC,MAAM,IAAI,uBAAW,CAAC,SAAS,EAAE,mCAAmC,IAAI,CAAC,OAAO,MAAM,IAAI,EAAE,CAAC,CAAC;QAChG,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,kEAAkE;IAClE,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,OAAO,KAAK,YAAY,IAAI,IAAI,CAAC,OAAO,KAAK,YAAY,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC;IACtG,CAAC;CACF;AAxBD,gDAwBC;AAED;;;;;;;GAOG;AACI,KAAK,UAAU,YAAY,CAAI,CAAa,EAAE,EAAU,EAAE,KAAa;IAC5E,IAAI,KAAgD,CAAC;IACrD,MAAM,IAAI,GAAG,IAAI,OAAO,CAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE;QAC5C,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,uBAAW,CAAC,aAAa,EAAE,GAAG,KAAK,aAAa,EAAE,aAAa,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC7G,CAAC,CAAC,CAAC;IACH,IAAI,CAAC;QACH,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;IACvC,CAAC;YAAS,CAAC;QACT,IAAI,KAAK;YAAE,YAAY,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;AACH,CAAC"}
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/attach/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAW1C,MAAM,KAAK,GAA0D,MAAM,CAAC,MAAM,CAAC;IACjF,YAAY,EAAE,CAAC,YAAY,CAAC;IAC5B,UAAU,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,cAAc,CAAC;IAC/C,KAAK,EAAE,CAAC,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,QAAQ,CAAC;IAC1D,UAAU,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC;IAC/B,OAAO,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC;IAC5B,MAAM,EAAE,CAAC,cAAc,CAAC;CACzB,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,OAAO,kBAAkB;IACrB,OAAO,GAAgB,cAAc,CAAC;IAE9C,yBAAyB;IACzB,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED;;;OAGG;IACH,EAAE,CAAC,IAAiB;QAClB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACxC,MAAM,IAAI,WAAW,CAAC,SAAS,EAAE,mCAAmC,IAAI,CAAC,OAAO,MAAM,IAAI,EAAE,CAAC,CAAC;QAChG,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,kEAAkE;IAClE,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,OAAO,KAAK,YAAY,IAAI,IAAI,CAAC,OAAO,KAAK,YAAY,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC;IACtG,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAI,CAAa,EAAE,EAAU,EAAE,KAAa;IAC5E,IAAI,KAAgD,CAAC;IACrD,MAAM,IAAI,GAAG,IAAI,OAAO,CAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE;QAC5C,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,WAAW,CAAC,aAAa,EAAE,GAAG,KAAK,aAAa,EAAE,aAAa,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC7G,CAAC,CAAC,CAAC;IACH,IAAI,CAAC;QACH,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;IACvC,CAAC;YAAS,CAAC;QACT,IAAI,KAAK;YAAE,YAAY,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;AACH,CAAC"}

package/dist/attach/tools.d.ts

@@ -138,6 +138,46 @@ export declare class AttachReadTool {
         data?: undefined;
     }>;
 }
+/** `browser_attach_screenshot` — PNG evidence capture of the agent tab (CDP only). */
+export declare class AttachScreenshotTool {
+    private controller;
+    readonly id = "browser_attach_screenshot";
+    readonly name = "browser_attach_screenshot";
+    readonly displayName = "Attach: screenshot";
+    readonly description = "Capture a PNG screenshot of the agent tab to a new file in the evidence directory \u2014 visual evidence for a research report. The result gives the path written. Requires the CDP transport (the AppleScript/JXA transport has no pixel access and refuses with UNSUPPORTED_OP). Never navigates or mutates the page; it writes one file, and never replaces one.";
+    readonly category = "browser";
+    readonly version = "0.1.0";
+    readonly hasSideEffects = true;
+    readonly inputSchema: {
+        type: "object";
+        properties: {
+            path: {
+                type: string;
+                description: string;
+            };
+            fullPage: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    constructor(controller: AttachSurface);
+    execute(args: {
+        path: string;
+        fullPage?: boolean;
+    }): Promise<{
+        success: boolean;
+        data: any;
+        error?: undefined;
+        code?: undefined;
+    } | {
+        success: boolean;
+        error: string;
+        code: import("./errors.js").AttachErrorCode;
+        data?: undefined;
+    }>;
+}
 /** `browser_attach_release` — park + release the lease (no browser teardown). */
 export declare class AttachReleaseTool {
     private controller;
@@ -202,7 +242,7 @@ export declare class AttachControlTool {
     }>;
 }
 /** Instantiate the full attach tool set sharing one controller. */
-export declare function createAttachTools(controller: AttachSurface): (AttachStatusTool | AttachClaimTool | AttachGotoTool | AttachReadTool | AttachReleaseTool | AttachControlTool)[];
+export declare function createAttachTools(controller: AttachSurface): (AttachStatusTool | AttachClaimTool | AttachGotoTool | AttachReadTool | AttachScreenshotTool | AttachReleaseTool | AttachControlTool)[];
 /** All attach tool ids (for registry/policy classification). */
-export declare const ATTACH_TOOL_IDS: readonly ["browser_attach_status", "browser_attach_claim", "browser_attach_goto", "browser_attach_read", "browser_attach_release", "browser_attach_control"];
+export declare const ATTACH_TOOL_IDS: readonly ["browser_attach_status", "browser_attach_claim", "browser_attach_goto", "browser_attach_read", "browser_attach_screenshot", "browser_attach_release", "browser_attach_control"];
 //# sourceMappingURL=tools.d.ts.map

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

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