@proagentstore/cli 0.4.71 → 0.4.73

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,312 @@
+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, on the trace — naming the site and the owner's decision behind it when there is one. */
+    refuse(tool, reason, host) {
+        const consentId = host ? this.host.consentIdFor(host) : undefined;
+        this.host.emit({ type: "policy.decision", ...(host ? { domain: host } : {}), ...(consentId ? { consentId } : {}), detail: { tool, decision: "refused", reason } });
+        return text(reason, true);
+    }
+    /** Hosts already admitted on this run — a site is recorded as allowed once, not on every page. */
+    admitted = new Set();
+    allowed(host, basis) {
+        if (this.admitted.has(host))
+            return;
+        this.admitted.add(host);
+        const consentId = basis === "consent" ? this.host.consentIdFor(host) : undefined;
+        this.host.emit({ type: "policy.decision", domain: host, ...(consentId ? { consentId } : {}), detail: { decision: "allowed", basis } });
+    }
+    /** 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)) {
+            this.allowed(host, this.host.consentIdFor(host) ? "consent" : "allow_list");
+            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.allowed(host, "consent");
+            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, host);
+        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,215 @@
+/**
+ * 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", "review.decision"];
+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;
+/** An env var NAME whose value is a credential. */
+const SECRET_ENV_NAME = /KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|COOKIE|SESSION|AUTH/i;
+/** Credential-shaped text, wherever it appears — the patterns a CLI or a page tends to print. */
+const SECRET_PATTERNS = [
+    // NAME=value for a credential-named variable: keep the name, drop the value.
+    [/\b([A-Z][A-Z0-9_]*(?:KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL)[A-Z0-9_]*)\s*[=:]\s*["']?[^\s"']+["']?/g, "$1=[REDACTED]"],
+    [/\b(Bearer|Basic|Token)\s+[A-Za-z0-9._~+/=-]{10,}/gi, "$1 [REDACTED]"],
+    [/\bsk-[A-Za-z0-9_-]{20,}/g, "[REDACTED]"],
+    [/\b(?:ghp|gho|ghs|ghu|github_pat|xox[abpr])_[A-Za-z0-9_]{20,}/g, "[REDACTED]"],
+    [/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g, "[REDACTED]"],
+    // Base64-ish runs over 40 characters: keys, tokens, session blobs.
+    [/[A-Za-z0-9+/_-]{41,}={0,2}/g, "[REDACTED]"],
+];
+/**
+ * The values of credential-named variables in an environment, longest first — what `redactText`
+ * must never let through even when the value has no recognisable shape.
+ */
+export function secretEnvValues(env) {
+    return Object.entries(env)
+        .filter(([k, v]) => SECRET_ENV_NAME.test(k) && typeof v === "string" && v.trim().length >= 8)
+        .map(([, v]) => v.trim())
+        .sort((a, b) => b.length - a.length);
+}
+/**
+ * Remove credentials from free text before it is stored (#947): first every known secret value,
+ * verbatim, then anything credential-shaped. Used on CLI output that becomes an error, on result
+ * text, and on every string in a trace detail.
+ */
+export function redactText(text, secrets = []) {
+    let out = text;
+    for (const s of secrets)
+        if (s.length >= 8)
+            out = out.split(s).join("[REDACTED]");
+    for (const [re, sub] of SECRET_PATTERNS)
+        out = out.replace(re, sub);
+    return out;
+}
+/**
+ * Drop sensitive keys, redact credential-shaped values 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, secrets = []) {
+    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] = redactText(v.slice(0, 1000), secrets);
+        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" ? redactText(x.slice(0, 300), secrets) : typeof x === "number" || typeof x === "boolean" ? x : null));
+        else if (typeof v === "object") {
+            const nested = redactDetail(v, depth + 1, secrets);
+            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: redactText(str(o.summary, LOCAL_BROWSER_CAPS.text) ?? ""), traceId, engineAuth };
+    // Redacted again here, whatever the runner did: an error is CLI output, and CLIs print keys.
+    const rawError = str(o.error, 1000);
+    const error = rawError === null ? null : redactText(rawError);
+    if (outcome === "failed")
+        out.error = error ?? "The run failed without a reason.";
+    return { result: out };
+}