@mehmoodqureshi/chrome-mcp 0.5.2 → 0.6.1

package/README.md

@@ -1,5 +1,9 @@
 # chrome-mcp
 
+[![CI](https://github.com/Mehmoodqureshi/chrome-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Mehmoodqureshi/chrome-mcp/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/%40mehmoodqureshi%2Fchrome-mcp?label=npm)](https://www.npmjs.com/package/@mehmoodqureshi/chrome-mcp)
+[![license](https://img.shields.io/npm/l/%40mehmoodqureshi%2Fchrome-mcp?label=license)](LICENSE)
+
 Drive a **real Chrome browser** from Claude (or any MCP host). One pluggable
 `Executor` interface, two backends:
 

package/dist/shared/protocol.d.ts

@@ -48,6 +48,10 @@ export interface HelloFrame extends BaseFrame {
         version: string;
         chrome: string;
     };
+    /** Routing label: which profile this browser pairs as. Absent/empty → "default".
+     *  NOT a security boundary (the token is) — it selects which connection slot the
+     *  server routes commands to, so several browsers can stay paired at once. */
+    profile?: string;
 }
 /**
  * The wire-serializable subset of the server's policy, delivered in `welcome` so

package/dist/src/bridge/datadir.d.ts

@@ -6,3 +6,42 @@
 /** Create (if needed) and return the data dir, 0700 so only the user can read it. */
 export declare function ensureDataDir(dir?: string): string;
 export declare function handshakePath(dir: string): string;
+/**
+ * One-time move of the pre-0.6 flat layout into the `default` profile's
+ * workspace: `<dataDir>/cdp-profile` → `profiles/default/cdp-profile` (logins)
+ * and `<dataDir>/downloads` → `profiles/default/tasks/default/downloads`.
+ *
+ * Idempotent and conservative: a leg is migrated only when the legacy dir exists
+ * AND its target does not, so it runs at most once and never clobbers a profile
+ * the user has already populated. Must be called BEFORE {@link ensureWorkspace},
+ * which would otherwise create the (empty) target and block the rename. Returns
+ * a human-readable description of each move performed.
+ */
+export declare function migrateLegacyLayout(dataDir: string): string[];
+export interface Workspace {
+    /** The data dir this workspace lives under — needed to switch profile/task at runtime. */
+    dataDir: string;
+    profile: string;
+    task: string;
+    /** `profiles/<profile>/` — passed to the CDP executor as its userDataDir. */
+    profileDir: string;
+    /** `profiles/<profile>/tasks/<task>/` — per-run artifact root. */
+    taskDir: string;
+    /** `profiles/<profile>/tasks/<task>/downloads` — captured files for this run. */
+    downloadDir: string;
+    /** `profiles/<profile>/tasks/<task>/results` — extracted text/markdown/links. */
+    resultsDir: string;
+    /** `profiles/<profile>/tasks/<task>/screenshots` — PNGs captured during the run. */
+    screenshotsDir: string;
+    /** `profiles/<profile>/tasks/<task>/history.jsonl` — append-only action log. */
+    historyPath: string;
+}
+/**
+ * Create (0700) the profile + task directories and stamp the task with a
+ * `meta.json`, returning the resolved paths. The CDP profile (identity: cookies
+ * & logins) and the downloads (per-run artifacts) live under here so distinct
+ * identities and distinct runs never collide. `createdAt` is preserved across
+ * restarts so a resumed task keeps its original timestamp; the meta write is
+ * best-effort and never fatal.
+ */
+export declare function ensureWorkspace(dataDir: string, profile: string, task: string, meta?: Record<string, unknown>): Workspace;

package/dist/src/bridge/datadir.js

@@ -7,6 +7,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ensureDataDir = ensureDataDir;
 exports.handshakePath = handshakePath;
+exports.migrateLegacyLayout = migrateLegacyLayout;
+exports.ensureWorkspace = ensureWorkspace;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const config_1 = require("../config");
@@ -19,4 +21,68 @@ function ensureDataDir(dir) {
 function handshakePath(dir) {
     return (0, node_path_1.join)(dir, 'handshake.json');
 }
+/**
+ * One-time move of the pre-0.6 flat layout into the `default` profile's
+ * workspace: `<dataDir>/cdp-profile` → `profiles/default/cdp-profile` (logins)
+ * and `<dataDir>/downloads` → `profiles/default/tasks/default/downloads`.
+ *
+ * Idempotent and conservative: a leg is migrated only when the legacy dir exists
+ * AND its target does not, so it runs at most once and never clobbers a profile
+ * the user has already populated. Must be called BEFORE {@link ensureWorkspace},
+ * which would otherwise create the (empty) target and block the rename. Returns
+ * a human-readable description of each move performed.
+ */
+function migrateLegacyLayout(dataDir) {
+    const moved = [];
+    const legs = [
+        { from: (0, node_path_1.join)(dataDir, 'cdp-profile'), to: (0, node_path_1.join)((0, config_1.resolveProfileDir)(dataDir, 'default'), 'cdp-profile') },
+        { from: (0, node_path_1.join)(dataDir, 'downloads'), to: (0, node_path_1.join)((0, config_1.resolveTaskDir)(dataDir, 'default', 'default'), 'downloads') },
+    ];
+    for (const { from, to } of legs) {
+        if (!(0, node_fs_1.existsSync)(from) || (0, node_fs_1.existsSync)(to))
+            continue;
+        try {
+            (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(to), { recursive: true, mode: 0o700 });
+            (0, node_fs_1.renameSync)(from, to);
+            moved.push(`${from} → ${to}`);
+        }
+        catch {
+            /* best effort: a failed move leaves the legacy dir untouched and usable */
+        }
+    }
+    return moved;
+}
+/**
+ * Create (0700) the profile + task directories and stamp the task with a
+ * `meta.json`, returning the resolved paths. The CDP profile (identity: cookies
+ * & logins) and the downloads (per-run artifacts) live under here so distinct
+ * identities and distinct runs never collide. `createdAt` is preserved across
+ * restarts so a resumed task keeps its original timestamp; the meta write is
+ * best-effort and never fatal.
+ */
+function ensureWorkspace(dataDir, profile, task, meta = {}) {
+    const profileDir = (0, config_1.resolveProfileDir)(dataDir, profile);
+    const taskDir = (0, config_1.resolveTaskDir)(dataDir, profile, task);
+    const downloadDir = (0, node_path_1.join)(taskDir, 'downloads');
+    const resultsDir = (0, node_path_1.join)(taskDir, 'results');
+    const screenshotsDir = (0, node_path_1.join)(taskDir, 'screenshots');
+    const historyPath = (0, node_path_1.join)(taskDir, 'history.jsonl');
+    // Create the three artifact buckets up front (0700) so every capture path can
+    // assume its directory exists.
+    for (const d of [downloadDir, resultsDir, screenshotsDir]) {
+        (0, node_fs_1.mkdirSync)(d, { recursive: true, mode: 0o700 });
+    }
+    const metaPath = (0, node_path_1.join)(taskDir, 'meta.json');
+    try {
+        let createdAt;
+        if ((0, node_fs_1.existsSync)(metaPath)) {
+            createdAt = JSON.parse((0, node_fs_1.readFileSync)(metaPath, 'utf8')).createdAt;
+        }
+        (0, node_fs_1.writeFileSync)(metaPath, JSON.stringify({ ...meta, profile, task, createdAt: createdAt ?? meta.createdAt }, null, 2), { mode: 0o600 });
+    }
+    catch {
+        /* non-fatal: a missing meta.json never blocks the server */
+    }
+    return { dataDir, profile, task, profileDir, taskDir, downloadDir, resultsDir, screenshotsDir, historyPath };
+}
 //# sourceMappingURL=datadir.js.map

package/dist/src/bridge/server.d.ts

@@ -34,7 +34,10 @@ export interface BridgeOptions {
 export declare class BridgeServer {
     private readonly opts;
     private wss;
-    private active;
+    /** Profile routing key → its live connection. Multiple browsers stay paired at
+     *  once; a command is routed to the connection for its target profile. A new
+     *  hello for the SAME profile supersedes that profile's connection only. */
+    private conns;
     private boundPort;
     private readonly heartbeatMs;
     constructor(opts: BridgeOptions);
@@ -44,16 +47,26 @@ export declare class BridgeServer {
     private listenOnce;
     stop(): Promise<void>;
     get port(): number;
+    /** True when ANY browser is paired (used as the selector's cheap gate). */
     hasActiveExtension(): boolean;
-    /** Send a command to the active extension, or reject if none is connected. */
+    /** True when the given profile has a live connection. */
+    hasConnection(profile: string): boolean;
+    /** Profiles with a live connection right now. */
+    connectedProfiles(): string[];
+    /**
+     * Send a command to the connection for `opts.profile` (default "default").
+     * Rejects with an actionable message if that profile has no live browser.
+     */
     sendCommand(method: WireMethod, params: Record<string, unknown>, opts?: {
         tabId?: string;
         timeoutMs?: number;
+        profile?: string;
     }): Promise<unknown>;
+    private noPairMessage;
     status(): {
         extensionConnected: boolean;
         port: number;
-        sessionId: string | null;
+        connectedProfiles: string[];
     };
     private handleConnection;
     private reject;

package/dist/src/bridge/server.js

@@ -20,6 +20,20 @@ const policy_1 = require("../../shared/policy");
 const types_1 = require("../executor/types");
 const connection_1 = require("./connection");
 const auth_1 = require("./auth");
+const config_1 = require("../config");
+/** The routing label for a hello with no/blank profile — the back-compat default. */
+const DEFAULT_PROFILE = 'default';
+/** Reduce a hello's profile label to a safe routing key; blank/invalid → "default". */
+function routeKey(profile) {
+    if (!profile || !profile.trim())
+        return DEFAULT_PROFILE;
+    try {
+        return (0, config_1.sanitizeName)(profile, 'profile');
+    }
+    catch {
+        return DEFAULT_PROFILE;
+    }
+}
 const HELLO_TIMEOUT_MS = 5_000;
 const DEFAULT_HEARTBEAT_MS = 15_000;
 /** Max pre-auth frames a socket may send before a valid hello (anti-idle-hold). */
@@ -41,7 +55,10 @@ function portBusyMessage(host, port) {
 class BridgeServer {
     opts;
     wss = null;
-    active = null;
+    /** Profile routing key → its live connection. Multiple browsers stay paired at
+     *  once; a command is routed to the connection for its target profile. A new
+     *  hello for the SAME profile supersedes that profile's connection only. */
+    conns = new Map();
     boundPort = 0;
     heartbeatMs;
     constructor(opts) {
@@ -106,8 +123,9 @@ class BridgeServer {
         });
     }
     async stop() {
-        this.active?.close(1001, 'server stopping');
-        this.active = null;
+        for (const conn of this.conns.values())
+            conn.close(1001, 'server stopping');
+        this.conns.clear();
         const wss = this.wss;
         this.wss = null;
         if (wss)
@@ -116,21 +134,48 @@ class BridgeServer {
     get port() {
         return this.boundPort;
     }
+    /** True when ANY browser is paired (used as the selector's cheap gate). */
     hasActiveExtension() {
-        return this.active?.isOpen() ?? false;
+        for (const conn of this.conns.values())
+            if (conn.isOpen())
+                return true;
+        return false;
     }
-    /** Send a command to the active extension, or reject if none is connected. */
+    /** True when the given profile has a live connection. */
+    hasConnection(profile) {
+        const conn = this.conns.get(routeKey(profile));
+        return !!conn && conn.isOpen();
+    }
+    /** Profiles with a live connection right now. */
+    connectedProfiles() {
+        const out = [];
+        for (const [profile, conn] of this.conns)
+            if (conn.isOpen())
+                out.push(profile);
+        return out;
+    }
+    /**
+     * Send a command to the connection for `opts.profile` (default "default").
+     * Rejects with an actionable message if that profile has no live browser.
+     */
     async sendCommand(method, params, opts) {
-        if (!this.active || !this.active.isOpen()) {
-            throw new types_1.ExecutorError('EXTENSION_DISCONNECTED', 'no extension is paired');
+        const profile = routeKey(opts?.profile);
+        const conn = this.conns.get(profile);
+        if (!conn || !conn.isOpen()) {
+            throw new types_1.ExecutorError('EXTENSION_DISCONNECTED', this.noPairMessage(profile));
         }
-        return this.active.sendCommand(method, params, opts);
+        return conn.sendCommand(method, params, opts);
+    }
+    noPairMessage(profile) {
+        return (`No browser is paired for profile "${profile}". In that Chrome's chrome-mcp ` +
+            `extension Options, set Port ${this.boundPort}, paste the token, set Profile to ` +
+            `"${profile}", and Save — then it joins without disturbing your other profiles.`);
     }
     status() {
         return {
             extensionConnected: this.hasActiveExtension(),
             port: this.boundPort,
-            sessionId: this.active?.sessionId ?? null,
+            connectedProfiles: this.connectedProfiles(),
         };
     }
     // -- internals ----------------------------------------------------------
@@ -174,11 +219,11 @@ class BridgeServer {
                 this.reject(ws, 'bad_token');
                 return;
             }
-            // Authenticated. Hand the socket to an ExtensionConnection.
+            // Authenticated. Hand the socket to an ExtensionConnection under its profile.
             authed = true;
             clearTimeout(helloTimer);
             ws.off('message', onMessage);
-            this.promote(ws, frame.ext ?? { id: 'unknown', version: '0', chrome: '0' });
+            this.promote(ws, frame.ext ?? { id: 'unknown', version: '0', chrome: '0' }, routeKey(frame.profile));
         };
         ws.on('message', onMessage);
         ws.on('error', () => {
@@ -195,12 +240,14 @@ class BridgeServer {
             /* ignore */
         }
     }
-    promote(ws, ext) {
+    promote(ws, ext, profile) {
         const sessionId = (0, node_crypto_1.randomUUID)();
-        if (this.active && this.active.isOpen()) {
-            const prev = this.active;
+        // Supersede only the SAME profile's connection (a re-pair). Other profiles
+        // keep their live connections, so several browsers stay paired at once.
+        const prev = this.conns.get(profile);
+        if (prev && prev.isOpen()) {
             const differentId = prev.extId !== ext.id;
-            this.log(`extension "${ext.id}" superseded active connection "${prev.extId}"` +
+            this.log(`extension "${ext.id}" superseded profile "${profile}" connection "${prev.extId}"` +
                 (differentId ? ' (DIFFERENT id — possible hijack; surfaced to status)' : ''));
             try {
                 this.opts.onDisplacement?.({ oldExtId: prev.extId, newExtId: ext.id, differentId });
@@ -219,11 +266,12 @@ class BridgeServer {
             onEvent: this.opts.onEvent,
             onLog: (m) => this.log(m),
             onClose: () => {
-                if (this.active?.sessionId === sessionId)
-                    this.active = null;
+                // Only clear if a newer re-pair hasn't already replaced this slot.
+                if (this.conns.get(profile)?.sessionId === sessionId)
+                    this.conns.delete(profile);
             },
         });
-        this.active = conn;
+        this.conns.set(profile, conn);
         const welcome = {
             type: 'welcome',
             v: protocol_1.PROTOCOL_VERSION,
@@ -233,7 +281,7 @@ class BridgeServer {
             policy: this.opts.policy ?? policy_1.DENY_ALL_WIRE_POLICY,
         };
         this.send(ws, welcome);
-        this.log(`extension paired (session ${sessionId}, id "${ext.id}")`);
+        this.log(`extension paired (profile "${profile}", session ${sessionId}, id "${ext.id}")`);
     }
     send(ws, frame) {
         try {

package/dist/src/bridge/tasks.d.ts

@@ -0,0 +1,44 @@
+/**
+ * src/bridge/tasks.ts — listing and garbage-collection over the per-profile
+ * task workspaces written by `ensureWorkspace` (datadir.ts).
+ *
+ * A task is `profiles/<profile>/tasks/<task>/`, carrying a `meta.json` and a
+ * `downloads/` bucket. These helpers walk that tree read-only (listTasks) or
+ * prune it (gcTasks). `now` is threaded in rather than read from the clock so
+ * GC is deterministic under test.
+ */
+export interface TaskInfo {
+    profile: string;
+    task: string;
+    /** Absolute path to `profiles/<profile>/tasks/<task>/`. */
+    dir: string;
+    /** ISO timestamp from meta.json, falling back to the dir's mtime. */
+    createdAt: string;
+    /** Total bytes under the task dir (downloads + meta.json; excludes the profile). */
+    bytes: number;
+    /** File count in `downloads/`. */
+    downloads: number;
+}
+/** Enumerate every task across every profile, newest first. */
+export declare function listTasks(dataDir: string): TaskInfo[];
+export interface GcOptions {
+    /** Remove tasks created more than this many days ago. */
+    olderThanDays?: number;
+    /** Always retain the newest N tasks (per scope), regardless of age. */
+    keep?: number;
+    /** Limit to a single profile; otherwise all profiles. */
+    profile?: string;
+    /** Compute what would be removed without deleting anything. */
+    dryRun?: boolean;
+}
+export interface GcResult {
+    removed: TaskInfo[];
+    freedBytes: number;
+}
+/**
+ * Prune task workspaces. A task is removed when it is NOT among the newest
+ * `keep` (if set) AND is older than `olderThanDays` (if set). At least one of
+ * `keep`/`olderThanDays` must be provided — the caller is responsible for
+ * refusing an unbounded sweep. `dryRun` reports the selection without deleting.
+ */
+export declare function gcTasks(dataDir: string, opts: GcOptions, now: number): GcResult;

package/dist/src/bridge/tasks.js

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * src/bridge/tasks.ts — listing and garbage-collection over the per-profile
+ * task workspaces written by `ensureWorkspace` (datadir.ts).
+ *
+ * A task is `profiles/<profile>/tasks/<task>/`, carrying a `meta.json` and a
+ * `downloads/` bucket. These helpers walk that tree read-only (listTasks) or
+ * prune it (gcTasks). `now` is threaded in rather than read from the clock so
+ * GC is deterministic under test.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listTasks = listTasks;
+exports.gcTasks = gcTasks;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+function subdirs(dir) {
+    try {
+        return (0, node_fs_1.readdirSync)(dir, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+function dirSize(dir) {
+    let total = 0;
+    let entries;
+    try {
+        entries = (0, node_fs_1.readdirSync)(dir, { withFileTypes: true });
+    }
+    catch {
+        return 0;
+    }
+    for (const e of entries) {
+        const p = (0, node_path_1.join)(dir, e.name);
+        if (e.isDirectory())
+            total += dirSize(p);
+        else {
+            try {
+                total += (0, node_fs_1.statSync)(p).size;
+            }
+            catch {
+                /* vanished mid-walk */
+            }
+        }
+    }
+    return total;
+}
+function countFiles(dir) {
+    try {
+        return (0, node_fs_1.readdirSync)(dir, { withFileTypes: true }).filter((e) => e.isFile()).length;
+    }
+    catch {
+        return 0;
+    }
+}
+function readCreatedAt(taskDir) {
+    try {
+        const meta = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(taskDir, 'meta.json'), 'utf8'));
+        if (typeof meta.createdAt === 'string')
+            return meta.createdAt;
+    }
+    catch {
+        /* fall through to mtime */
+    }
+    try {
+        return (0, node_fs_1.statSync)(taskDir).mtime.toISOString();
+    }
+    catch {
+        return '';
+    }
+}
+/** Enumerate every task across every profile, newest first. */
+function listTasks(dataDir) {
+    const profilesRoot = (0, node_path_1.join)(dataDir, 'profiles');
+    if (!(0, node_fs_1.existsSync)(profilesRoot))
+        return [];
+    const out = [];
+    for (const profile of subdirs(profilesRoot)) {
+        const tasksRoot = (0, node_path_1.join)(profilesRoot, profile, 'tasks');
+        for (const task of subdirs(tasksRoot)) {
+            const dir = (0, node_path_1.join)(tasksRoot, task);
+            out.push({
+                profile,
+                task,
+                dir,
+                createdAt: readCreatedAt(dir),
+                bytes: dirSize(dir),
+                downloads: countFiles((0, node_path_1.join)(dir, 'downloads')),
+            });
+        }
+    }
+    return out.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+}
+/**
+ * Prune task workspaces. A task is removed when it is NOT among the newest
+ * `keep` (if set) AND is older than `olderThanDays` (if set). At least one of
+ * `keep`/`olderThanDays` must be provided — the caller is responsible for
+ * refusing an unbounded sweep. `dryRun` reports the selection without deleting.
+ */
+function gcTasks(dataDir, opts, now) {
+    if (opts.olderThanDays === undefined && opts.keep === undefined) {
+        throw new Error('gcTasks requires olderThanDays or keep (refusing to remove every task)');
+    }
+    const scoped = listTasks(dataDir).filter((t) => !opts.profile || t.profile === opts.profile);
+    const protectedDirs = new Set(opts.keep === undefined ? [] : scoped.slice(0, opts.keep).map((t) => t.dir));
+    const ageCutoffMs = (opts.olderThanDays ?? 0) * 86_400_000;
+    const removed = scoped.filter((t) => {
+        if (protectedDirs.has(t.dir))
+            return false;
+        if (opts.olderThanDays !== undefined) {
+            const created = Date.parse(t.createdAt);
+            if (Number.isNaN(created) || now - created <= ageCutoffMs)
+                return false;
+        }
+        return true;
+    });
+    if (!opts.dryRun) {
+        for (const t of removed) {
+            try {
+                (0, node_fs_1.rmSync)(t.dir, { recursive: true, force: true });
+            }
+            catch {
+                /* best effort */
+            }
+        }
+    }
+    return { removed, freedBytes: removed.reduce((sum, t) => sum + t.bytes, 0) };
+}
+//# sourceMappingURL=tasks.js.map

package/dist/src/bridge/workspace.d.ts

@@ -0,0 +1,54 @@
+/**
+ * src/bridge/workspace.ts — the *active* task workspace (mutable, process-global)
+ * plus the memory writers that persist a task's artifacts into it.
+ *
+ * Modeled on the executor singleton in `executor/manager.ts`: the boot path
+ * installs an initial workspace, and the runtime tools (`profile_use`/`task_new`)
+ * swap it via {@link switchWorkspace}. Tool handlers reach the current workspace
+ * through {@link getActiveWorkspace} so downloads, extracted results, screenshots,
+ * and the action log all land under `profiles/<profile>/tasks/<task>/`.
+ *
+ * Every writer here is BEST-EFFORT: a failed persist (full disk, races a task
+ * switch) is logged to stderr and swallowed so it can never break a tool call.
+ */
+import { type Workspace } from './datadir';
+/** Install the initial workspace at boot (from cli.ts). */
+export declare function setActiveWorkspace(w: Workspace): void;
+/** The current workspace. Throws if the boot path never installed one. */
+export declare function getActiveWorkspace(): Workspace;
+/** The current workspace, or null before boot completes (for non-throwing callers). */
+export declare function peekActiveWorkspace(): Workspace | null;
+/** Reset for tests. */
+export declare function resetActiveWorkspaceForTesting(): void;
+/**
+ * Switch the active profile and/or task, creating the workspace dirs if new, and
+ * make it current. Names are sanitized to a single safe path segment (reusing
+ * {@link sanitizeName}) so a tool argument can never escape the data dir. Returns
+ * the resolved workspace.
+ */
+export declare function switchWorkspace(opts: {
+    profile?: string;
+    task?: string;
+    meta?: Record<string, unknown>;
+}): Workspace;
+/**
+ * Save an extracted-content result (get_text / read_as_markdown / extract_links)
+ * into the active task's `results/`. `ext` is the file extension without a dot.
+ * Returns the path written, or null if persisted nowhere (no workspace / error).
+ */
+export declare function saveResult(tool: string, ext: string, body: string): string | null;
+/** Save a screenshot PNG (base64) into the active task's `screenshots/`. */
+export declare function saveScreenshot(dataBase64: string): string | null;
+/**
+ * Move a file Chrome saved to the user's Downloads dir into the active task's
+ * `downloads/`. The name is re-hardened via {@link sanitizeDownloadName} and the
+ * size is capped at {@link MAX_DOWNLOAD_BYTES} (over-cap files are left where they
+ * are and rejected). Falls back to copy+unlink when source and destination are on
+ * different filesystems (rename's `EXDEV`). Returns the final path and byte size.
+ */
+export declare function captureDownload(sourcePath: string, suggestedName?: string): {
+    path: string;
+    bytes: number;
+};
+/** Append one action record to the active task's `history.jsonl`. */
+export declare function appendHistory(entry: Record<string, unknown>): void;