@proagentstore/cli 0.4.71 → 0.4.72

package/dist/browser-runner/errors.js

@@ -7,7 +7,11 @@ export class HumanHandoffError extends Error {
         this.name = "HumanHandoffError";
     }
 }
-/** A bad client request to the runner (maps to HTTP 400). */
+/** A bad client request to the runner (HTTP 400 by default; 404/409 where the request names a missing or busy thing). */
 export class RunnerInputError extends Error {
-    status = 400;
+    status;
+    constructor(message, status = 400) {
+        super(message);
+        this.status = status;
+    }
 }

package/dist/browser-runner/local-browser/bridge-stdio.js

@@ -0,0 +1,75 @@
+/**
+ * The research CLI's only MCP server (#944): a stdio forwarder to the runner.
+ *
+ * Codex and Claude Code launch MCP servers as their own child processes, so the policy cannot live
+ * in this process — it would be a second copy of the run's state. This file therefore holds NO
+ * policy: it relays `tools/list` and `tools/call` to the runner's `POST /local-browser/bridge`,
+ * where `BrowserBridge` decides everything. A run-scoped token authorizes it, and the runner
+ * accepts that token for that one run and that one path only.
+ *
+ * `node:http` rather than `fetch`: a consent or captcha pause holds a call open for minutes, and
+ * fetch's undici agent abandons a response that has not started within five.
+ */
+import { request } from "node:http";
+import { fileURLToPath } from "node:url";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+/** Env var names the runtime sets on this process. */
+export const BRIDGE_ENV = { url: "PAGS_BRIDGE_URL", runId: "PAGS_BRIDGE_RUN", token: "PAGS_BRIDGE_TOKEN" };
+/** POST to the runner's bridge path and return the parsed JSON body. */
+export const postToRunner = (endpoint, body) => new Promise((resolve, reject) => {
+    const payload = JSON.stringify({ ...body, runId: endpoint.runId });
+    const req = request(`${endpoint.url.replace(/\/$/, "")}/local-browser/bridge`, { method: "POST", headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(payload), "X-Pags-Bridge-Token": endpoint.token } }, (res) => {
+        const chunks = [];
+        res.on("data", (c) => chunks.push(Buffer.from(c)));
+        res.on("end", () => {
+            try {
+                const parsed = JSON.parse(Buffer.concat(chunks).toString("utf-8"));
+                if ((res.statusCode ?? 500) >= 400)
+                    reject(new Error(typeof parsed.error === "string" ? parsed.error : `runner answered ${res.statusCode}`));
+                else
+                    resolve(parsed);
+            }
+            catch (err) {
+                reject(err);
+            }
+        });
+    });
+    req.on("error", reject);
+    req.end(payload);
+});
+/** The MCP server, wired to a runner endpoint. Exported so tests drive it without a real stdio. */
+export function createBridgeServer(endpoint, post = postToRunner) {
+    const server = new Server({ name: "pags_browser", version: "1.0.0" }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        const res = (await post(endpoint, { op: "list" }));
+        return { tools: (res.tools ?? []) };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        try {
+            return (await post(endpoint, { op: "call", name: req.params.name, args: req.params.arguments ?? {} }));
+        }
+        catch (err) {
+            // The runner refusing or going away is a tool error the CLI can read, not a crash.
+            return { content: [{ type: "text", text: `The research browser is unavailable: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+        }
+    });
+    return server;
+}
+async function main() {
+    const url = process.env[BRIDGE_ENV.url];
+    const runId = process.env[BRIDGE_ENV.runId];
+    const token = process.env[BRIDGE_ENV.token];
+    if (!url || !runId || !token) {
+        process.stderr.write("pags_browser: missing bridge environment; this server is started by the PAGS runner only\n");
+        process.exit(2);
+    }
+    await createBridgeServer({ url, runId, token }).connect(new StdioServerTransport());
+}
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+    main().catch((err) => {
+        process.stderr.write(`pags_browser: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+    });
+}

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

@@ -0,0 +1,299 @@
+import { LOCAL_BROWSER_SOURCE_FAILURE_REASONS, redactDetail } from "./contract.js";
+/** The browser tools a research run may use. Everything else from the browser is not even listed. */
+const READ_TOOLS = new Set(["browser_navigate", "browser_navigate_back", "browser_snapshot", "browser_wait_for", "browser_click"]);
+/** Refused BY NAME with the reason, so a CLI that guesses one is told why rather than "unknown tool". */
+const WRITE_TOOLS = new Set([
+    "browser_type",
+    "browser_fill_form",
+    "browser_select_option",
+    "browser_file_upload",
+    "browser_evaluate",
+    "browser_run_code",
+    "browser_press_key",
+    "browser_drag",
+    "browser_hover",
+    "browser_handle_dialog",
+    "browser_install",
+]);
+/** Roles a click may target in research mode: moving between pages, never acting on one. */
+const CLICKABLE_ROLES = new Set(["link", "tab", "menuitem", "treeitem", "option"]);
+const PAGINATION_NAME = /^(next|previous|prev|more|load more|show more|see more|view more|older|newer|page \d+|\d+|›|»|‹|«)( page| results| jobs)?$/i;
+const RESEARCH_TOOLS = [
+    {
+        name: "record_finding",
+        description: "Record one finding from a page you opened in this run. url must be on a site you navigated to; evidence is the exact text on that page the finding comes from.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                title: { type: "string" },
+                url: { type: "string" },
+                evidence: { type: "string" },
+                fields: { type: "object", additionalProperties: { type: ["string", "number", "boolean", "null"] } },
+            },
+            required: ["title", "url", "evidence"],
+        },
+    },
+    {
+        name: "report_source_failure",
+        description: `Record a source you could not read, and why: ${LOCAL_BROWSER_SOURCE_FAILURE_REASONS.join(", ")}.`,
+        inputSchema: {
+            type: "object",
+            properties: { url: { type: "string" }, reason: { type: "string", enum: [...LOCAL_BROWSER_SOURCE_FAILURE_REASONS] }, detail: { type: "string" } },
+            required: ["url", "reason"],
+        },
+    },
+    {
+        name: "finish_research",
+        description: "End the research with a short summary of what you found and what you could not reach. Call it once, last.",
+        inputSchema: { type: "object", properties: { summary: { type: "string" } }, required: ["summary"] },
+    },
+];
+/** Runs inside the page, through the browser's own evaluate tool — privileged, never offered to the CLI. */
+const INSPECT_PAGE = `() => {
+	const text = (document.body ? document.body.innerText : "").slice(0, 20000).toLowerCase();
+	const has = (s) => !!document.querySelector(s);
+	const captcha = has('iframe[src*="hcaptcha.com"], .h-captcha, iframe[src*="challenges.cloudflare.com"], .cf-turnstile, iframe[src*="arkoselabs"], .geetest_holder')
+		|| /confirm (that )?you('?re| are) not a robot|i'?m not a robot|verify (that )?you('?re| are) (a )?human|checking (if the site connection is secure|your browser)/.test(text);
+	const login = has('input[type=password]');
+	const paywall = /subscribe to (continue|read)|you('ve| have) reached your (free )?(article )?limit|sign in to (continue|read)/.test(text);
+	return { url: location.href, title: document.title.slice(0, 200), captcha, login, paywall };
+}`;
+/** A bare lowercase hostname, or null — the same rule the API applies to the lists it sends. */
+export function hostOf(raw) {
+    try {
+        const u = new URL(raw);
+        if (u.protocol !== "https:" && u.protocol !== "http:")
+            return null;
+        return u.hostname.toLowerCase().replace(/\.$/, "");
+    }
+    catch {
+        return null;
+    }
+}
+export function domainWithin(host, base) {
+    return host === base || host.endsWith(`.${base}`);
+}
+const text = (t, isError = false) => ({ content: [{ type: "text", text: t }], ...(isError ? { isError: true } : {}) });
+const textOf = (r) => (r.content ?? []).map((c) => c.text ?? "").join("\n");
+/** Pull the JSON value out of an evaluate result (`### Result\n<json>\n### …`). */
+export function evaluateResult(raw) {
+    const i = raw.indexOf("### Result");
+    const after = (i >= 0 ? raw.slice(i + "### Result".length) : raw).trim();
+    const end = after.indexOf("\n###");
+    const block = (end >= 0 ? after.slice(0, end) : after).trim().replace(/^```[a-z]*\n?|```$/g, "").trim();
+    try {
+        return JSON.parse(block);
+    }
+    catch {
+        return null;
+    }
+}
+/** The role and accessible name of a snapshot line holding this ref, e.g. `- link "Next" [ref=e12]`. */
+export function refRole(snapshot, ref) {
+    for (const line of snapshot.split("\n")) {
+        if (!line.includes(`[ref=${ref}]`))
+            continue;
+        const m = line.match(/^\s*-\s*([a-z]+)(?:\s+"([^"]*)")?/i);
+        return m ? { role: m[1].toLowerCase(), name: m[2] ?? "" } : null;
+    }
+    return null;
+}
+export class BrowserBridge {
+    browser;
+    host;
+    actions = 0;
+    pages = 0;
+    lastSnapshot = "";
+    visited = new Set();
+    findings = [];
+    sourceFailures = [];
+    summary = null;
+    constructor(browser, host) {
+        this.browser = browser;
+        this.host = host;
+    }
+    /** What the CLI sees: the read-only browser tools that exist, plus the research tools. */
+    async listTools() {
+        const tools = (await this.browser.listTools()).filter((t) => READ_TOOLS.has(t.name));
+        return [
+            ...tools.map((t) => (t.name === "browser_click" ? { ...t, description: "Click a link, tab or pagination button (Next, More, a page number) from the latest snapshot. Nothing else can be clicked in research mode." } : t)),
+            ...RESEARCH_TOOLS,
+        ];
+    }
+    async callTool(name, args = {}) {
+        if (name === "record_finding")
+            return this.recordFinding(args);
+        if (name === "report_source_failure")
+            return this.reportFailure(args);
+        if (name === "finish_research") {
+            this.summary = typeof args.summary === "string" ? args.summary.slice(0, 4000) : "";
+            return text("Recorded. The research is finished; stop now.");
+        }
+        if (WRITE_TOOLS.has(name))
+            return this.refuse(name, `${name} is not available: this run is research only — no typing, forms, uploads, key presses or scripts.`);
+        if (!READ_TOOLS.has(name))
+            return this.refuse(name, `${name} is not available in research mode.`);
+        if (this.host.overTime())
+            return this.refuse(name, "The run's time limit is reached. Call finish_research now.");
+        if (++this.actions > this.host.limits.maxActions)
+            return this.refuse(name, `The run's limit of ${this.host.limits.maxActions} browser actions is reached. Call finish_research now.`);
+        if (name === "browser_navigate")
+            return this.navigate(String(args.url ?? ""));
+        if (name === "browser_click")
+            return this.click(args);
+        const res = await this.browser.callTool(name, args);
+        if (name === "browser_snapshot") {
+            this.lastSnapshot = textOf(res);
+            this.host.emit({ type: "browser.snapshot", ...this.currentHost() });
+        }
+        if (name === "browser_navigate_back") {
+            const state = await this.inspect();
+            if (state)
+                this.noteNavigation(state);
+        }
+        return { content: [{ type: "text", text: textOf(res) }], ...(res.isError ? { isError: true } : {}) };
+    }
+    currentHost() {
+        const last = [...this.visited].pop();
+        return last ? { domain: last } : {};
+    }
+    refuse(tool, reason) {
+        this.host.emit({ type: "policy.decision", detail: { tool, decision: "refused", reason } });
+        return text(reason, true);
+    }
+    /** May the run be on this host — asking the owner, and waiting, when it is a new one. */
+    async admit(host, url) {
+        if (this.host.isDenied(host))
+            return `${host} is on this run's deny list.`;
+        if (this.host.isPermitted(host))
+            return null;
+        if (this.host.allowListOnly())
+            return `${host} is not on this run's list of allowed sites.`;
+        this.host.emit({ type: "consent.requested", url, domain: host, detail: { scope: "navigate" } });
+        const outcome = await this.host.pause("consent_required", { domain: host });
+        if (outcome === "resumed" && this.host.isPermitted(host) && !this.host.isDenied(host)) {
+            this.host.emit({ type: "policy.decision", domain: host, detail: { decision: "consented" } });
+            return null;
+        }
+        return `The owner did not allow ${host}. Skip it and record it with report_source_failure (access_denied).`;
+    }
+    async navigate(url) {
+        const host = hostOf(url);
+        if (!host)
+            return this.refuse("browser_navigate", "Only http(s) URLs can be opened.");
+        if (this.pages >= this.host.limits.maxPages)
+            return this.refuse("browser_navigate", `The run's limit of ${this.host.limits.maxPages} pages is reached. Call finish_research now.`);
+        const refusal = await this.admit(host, url);
+        if (refusal)
+            return this.refuse("browser_navigate", refusal);
+        const res = await this.browser.callTool("browser_navigate", { url });
+        if (res.isError)
+            return { content: [{ type: "text", text: textOf(res) }], isError: true };
+        // A redirect is a second navigation the CLI did not choose. Following one within the same
+        // site (www., a jobs. subdomain) is fine; landing somewhere unrelated and unpermitted is not.
+        const state = await this.inspect();
+        const landedOn = state ? hostOf(state.url) : null;
+        const related = (a, b) => domainWithin(a, b) || domainWithin(b, a);
+        if (landedOn && !related(landedOn, host) && (this.host.isDenied(landedOn) || !this.host.isPermitted(landedOn))) {
+            await this.browser.callTool("browser_navigate_back", {}).catch(() => undefined);
+            return this.refuse("browser_navigate", `${host} redirected to ${landedOn}, a site this run has not been allowed on. Open ${landedOn} with browser_navigate to ask the owner, or skip it.`);
+        }
+        return this.landed(textOf(res), state);
+    }
+    async click(args) {
+        const ref = typeof args.target === "string" ? args.target : typeof args.ref === "string" ? args.ref : "";
+        const target = ref ? refRole(this.lastSnapshot, ref) : null;
+        const allowed = target && (CLICKABLE_ROLES.has(target.role) || (target.role === "button" && PAGINATION_NAME.test(target.name.trim())));
+        if (!allowed)
+            return this.refuse("browser_click", "In research mode only links, tabs and pagination buttons (Next, More, a page number) from the latest browser_snapshot can be clicked.");
+        if (this.pages >= this.host.limits.maxPages)
+            return this.refuse("browser_click", `The run's limit of ${this.host.limits.maxPages} pages is reached. Call finish_research now.`);
+        const res = await this.browser.callTool("browser_click", { element: typeof args.element === "string" ? args.element : target.name, target: ref });
+        if (res.isError)
+            return { content: [{ type: "text", text: textOf(res) }], isError: true };
+        const state = await this.inspect();
+        const host = state ? hostOf(state.url) : null;
+        // A click that lands on a site this run may not be on is undone, and the CLI is told to
+        // navigate there instead — which is the path that asks the owner.
+        if (host && !this.visited.has(host) && (this.host.isDenied(host) || !this.host.isPermitted(host))) {
+            await this.browser.callTool("browser_navigate_back", {}).catch(() => undefined);
+            return this.refuse("browser_click", `That link leads to ${host}, a site this run has not been allowed on. Open it with browser_navigate to ask the owner.`);
+        }
+        return this.landed(textOf(res), state);
+    }
+    /** After a page change: count it, trace it, and stop for a person when the page needs one. */
+    async landed(toolText, known) {
+        const state = known ?? (await this.inspect());
+        if (!state)
+            return text(toolText);
+        this.pages++;
+        this.noteNavigation(state);
+        const host = hostOf(state.url) ?? "";
+        const blocker = state.captcha ? "captcha" : state.login ? "login_required" : null;
+        if (blocker) {
+            this.host.emit({ type: "browser.blocked", url: state.url, domain: host, detail: { reason: blocker } });
+            const outcome = await this.host.pause(blocker, { domain: host });
+            if (outcome !== "resumed")
+                return text(`${host} needs a person (${blocker === "captcha" ? "a captcha" : "a sign-in"}) and nobody resolved it. Record it with report_source_failure (${blocker}) and move on.`, true);
+            const after = await this.inspect();
+            if (after && (after.captcha || after.login))
+                return text(`${host} still shows ${blocker === "captcha" ? "a captcha" : "a sign-in"}. Record it with report_source_failure (${blocker}) and move on.`, true);
+            return text(`Resumed after the owner handled ${host}. Take a browser_snapshot to read the page.`);
+        }
+        if (state.paywall) {
+            this.host.emit({ type: "browser.blocked", url: state.url, domain: host, detail: { reason: "paywall" } });
+            return text(`${host} is behind a paywall. Do not try to get around it: record it with report_source_failure (paywall) and move on.`, true);
+        }
+        return text(toolText);
+    }
+    noteNavigation(state) {
+        const host = hostOf(state.url);
+        if (!host)
+            return;
+        this.visited.add(host);
+        this.host.emit({ type: "browser.navigated", url: state.url, domain: host, detail: redactDetail({ title: state.title }) });
+    }
+    async inspect() {
+        const res = await this.browser.callTool("browser_evaluate", { function: INSPECT_PAGE }).catch(() => null);
+        const v = res && !res.isError ? evaluateResult(textOf(res)) : null;
+        if (!v || typeof v.url !== "string")
+            return null;
+        return { url: v.url, title: typeof v.title === "string" ? v.title : "", captcha: !!v.captcha, login: !!v.login, paywall: !!v.paywall };
+    }
+    recordFinding(args) {
+        const title = typeof args.title === "string" ? args.title.trim() : "";
+        const url = typeof args.url === "string" ? args.url.trim() : "";
+        const evidence = typeof args.evidence === "string" ? args.evidence.trim() : "";
+        const host = hostOf(url);
+        if (!title || !evidence || !host)
+            return text("A finding needs a title, an http(s) url and evidence text.", true);
+        if (![...this.visited].some((v) => domainWithin(host, v) || domainWithin(v, host))) {
+            return text(`${host} was not opened in this run. A finding must cite a page you navigated to.`, true);
+        }
+        if (this.findings.some((f) => f.url === url && f.title === title))
+            return text("Already recorded.");
+        if (this.findings.length >= 200)
+            return text("This run holds at most 200 findings. Call finish_research.", true);
+        const fields = {};
+        const raw = args.fields && typeof args.fields === "object" && !Array.isArray(args.fields) ? args.fields : {};
+        for (const [k, v] of Object.entries(redactDetail(raw) ?? {})) {
+            if (typeof v === "string" || typeof v === "number" || typeof v === "boolean" || v === null)
+                fields[k] = v;
+        }
+        const finding = { title: title.slice(0, 500), url: url.slice(0, 2000), evidence: evidence.slice(0, 4000), fields };
+        this.findings.push(finding);
+        this.host.emit({ type: "finding.parsed", url: finding.url, domain: host, detail: { title: finding.title } });
+        return text(`Recorded finding ${this.findings.length}.`);
+    }
+    reportFailure(args) {
+        const url = typeof args.url === "string" ? args.url.trim() : "";
+        const reason = LOCAL_BROWSER_SOURCE_FAILURE_REASONS.includes(args.reason) ? args.reason : null;
+        if (!url || !reason)
+            return text(`A source failure needs a url and a reason: ${LOCAL_BROWSER_SOURCE_FAILURE_REASONS.join(", ")}.`, true);
+        if (this.sourceFailures.length >= 200)
+            return text("This run holds at most 200 source failures.", true);
+        const detail = typeof args.detail === "string" ? args.detail.slice(0, 1000) : undefined;
+        this.sourceFailures.push(detail ? { url: url.slice(0, 2000), reason, detail } : { url: url.slice(0, 2000), reason });
+        return text("Recorded.");
+    }
+}

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

@@ -0,0 +1,175 @@
+/**
+ * Local CLI browser research: the wire contract between PAGS and the runner (#943, #945, #944).
+ *
+ * PAGS supervises a general agent; a Codex or Claude Code CLI signed in on the owner's machine
+ * drives the runner's browser. This file is everything that crosses the relay: the task envelope
+ * PAGS sends, the events the runner reports while it works, and the result envelope it returns.
+ *
+ * ── Why it is a file pair, not a package import
+ *
+ * The Worker and the runner each typecheck with `rootDir: "src"`, so neither can import the
+ * other's source, and the runner ships inside the published CLI. The repo's answer to that is to
+ * vendor (root CLAUDE.md, "Vendor, don't depend"). This file is therefore kept BYTE-IDENTICAL at
+ *
+ *   workers/api/src/lib/local-browser/contract.ts
+ *   packages/browser-runner/src/local-browser/contract.ts
+ *
+ * and `local-browser-contract-copy.test.ts` fails the moment the two differ. Edit both together.
+ * It must stay dependency-free (no imports) for the same reason.
+ */
+/**
+ * The runner task type, and the runner endpoints PAGS calls.
+ *
+ * PULL, not push (#944): the relay carries only cloud→runner commands and their replies, and the
+ * runner process holds no API token. So the runner keeps each run's events and result, and PAGS
+ * reads them with `status` — when a run is read and from the per-minute cron.
+ */
+export const LOCAL_BROWSER_TASK_TYPE = "local_browser.research";
+export const LOCAL_BROWSER_RUN_PATH = "/local-browser/run";
+export const LOCAL_BROWSER_CANCEL_PATH = "/local-browser/cancel";
+export const LOCAL_BROWSER_STATUS_PATH = "/local-browser/status";
+export const LOCAL_BROWSER_RESUME_PATH = "/local-browser/resume";
+export const LOCAL_BROWSER_ENGINES = ["claude", "codex"];
+export const LOCAL_BROWSER_AUTH_MODES = ["subscription", "machine", "api-key"];
+export const LOCAL_BROWSER_MODES = ["research_only"];
+export const LOCAL_BROWSER_PAUSE_REASONS = ["login_required", "captcha", "consent_required", "access_blocked", "paywall", "write_affordance"];
+export const LOCAL_BROWSER_EVENT_TYPES = [
+    "engine.started",
+    "engine.auth_checked",
+    "engine.ended",
+    "browser.navigated",
+    "browser.snapshot",
+    "browser.blocked",
+    "policy.decision",
+    "consent.requested",
+    "finding.parsed",
+    "run.paused",
+    "run.resumed",
+    "note",
+];
+export const LOCAL_BROWSER_PLATFORM_EVENT_TYPES = ["run.requested", "runner.dispatched", "run.ended"];
+export const LOCAL_BROWSER_ENGINE_AUTHS = ["subscription", "machine-login", "api-key", "missing_login", "unknown"];
+export const LOCAL_BROWSER_SOURCE_FAILURE_REASONS = ["login_required", "captcha", "paywall", "access_denied", "robots", "timeout", "error"];
+export const LOCAL_BROWSER_CAPS = { findings: 200, sourceFailures: 200, text: 4000, fieldCount: 40 };
+const SENSITIVE_KEY = /cookie|password|passwd|secret|token|authorization|api[_-]?key|otp|form[_-]?values?|credential/i;
+/**
+ * Drop sensitive keys and bound sizes. A trace is for a supervisor to read, so nothing in it may
+ * carry a cookie, a password, a form value or a key — whatever the runner sent.
+ */
+export function redactDetail(detail, depth = 0) {
+    if (!detail || typeof detail !== "object" || Array.isArray(detail) || depth > 3)
+        return undefined;
+    const out = {};
+    for (const [k, v] of Object.entries(detail).slice(0, 40)) {
+        if (SENSITIVE_KEY.test(k))
+            continue;
+        if (typeof v === "string")
+            out[k] = v.slice(0, 1000);
+        else if (typeof v === "number" || typeof v === "boolean" || v === null)
+            out[k] = v;
+        else if (Array.isArray(v))
+            out[k] = v.slice(0, 20).map((x) => (typeof x === "string" ? x.slice(0, 300) : typeof x === "number" || typeof x === "boolean" ? x : null));
+        else if (typeof v === "object") {
+            const nested = redactDetail(v, depth + 1);
+            if (nested)
+                out[k] = nested;
+        }
+    }
+    return out;
+}
+const str = (v, max) => (typeof v === "string" && v.trim() ? v.trim().slice(0, max) : null);
+const isHttpUrl = (v) => /^https?:\/\/[^\s/]+/i.test(v);
+const oneOf = (list, v) => (list.includes(v) ? v : null);
+/** A validated event, or null. */
+export function parseLocalBrowserEvent(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const o = raw;
+    const type = oneOf(LOCAL_BROWSER_EVENT_TYPES, o.type);
+    const at = str(o.at, 40);
+    if (!type || !at || Number.isNaN(Date.parse(at)))
+        return null;
+    const event = { type, at };
+    const url = str(o.url, 2000);
+    if (url && isHttpUrl(url))
+        event.url = url;
+    const domain = str(o.domain, 253);
+    if (domain)
+        event.domain = domain.toLowerCase();
+    const pauseReason = oneOf(LOCAL_BROWSER_PAUSE_REASONS, o.pauseReason);
+    if (type === "run.paused" && !pauseReason)
+        return null;
+    if (pauseReason)
+        event.pauseReason = pauseReason;
+    const consentId = str(o.consentId, 100);
+    if (consentId)
+        event.consentId = consentId;
+    const detail = redactDetail(o.detail);
+    if (detail && Object.keys(detail).length)
+        event.detail = detail;
+    return event;
+}
+/**
+ * A validated result envelope, or the reason it is not one.
+ *
+ * Wrapped as `{ result }` on purpose: a FAILED envelope carries its own `error` field, so returning
+ * the envelope bare made `"error" in parsed` true for every failed run and rejected it as invalid.
+ */
+export function parseLocalBrowserResult(raw) {
+    if (!raw || typeof raw !== "object")
+        return { error: "result must be an object" };
+    const o = raw;
+    const runId = str(o.runId, 100);
+    if (!runId)
+        return { error: "runId is required" };
+    const outcome = o.outcome === "completed" || o.outcome === "failed" ? o.outcome : null;
+    if (!outcome)
+        return { error: "outcome must be completed or failed" };
+    const traceId = str(o.traceId, 100);
+    if (!traceId)
+        return { error: "traceId is required" };
+    const engineAuth = oneOf(LOCAL_BROWSER_ENGINE_AUTHS, o.engineAuth);
+    if (!engineAuth)
+        return { error: `engineAuth must be one of ${LOCAL_BROWSER_ENGINE_AUTHS.join(", ")}` };
+    if (!Array.isArray(o.findings) || !Array.isArray(o.sourceFailures))
+        return { error: "findings and sourceFailures must be arrays" };
+    if (o.findings.length > LOCAL_BROWSER_CAPS.findings)
+        return { error: `at most ${LOCAL_BROWSER_CAPS.findings} findings` };
+    if (o.sourceFailures.length > LOCAL_BROWSER_CAPS.sourceFailures)
+        return { error: `at most ${LOCAL_BROWSER_CAPS.sourceFailures} source failures` };
+    const findings = [];
+    for (const [i, f] of o.findings.entries()) {
+        const r = (f && typeof f === "object" ? f : {});
+        const title = str(r.title, 500);
+        const url = str(r.url, 2000);
+        const evidence = str(r.evidence, LOCAL_BROWSER_CAPS.text);
+        if (!title || !url || !isHttpUrl(url) || !evidence)
+            return { error: `findings[${i}] needs title, an http(s) url and evidence` };
+        const fields = {};
+        const rawFields = r.fields && typeof r.fields === "object" && !Array.isArray(r.fields) ? r.fields : {};
+        for (const [k, v] of Object.entries(rawFields).slice(0, LOCAL_BROWSER_CAPS.fieldCount)) {
+            if (SENSITIVE_KEY.test(k))
+                continue;
+            if (typeof v === "string")
+                fields[k.slice(0, 100)] = v.slice(0, LOCAL_BROWSER_CAPS.text);
+            else if (typeof v === "number" || typeof v === "boolean" || v === null)
+                fields[k.slice(0, 100)] = v;
+        }
+        findings.push({ title, url, evidence, fields });
+    }
+    const sourceFailures = [];
+    for (const [i, f] of o.sourceFailures.entries()) {
+        const r = (f && typeof f === "object" ? f : {});
+        const url = str(r.url, 2000);
+        const reason = oneOf(LOCAL_BROWSER_SOURCE_FAILURE_REASONS, r.reason);
+        if (!url || !reason)
+            return { error: `sourceFailures[${i}] needs url and a known reason` };
+        const detail = str(r.detail, 1000);
+        sourceFailures.push(detail ? { url, reason, detail } : { url, reason });
+    }
+    const out = { runId, outcome, findings, sourceFailures, summary: str(o.summary, LOCAL_BROWSER_CAPS.text) ?? "", traceId, engineAuth };
+    const error = str(o.error, 1000);
+    if (outcome === "failed")
+        out.error = error ?? "The run failed without a reason.";
+    return { result: out };
+}

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,412 @@
+/**
+ * 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, } 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 },
+        limits,
+        resultSchema: { id: typeof schema.id === "string" ? schema.id : "findings", version: typeof schema.version === "number" ? schema.version : 1 },
+    };
+}
+/**
+ * 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,
+            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.");
+        }
+        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),
+            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 });
+        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);
+        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 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");
+    }
+    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: (r.summary ?? "").slice(0, 4000),
+            traceId: run.envelope.runId,
+            engineAuth: r.engineAuth ?? run.engineAuth,
+            ...(r.outcome === "failed" ? { error: (r.error ?? "The run failed without a reason.").slice(0, 1000) } : {}),
+        };
+        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();
         }

package/dist/browser-runner/server.js

@@ -7,6 +7,15 @@ import { listGithubOrgs, listGithubRepos, searchGithubRepos, getGithubRepoDetail
 export function createRunnerServer(runner) {
     return createServer(async (req, res) => {
         try {
+            // The research CLI's bridge forwarder (#944) holds a run-scoped token, not the runner's —
+            // accepted for this one path and that one run only, and still never from a browser origin.
+            if (!req.headers.origin && req.method === "POST" && (req.url || "").split("?")[0] === "/local-browser/bridge") {
+                const body = await readJson(req);
+                const token = String(req.headers["x-pags-bridge-token"] || "");
+                if (!runner.localBrowser.authorizeBridge(String(body.runId ?? ""), token))
+                    return json(res, 401, { error: "Unauthorized" });
+                return json(res, 200, await runner.localBrowser.bridge(body));
+            }
             if (!authorize(req, runner.config)) {
                 return json(res, 401, { error: "Unauthorized" });
             }
@@ -28,6 +37,7 @@ export async function startRunnerServer(config) {
     });
     const address = server.address();
     const actualPort = address.port;
+    runner.selfUrl = `http://${config.host}:${actualPort}`;
     return {
         runner,
         url: `http://${config.host}:${actualPort}`,
@@ -154,6 +164,19 @@ async function route(runner, req, res) {
     }
     // ── Brain-driven coding control (remote LLM drives a tmux coding CLI) ────
     // The tmux analogue of the /browser/* surface: start → capture → act → end.
+    // Local CLI browser research (#944). The API pulls state with /status — the runner never pushes.
+    if (req.method === "POST" && path === "/local-browser/run") {
+        return json(res, 202, runner.localBrowser.start(await readJson(req)));
+    }
+    if (req.method === "POST" && path === "/local-browser/status") {
+        return json(res, 200, runner.localBrowser.status(await readJson(req)));
+    }
+    if (req.method === "POST" && path === "/local-browser/resume") {
+        return json(res, 200, runner.localBrowser.resume(await readJson(req)));
+    }
+    if (req.method === "POST" && path === "/local-browser/cancel") {
+        return json(res, 200, runner.localBrowser.cancel(await readJson(req)));
+    }
     if (req.method === "POST" && path === "/coding/start") {
         const b = await readJson(req);
         return json(res, 200, runner.coding.start(b));

package/dist/browser-runner/task-types.js

@@ -19,4 +19,7 @@ export const WORKFLOW_DRIVEN_TASKS = new Set([
     "browser.handoff",
     // #841: local Claude/Codex authors an FWS draft; PAGS retains the audit and deployment gate.
     "site_builder_runtime",
+    // #944: local CLI browser research. Its state is the LocalBrowserRuntime's run, not a task the
+    // runner executes from its task list, so a restart must not expire a card for it.
+    "local_browser.research",
 ]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proagentstore/cli",
-  "version": "0.4.71",
+  "version": "0.4.72",
   "description": "CLI for creating, publishing, and running ProAgentStore agents",
   "license": "MIT",
   "type": "module",