@proagentstore/cli 0.4.78 → 0.4.80

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

@@ -0,0 +1,50 @@
+/**
+ * How an application run launches its CLI (#957). The research launch (`local-browser/engine.ts`) —
+ * no built-in web or shell tools, the bridge as the only MCP server — with two differences:
+ *
+ *  - Codex pre-approves the APPLY bridge's own tool names, not the research set;
+ *  - subscription-only, like the Tailor: provider API keys are always stripped, `machine` also
+ *    drops the Claude subscription token, and the runtime refuses a run whose spawn env would
+ *    still carry a key.
+ */
+import { artifactEngineEnv, observedArtifactAuth } from "../local-artifact/engine.js";
+import { buildEngineSpec, BRIDGE_SERVER_NAME } from "../local-browser/engine.js";
+import { APPLY_BRIDGE_TOOL_NAMES } from "./bridge.js";
+export { observedArtifactAuth as observedApplyAuth };
+export function buildApplyEngineSpec(e, prompt, bridge, mcpConfigPath) {
+    return buildEngineSpec({
+        engine: e.engine,
+        authMode: e.authMode,
+        prompt,
+        bridge,
+        mcpConfigPath,
+        toolTimeoutMs: e.limits.maxMinutes * 60_000,
+        baseEnv: artifactEngineEnv(e.authMode),
+        toolNames: APPLY_BRIDGE_TOOL_NAMES,
+    });
+}
+/** The brief. The bridge, not this text, is what enforces the rules. */
+export function applyPrompt(e, sources) {
+    const t = (name) => `mcp__${BRIDGE_SERVER_NAME}__${name}`;
+    const job = [`Title: ${e.job.title}`, e.job.company ? `Company: ${e.job.company}` : "", e.job.location ? `Location: ${e.job.location}` : "", `Application page: ${e.applicationUrl}`].filter(Boolean).join("\n");
+    const finish = e.policy.mode === "auto_submit"
+        ? `- When every field you can ground is filled and the documents are attached, you may press the final submit button ONCE. If anything is uncertain, call ${t("ready_for_review")} instead.`
+        : `- Do NOT submit. When every field you can ground is filled and the documents are attached, call ${t("ready_for_review")} with a short summary and stop.`;
+    return [
+        "You fill in ONE job application for the owner of this machine, in their browser, from their own information.",
+        "",
+        "<job>",
+        job,
+        "</job>",
+        "",
+        ...sources.map((s) => `<source name="${s.label}">\n${s.text}\n</source>\n`),
+        "How to work:",
+        `- Your only tools are from the ${BRIDGE_SERVER_NAME} server. Open the application page with ${t("browser_navigate")}, read it with ${t("browser_snapshot")}, and act on elements by their ref.`,
+        `- Every answer — ${t("browser_type")}, ${t("browser_select_option")}, or a click on a checkbox, radio or option — must carry source_quote: the exact text from a source above that the value comes from. Type values exactly as the source writes them.`,
+        `- If a question has no answer in the sources, or is ambiguous, call ${t("request_answer")}. Never guess, never invent, never pick a "safe" default.`,
+        `- To attach a document, click the field's upload control, then call ${t("upload_artifact")} with kind resume or cover_letter.`,
+        "- Never sign in, solve a captcha, accept terms or work around any block; the run pauses for the owner by itself.",
+        `- Stay on the application's site. Limits: ${e.limits.maxPages} pages, ${e.limits.maxActions} browser actions, ${e.limits.maxMinutes} minutes.`,
+        finish,
+    ].join("\n");
+}

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

