@proagentstore/cli 0.4.71 → 0.4.73

package/dist/browser-runner/local-browser/engine.js

@@ -0,0 +1,150 @@
+/**
+ * How a research run launches its CLI (#944): arguments, environment and prompt, per engine.
+ *
+ * The opposite of a coding session's launch. Coder starts its engines with every permission
+ * (`--dangerously-skip-permissions`, `--sandbox danger-full-access`, `coding/handlers.ts`) because
+ * it edits a repository; a research run must not be able to reach the web any way except through
+ * the runner's policy bridge. So:
+ *
+ *  - Claude Code: `--tools ""` removes EVERY built-in tool (WebFetch, WebSearch, Bash, file edits),
+ *    `--strict-mcp-config` loads only the bridge, `--allowedTools mcp__pags_browser` pre-approves
+ *    it, and `--permission-mode dontAsk` refuses anything else without stopping to ask.
+ *  - Codex: `--sandbox read-only` (its shell cannot write, and per Codex's sandbox design has no
+ *    network), `--ignore-user-config` (no MCP servers or providers from the user's own config — auth
+ *    still comes from the login), web search switched off, and the bridge as its only MCP server.
+ *    NOT VERIFIED END TO END on a live machine: that read-only shell commands get no network, and
+ *    which of the two web-search keys a given Codex version honours. #947 holds that test.
+ *
+ * Neither ever gets a provider API key unless the owner chose `api-key`: subscription and machine
+ * sign-in remove ANTHROPIC_API_KEY and OPENAI_API_KEY from the inherited environment (an empty
+ * overlay value means remove — `mergeEnv`), because a key left in a developer's shell silently
+ * turns a subscription run into per-token billing.
+ */
+import { mergeEnv } from "../coding/engine-env.js";
+import { resolveEngineAuth } from "../coding/engine-auth.js";
+/** The bridge's MCP server name — and so the prefix of its tools inside the CLI. */
+export const BRIDGE_SERVER_NAME = "pags_browser";
+const PROVIDER_KEYS = ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"];
+/** The engine's environment: the machine's, minus provider keys unless the owner chose api-key. */
+export function engineEnv(authMode, engine, toolTimeoutMs, base = process.env) {
+    const overlay = {};
+    if (authMode !== "api-key")
+        for (const k of PROVIDER_KEYS)
+            overlay[k] = "";
+    // A consent or captcha pause holds the tool call open until the owner acts. Claude Code's
+    // default MCP tool timeout would end that call long before; give it the run's own budget.
+    if (engine === "claude")
+        overlay.MCP_TOOL_TIMEOUT = String(toolTimeoutMs);
+    return mergeEnv(base, overlay);
+}
+/** What the engine authenticates with, read from the env it is spawned with. */
+export function observedEngineAuth(engine, env) {
+    return resolveEngineAuth(engine, env);
+}
+const toml = (v) => JSON.stringify(v); // a TOML basic string accepts JSON's escapes
+export function buildEngineSpec(input) {
+    const env = engineEnv(input.authMode, input.engine, input.toolTimeoutMs, input.baseEnv);
+    if (input.engine === "claude") {
+        const json = JSON.stringify({ mcpServers: { [BRIDGE_SERVER_NAME]: { command: input.bridge.command, args: input.bridge.args, env: input.bridge.env } } });
+        return {
+            command: "claude",
+            args: [
+                "-p",
+                input.prompt,
+                "--output-format",
+                "stream-json",
+                "--verbose",
+                "--tools",
+                "",
+                "--strict-mcp-config",
+                "--mcp-config",
+                input.mcpConfigPath,
+                "--allowedTools",
+                `mcp__${BRIDGE_SERVER_NAME}`,
+                "--permission-mode",
+                "dontAsk",
+            ],
+            env,
+            mcpConfig: { path: input.mcpConfigPath, json },
+        };
+    }
+    const envTable = `{ ${Object.entries(input.bridge.env)
+        .map(([k, v]) => `${k} = ${toml(v)}`)
+        .join(", ")} }`;
+    const key = `mcp_servers.${BRIDGE_SERVER_NAME}`;
+    return {
+        command: "codex",
+        args: [
+            "exec",
+            "--json",
+            "--skip-git-repo-check",
+            "--sandbox",
+            "read-only",
+            "--ignore-user-config",
+            "-c",
+            `${key}.command=${toml(input.bridge.command)}`,
+            "-c",
+            `${key}.args=[${input.bridge.args.map(toml).join(", ")}]`,
+            "-c",
+            `${key}.env=${envTable}`,
+            "-c",
+            `${key}.tool_timeout_sec=${Math.ceil(input.toolTimeoutMs / 1000)}`,
+            // Two spellings across Codex versions; an unknown key is ignored, so both are set.
+            "-c",
+            'web_search="disabled"',
+            "-c",
+            "tools.web_search=false",
+            input.prompt,
+        ],
+        env,
+    };
+}
+/** The brief the CLI is given. The rules are restated, but the bridge is what enforces them. */
+export function researchPrompt(e) {
+    const t = (name) => `mcp__${BRIDGE_SERVER_NAME}__${name}`;
+    const sites = e.policy.allowDomains.length ? `Stay on these sites: ${e.policy.allowDomains.join(", ")}.` : "Any public site may be visited; a site the owner has not approved pauses the run until they decide.";
+    return [
+        "You are doing read-only web research for the owner of this machine.",
+        "",
+        `Objective: ${e.objective}`,
+        "",
+        "How to work:",
+        `- Your only tools are the browser tools from the ${BRIDGE_SERVER_NAME} server. Use ${t("browser_navigate")} to open pages (build search URLs with query parameters — you cannot type into pages), ${t("browser_snapshot")} to read them, and ${t("browser_click")} only for links, tabs and pagination.`,
+        "- Never try to sign in, submit, apply, buy, post or message anything. Never work around a captcha, a login wall, a paywall or a block — report it.",
+        `- ${sites}${e.policy.denyDomains.length ? ` Never visit: ${e.policy.denyDomains.join(", ")}.` : ""}`,
+        `- Limits: ${e.limits.maxPages} pages, ${e.limits.maxActions} browser actions, ${e.limits.maxMinutes} minutes.`,
+        `- For every result, call ${t("record_finding")} with the page URL and the exact text that supports it. For every source you could not read, call ${t("report_source_failure")}.`,
+        `- When done, call ${t("finish_research")} with a short summary of what you found and what you could not reach, then stop.`,
+    ].join("\n");
+}
+const LOGIN_MISSING = {
+    claude: /not logged in|please run \/login|invalid api key|oauth token (has )?expired|authentication_error/i,
+    codex: /not logged in|run `?codex login|401 unauthorized|please log ?in|token (is )?expired/i,
+};
+/** Is this output the CLI saying it is not signed in? */
+export function missingLogin(engine, output) {
+    return LOGIN_MISSING[engine].test(output);
+}
+export function signInHelp(engine) {
+    return engine === "claude"
+        ? "The Claude Code CLI on this machine is not signed in. Run `claude`, then /login, on that machine and start the run again."
+        : "The Codex CLI on this machine is not signed in. Run `codex login` on that machine and start the run again.";
+}
+/** The CLI's own closing text, from its structured output — the summary when it never called finish_research. */
+export function finalText(engine, lines) {
+    for (let i = lines.length - 1; i >= 0; i--) {
+        let ev;
+        try {
+            ev = JSON.parse(lines[i]);
+        }
+        catch {
+            continue;
+        }
+        if (engine === "claude" && ev.type === "result" && typeof ev.result === "string")
+            return ev.result;
+        const item = ev.item;
+        if (engine === "codex" && ev.type === "item.completed" && item?.type === "agent_message" && typeof item.text === "string")
+            return item.text;
+    }
+    return "";
+}

package/dist/browser-runner/local-browser/runtime.js

@@ -0,0 +1,449 @@
+/**
+ * Local CLI browser research on the runner (#944) — the run registry and its lifecycle.
+ *
+ * One run = one Codex or Claude Code process, signed in on this machine, in its own working folder
+ * (a managed scratch folder by default; never a repository), whose only window on the web is the
+ * policy bridge (bridge.ts). The runtime owns everything PAGS later pulls with `status`:
+ *
+ *  - idempotency: a start with a requestId this runner already holds returns that run;
+ *  - the concurrency cap the API resolved (`limits.maxConcurrent`), per instance;
+ *  - the time limit — ACTIVE time only, so a run waiting on the owner is not timed out by the wait;
+ *  - pauses: a consent, captcha or sign-in pause holds the bridge call until `resume` (or cancel,
+ *    or the time limit) releases it;
+ *  - the trace: seq-numbered, redacted events, capped per run;
+ *  - the result envelope, once the CLI exits;
+ *  - retention: an ended run's folder and record are removed after `retentionMs`.
+ *
+ * Runs live in memory. A runner restart loses them, and `status` then answers 404 for the run —
+ * which the API reads as "the runner lost this run" and ends it, rather than waiting forever.
+ */
+import { spawn as nodeSpawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { RunnerInputError } from "../errors.js";
+import { BrowserBridge, domainWithin } from "./bridge.js";
+import { BRIDGE_ENV } from "./bridge-stdio.js";
+import { LOCAL_BROWSER_AUTH_MODES, LOCAL_BROWSER_ENGINES, LOCAL_BROWSER_TASK_TYPE, redactDetail, redactText, secretEnvValues, } from "./contract.js";
+import { buildEngineSpec, finalText, missingLogin, observedEngineAuth, researchPrompt, signInHelp } from "./engine.js";
+const MAX_EVENTS = 2000;
+const OUTPUT_LINES = 400;
+const SAFE_ID = /^[A-Za-z0-9_.:-]{1,100}$/;
+const strList = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === "string").map((x) => x.toLowerCase()) : []);
+const posInt = (v, max) => (typeof v === "number" && Number.isInteger(v) && v >= 1 && v <= max ? v : null);
+/** The envelope, validated at the runner's boundary — PAGS sends it, but the relay is a boundary. */
+export function parseEnvelope(raw) {
+    const o = (raw && typeof raw === "object" ? raw : {});
+    const bad = (what) => new RunnerInputError(`Invalid local browser task: ${what}`);
+    if (o.type !== LOCAL_BROWSER_TASK_TYPE)
+        throw bad(`type must be ${LOCAL_BROWSER_TASK_TYPE}`);
+    for (const k of ["runId", "requestId", "instanceId"])
+        if (typeof o[k] !== "string" || !SAFE_ID.test(o[k]))
+            throw bad(`${k} is required`);
+    if (typeof o.objective !== "string" || !o.objective.trim() || o.objective.length > 4000)
+        throw bad("objective is required");
+    if (!LOCAL_BROWSER_ENGINES.includes(o.engine))
+        throw bad("engine must be claude or codex");
+    if (!LOCAL_BROWSER_AUTH_MODES.includes(o.authMode))
+        throw bad("authMode is invalid");
+    const ws = (o.workspace && typeof o.workspace === "object" ? o.workspace : {});
+    if (ws.kind !== "scratch" && !(ws.kind === "path" && typeof ws.path === "string"))
+        throw bad("workspace must be scratch or a path");
+    if (o.browserProfile !== "isolated" && o.browserProfile !== "default")
+        throw bad("browserProfile must be isolated or default");
+    const p = (o.policy && typeof o.policy === "object" ? o.policy : {});
+    if (p.mode !== "research_only")
+        throw bad("only research_only runs are supported");
+    const l = (o.limits && typeof o.limits === "object" ? o.limits : {});
+    const limits = {
+        maxMinutes: posInt(l.maxMinutes, 60) ?? 0,
+        maxPages: posInt(l.maxPages, 200) ?? 0,
+        maxActions: posInt(l.maxActions, 1000) ?? 0,
+        maxConcurrent: posInt(l.maxConcurrent, 3) ?? 0,
+    };
+    if (Object.values(limits).some((v) => !v))
+        throw bad("limits are out of range");
+    const schema = (o.resultSchema && typeof o.resultSchema === "object" ? o.resultSchema : {});
+    return {
+        type: LOCAL_BROWSER_TASK_TYPE,
+        runId: o.runId,
+        requestId: o.requestId,
+        instanceId: o.instanceId,
+        objective: o.objective.trim(),
+        engine: o.engine,
+        authMode: o.authMode,
+        workspace: ws.kind === "path" ? { kind: "path", path: ws.path } : { kind: "scratch" },
+        browserProfile: o.browserProfile,
+        policy: {
+            mode: "research_only",
+            allowDomains: strList(p.allowDomains),
+            denyDomains: strList(p.denyDomains),
+            consentedDomains: strList(p.consentedDomains),
+            profileConsented: p.profileConsented === true,
+            consentIds: consentIdMap(p.consentIds),
+        },
+        limits,
+        resultSchema: { id: typeof schema.id === "string" ? schema.id : "findings", version: typeof schema.version === "number" ? schema.version : 1 },
+    };
+}
+/** Decision ids keyed by lowercase domain (or `*`), from an untrusted object. */
+function consentIdMap(raw) {
+    const out = {};
+    if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+        for (const [k, v] of Object.entries(raw).slice(0, 200))
+            if (typeof v === "string" && SAFE_ID.test(v))
+                out[k.toLowerCase()] = v;
+    }
+    return out;
+}
+/**
+ * A `~/…` workspace, resolved under the home directory — re-checked here against the real disk,
+ * because the API could only check the string. A symlink out of home is refused like `..` is.
+ */
+export function resolveWorkspacePath(path, home) {
+    if (!/^~\/[^\0]+$/.test(path))
+        throw new RunnerInputError('The workspace folder must be written "~/…", under this machine\'s home folder.');
+    const realHome = realpathSync(home);
+    const target = resolve(realHome, path.slice(2));
+    if (!target.startsWith(realHome + sep))
+        throw new RunnerInputError("The workspace folder must be inside this machine's home folder.");
+    mkdirSync(target, { recursive: true });
+    const real = realpathSync(target);
+    if (!real.startsWith(realHome + sep))
+        throw new RunnerInputError("The workspace folder resolves outside this machine's home folder (a symlink).");
+    return real;
+}
+export class LocalBrowserRuntime {
+    deps;
+    runs = new Map();
+    root;
+    now;
+    spawn;
+    retentionMs;
+    constructor(deps) {
+        this.deps = deps;
+        this.root = join(deps.dataDir, "local-browser");
+        this.now = deps.now ?? Date.now;
+        this.spawn = deps.spawn ?? nodeSpawn;
+        this.retentionMs = deps.retentionMs ?? 24 * 60 * 60 * 1000;
+    }
+    /** Start a run. A requestId already held for the instance returns that run instead. */
+    start(raw) {
+        const envelope = parseEnvelope(raw);
+        this.sweep();
+        const same = [...this.runs.values()].find((r) => r.envelope.instanceId === envelope.instanceId && r.envelope.requestId === envelope.requestId);
+        if (same)
+            return { runId: same.envelope.runId, taskId: same.envelope.runId, status: same.state, existing: true };
+        if (this.runs.has(envelope.runId))
+            throw new RunnerInputError(`Run ${envelope.runId} already exists with another requestId`, 409);
+        const active = [...this.runs.values()].filter((r) => r.envelope.instanceId === envelope.instanceId && r.state !== "ended").length;
+        if (active >= envelope.limits.maxConcurrent)
+            throw new RunnerInputError(`This machine is already running ${active} research run(s) for this agent (limit ${envelope.limits.maxConcurrent}).`, 409);
+        const selfUrl = this.deps.selfUrl();
+        if (!selfUrl)
+            throw new RunnerInputError("The runner is still starting; try again in a moment.", 409);
+        const dir = join(this.root, envelope.instanceId, envelope.runId);
+        mkdirSync(dir, { recursive: true });
+        const workDir = envelope.workspace.kind === "path" ? resolveWorkspacePath(envelope.workspace.path, this.deps.homeDir ?? homedir()) : join(dir, "scratch");
+        mkdirSync(workDir, { recursive: true });
+        const run = {
+            envelope,
+            dir,
+            workDir,
+            token: randomBytes(24).toString("hex"),
+            state: "running",
+            events: [],
+            seq: 0,
+            consented: new Set(envelope.policy.consentedDomains),
+            deny: new Set(envelope.policy.denyDomains),
+            profileConsented: envelope.policy.profileConsented,
+            consentIds: new Map(Object.entries(envelope.policy.consentIds ?? {})),
+            secrets: secretEnvValues(process.env),
+            activeSince: this.now(),
+            activeMs: 0,
+            waiters: [],
+            output: [],
+            engineAuth: "unknown",
+            cancelled: false,
+            timedOut: false,
+        };
+        this.runs.set(envelope.runId, run);
+        // Not awaited: a signed-in-profile consent pause can hold the launch for minutes, and the
+        // relay command that started the run must answer now. Everything after this is in `status`.
+        void this.launch(run, selfUrl).catch((err) => this.end(run, { outcome: "failed", error: err instanceof Error ? err.message : String(err) }));
+        return { runId: envelope.runId, taskId: envelope.runId, status: run.state, existing: false };
+    }
+    async launch(run, selfUrl) {
+        const e = run.envelope;
+        // The signed-in profile is the owner's own browser — never without their say-so (#947).
+        if (e.browserProfile === "default" && !run.profileConsented) {
+            this.emit(run, { type: "consent.requested", detail: { scope: "signed_in_profile" } });
+            const outcome = await this.pause(run, "consent_required", { scope: "signed_in_profile" });
+            if (outcome !== "resumed" || !run.profileConsented)
+                throw new Error("The owner did not allow research in their signed-in browser profile.");
+        }
+        if (e.browserProfile === "default")
+            this.emit(run, { type: "policy.decision", ...this.consentRef(run, "*"), detail: { scope: "signed_in_profile", decision: "consented" } });
+        run.browser = await this.deps.browserFor(e.browserProfile, run.dir);
+        run.bridge = new BrowserBridge(run.browser.tools, {
+            emit: (ev) => this.emit(run, ev),
+            pause: (reason, detail) => this.pause(run, reason, detail),
+            consentIdFor: (host) => this.consentRef(run, host).consentId,
+            isDenied: (host) => [...run.deny].some((d) => domainWithin(host, d)),
+            isPermitted: (host) => [...e.policy.allowDomains, ...run.consented].some((d) => domainWithin(host, d)),
+            allowListOnly: () => e.policy.allowDomains.length > 0,
+            overTime: () => this.activeMs(run) >= e.limits.maxMinutes * 60_000,
+            limits: e.limits,
+        });
+        const bridgeScript = this.deps.bridgeScript ?? fileURLToPath(new URL("./bridge-stdio.js", import.meta.url));
+        const spec = buildEngineSpec({
+            engine: e.engine,
+            authMode: e.authMode,
+            prompt: researchPrompt(e),
+            bridge: { command: process.execPath, args: [bridgeScript], env: { [BRIDGE_ENV.url]: selfUrl, [BRIDGE_ENV.runId]: e.runId, [BRIDGE_ENV.token]: run.token } },
+            mcpConfigPath: join(run.dir, "mcp.json"),
+            toolTimeoutMs: e.limits.maxMinutes * 60_000,
+        });
+        if (spec.mcpConfig)
+            writeFileSync(spec.mcpConfig.path, spec.mcpConfig.json, { mode: 0o600 });
+        // The env the engine actually gets — a key the owner chose to pass (api-key mode) included.
+        run.secrets = secretEnvValues({ ...process.env, ...spec.env });
+        run.engineAuth = observedEngineAuth(e.engine, spec.env);
+        this.emit(run, { type: "engine.auth_checked", detail: { engine: e.engine, authMode: e.authMode, engineAuth: run.engineAuth } });
+        const child = this.spawn(spec.command, spec.args, { cwd: run.workDir, env: spec.env, stdio: ["ignore", "pipe", "pipe"] });
+        run.child = child;
+        this.emit(run, { type: "engine.started", detail: { engine: e.engine, workspace: e.workspace.kind } });
+        let buf = "";
+        const keep = (chunk) => {
+            buf += chunk.toString();
+            const lines = buf.split("\n");
+            buf = lines.pop() ?? "";
+            for (const line of lines)
+                if (line.trim())
+                    run.output.push(line.slice(0, 20_000));
+            if (run.output.length > OUTPUT_LINES)
+                run.output.splice(0, run.output.length - OUTPUT_LINES);
+        };
+        child.stdout?.on("data", keep);
+        child.stderr?.on("data", keep);
+        child.on("error", (err) => {
+            const missing = err.code === "ENOENT";
+            this.end(run, { outcome: "failed", error: missing ? `The ${e.engine === "claude" ? "Claude Code" : "Codex"} CLI is not installed on this machine (\`${spec.command}\` was not found).` : err.message });
+        });
+        child.on("close", (code) => {
+            if (buf.trim())
+                run.output.push(buf);
+            this.emit(run, { type: "engine.ended", detail: { exitCode: code ?? -1 } });
+            this.finish(run, code ?? -1);
+        });
+        run.timer = setInterval(() => {
+            if (run.state !== "ended" && this.activeMs(run) >= e.limits.maxMinutes * 60_000 + 60_000) {
+                // The bridge already refuses past the limit; this is the backstop for a CLI that keeps
+                // thinking without calling a tool.
+                run.timedOut = true;
+                this.kill(run);
+            }
+        }, 5_000);
+        run.timer.unref?.();
+    }
+    activeMs(run) {
+        return run.activeMs + (run.state === "running" ? this.now() - run.activeSince : 0);
+    }
+    emit(run, ev) {
+        if (run.events.length >= MAX_EVENTS)
+            return;
+        const { detail: raw, ...rest } = ev;
+        const detail = redactDetail(raw, 0, run.secrets);
+        run.events.push({ ...rest, ...(detail && Object.keys(detail).length ? { detail } : {}), at: new Date(this.now()).toISOString(), seq: ++run.seq });
+    }
+    pause(run, reason, detail) {
+        if (run.state === "ended" || run.cancelled)
+            return Promise.resolve("stopped");
+        if (run.state === "running") {
+            run.activeMs += this.now() - run.activeSince;
+            run.state = "paused";
+            run.pauseReason = reason;
+            this.emit(run, { type: "run.paused", pauseReason: reason, detail });
+        }
+        return new Promise((resolveWait) => run.waiters.push(resolveWait));
+    }
+    release(run, outcome) {
+        if (run.state === "paused") {
+            run.state = "running";
+            run.pauseReason = undefined;
+            run.activeSince = this.now();
+            if (outcome === "resumed")
+                this.emit(run, { type: "run.resumed" });
+        }
+        for (const w of run.waiters.splice(0))
+            w(outcome);
+    }
+    /** The owner acted: refresh consent and release whatever the run was waiting on. */
+    resume(raw) {
+        const o = (raw && typeof raw === "object" ? raw : {});
+        const run = this.get(String(o.runId ?? ""));
+        if (run.state === "ended")
+            throw new RunnerInputError("The run has ended", 409);
+        for (const [d, id] of Object.entries(consentIdMap(o.consentIds)))
+            run.consentIds.set(d, id);
+        for (const d of strList(o.consentedDomains))
+            run.consented.add(d);
+        for (const d of strList(o.denyDomains))
+            run.deny.add(d);
+        if (o.profileConsented === true)
+            run.profileConsented = true;
+        this.release(run, "resumed");
+        return this.status({ runId: run.envelope.runId, afterSeq: run.seq });
+    }
+    cancel(raw) {
+        const runId = String(raw?.runId ?? "");
+        const run = this.get(runId);
+        if (run.state !== "ended") {
+            run.cancelled = true;
+            this.release(run, "stopped");
+            if (run.child)
+                this.kill(run);
+            else
+                this.end(run, { outcome: "failed", error: "Cancelled by the owner" });
+        }
+        return { runId, state: run.state };
+    }
+    status(raw) {
+        const o = (raw && typeof raw === "object" ? raw : {});
+        const run = this.get(String(o.runId ?? ""));
+        const after = typeof o.afterSeq === "number" && o.afterSeq > 0 ? o.afterSeq : 0;
+        return {
+            runId: run.envelope.runId,
+            state: run.state,
+            ...(run.pauseReason ? { pauseReason: run.pauseReason } : {}),
+            events: run.events.filter((e) => e.seq > after).slice(0, 500),
+            lastSeq: run.seq,
+            ...(run.result ? { result: run.result } : {}),
+        };
+    }
+    /** Does this token belong to this run? The bridge forwarder's only credential. */
+    authorizeBridge(runId, token) {
+        const run = this.runs.get(runId);
+        return !!run && run.state !== "ended" && token.length > 0 && token === run.token;
+    }
+    async bridge(raw) {
+        const o = (raw && typeof raw === "object" ? raw : {});
+        const run = this.get(String(o.runId ?? ""));
+        if (!run.bridge || run.state === "ended")
+            throw new RunnerInputError("The run is not active", 409);
+        if (o.op === "list")
+            return { tools: await run.bridge.listTools() };
+        if (o.op === "call" && typeof o.name === "string")
+            return run.bridge.callTool(o.name, (o.args && typeof o.args === "object" ? o.args : {}));
+        throw new RunnerInputError("op must be list or call");
+    }
+    /** The decision that covers this host (or `*`), as an event field — empty when none does. */
+    consentRef(run, host) {
+        if (host === "*")
+            return run.consentIds.has("*") ? { consentId: run.consentIds.get("*") } : {};
+        let best = null;
+        for (const [d, id] of run.consentIds)
+            if (d !== "*" && domainWithin(host, d) && (!best || d.length > best[0].length))
+                best = [d, id];
+        return best ? { consentId: best[1] } : {};
+    }
+    get(runId) {
+        const run = this.runs.get(runId);
+        if (!run)
+            throw new RunnerInputError(`No local browser run ${runId} on this runner (it may have restarted)`, 404);
+        return run;
+    }
+    kill(run) {
+        const child = run.child;
+        if (!child || child.exitCode !== null)
+            return;
+        child.kill("SIGTERM");
+        setTimeout(() => {
+            if (child.exitCode === null)
+                child.kill("SIGKILL");
+        }, 5_000).unref?.();
+    }
+    /** The CLI exited: assemble the result from what the bridge recorded and what the CLI said. */
+    finish(run, code) {
+        if (run.state === "ended")
+            return;
+        this.end(run, this.outcomeOf(run, code));
+    }
+    outcomeOf(run, code) {
+        const e = run.envelope;
+        const bridge = run.bridge;
+        const summary = bridge?.summary ?? finalText(e.engine, run.output);
+        const found = (bridge?.findings.length ?? 0) > 0;
+        if (run.cancelled)
+            return { outcome: "failed", error: "Cancelled by the owner" };
+        if (missingLogin(e.engine, run.output.join("\n")) && !found)
+            return { outcome: "failed", error: signInHelp(e.engine), engineAuth: "missing_login" };
+        const limit = `Stopped at the ${e.limits.maxMinutes}-minute limit.`;
+        if (run.timedOut)
+            return { outcome: found ? "completed" : "failed", summary: summary || limit, error: limit };
+        if (code !== 0 && !bridge?.summary) {
+            const tail = run.output.slice(-5).join("\n").slice(-800);
+            return { outcome: "failed", summary, error: `The ${e.engine} CLI exited with code ${code}${tail ? `: ${tail}` : ""}` };
+        }
+        return { outcome: "completed", summary };
+    }
+    end(run, r) {
+        if (run.state === "ended")
+            return;
+        if (run.state === "paused")
+            this.release(run, "stopped");
+        if (run.timer)
+            clearInterval(run.timer);
+        run.state = "ended";
+        run.endedAt = this.now();
+        run.result = {
+            runId: run.envelope.runId,
+            outcome: r.outcome,
+            findings: run.bridge?.findings ?? [],
+            sourceFailures: run.bridge?.sourceFailures ?? [],
+            summary: redactText((r.summary ?? "").slice(0, 4000), run.secrets),
+            traceId: run.envelope.runId,
+            engineAuth: r.engineAuth ?? run.engineAuth,
+            // CLI output becomes this text, and a CLI prints whatever it was given: redacted before it is kept.
+            ...(r.outcome === "failed" ? { error: redactText((r.error ?? "The run failed without a reason.").slice(0, 1000), run.secrets) } : {}),
+        };
+        if (run.child && run.child.exitCode === null)
+            this.kill(run);
+        void run.browser?.stop().catch(() => undefined);
+    }
+    /** Drop ended runs past retention, with their folders. Custom workspaces are the owner's and are never deleted. */
+    sweep() {
+        const cutoff = this.now() - this.retentionMs;
+        for (const [id, run] of this.runs) {
+            if (run.state === "ended" && (run.endedAt ?? 0) < cutoff) {
+                rmSync(run.dir, { recursive: true, force: true });
+                this.runs.delete(id);
+            }
+        }
+        // Folders left by a previous runner process (its runs are gone from memory).
+        if (!existsSync(this.root))
+            return;
+        for (const instance of readdirSync(this.root)) {
+            const instDir = join(this.root, instance);
+            for (const runId of readdirSync(instDir)) {
+                if (this.runs.has(runId))
+                    continue;
+                const dir = join(instDir, runId);
+                if (statSync(dir).mtimeMs < cutoff)
+                    rmSync(dir, { recursive: true, force: true });
+            }
+        }
+    }
+    /** Runner shutdown: stop every engine. Their runs end failed — the process that held them is going. */
+    closeAll() {
+        for (const run of this.runs.values()) {
+            if (run.state !== "ended") {
+                run.cancelled = true;
+                this.release(run, "stopped");
+                this.end(run, { outcome: "failed", error: "The runner shut down during the run" });
+            }
+        }
+    }
+}

