@mehmoodqureshi/chrome-mcp 0.5.2 → 0.6.0

package/dist/src/bridge/workspace.js

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setActiveWorkspace = setActiveWorkspace;
+exports.getActiveWorkspace = getActiveWorkspace;
+exports.peekActiveWorkspace = peekActiveWorkspace;
+exports.resetActiveWorkspaceForTesting = resetActiveWorkspaceForTesting;
+exports.switchWorkspace = switchWorkspace;
+exports.saveResult = saveResult;
+exports.saveScreenshot = saveScreenshot;
+exports.captureDownload = captureDownload;
+exports.appendHistory = appendHistory;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const config_1 = require("../config");
+const download_1 = require("../../shared/download");
+const datadir_1 = require("./datadir");
+/** stderr only (never stdout in stdio mode); local to avoid an import cycle with mcp/server. */
+function logErr(message) {
+    process.stderr.write(`[chrome-mcp] ${message}\n`);
+}
+let active = null;
+/** Monotonic counter so saved result/screenshot filenames sort in capture order. */
+let seq = 0;
+/** Install the initial workspace at boot (from cli.ts). */
+function setActiveWorkspace(w) {
+    active = w;
+}
+/** The current workspace. Throws if the boot path never installed one. */
+function getActiveWorkspace() {
+    if (!active)
+        throw new Error('no active workspace (server not fully booted)');
+    return active;
+}
+/** The current workspace, or null before boot completes (for non-throwing callers). */
+function peekActiveWorkspace() {
+    return active;
+}
+/** Reset for tests. */
+function resetActiveWorkspaceForTesting() {
+    active = null;
+    seq = 0;
+}
+/**
+ * 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.
+ */
+function switchWorkspace(opts) {
+    const cur = getActiveWorkspace();
+    const profile = opts.profile === undefined ? cur.profile : (0, config_1.sanitizeName)(opts.profile, 'profile');
+    // A profile switch resets the task to "default" unless the caller names one.
+    const task = opts.task !== undefined
+        ? (0, config_1.sanitizeName)(opts.task, 'task')
+        : opts.profile !== undefined
+            ? 'default'
+            : cur.task;
+    const w = (0, datadir_1.ensureWorkspace)(cur.dataDir, profile, task, {
+        ...opts.meta,
+        createdAt: new Date().toISOString(),
+    });
+    active = w;
+    return w;
+}
+// ---------------------------------------------------------------------------
+// Memory writers — persist a task's artifacts under its workspace.
+// ---------------------------------------------------------------------------
+/** A short safe stem like `0007-get_text`; the seq keeps capture order + uniqueness. */
+function stem(tool) {
+    seq += 1;
+    const n = String(seq).padStart(4, '0');
+    return `${n}-${tool.replace(/[^A-Za-z0-9._-]/g, '_')}`;
+}
+/**
+ * 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).
+ */
+function saveResult(tool, ext, body) {
+    const w = peekActiveWorkspace();
+    if (!w)
+        return null;
+    try {
+        const path = (0, node_path_1.join)(w.resultsDir, `${stem(tool)}.${ext}`);
+        (0, node_fs_1.writeFileSync)(path, body, { mode: 0o600 });
+        return path;
+    }
+    catch (err) {
+        logErr(`results save failed: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}
+/** Save a screenshot PNG (base64) into the active task's `screenshots/`. */
+function saveScreenshot(dataBase64) {
+    const w = peekActiveWorkspace();
+    if (!w)
+        return null;
+    try {
+        const path = (0, node_path_1.join)(w.screenshotsDir, `${stem('screenshot')}.png`);
+        (0, node_fs_1.writeFileSync)(path, Buffer.from(dataBase64, 'base64'), { mode: 0o600 });
+        return path;
+    }
+    catch (err) {
+        logErr(`screenshot save failed: ${err instanceof Error ? err.message : String(err)}`);
+        return 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.
+ */
+function captureDownload(sourcePath, suggestedName) {
+    const w = getActiveWorkspace();
+    const bytes = (0, node_fs_1.statSync)(sourcePath).size;
+    if (bytes > download_1.MAX_DOWNLOAD_BYTES) {
+        throw new Error(`download exceeds the ${download_1.MAX_DOWNLOAD_BYTES}-byte cap (left at ${sourcePath})`);
+    }
+    const name = (0, download_1.sanitizeDownloadName)(suggestedName ?? (0, node_path_1.basename)(sourcePath));
+    const dest = (0, node_path_1.join)(w.downloadDir, name);
+    try {
+        (0, node_fs_1.renameSync)(sourcePath, dest);
+    }
+    catch {
+        (0, node_fs_1.copyFileSync)(sourcePath, dest);
+        try {
+            (0, node_fs_1.unlinkSync)(sourcePath);
+        }
+        catch {
+            /* best effort: a left-behind source is harmless */
+        }
+    }
+    return { path: dest, bytes: (0, node_fs_1.statSync)(dest).size };
+}
+/** Append one action record to the active task's `history.jsonl`. */
+function appendHistory(entry) {
+    const w = peekActiveWorkspace();
+    if (!w)
+        return;
+    try {
+        (0, node_fs_1.appendFileSync)(w.historyPath, `${JSON.stringify(entry)}\n`, { mode: 0o600 });
+    }
+    catch (err) {
+        logErr(`history append failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+//# sourceMappingURL=workspace.js.map

package/dist/src/cli.js

@@ -13,10 +13,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const config_1 = require("./config");
+const tasks_1 = require("./bridge/tasks");
 const manager_1 = require("./executor/manager");
 const select_1 = require("./executor/select");
 const server_1 = require("./bridge/server");
 const datadir_1 = require("./bridge/datadir");
+const workspace_1 = require("./bridge/workspace");
 const auth_1 = require("./bridge/auth");
 const server_2 = require("./mcp/server");
 /** Hard deadline for clean shutdown before we force-exit (a stuck socket must not hang us). */
@@ -49,7 +51,96 @@ function version() {
         return '0.0.0';
     }
 }
+/** Render a byte count as a short human string (1.2 MB, 904 KB, …). */
+function humanBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    const units = ['KB', 'MB', 'GB', 'TB'];
+    let v = n / 1024;
+    let i = 0;
+    while (v >= 1024 && i < units.length - 1) {
+        v /= 1024;
+        i++;
+    }
+    return `${v.toFixed(1)} ${units[i]}`;
+}
+/** Pull `--flag value` / `--flag` out of an arg list, leaving positionals. */
+function flag(args, name) {
+    const i = args.indexOf(name);
+    if (i === -1)
+        return undefined;
+    return args[i + 1];
+}
+function hasFlag(args, name) {
+    return args.includes(name);
+}
+const TASKS_HELP = `chrome-mcp tasks — inspect and prune per-profile task workspaces.
+
+Usage:
+  chrome-mcp tasks list [--json] [--data-dir <path>]
+  chrome-mcp tasks gc   [--older-than <days>] [--keep <n>] [--profile <name>]
+                        [--dry-run] [--data-dir <path>]
+
+gc removes a task only when it is NOT among the newest --keep AND is older than
+--older-than. At least one of --older-than / --keep is required.
+`;
+/**
+ * Handle the `tasks` subcommand family (list / gc). Returns true if argv was a
+ * tasks command (so main() should not start the server), false otherwise.
+ */
+function runTasksCommand(argv) {
+    if (argv[0] !== 'tasks')
+        return false;
+    const args = argv.slice(1);
+    const sub = args[0];
+    const dataDirFlag = flag(args, '--data-dir');
+    if (dataDirFlag)
+        process.env.CHROME_MCP_DATA = dataDirFlag;
+    const dataDir = (0, config_1.resolveDataDir)();
+    if (sub === 'list') {
+        const tasks = (0, tasks_1.listTasks)(dataDir);
+        if (hasFlag(args, '--json')) {
+            process.stdout.write(`${JSON.stringify(tasks, null, 2)}\n`);
+            return true;
+        }
+        if (tasks.length === 0) {
+            process.stdout.write('no tasks found.\n');
+            return true;
+        }
+        process.stdout.write('PROFILE\tTASK\tCREATED\tFILES\tSIZE\n');
+        for (const t of tasks) {
+            process.stdout.write(`${t.profile}\t${t.task}\t${t.createdAt}\t${t.downloads}\t${humanBytes(t.bytes)}\n`);
+        }
+        return true;
+    }
+    if (sub === 'gc') {
+        const olderThan = flag(args, '--older-than');
+        const keep = flag(args, '--keep');
+        if (olderThan === undefined && keep === undefined) {
+            process.stderr.write('tasks gc: pass --older-than <days> and/or --keep <n>.\n');
+            process.exitCode = 1;
+            return true;
+        }
+        const opts = {
+            olderThanDays: olderThan === undefined ? undefined : Number.parseFloat(olderThan),
+            keep: keep === undefined ? undefined : Number.parseInt(keep, 10),
+            profile: flag(args, '--profile'),
+            dryRun: hasFlag(args, '--dry-run'),
+        };
+        const { removed, freedBytes } = (0, tasks_1.gcTasks)(dataDir, opts, Date.now());
+        const prefix = opts.dryRun ? '[dry-run] would remove' : 'removed';
+        process.stdout.write(`${prefix} ${removed.length} task(s), ${humanBytes(freedBytes)}\n`);
+        for (const t of removed) {
+            process.stdout.write(`  ${t.profile}/${t.task} (${humanBytes(t.bytes)})\n`);
+        }
+        return true;
+    }
+    process.stdout.write(TASKS_HELP);
+    return true;
+}
 async function main() {
+    if (runTasksCommand(process.argv.slice(2)))
+        return;
     const cfg = (0, config_1.parseArgs)(process.argv.slice(2));
     if (cfg.showHelp) {
         process.stdout.write(config_1.HELP_TEXT);
@@ -93,6 +184,19 @@ async function main() {
         });
         return;
     }
+    // Each profile is an identity (its own Chrome user-data dir); each task is a
+    // run whose downloads/meta.json live under it. Handshake stays at the data-dir
+    // root (auth is machine-scoped, not per-profile). Fold any pre-0.6 flat layout
+    // into profiles/default/ first — before ensureWorkspace creates the targets.
+    for (const m of (0, datadir_1.migrateLegacyLayout)(dataDir))
+        (0, server_2.logErr)(`migrated legacy layout: ${m}`);
+    const workspace = (0, datadir_1.ensureWorkspace)(dataDir, cfg.profile, cfg.task, {
+        version: version(),
+        pid: process.pid,
+        createdAt: new Date().toISOString(),
+    });
+    (0, workspace_1.setActiveWorkspace)(workspace);
+    (0, server_2.logErr)(`workspace: profile "${workspace.profile}" task "${workspace.task}" → ${workspace.taskDir}`);
     (0, manager_1.configureManager)({
         policy: cfg.policy,
         select: (0, select_1.createSelector)({
@@ -102,7 +206,8 @@ async function main() {
             cdp: {
                 mode: cfg.cdpEndpoint ? 'connect' : 'launch',
                 cdpEndpoint: cfg.cdpEndpoint,
-                userDataDir: dataDir,
+                userDataDir: workspace.profileDir,
+                downloadDir: workspace.downloadDir,
                 headless: cfg.headless,
             },
         }),

package/dist/src/config.d.ts

@@ -12,8 +12,12 @@ export type BackendPreference = 'extension' | 'cdp';
 export interface CliConfig {
     /** Port the bridge binds; 0 = ephemeral (written to the handshake file). */
     wsPort: number;
-    /** Directory holding handshake.json and the CDP-fallback profile. */
+    /** Directory holding handshake.json and the per-profile workspaces. */
     dataDir: string;
+    /** Browser profile (identity). Selects `profiles/<profile>/` under the data dir. */
+    profile: string;
+    /** Task (run). Artifacts land in `profiles/<profile>/tasks/<task>/`. */
+    task: string;
     /** Resolved, fully-defaulted security policy. */
     policy: Policy;
     /** Whether to fall back to a Playwright-driven Chromium when no extension is paired. */
@@ -34,6 +38,20 @@ export interface CliConfig {
 }
 /** Resolve the data dir: `$CHROME_MCP_DATA` or `~/.chrome-mcp`. */
 export declare function resolveDataDir(): string;
+/**
+ * Reduce an arbitrary label to a single safe path segment: no separators, no
+ * `..` traversal, no leading dots. Profile/task names become directories under
+ * the data dir, so they must never escape it.
+ */
+export declare function sanitizeName(name: string, kind: 'profile' | 'task'): string;
+/** Active profile: `$CHROME_MCP_PROFILE` (set by `--profile`) or "default". */
+export declare function resolveProfile(): string;
+/** Active task: `$CHROME_MCP_TASK` (set by `--task`) or "default". */
+export declare function resolveTask(): string;
+/** `profiles/<profile>/` — holds the Chrome user-data dir and this profile's tasks. */
+export declare function resolveProfileDir(dataDir: string, profile: string): string;
+/** `profiles/<profile>/tasks/<task>/` — per-run artifacts (downloads, meta.json). */
+export declare function resolveTaskDir(dataDir: string, profile: string, task: string): string;
 /**
  * Parse argv (the slice AFTER `node script`, i.e. `process.argv.slice(2)`) plus
  * env into a fully-resolved `CliConfig`. Pure except for the optional policy-file

package/dist/src/config.js

@@ -10,6 +10,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HELP_TEXT = void 0;
 exports.resolveDataDir = resolveDataDir;
+exports.sanitizeName = sanitizeName;
+exports.resolveProfile = resolveProfile;
+exports.resolveTask = resolveTask;
+exports.resolveProfileDir = resolveProfileDir;
+exports.resolveTaskDir = resolveTaskDir;
 exports.parseArgs = parseArgs;
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
@@ -20,6 +25,36 @@ const policy_1 = require("./security/policy");
 function resolveDataDir() {
     return process.env.CHROME_MCP_DATA ?? (0, node_path_1.join)((0, node_os_1.homedir)(), '.chrome-mcp');
 }
+const DEFAULT_PROFILE = 'default';
+const DEFAULT_TASK = 'default';
+/**
+ * Reduce an arbitrary label to a single safe path segment: no separators, no
+ * `..` traversal, no leading dots. Profile/task names become directories under
+ * the data dir, so they must never escape it.
+ */
+function sanitizeName(name, kind) {
+    const clean = name.trim().replace(/[^A-Za-z0-9._-]/g, '-').replace(/^\.+/, '');
+    if (!clean || clean === '.' || clean === '..') {
+        throw new Error(`invalid ${kind} name: ${JSON.stringify(name)}`);
+    }
+    return clean;
+}
+/** Active profile: `$CHROME_MCP_PROFILE` (set by `--profile`) or "default". */
+function resolveProfile() {
+    return sanitizeName(process.env.CHROME_MCP_PROFILE ?? DEFAULT_PROFILE, 'profile');
+}
+/** Active task: `$CHROME_MCP_TASK` (set by `--task`) or "default". */
+function resolveTask() {
+    return sanitizeName(process.env.CHROME_MCP_TASK ?? DEFAULT_TASK, 'task');
+}
+/** `profiles/<profile>/` — holds the Chrome user-data dir and this profile's tasks. */
+function resolveProfileDir(dataDir, profile) {
+    return (0, node_path_1.join)(dataDir, 'profiles', profile);
+}
+/** `profiles/<profile>/tasks/<task>/` — per-run artifacts (downloads, meta.json). */
+function resolveTaskDir(dataDir, profile, task) {
+    return (0, node_path_1.join)(resolveProfileDir(dataDir, profile), 'tasks', task);
+}
 function readPolicyFile(path) {
     const raw = (0, node_fs_1.readFileSync)(path, 'utf8');
     const parsed = JSON.parse(raw);
@@ -66,6 +101,12 @@ function parseArgs(argv) {
             case '--data-dir':
                 process.env.CHROME_MCP_DATA = requireValue(argv[++i], '--data-dir');
                 break;
+            case '--profile':
+                process.env.CHROME_MCP_PROFILE = requireValue(argv[++i], '--profile');
+                break;
+            case '--task':
+                process.env.CHROME_MCP_TASK = requireValue(argv[++i], '--task');
+                break;
             case '--policy':
                 policyFile = readPolicyFile(requireValue(argv[++i], '--policy'));
                 break;
@@ -131,6 +172,8 @@ function parseArgs(argv) {
     return {
         wsPort,
         dataDir: resolveDataDir(),
+        profile: resolveProfile(),
+        task: resolveTask(),
         policy,
         cdpFallback,
         cdpEndpoint,
@@ -180,10 +223,19 @@ function requireLogLevel(value) {
 exports.HELP_TEXT = `chrome-mcp — drive a real Chrome browser over MCP.
 
 Usage: chrome-mcp [options]
+       chrome-mcp tasks list [--json]
+       chrome-mcp tasks gc   [--older-than <days>] [--keep <n>] [--profile <name>] [--dry-run]
 
 Connection:
   --port <n>             WebSocket bridge port (default ${protocol_1.DEFAULT_WS_PORT}; 0 = ephemeral)
   --data-dir <path>      Override the data dir (default ~/.chrome-mcp)
+  --profile <name>       Default browser profile / identity (default "default").
+                         Artifacts live under profiles/<name>/. At runtime, switch
+                         with the profile_use tool. Several browsers can pair to the
+                         SAME port+token at once, each declaring its own Profile in
+                         the extension Options; tools route to the active profile.
+  --task <name>          Task label (default "default"). Downloads and a meta.json
+                         land in profiles/<profile>/tasks/<task>/.
   --print-pairing        Write the handshake and print its path, then exit
   --persist-token        Reuse a stable on-disk token across restarts so the
                          extension never has to re-pair (default: fresh per boot).

package/dist/src/executor/extension-executor.d.ts

@@ -13,6 +13,9 @@ export declare class ExtensionExecutor implements Executor {
     private readonly bridge;
     readonly backend: BackendKind;
     constructor(bridge: BridgeServer);
+    /** The profile this executor routes to = the active task workspace's profile
+     *  (set by `profile_use`). Falls back to "default" before a workspace exists. */
+    private activeProfile;
     private send;
     status(): ExecutorStatus;
     ensureReady(): Promise<void>;

package/dist/src/executor/extension-executor.js

@@ -11,6 +11,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ExtensionExecutor = void 0;
 const types_1 = require("./types");
+const workspace_1 = require("../bridge/workspace");
 /** Flatten a Target into the params a wire command carries. */
 function targetParams(t) {
     if (!t)
@@ -23,17 +24,26 @@ class ExtensionExecutor {
     constructor(bridge) {
         this.bridge = bridge;
     }
+    /** The profile this executor routes to = the active task workspace's profile
+     *  (set by `profile_use`). Falls back to "default" before a workspace exists. */
+    activeProfile() {
+        return (0, workspace_1.peekActiveWorkspace)()?.profile ?? 'default';
+    }
     send(method, params, opts) {
-        return this.bridge.sendCommand(method, params, opts);
+        return this.bridge.sendCommand(method, params, { ...opts, profile: this.activeProfile() });
     }
     status() {
-        const connected = this.bridge.hasActiveExtension();
+        const profile = this.activeProfile();
+        const connected = this.bridge.hasConnection(profile);
         return {
             ready: connected,
             backend: this.backend,
             activeTabId: null, // not known synchronously
             extensionConnected: connected,
             cdpAttached: false,
+            detail: connected ? undefined : `active profile "${profile}" has no paired browser`,
+            activeProfile: profile,
+            connectedProfiles: this.bridge.connectedProfiles(),
         };
     }
     async ensureReady() {
@@ -41,7 +51,7 @@ class ExtensionExecutor {
         // already confirmed an extension is paired + responsive before picking us.
     }
     async ping(deadlineMs = 800) {
-        if (!this.bridge.hasActiveExtension())
+        if (!this.bridge.hasConnection(this.activeProfile()))
             return false;
         try {
             await this.send('ping_probe', {}, { timeoutMs: deadlineMs });
@@ -131,7 +141,22 @@ class ExtensionExecutor {
     }
     // -- privileged ---------------------------------------------------------
     async download(args) {
-        return (await this.send('download_file', { url: args.url, ...targetParams(args.target), suggestedName: args.suggestedName }, { tabId: args.tabId }));
+        const res = (await this.send('download_file', { url: args.url, ...targetParams(args.target), suggestedName: args.suggestedName }, { tabId: args.tabId }));
+        // The extension can only write to the user's Downloads dir; relocate the file
+        // into the active task's downloads/ so each task collects its own artifacts.
+        // If the move fails, keep Chrome's path rather than reporting a phantom failure.
+        if (res.sourcePath) {
+            try {
+                const moved = (0, workspace_1.captureDownload)(res.sourcePath, res.suggestedName);
+                return { ...res, path: moved.path, bytes: moved.bytes, sourcePath: undefined };
+            }
+            catch {
+                // Capture failed (e.g. over the size cap): leave the file where Chrome put
+                // it and report that path instead of failing the call.
+                return { ...res, sourcePath: undefined };
+            }
+        }
+        return res;
     }
     async uploadFile(t, files, opts) {
         return (await this.send('upload_file', { ...targetParams(t), files }, { tabId: opts?.tabId }));

package/dist/src/executor/types.d.ts

@@ -86,6 +86,15 @@ export interface DownloadResult {
     bytes: number;
     mimeType?: string;
     suggestedName?: string;
+    /**
+     * Extension backend only: the absolute path where Chrome first saved the file
+     * (the user's Downloads dir). The server moves it into the active task's
+     * `downloads/` and clears this field, so it is never present in a final result
+     * returned to the MCP client.
+     */
+    sourcePath?: string;
+    /** Extension backend only: the chrome.downloads id, surfaced for diagnostics. */
+    downloadId?: number;
 }
 /** One interactive/landmark element in an accessibility snapshot. `ref` is stable until the tab navigates. */
 export interface SnapshotNode {
@@ -128,6 +137,10 @@ export interface ExecutorStatus {
     detail?: string;
     extensionConnected: boolean;
     cdpAttached: boolean;
+    /** Extension backend: the profile tools currently route to (set by profile_use). */
+    activeProfile?: string;
+    /** Extension backend: every profile with a live browser right now. */
+    connectedProfiles?: string[];
 }
 export interface Executor {
     readonly backend: BackendKind;