@@ -0,0 +1,497 @@
+/**
+ * Local application execution on the runner (#957) — the Job Application Runner's hands.
+ *
+ * One run = one Codex or Claude Code process, signed in on this machine, filling ONE application
+ * through the apply bridge (bridge.ts) in a real browser. The runtime owns what PAGS later pulls
+ * with `status`, as local browser research does (`local-browser/runtime.ts`):
+ *
+ *  - idempotency: a start with a requestId this runner already holds returns that run, so a
+ *    replayed materials_ready event can never fill — or upload, or submit — a second time;
+ *  - one active application run per instance;
+ *  - the owner's answer sources and approved artifacts, read and hashed HERE before the CLI starts.
+ *    An artifact whose hash no longer matches what #956 reported is refused, not uploaded;
+ *  - pauses: the bridge holds a call until `resume` (with the owner's answer or a newly allowed
+ *    site), cancel, or the time limit — active time only, so waiting on the owner is not counted;
+ *  - the result: `awaiting_review`, `submitted` (only with the site's confirmation), `blocked`
+ *    with the reason, or `failed`.
+ *
+ * Runs live in memory: a runner restart loses them, and `status` answers 404, which PAGS reads as
+ * "the runner lost this run".
+ */
+import { spawn as nodeSpawn } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, 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 { isHomeRelative, isWorkspaceRelative } from "../local-artifact/contract.js";
+import { resolveSource } from "../local-artifact/runtime.js";
+import { domainWithin } from "../local-browser/bridge.js";
+import { BRIDGE_ENV } from "../local-browser/bridge-stdio.js";
+import { redactText, secretEnvValues } from "../local-browser/contract.js";
+import { finalText, missingLogin, signInHelp } from "../local-browser/engine.js";
+import { resolveWorkspacePath } from "../local-browser/runtime.js";
+import { ApplyBridge } from "./bridge.js";
+import { LOCAL_APPLY_AUTH_MODES, LOCAL_APPLY_CAPS, LOCAL_APPLY_ENGINES, LOCAL_APPLY_MODES, LOCAL_APPLY_TASK_TYPE, } from "./contract.js";
+import { applyPrompt, buildApplyEngineSpec, observedApplyAuth } from "./engine.js";
+const MAX_EVENTS = 1000;
+const OUTPUT_LINES = 400;
+const SOURCE_BYTES = 256 * 1024;
+const SAFE_ID = /^[A-Za-z0-9_.:-]{1,300}$/;
+const HASH = /^[a-f0-9]{64}$/;
+/** One application at a time per agent: two runs on one employer's form is how duplicates happen. */
+const MAX_ACTIVE = 1;
+class Blocked extends Error {
+    reason;
+    questions;
+    constructor(reason, questions) {
+        super(reason);
+        this.reason = reason;
+        this.questions = questions;
+    }
+}
+const posInt = (v, max) => (typeof v === "number" && Number.isInteger(v) && v >= 1 && v <= max ? v : null);
+const strList = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === "string").map((x) => x.trim().toLowerCase()).filter(Boolean) : []);
+const sha256 = (data) => createHash("sha256").update(data).digest("hex");
+/** The envelope, validated at the runner's boundary. */
+export function parseApplyEnvelope(raw) {
+    const o = (raw && typeof raw === "object" ? raw : {});
+    const bad = (what) => new RunnerInputError(`Invalid application task: ${what}`);
+    if (o.type !== LOCAL_APPLY_TASK_TYPE)
+        throw bad(`type must be ${LOCAL_APPLY_TASK_TYPE}`);
+    for (const k of ["runId", "requestId", "instanceId", "applicationId"])
+        if (typeof o[k] !== "string" || !SAFE_ID.test(o[k]))
+            throw bad(`${k} is required`);
+    if (!/^[A-Za-z0-9_-]{1,100}$/.test(o.runId))
+        throw bad("runId must be a plain id");
+    if (!LOCAL_APPLY_ENGINES.includes(o.engine))
+        throw bad("engine must be claude or codex");
+    if (!LOCAL_APPLY_AUTH_MODES.includes(o.authMode))
+        throw bad("authMode must be machine or subscription — a provider API key is never used");
+    if (o.browserProfile !== "isolated" && o.browserProfile !== "default")
+        throw bad("browserProfile must be isolated or default");
+    if (typeof o.applicationUrl !== "string" || !/^https?:\/\/[^\s/]+/i.test(o.applicationUrl) || o.applicationUrl.length > 2000)
+        throw bad("applicationUrl must be an http(s) URL");
+    const job = (o.job && typeof o.job === "object" ? o.job : {});
+    if (typeof job.title !== "string" || !job.title.trim())
+        throw bad("job.title is required");
+    if (typeof o.workspace !== "string" || !isHomeRelative(o.workspace))
+        throw bad('workspace must be a folder written "~/…"');
+    const sources = [];
+    for (const s of Array.isArray(o.sources) ? o.sources.slice(0, 4) : []) {
+        const r = (s && typeof s === "object" ? s : {});
+        if ((r.role !== "profile" && r.role !== "answers") || typeof r.path !== "string" || !isWorkspaceRelative(r.path) || r.path.split("/")[0] === "applications")
+            throw bad("each source needs a role (profile, answers) and a path inside the workspace");
+        sources.push({ role: r.role, path: r.path });
+    }
+    const artifacts = [];
+    for (const a of Array.isArray(o.artifacts) ? o.artifacts.slice(0, 2) : []) {
+        const r = (a && typeof a === "object" ? a : {});
+        if ((r.kind !== "resume" && r.kind !== "cover_letter") || typeof r.path !== "string" || !isHomeRelative(r.path) || typeof r.sha256 !== "string" || !HASH.test(r.sha256))
+            throw bad("each artifact needs a kind, a ~/ path and a sha256");
+        if (artifacts.some((x) => x.kind === r.kind))
+            throw bad(`artifact ${r.kind} is listed twice`);
+        artifacts.push({ kind: r.kind, path: r.path, sha256: r.sha256 });
+    }
+    const p = (o.policy && typeof o.policy === "object" ? o.policy : {});
+    if (!LOCAL_APPLY_MODES.includes(p.mode))
+        throw bad("policy.mode must be fill_and_review or auto_submit");
+    const gate = (p.submitGate && typeof p.submitGate === "object" ? p.submitGate : null);
+    const gateId = gate && typeof gate.gateId === "string" && SAFE_ID.test(gate.gateId) ? gate.gateId : null;
+    // auto_submit without the gate PAGS evaluated is not a mode this runner will run.
+    if (p.mode === "auto_submit" && !gateId)
+        throw bad("auto_submit requires policy.submitGate");
+    const allowDomains = strList(p.allowDomains);
+    if (!allowDomains.length)
+        throw bad("policy.allowDomains must name the application's site");
+    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 };
+    if (Object.values(limits).some((v) => !v))
+        throw bad("limits are out of range");
+    const opt = (v) => (typeof v === "string" && v.trim() ? v.trim().slice(0, 300) : undefined);
+    return {
+        type: LOCAL_APPLY_TASK_TYPE,
+        runId: o.runId,
+        requestId: o.requestId,
+        instanceId: o.instanceId,
+        applicationId: o.applicationId,
+        engine: o.engine,
+        authMode: o.authMode,
+        browserProfile: o.browserProfile,
+        applicationUrl: o.applicationUrl,
+        job: { title: job.title.trim().slice(0, 300), company: opt(job.company), location: opt(job.location) },
+        workspace: o.workspace,
+        sources,
+        artifacts,
+        policy: { mode: p.mode, allowDomains, ...(p.mode === "auto_submit" && gateId ? { submitGate: { gateId } } : {}) },
+        limits,
+    };
+}
+/**
+ * An approved artifact on the real disk: inside the workspace's `applications/`, and still the
+ * file #956 hashed. Anything else is not uploaded.
+ */
+export function verifyArtifact(workspace, home, a) {
+    const label = a.kind.replace("_", " ");
+    try {
+        const real = realpathSync(resolve(realpathSync(home), a.path.slice(2)));
+        if (!real.startsWith(join(workspace, "applications") + sep))
+            return { error: `The approved ${label} is not inside the workspace's applications/ folder.` };
+        const buf = readFileSync(real);
+        if (sha256(buf) !== a.sha256)
+            return { error: `The approved ${label} at ${a.path} has changed since it was generated; it will not be uploaded.` };
+        return { path: real, text: buf.toString("utf8") };
+    }
+    catch {
+        return { error: `The approved ${label} at ${a.path} could not be read.` };
+    }
+}
+export class LocalApplyRuntime {
+    deps;
+    runs = new Map();
+    root;
+    now;
+    spawn;
+    retentionMs;
+    constructor(deps) {
+        this.deps = deps;
+        this.root = join(deps.dataDir, "local-apply");
+        this.now = deps.now ?? Date.now;
+        this.spawn = deps.spawn ?? nodeSpawn;
+        this.retentionMs = deps.retentionMs ?? 24 * 60 * 60 * 1000;
+    }
+    start(raw) {
+        const envelope = parseApplyEnvelope(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 >= MAX_ACTIVE)
+            throw new RunnerInputError("This machine is already filling an application for this agent; one at a time.", 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.replace(/[^A-Za-z0-9_-]/g, "_"), envelope.runId);
+        mkdirSync(join(dir, "scratch"), { recursive: true });
+        const run = {
+            envelope,
+            dir,
+            token: randomBytes(24).toString("hex"),
+            state: "running",
+            events: [],
+            seq: 0,
+            allow: new Set(envelope.policy.allowDomains),
+            grounding: [],
+            secrets: secretEnvValues(process.env),
+            activeSince: this.now(),
+            activeMs: 0,
+            waiters: [],
+            output: [],
+            engineAuth: "unknown",
+            cancelled: false,
+            timedOut: false,
+        };
+        this.runs.set(envelope.runId, run);
+        void this.launch(run, selfUrl).catch((err) => {
+            if (err instanceof Blocked)
+                this.end(run, { outcome: "blocked", blockReason: err.reason, questions: err.questions });
+            else
+                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;
+        const home = this.deps.homeDir ?? homedir();
+        let workspace;
+        try {
+            workspace = resolveWorkspacePath(e.workspace, home);
+        }
+        catch (err) {
+            throw new Blocked("source_unavailable", [`The workspace ${e.workspace} cannot be used: ${err instanceof Error ? err.message : String(err)}`]);
+        }
+        const blocks = [];
+        const missing = [];
+        if (!e.sources.some((s) => s.role === "profile"))
+            missing.push("No profile source is configured. Choose one in the Application Runner settings.");
+        for (const s of e.sources) {
+            const shown = `${e.workspace}/${s.path}`;
+            try {
+                const buf = readFileSync(resolveSource(workspace, s.path));
+                if (!buf.length || buf.length > SOURCE_BYTES)
+                    throw new Error("empty or too large");
+                blocks.push({ label: s.role, text: buf.toString("utf8") });
+                this.emit(run, { type: "source.read", detail: { role: s.role, path: shown, sha256: sha256(buf), bytes: buf.length } });
+            }
+            catch {
+                missing.push(`Your ${s.role} at ${shown} could not be read. Add it, or choose another file in the Application Runner settings.`);
+            }
+        }
+        if (missing.length)
+            throw new Blocked("source_unavailable", missing);
+        for (const a of e.artifacts) {
+            const v = verifyArtifact(workspace, home, a);
+            if ("error" in v)
+                throw new Blocked("artifact_changed", [`${v.error} Re-run tailoring for this application.`]);
+            blocks.push({ label: a.kind, text: v.text });
+        }
+        run.grounding = blocks.map((b) => b.text);
+        const bridgeScript = this.deps.bridgeScript ?? fileURLToPath(new URL("../local-browser/bridge-stdio.js", import.meta.url));
+        const spec = buildApplyEngineSpec(e, applyPrompt(e, blocks), { command: process.execPath, args: [bridgeScript], env: { [BRIDGE_ENV.url]: selfUrl, [BRIDGE_ENV.runId]: e.runId, [BRIDGE_ENV.token]: run.token } }, join(run.dir, "mcp.json"));
+        run.secrets = secretEnvValues({ ...process.env, ...spec.env });
+        run.engineAuth = observedApplyAuth(e.engine, spec.env);
+        this.emit(run, { type: "engine.auth_checked", detail: { engine: e.engine, authMode: e.authMode, engineAuth: run.engineAuth, mode: e.policy.mode } });
+        if (run.engineAuth === "api-key")
+            throw new Blocked("api_key_refused", ["A provider API key would reach the CLI. Applications run on this machine's sign-in only — remove the key from the runner's environment."]);
+        run.browser = await this.deps.browserFor(e.browserProfile, run.dir);
+        const artifactsByKind = new Map(e.artifacts.map((a) => [a.kind, a]));
+        run.bridge = new ApplyBridge(run.browser.tools, {
+            emit: (ev) => this.emit(run, ev),
+            pause: (p) => this.pause(run, p),
+            isAllowed: (host) => [...run.allow].some((d) => domainWithin(host, d)),
+            grounding: () => run.grounding.join("\n"),
+            artifactPath: (kind) => {
+                const a = artifactsByKind.get(kind);
+                if (!a)
+                    return { error: `No approved ${kind.replace("_", " ")} for this application.` };
+                const v = verifyArtifact(workspace, home, a);
+                return "error" in v ? v : { path: v.path, sha256: a.sha256 };
+            },
+            overTime: () => this.activeMs(run) >= e.limits.maxMinutes * 60_000,
+            now: this.now,
+            limits: e.limits,
+            mode: e.policy.mode,
+            gateId: e.policy.submitGate?.gateId,
+        });
+        if (spec.mcpConfig)
+            writeFileSync(spec.mcpConfig.path, spec.mcpConfig.json, { mode: 0o600 });
+        const child = this.spawn(spec.command, spec.args, { cwd: join(run.dir, "scratch"), env: spec.env, stdio: ["ignore", "pipe", "pipe"] });
+        run.child = child;
+        this.emit(run, { type: "engine.started", detail: { engine: e.engine, mode: e.policy.mode } });
+        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) => {
+            this.end(run, { outcome: "failed", error: err.code === "ENOENT" ? `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.end(run, this.outcomeOf(run, code ?? -1));
+        });
+        run.timer = setInterval(() => {
+            if (run.state !== "ended" && this.activeMs(run) >= e.limits.maxMinutes * 60_000 + 60_000) {
+                run.timedOut = true;
+                this.kill(run);
+            }
+        }, 5_000);
+        run.timer.unref?.();
+    }
+    /** What the run amounts to when the CLI exits — decided by what the bridge did, not what the CLI says. */
+    outcomeOf(run, code) {
+        const e = run.envelope;
+        const b = run.bridge;
+        const summary = b?.summary ?? finalText(e.engine, run.output);
+        if (run.cancelled)
+            return { outcome: "failed", summary, error: "Cancelled by the owner" };
+        if (b?.submitted)
+            return { outcome: "submitted", summary, submitted: b.submitted };
+        if (b?.submitAttempted)
+            return { outcome: "blocked", summary, blockReason: "submit_unconfirmed", questions: b.blocked?.questions ?? [] };
+        if (b?.reviewReady)
+            return { outcome: "awaiting_review", summary };
+        if (!b?.filled && missingLogin(e.engine, run.output.join("\n")))
+            return { outcome: "blocked", summary, blockReason: "engine_not_signed_in", questions: [signInHelp(e.engine)], engineAuth: "missing_login" };
+        if (b?.blocked)
+            return { outcome: "blocked", summary, blockReason: b.blocked.reason, questions: b.blocked.questions };
+        if (run.timedOut)
+            return { outcome: "blocked", summary, blockReason: "incomplete", questions: [`Stopped at the ${e.limits.maxMinutes}-minute limit before the form was ready for review.`] };
+        const tail = code !== 0 ? ` (the ${e.engine} CLI exited with code ${code})` : "";
+        return { outcome: "blocked", summary, blockReason: "incomplete", questions: [`The CLI stopped before marking the form ready for review${tail}. Review the form yourself, or retry.`] };
+    }
+    activeMs(run) {
+        return run.activeMs + (run.state === "running" ? this.now() - run.activeSince : 0);
+    }
+    emit(run, ev) {
+        if (run.events.length >= MAX_EVENTS)
+            return;
+        run.events.push({ ...ev, at: new Date(this.now()).toISOString(), seq: ++run.seq });
+    }
+    pause(run, p) {
+        if (run.state === "ended" || run.cancelled)
+            return Promise.resolve("stopped");
+        if (run.state === "running") {
+            run.activeMs += this.now() - run.activeSince;
+            run.state = "paused";
+            run.pause = p;
+            this.emit(run, { type: "run.paused", pauseReason: p.reason, ...(p.url ? { url: p.url } : {}), ...(p.domain ? { domain: p.domain } : {}) });
+        }
+        return new Promise((done) => run.waiters.push(done));
+    }
+    release(run, outcome) {
+        if (run.state === "paused") {
+            run.state = "running";
+            run.pause = 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: add their answers to what values may be grounded in, admit any site they allowed, release. */
+    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 a of (Array.isArray(o.answers) ? o.answers : []).slice(0, LOCAL_APPLY_CAPS.answers)) {
+            const r = (a && typeof a === "object" ? a : {});
+            if (typeof r.question === "string" && typeof r.answer === "string" && r.answer.trim())
+                run.grounding.push(`Q: ${r.question.slice(0, LOCAL_APPLY_CAPS.questionChars)}\nA: ${r.answer.trim().slice(0, LOCAL_APPLY_CAPS.answerChars)}`);
+        }
+        for (const d of strList(o.allowDomains))
+            run.allow.add(d);
+        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 && run.child.exitCode === null)
+                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;
+        // A page of at most 500 events; `lastSeq` is the cursor for the next page, so nothing is skipped.
+        const pending = run.events.filter((e) => e.seq > after);
+        const page = pending.length > 500 ? pending.slice(0, 500) : pending;
+        return {
+            runId: run.envelope.runId,
+            state: run.state,
+            ...(run.pause ? { pause: run.pause } : {}),
+            events: page,
+            lastSeq: page.length < pending.length ? page[page.length - 1].seq : 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() };
+        // A call that arrives while the run waits on the owner (the CLI gave up waiting on its own
+        // call) does not go ahead of them: nothing reaches the page until the owner resumes.
+        if (o.op === "call" && run.state === "paused")
+            return { content: [{ type: "text", text: `The run is paused for the owner (${run.pause?.reason.replace(/_/g, " ") ?? "waiting"}). Nothing can be done until they resume it. Stop now.` }], isError: true };
+        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 application 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?.();
+    }
+    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();
+        const b = run.bridge;
+        run.result = {
+            runId: run.envelope.runId,
+            outcome: r.outcome,
+            mode: run.envelope.policy.mode,
+            traceId: run.envelope.runId,
+            engineAuth: r.engineAuth ?? run.engineAuth,
+            filled: b?.filled ?? 0,
+            uploaded: [...(b?.uploaded ?? [])],
+            submitAttempted: b?.submitAttempted ?? false,
+            summary: redactText((r.summary ?? "").slice(0, LOCAL_APPLY_CAPS.summary), run.secrets),
+            ...(r.outcome === "submitted" && r.submitted ? { submitted: r.submitted } : {}),
+            ...(r.outcome === "blocked" ? { blockReason: r.blockReason ?? "incomplete", questions: (r.questions ?? []).map((q) => redactText(q, run.secrets)) } : {}),
+            ...(r.outcome === "failed" ? { error: redactText((r.error ?? "The run failed without a reason.").slice(0, 1000), run.secrets) } : {}),
+        };
+        if (run.child && run.child.exitCode === null)
+            this.kill(run);
+        void run.browser?.stop().catch(() => undefined);
+    }
+    /** Drop ended runs past retention, with their folders (scratch, MCP config, isolated profile). */
+    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);
+            }
+        }
+        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 });
+            }
+        }
+    }
+    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/local-artifact/runtime.js

@@ -89,7 +89,7 @@ export function parseArtifactEnvelope(raw) {
 }
 const sha256 = (data) => createHash("sha256").update(data).digest("hex");
 /** A source file resolved on the real disk, strictly inside the workspace. */
-function resolveSource(workspace, rel) {
+export function resolveSource(workspace, rel) {
     const real = realpathSync(resolve(workspace, rel));
     if (!real.startsWith(workspace + sep))
         throw new Error("outside the workspace");

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

@@ -115,6 +115,8 @@ export class BrowserBridge {
     findings = [];
     sourceFailures = [];
     summary = null;
+    /** Tool calls that reached the bridge. Zero at exit means the CLI never used the browser (#944). */
+    calls = 0;
     constructor(browser, host) {
         this.browser = browser;
         this.host = host;
@@ -128,6 +130,7 @@ export class BrowserBridge {
         ];
     }
     async callTool(name, args = {}) {
+        this.calls++;
         if (name === "record_finding")
             return this.recordFinding(args);
         if (name === "report_source_failure")

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

@@ -101,7 +101,7 @@ export function buildEngineSpec(input) {
             "-c",
             `${key}.default_tools_approval_mode="approve"`,
             "-c",
-            `${key}.enabled_tools=[${BRIDGE_TOOL_NAMES.map(toml).join(", ")}]`,
+            `${key}.enabled_tools=[${(input.toolNames ?? BRIDGE_TOOL_NAMES).map(toml).join(", ")}]`,
             // Two spellings across Codex versions; an unknown key is ignored, so both are set.
             "-c",
             'web_search="disabled"',
@@ -143,6 +143,17 @@ export function signInHelp(engine) {
         ? "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.";
 }
+/**
+ * Why a run that never touched the browser bridge failed, and the step that fixes it (#944). The usual
+ * cause is the CLI refusing the bridge's tools (an approval policy, #952) or not loading the server.
+ */
+export function bridgeUnused(engine, said) {
+    const blocked = /approval|not (allowed|permitted)|permission|denied/i.test(said);
+    const cause = blocked
+        ? `The ${engine === "claude" ? "Claude Code" : "Codex"} CLI was refused the PAGS browser tools.`
+        : `The ${engine === "claude" ? "Claude Code" : "Codex"} CLI finished without using the PAGS browser tools.`;
+    return `${cause} No page was opened, so this run found nothing. Update the CLI on that machine (npm i -g @proagentstore/cli), restart \`pags up\`, 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--) {

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

@@ -27,7 +27,7 @@ import { RunnerInputError } from "../errors.js";
 import { BrowserBridge, domainWithin } from "./bridge.js";
 import { BRIDGE_ENV } from "./bridge-stdio.js";
 import { LOCAL_BROWSER_AUTH_MODES, LOCAL_BROWSER_ENGINES, LOCAL_BROWSER_TASK_TYPE, redactDetail, redactText, secretEnvValues, } from "./contract.js";
-import { buildEngineSpec, finalText, missingLogin, observedEngineAuth, researchPrompt, signInHelp } from "./engine.js";
+import { bridgeUnused, 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}$/;
@@ -387,6 +387,11 @@ export class LocalBrowserRuntime {
             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}` : ""}` };
         }
+        // A CLI that exits cleanly having never called the bridge did no research, whatever its prose
+        // says. Live run aac758dc (#952) ended `completed` with "the browser bridge required approval":
+        // no page opened, and the run looked like a success with nothing found.
+        if (!bridge?.calls)
+            return { outcome: "failed", summary, error: bridgeUnused(e.engine, summary) };
         return { outcome: "completed", summary };
     }
     end(run, r) {