package/dist/browser-runner/runner.js

@@ -12,6 +12,8 @@ import { HumanHandoffError, RunnerInputError } from "./errors.js";
 import { resolveHandoffStatus } from "./handoff-status.js";
 import { RunnerStore } from "./store.js";
 import { CodingRuntime } from "./coding/runtime.js";
+import { LocalBrowserRuntime } from "./local-browser/runtime.js";
+import { LOCAL_BROWSER_TASK_TYPE } from "./local-browser/contract.js";
 import { WORKFLOW_DRIVEN_TASKS } from "./task-types.js";
 /** True for a plain object. */
 function isRecord(value) {
@@ -73,6 +75,10 @@ export class LocalRunner {
     store;
     /** Local tmux coding sessions (the second runtime — AgentCoder port). */
     coding;
+    /** Local CLI browser research (#944): a signed-in Codex / Claude Code CLI researching through the policy bridge. */
+    localBrowser;
+    /** This runner's own local URL, once the server listens — the bridge forwarder calls back to it. */
+    selfUrl = null;
     /** Live human-takeover sessions, keyed by task id (the page is kept alive). */
     takeovers = new Map();
     constructor(config) {
@@ -80,6 +86,19 @@ export class LocalRunner {
         mkdirSync(config.dataDir, { recursive: true });
         this.store = new RunnerStore(config.dataDir);
         this.coding = new CodingRuntime(join(config.dataDir, "repos"));
+        this.localBrowser = new LocalBrowserRuntime({
+            dataDir: config.dataDir,
+            selfUrl: () => this.selfUrl,
+            // `default` is the runner's own signed-in browser, shared and never closed by a run;
+            // `isolated` is a fresh profile inside the run's folder, removed with it.
+            browserFor: async (profile, runDir) => {
+                if (profile === "default")
+                    return { tools: await this.getMcp(), stop: async () => undefined };
+                const mcp = new McpRuntime();
+                await mcp.start({ userDataDir: join(runDir, "profile"), headless: config.headless });
+                return { tools: mcp, stop: () => mcp.stop() };
+            },
+        });
         // Tasks paused/running on a previous process are orphaned now — their
         // pages and takeover sessions are gone. Fail them so the board is clean.
         const expired = this.store.expireInFlightTasks();
@@ -94,7 +113,7 @@ export class LocalRunner {
             runtimePlane: "pags",
             runnerRole: "tool-executor",
             capabilities: [...CAPABILITIES, ...CodingRuntime.capabilities()],
-            taskTypes: ["echo", "browser.open", "job.apply_agent", "site_builder_runtime", ...CodingRuntime.taskTypes()],
+            taskTypes: ["echo", "browser.open", "job.apply_agent", "site_builder_runtime", LOCAL_BROWSER_TASK_TYPE, ...CodingRuntime.taskTypes()],
             approvalRequiredFor: [...APPROVAL_REQUIRED_TASKS],
         };
     }
@@ -230,6 +249,7 @@ export class LocalRunner {
      * what orphans the browser, so an unswallowed error here MADE the leak.
      */
     async close() {
+        this.localBrowser.closeAll();
         try {
             this.coding.closeAll();
         }