@proagentstore/cli 0.4.78 → 0.4.79

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

@@ -0,0 +1,442 @@
+/**
+ * The apply bridge (#957): the only way an application CLI reaches the page, and where the write
+ * policy is enforced. Like the research bridge (`local-browser/bridge.ts`), the CLI gets no web
+ * access of its own and exactly one MCP server, whose calls land HERE, in the runner.
+ *
+ * Every call is put in an action class (see contract.ts) and allowed or refused by code:
+ *
+ *  - read: navigate / back / snapshot / wait, and clicks on links, tabs and pagination — on the
+ *    allowed sites only. Leaving them pauses the run (`external_redirect`).
+ *  - fill: `browser_type`, `browser_select_option`, and clicks on checkboxes, radios and options.
+ *    Each carries a `source_quote` that must be verbatim text from the owner's profile, answers or
+ *    approved materials, and the value must appear in that quote — a form answer not grounded in
+ *    the profile is refused, and the CLI is told to ask (`request_answer`). Uploads go through
+ *    `upload_artifact`, which can only attach an approved artifact whose hash still matches, once.
+ *  - submit: any click on a control that submits a POST form (a DOM fact, read from the page by
+ *    the commit-guard probe) or whose own accessible name commits, in any of the guard's
+ *    languages. Under `fill_and_review` it is NEVER performed: the run stops `awaiting_review`.
+ *    Under `auto_submit` it is performed at most once, after a fresh blocker check, between a
+ *    `submit.attempted` and a `submit.confirmed` / `submit.unconfirmed` trace event.
+ *
+ * Enter, Space, typed characters by key, scripts, drag, dialogs, `browser_fill_form` and raw
+ * `browser_file_upload` are refused by name. A captcha, a sign-in, a consent box, a duplicate
+ * application or an anti-bot wall pauses the run for a person; nothing here works around one.
+ *
+ * The trace carries classes, domains, decisions and artifact handles — never a typed value.
+ */
+import { ELEMENT_PROBE_FN, FALLBACK_COMMIT_RE } from "../commit-guard.js";
+import { normalize } from "../local-artifact/engine.js";
+import { evaluateResult, hostOf, refRole } from "../local-browser/bridge.js";
+const READ_TOOLS = new Set(["browser_navigate", "browser_navigate_back", "browser_snapshot", "browser_wait_for"]);
+const FILL_TOOLS = new Set(["browser_type", "browser_select_option"]);
+const BRIDGE_TOOLS = ["upload_artifact", "request_answer", "ready_for_review"];
+const REFUSED = new Set([
+    "browser_fill_form",
+    "browser_file_upload",
+    "browser_evaluate",
+    "browser_run_code",
+    "browser_drag",
+    "browser_hover",
+    "browser_handle_dialog",
+    "browser_install",
+    "browser_tabs",
+    "browser_close",
+]);
+/** Every tool name the bridge can list — what a CLI may be told to trust without asking. */
+export const APPLY_BRIDGE_TOOL_NAMES = [...READ_TOOLS, "browser_click", ...FILL_TOOLS, "browser_press_key", ...BRIDGE_TOOLS];
+/** Roles whose click is an ANSWER (a fill), never a navigation or a submit. */
+const FIELD_ROLES = new Set(["checkbox", "radio", "option", "switch", "menuitemradio", "menuitemcheckbox"]);
+const TYPE_ROLES = new Set(["textbox", "searchbox", "combobox", "spinbutton"]);
+const NAV_ROLES = new Set(["link", "tab", "menuitem", "treeitem"]);
+const PAGINATION_NAME = /^(next|previous|prev|more|load more|show more|see more|view more|page \d+|\d+|›|»|‹|«)( page| results| jobs)?$/i;
+/** Buttons that move within a form or open a file chooser — allowed when they do NOT submit. */
+const STEP_NAME = /^(next|continue|back|previous|add( another)?|upload|attach|browse|choose( a)? file|select( a)? file|remove|edit|expand|collapse|show more)\b/i;
+/** A tick that is a legal or privacy agreement: the owner's call, not the CLI's. */
+const CONSENT_NAME = /\b(agree|consent|terms|privacy|acknowledge|certify|accept|declaration|gdpr)\b/i;
+/** A field that is a credential: a sign-in, never an application answer. */
+const CREDENTIAL_NAME = /password|passcode|one[- ]?time|\botp\b|verification code|security code|2fa|two[- ]factor/i;
+/** Keys that move between fields without entering or activating anything. */
+const SAFE_KEYS = /^(Tab|Shift\+Tab|Arrow(Up|Down|Left|Right)|Escape|Home|End|PageUp|PageDown)$/;
+/** Runs inside the page, through the browser's own evaluate tool — 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);
+	return {
+		url: location.href,
+		title: document.title.slice(0, 200),
+		captcha: has('iframe[src*="recaptcha"], .g-recaptcha, 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/.test(text),
+		login: has('input[type=password]'),
+		duplicate: /you('ve| have) already applied|already applied (for|to) this|application (already exists|has already been (submitted|received))|duplicate application/.test(text),
+		antiBot: /unusual traffic|access (is )?denied|request (has been )?blocked|bot detected|checking (if the site connection is secure|your browser)/.test(text),
+		confirmed: /thank you for (your )?appl|application (has been |was )?(received|submitted)|we('ve| have) received your application|successfully (applied|submitted)/.test(text),
+	};
+}`;
+const text = (t, isError = false) => ({ content: [{ type: "text", text: t }], ...(isError ? { isError: true } : {}) });
+const textOf = (r) => (r.content ?? []).map((c) => c.text ?? "").join("\n");
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/**
+ * Is `value` grounded? The quote must be verbatim text from the owner's sources, and the value must
+ * appear in the quote as a whole phrase ("No" is not found inside "Notice"). Returns the refusal,
+ * or null. Pure, so the rule is tested as a rule.
+ */
+export function groundingRefusal(value, quote, grounding) {
+    const q = typeof quote === "string" ? normalize(quote) : "";
+    if (q.length < 2)
+        return "Every answer needs a source_quote: the exact text from the owner's profile, answers or materials that this value comes from.";
+    if (!normalize(grounding).includes(q))
+        return "The source_quote is not text from the owner's profile, answers or materials. Quote them exactly, or call request_answer.";
+    const v = normalize(value);
+    if (!v)
+        return "The value is empty.";
+    if (!new RegExp(`(?<![\\p{L}\\p{N}])${escapeRe(v)}(?![\\p{L}\\p{N}])`, "u").test(q))
+        return `"${value.slice(0, 80)}" does not appear in the source_quote. Use the owner's value as written, or call request_answer.`;
+    return null;
+}
+const QUOTE_PROP = { type: "string", description: "The exact text from the owner's profile, answers or materials that this answer comes from. Required; the value must appear in it." };
+/** A browser tool's schema with `source_quote` added — the CLI must say where an answer comes from. */
+function withQuote(schema, required) {
+    const s = (schema && typeof schema === "object" ? schema : { type: "object" });
+    return { ...s, type: "object", properties: { ...(s.properties ?? {}), source_quote: QUOTE_PROP }, ...(required ? { required: [...(s.required ?? []), "source_quote"] } : {}) };
+}
+export class ApplyBridge {
+    browser;
+    host;
+    actions = 0;
+    pages = 0;
+    lastSnapshot = "";
+    admitted = new Set();
+    filled = 0;
+    uploaded = new Set();
+    reviewReady = false;
+    summary = null;
+    submitAttempted = false;
+    submitted = null;
+    /** The last thing that stopped the work and was not resolved — the block reason if the run ends here. */
+    blocked = null;
+    constructor(browser, host) {
+        this.browser = browser;
+        this.host = host;
+    }
+    get done() {
+        return this.reviewReady || this.submitAttempted;
+    }
+    async listTools() {
+        const own = (await this.browser.listTools()).filter((t) => READ_TOOLS.has(t.name) || FILL_TOOLS.has(t.name) || t.name === "browser_click" || t.name === "browser_press_key");
+        const tools = own.map((t) => {
+            if (t.name === "browser_click")
+                return { ...t, description: "Click a link, tab, pagination or form-step button, or answer a checkbox / radio / option (answers need source_quote). A control that submits the application is governed by the run's policy.", inputSchema: withQuote(t.inputSchema, false) };
+            if (t.name === "browser_press_key")
+                return { ...t, description: "Press Tab, Shift+Tab, an arrow key, Escape, Home/End or PageUp/PageDown. Nothing that types or submits." };
+            if (FILL_TOOLS.has(t.name))
+                return { ...t, inputSchema: withQuote(t.inputSchema, true) };
+            return t;
+        });
+        return [
+            ...tools,
+            {
+                name: "upload_artifact",
+                description: "Attach an approved document. First click the field's upload control (it opens a file chooser), then call this. Each document can be attached once.",
+                inputSchema: { type: "object", properties: { kind: { type: "string", enum: ["resume", "cover_letter"] } }, required: ["kind"] },
+            },
+            {
+                name: "request_answer",
+                description: "Ask the owner for an answer the sources do not give (missing_answer), or when a question is ambiguous (screening_ambiguity). The run waits for them.",
+                inputSchema: { type: "object", properties: { question: { type: "string" }, kind: { type: "string", enum: ["missing_answer", "screening_ambiguity"] } }, required: ["question"] },
+            },
+            {
+                name: "ready_for_review",
+                description: "The form is filled as far as the sources allow. Stop here; the owner reviews it. Call once, last.",
+                inputSchema: { type: "object", properties: { summary: { type: "string" } }, required: ["summary"] },
+            },
+        ];
+    }
+    async callTool(name, args = {}) {
+        if (this.done)
+            return text("The application is finished for this run. Stop now.", true);
+        if (name === "ready_for_review")
+            return this.review(typeof args.summary === "string" ? args.summary : "");
+        if (name === "request_answer")
+            return this.requestAnswer(args);
+        if (REFUSED.has(name))
+            return this.refuse(name, "read", `${name} is not available to an application run.`);
+        if (!READ_TOOLS.has(name) && !FILL_TOOLS.has(name) && name !== "browser_click" && name !== "browser_press_key" && name !== "upload_artifact")
+            return this.refuse(name, "read", `${name} is not available.`);
+        if (this.host.overTime())
+            return this.refuse(name, "read", "The run's time limit is reached. Call ready_for_review now.");
+        if (++this.actions > this.host.limits.maxActions)
+            return this.refuse(name, "read", `The run's limit of ${this.host.limits.maxActions} browser actions is reached. Call ready_for_review now.`);
+        if (name === "browser_navigate")
+            return this.navigate(String(args.url ?? ""));
+        if (name === "browser_click")
+            return this.click(args);
+        if (name === "browser_type")
+            return this.type(args);
+        if (name === "browser_select_option")
+            return this.select(args);
+        if (name === "browser_press_key")
+            return this.pressKey(args);
+        if (name === "upload_artifact")
+            return this.upload(args);
+        const res = await this.browser.callTool(name, args);
+        if (name === "browser_snapshot")
+            this.lastSnapshot = textOf(res);
+        if (name === "browser_navigate_back") {
+            const state = await this.inspect();
+            if (state)
+                return this.landed(textOf(res), state);
+        }
+        return { content: [{ type: "text", text: textOf(res) }], ...(res.isError ? { isError: true } : {}) };
+    }
+    refuse(tool, cls, reason, domain) {
+        this.host.emit({ type: "policy.decision", ...(domain ? { domain } : {}), detail: { tool, class: cls, decision: "refused", reason: reason.slice(0, 200) } });
+        return text(reason, true);
+    }
+    allow(tool, cls) {
+        this.host.emit({ type: "policy.decision", detail: { tool, class: cls, decision: "allowed" } });
+    }
+    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: String(v.title ?? ""), captcha: !!v.captcha, login: !!v.login, duplicate: !!v.duplicate, antiBot: !!v.antiBot, confirmed: !!v.confirmed };
+    }
+    blockerOf(s) {
+        return s.captcha ? "captcha" : s.antiBot ? "anti_bot" : s.duplicate ? "duplicate_application" : s.login ? "login_required" : null;
+    }
+    /** Pause for the owner; true when they resolved it and work may continue. */
+    async pauseFor(p, recheck) {
+        this.blocked = { reason: p.reason, questions: p.question ? [p.question] : [] };
+        const outcome = await this.host.pause(p);
+        if (outcome !== "resumed")
+            return false;
+        if (recheck && !(await recheck()))
+            return false;
+        this.blocked = null;
+        return true;
+    }
+    /** 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++;
+        const host = hostOf(state.url) ?? "";
+        this.host.emit({ type: "browser.navigated", url: state.url, domain: host });
+        const blocker = this.blockerOf(state);
+        if (!blocker)
+            return text(toolText);
+        this.host.emit({ type: "browser.blocked", url: state.url, domain: host, detail: { reason: blocker } });
+        const ok = await this.pauseFor({ reason: blocker, url: state.url, domain: host }, async () => {
+            const after = await this.inspect();
+            return !!after && this.blockerOf(after) === null;
+        });
+        if (!ok)
+            return text(`${host} needs a person (${blocker.replace(/_/g, " ")}) and it was not resolved. Do not work around it. Stop now.`, true);
+        return text("Resumed after the owner handled it. Take a browser_snapshot to read the page.");
+    }
+    /** May the run be on this host? Asks the owner (external_redirect) when it is not an allowed site. */
+    async admit(host, url) {
+        if (this.host.isAllowed(host)) {
+            if (!this.admitted.has(host)) {
+                this.admitted.add(host);
+                this.host.emit({ type: "policy.decision", domain: host, detail: { class: "read", decision: "allowed", basis: "allow_list" } });
+            }
+            return true;
+        }
+        return this.pauseFor({ reason: "external_redirect", url, domain: host }, async () => this.host.isAllowed(host));
+    }
+    async navigate(url) {
+        const host = hostOf(url);
+        if (!host)
+            return this.refuse("browser_navigate", "read", "Only http(s) URLs can be opened.");
+        if (this.pages >= this.host.limits.maxPages)
+            return this.refuse("browser_navigate", "read", `The run's limit of ${this.host.limits.maxPages} pages is reached. Call ready_for_review now.`);
+        if (!(await this.admit(host, url)))
+            return this.refuse("browser_navigate", "read", `${host} is not one of this application's sites and the owner did not allow it. Stop now.`, host);
+        const res = await this.browser.callTool("browser_navigate", { url });
+        if (res.isError)
+            return { content: [{ type: "text", text: textOf(res) }], isError: true };
+        return this.afterMove("browser_navigate", textOf(res));
+    }
+    /** A page change the CLI did not fully choose (a redirect, a link): leaving the allowed sites is undone and paused. */
+    async afterMove(tool, toolText) {
+        const state = await this.inspect();
+        const landedOn = state ? hostOf(state.url) : null;
+        if (state && landedOn && !this.host.isAllowed(landedOn)) {
+            await this.browser.callTool("browser_navigate_back", {}).catch(() => undefined);
+            if (!(await this.pauseFor({ reason: "external_redirect", url: state.url, domain: landedOn }, async () => this.host.isAllowed(landedOn)))) {
+                return this.refuse(tool, "read", `That led to ${landedOn}, which is not one of this application's sites. It was undone. Stop now.`, landedOn);
+            }
+            return text(`The owner allowed ${landedOn}. Open it with browser_navigate.`);
+        }
+        return this.landed(toolText, state);
+    }
+    target(args) {
+        const ref = typeof args.target === "string" ? args.target : typeof args.ref === "string" ? args.ref : "";
+        const found = ref ? refRole(this.lastSnapshot, ref) : null;
+        return found ? { ref, ...found } : null;
+    }
+    async probe(ref, label) {
+        const res = await this.browser.callTool("browser_evaluate", { element: label || "control", target: ref, function: ELEMENT_PROBE_FN }).catch(() => null);
+        const v = res && !res.isError ? evaluateResult(textOf(res)) : null;
+        return v && typeof v.submits === "boolean" ? v : null;
+    }
+    async click(args) {
+        const t = this.target(args);
+        if (!t)
+            return this.refuse("browser_click", "read", "Click only elements from the latest browser_snapshot, by their ref.");
+        const forward = { element: typeof args.element === "string" ? args.element : t.name, target: t.ref };
+        if (FIELD_ROLES.has(t.role)) {
+            if ((t.role === "checkbox" || t.role === "switch") && CONSENT_NAME.test(t.name)) {
+                this.host.emit({ type: "policy.decision", detail: { tool: "browser_click", class: "fill", decision: "paused", reason: "consent_required" } });
+                const ok = await this.pauseFor({ reason: "consent_required", question: `Agree to: ${t.name.slice(0, 200)}` });
+                return ok ? text("The owner handled that agreement in the browser. Do not click it yourself; take a browser_snapshot and continue.") : text("The owner did not handle that agreement. Stop now.", true);
+            }
+            const refusal = groundingRefusal(t.name, args.source_quote, this.host.grounding());
+            if (refusal)
+                return this.refuse("browser_click", "fill", refusal);
+            return this.fill("browser_click", t.role, forward);
+        }
+        const facts = await this.probe(t.ref, t.name);
+        if (!facts)
+            return this.refuse("browser_click", "read", "That element could not be read from the page, so the click cannot be shown to be safe. Take a fresh browser_snapshot.");
+        const commits = (facts.submits && facts.method === "post") || [facts.name, t.name, String(forward.element)].some((n) => n && FALLBACK_COMMIT_RE.test(n));
+        if (commits)
+            return this.submit(forward);
+        if (NAV_ROLES.has(t.role) || (t.role === "button" && PAGINATION_NAME.test(t.name.trim()))) {
+            if (this.pages >= this.host.limits.maxPages)
+                return this.refuse("browser_click", "read", `The run's limit of ${this.host.limits.maxPages} pages is reached. Call ready_for_review now.`);
+            const res = await this.browser.callTool("browser_click", forward);
+            if (res.isError)
+                return { content: [{ type: "text", text: textOf(res) }], isError: true };
+            return this.afterMove("browser_click", textOf(res));
+        }
+        // A native file input opens the file chooser for upload_artifact — a DOM fact, whatever its label.
+        const fileInput = facts.tag === "input" && facts.type === "file";
+        if (fileInput || (t.role === "button" && STEP_NAME.test(t.name.trim()) && !facts.submits)) {
+            this.allow("browser_click", "fill");
+            const res = await this.browser.callTool("browser_click", forward);
+            return { content: [{ type: "text", text: textOf(res) }], ...(res.isError ? { isError: true } : {}) };
+        }
+        return this.refuse("browser_click", "read", `"${t.name || t.role}" is not a control an application run may press. Links, form-step buttons (Next, Upload, Add) and answers are allowed.`);
+    }
+    async fill(tool, role, forward) {
+        const res = await this.browser.callTool(tool, forward);
+        if (res.isError)
+            return { content: [{ type: "text", text: textOf(res) }], isError: true };
+        this.filled++;
+        this.host.emit({ type: "field.filled", detail: { tool, class: "fill", role } });
+        return text(textOf(res));
+    }
+    async type(args) {
+        const t = this.target(args);
+        if (!t || !TYPE_ROLES.has(t.role))
+            return this.refuse("browser_type", "fill", "Type only into a text field from the latest browser_snapshot, by its ref.");
+        if (args.submit === true)
+            return this.refuse("browser_type", "submit", "Typing may not submit the form (submit: true is refused).");
+        if (CREDENTIAL_NAME.test(t.name)) {
+            const ok = await this.pauseFor({ reason: "login_required", question: `Sign in: ${t.name.slice(0, 200)}` });
+            return ok ? text("The owner handled the sign-in. Take a browser_snapshot and continue.") : text("A sign-in needs the owner and was not handled. Stop now.", true);
+        }
+        const value = typeof args.text === "string" ? args.text : "";
+        const refusal = groundingRefusal(value, args.source_quote, this.host.grounding());
+        if (refusal)
+            return this.refuse("browser_type", "fill", refusal);
+        return this.fill("browser_type", t.role, { element: typeof args.element === "string" ? args.element : t.name, target: t.ref, text: value });
+    }
+    async select(args) {
+        const t = this.target(args);
+        if (!t)
+            return this.refuse("browser_select_option", "fill", "Select only in a field from the latest browser_snapshot, by its ref.");
+        const values = Array.isArray(args.values) ? args.values.filter((v) => typeof v === "string") : [];
+        if (!values.length)
+            return this.refuse("browser_select_option", "fill", "values is required.");
+        for (const v of values) {
+            const refusal = groundingRefusal(v, args.source_quote, this.host.grounding());
+            if (refusal)
+                return this.refuse("browser_select_option", "fill", refusal);
+        }
+        return this.fill("browser_select_option", t.role, { element: typeof args.element === "string" ? args.element : t.name, target: t.ref, values });
+    }
+    async pressKey(args) {
+        const key = typeof args.key === "string" ? args.key : "";
+        if (!SAFE_KEYS.test(key))
+            return this.refuse("browser_press_key", "submit", `${key || "That key"} is refused: only Tab, arrows, Escape, Home/End and PageUp/PageDown move between fields. Enter and Space can submit.`);
+        const res = await this.browser.callTool("browser_press_key", { key });
+        return { content: [{ type: "text", text: textOf(res) }], ...(res.isError ? { isError: true } : {}) };
+    }
+    async upload(args) {
+        const kind = args.kind === "resume" || args.kind === "cover_letter" ? args.kind : null;
+        if (!kind)
+            return this.refuse("upload_artifact", "fill", "kind must be resume or cover_letter.");
+        if (this.uploaded.has(kind))
+            return this.refuse("upload_artifact", "fill", `The ${kind.replace("_", " ")} is already attached; it is never attached twice.`);
+        const file = this.host.artifactPath(kind);
+        if ("error" in file) {
+            this.blocked = { reason: "artifact_changed", questions: [file.error] };
+            return this.refuse("upload_artifact", "fill", `${file.error} Stop now.`);
+        }
+        const res = await this.browser.callTool("browser_file_upload", { paths: [file.path] });
+        if (res.isError) {
+            const msg = textOf(res);
+            return text(/modal state|file chooser/i.test(msg) ? "No file chooser is open. Click the field's upload control first, then call upload_artifact." : msg, true);
+        }
+        this.uploaded.add(kind);
+        this.host.emit({ type: "artifact.uploaded", detail: { kind, sha256: file.sha256, class: "fill" } });
+        return text(`Attached the approved ${kind.replace("_", " ")}.`);
+    }
+    async requestAnswer(args) {
+        const question = typeof args.question === "string" ? args.question.trim().slice(0, 300) : "";
+        if (!question)
+            return text("request_answer needs the question.", true);
+        const reason = args.kind === "screening_ambiguity" ? "screening_ambiguity" : "missing_answer";
+        const before = this.host.grounding().length;
+        const ok = await this.pauseFor({ reason, question });
+        if (!ok)
+            return text("Nobody answered. Do not guess. Stop now.", true);
+        // Resumed without an answer: the owner chose to leave it — never a cue to guess.
+        if (this.host.grounding().length === before)
+            return text("The owner resumed without answering: leave that field empty and continue with the others.");
+        return text("The owner answered. Their answer is now part of your sources — quote it as source_quote. Take a browser_snapshot and continue.");
+    }
+    review(summary) {
+        this.reviewReady = true;
+        this.summary = summary; // bounded where the result is built (runtime.ts `end`)
+        this.host.emit({ type: "review.ready", detail: { class: "review", count: this.filled } });
+        return text("Recorded. The application waits for the owner's review; nothing was submitted. Stop now.");
+    }
+    /** The final Submit. Never under fill_and_review; once, gated and traced, under auto_submit. */
+    async submit(forward) {
+        if (this.host.mode !== "auto_submit" || !this.host.gateId) {
+            this.host.emit({ type: "policy.decision", detail: { tool: "browser_click", class: "submit", decision: "refused", reason: "fill_and_review" } });
+            this.review("Stopped at the final submit: this run fills and waits for review.");
+            return text("That control submits the application, and this run is fill-and-review: it was NOT pressed. The application waits for the owner's review. Stop now.");
+        }
+        const before = await this.inspect();
+        if (!before)
+            return this.refuse("browser_click", "submit", "The page could not be read, so the submit cannot be shown to be safe. Take a fresh browser_snapshot.");
+        const blocker = this.blockerOf(before);
+        if (blocker) {
+            this.blocked = { reason: blocker, questions: [] };
+            return this.refuse("browser_click", "submit", `The page shows a blocker (${blocker.replace(/_/g, " ")}); nothing was submitted. Stop now.`, hostOf(before.url) ?? undefined);
+        }
+        const domain = hostOf(before.url) ?? "";
+        if (!this.host.isAllowed(domain))
+            return this.refuse("browser_click", "submit", `${domain} is not one of this application's sites; nothing was submitted.`, domain);
+        this.submitAttempted = true;
+        this.host.emit({ type: "submit.attempted", url: before.url, domain, detail: { class: "submit", gateId: this.host.gateId } });
+        const res = await this.browser.callTool("browser_click", forward);
+        await this.browser.callTool("browser_wait_for", { time: 2 }).catch(() => undefined);
+        const after = res.isError ? null : await this.inspect();
+        if (after?.confirmed) {
+            this.submitted = { url: after.url, at: new Date(this.host.now()).toISOString(), gateId: this.host.gateId };
+            this.host.emit({ type: "submit.confirmed", url: after.url, domain: hostOf(after.url) ?? domain, detail: { gateId: this.host.gateId } });
+            return text("Submitted, and the site confirmed it. Stop now.");
+        }
+        this.blocked = { reason: "submit_unconfirmed", questions: ["The application was submitted but the site did not confirm it. Check the employer's site or your email before anything is retried."] };
+        this.host.emit({ type: "submit.unconfirmed", ...(after ? { url: after.url } : {}), domain, detail: { gateId: this.host.gateId } });
+        return text("The submit was pressed but no confirmation was seen. Do not press it again. Stop now.", true);
+    }
+}

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

@@ -0,0 +1,165 @@
+/**
+ * Local application execution — the wire contract between PAGS and the runner (#957, epic #943).
+ *
+ * The Job Application Runner takes ONE application whose materials are ready (#956) and fills its
+ * form in a real browser on the owner's machine, driven by a Codex or Claude Code CLI signed in on
+ * that machine. The CLI reaches the page only through the runner's apply bridge, which enforces the
+ * write policy below: every browser action belongs to an ACTION CLASS, and a class is allowed or
+ * refused by the runner, not asked of the model.
+ *
+ *   read    — navigate, snapshot, wait, follow a link inside the allowed sites;
+ *   fill    — type, select, tick, upload an approved artifact — each value grounded in the owner's
+ *             own profile / answers / artifacts;
+ *   review  — stop with the form filled and nothing sent (`awaiting_review`);
+ *   submit  — the final external Submit. Only under `auto_submit`, only with the gate PAGS
+ *             evaluated (`policy.submitGate`), and at most once per run.
+ *
+ * The default mode is `fill_and_review`, in which a submit-class action is never performed.
+ *
+ * Kept BYTE-IDENTICAL at
+ *
+ *   workers/api/src/lib/local-apply/contract.ts
+ *   packages/browser-runner/src/local-apply/contract.ts
+ *
+ * (`contract.test.ts` fails the moment they differ) and imports nothing, so it can be vendored.
+ *
+ * PULL, not push: the runner holds no API token, so PAGS reads a run with `status` — when it is
+ * read and from the per-minute cron — exactly like local browser research.
+ */
+export const LOCAL_APPLY_TASK_TYPE = "local_browser.apply";
+export const LOCAL_APPLY_RUN_PATH = "/local-apply/run";
+export const LOCAL_APPLY_STATUS_PATH = "/local-apply/status";
+export const LOCAL_APPLY_RESUME_PATH = "/local-apply/resume";
+export const LOCAL_APPLY_CANCEL_PATH = "/local-apply/cancel";
+export const LOCAL_APPLY_ENGINES = ["claude", "codex"];
+export const LOCAL_APPLY_AUTH_MODES = ["machine", "subscription"];
+export const LOCAL_APPLY_MODES = ["fill_and_review", "auto_submit"];
+export const LOCAL_APPLY_PAUSE_REASONS = [
+    "captcha",
+    "login_required",
+    "consent_required",
+    "missing_answer",
+    "screening_ambiguity",
+    "external_redirect",
+    "duplicate_application",
+    "anti_bot",
+];
+export const LOCAL_APPLY_BLOCK_REASONS = [
+    ...LOCAL_APPLY_PAUSE_REASONS,
+    "submit_unconfirmed",
+    "incomplete",
+    "engine_not_signed_in",
+    "api_key_refused",
+    "source_unavailable",
+    "artifact_changed",
+];
+export const LOCAL_APPLY_EVENT_TYPES = [
+    "engine.auth_checked",
+    "engine.started",
+    "engine.ended",
+    "source.read",
+    "browser.navigated",
+    "browser.blocked",
+    "policy.decision",
+    "field.filled",
+    "artifact.uploaded",
+    "review.ready",
+    "submit.attempted",
+    "submit.confirmed",
+    "submit.unconfirmed",
+    "run.paused",
+    "run.resumed",
+    "note",
+];
+export const LOCAL_APPLY_ENGINE_AUTHS = ["machine-login", "subscription", "api-key", "missing_login", "unknown"];
+export const LOCAL_APPLY_CAPS = { questions: 20, questionChars: 300, answers: 20, answerChars: 2000, summary: 2000 };
+const str = (v, max) => (typeof v === "string" && v.trim() ? v.trim().slice(0, max) : null);
+const oneOf = (list, v) => (list.includes(v) ? v : null);
+const isHttpUrl = (v) => /^https?:\/\/[^\s/]+/i.test(v);
+const DETAIL_KEYS = new Set(["engine", "authMode", "engineAuth", "mode", "class", "tool", "decision", "reason", "role", "kind", "path", "sha256", "bytes", "gateId", "exitCode", "count", "status", "basis"]);
+/** A validated event, or null. Detail keeps only whitelisted, primitive, bounded values. */
+export function parseLocalApplyEvent(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const o = raw;
+    const type = oneOf(LOCAL_APPLY_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_APPLY_PAUSE_REASONS, o.pauseReason);
+    if (type === "run.paused" && !pauseReason)
+        return null;
+    if (pauseReason)
+        event.pauseReason = pauseReason;
+    if (o.detail && typeof o.detail === "object" && !Array.isArray(o.detail)) {
+        const detail = {};
+        for (const [k, v] of Object.entries(o.detail)) {
+            if (!DETAIL_KEYS.has(k))
+                continue;
+            if (typeof v === "string")
+                detail[k] = v.slice(0, 300);
+            else if (typeof v === "number" || typeof v === "boolean")
+                detail[k] = v;
+        }
+        if (Object.keys(detail).length)
+            event.detail = detail;
+    }
+    return event;
+}
+/**
+ * A validated result envelope, or the reason it is not one. A `submitted` outcome must carry the
+ * confirmed page, the gate it ran under, and a run in `auto_submit` — anything less is not a
+ * submission PAGS will record.
+ */
+export function parseLocalApplyResult(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 = oneOf(["awaiting_review", "submitted", "blocked", "failed"], o.outcome);
+    if (!outcome)
+        return { error: "outcome must be awaiting_review, submitted, blocked or failed" };
+    const mode = oneOf(LOCAL_APPLY_MODES, o.mode);
+    if (!mode)
+        return { error: "mode is required" };
+    const traceId = str(o.traceId, 100);
+    if (!traceId)
+        return { error: "traceId is required" };
+    const engineAuth = oneOf(LOCAL_APPLY_ENGINE_AUTHS, o.engineAuth);
+    if (!engineAuth)
+        return { error: `engineAuth must be one of ${LOCAL_APPLY_ENGINE_AUTHS.join(", ")}` };
+    const filled = typeof o.filled === "number" && Number.isInteger(o.filled) && o.filled >= 0 ? o.filled : 0;
+    const uploaded = (Array.isArray(o.uploaded) ? o.uploaded : []).filter((k) => k === "resume" || k === "cover_letter");
+    const out = { runId, outcome, mode, traceId, engineAuth, filled, uploaded: [...new Set(uploaded)], submitAttempted: o.submitAttempted === true, summary: str(o.summary, LOCAL_APPLY_CAPS.summary) ?? "" };
+    if (outcome === "submitted") {
+        const s = (o.submitted && typeof o.submitted === "object" ? o.submitted : {});
+        const url = str(s.url, 2000);
+        const at = str(s.at, 40);
+        const gateId = str(s.gateId, 100);
+        if (mode !== "auto_submit")
+            return { error: "a submitted outcome requires a run in auto_submit mode" };
+        if (!url || !isHttpUrl(url) || !at || Number.isNaN(Date.parse(at)) || !gateId)
+            return { error: "a submitted outcome needs the confirmed url, its time and the gateId" };
+        out.submitted = { url, at, gateId };
+        out.submitAttempted = true;
+    }
+    if (outcome === "blocked") {
+        out.blockReason = oneOf(LOCAL_APPLY_BLOCK_REASONS, o.blockReason) ?? "incomplete";
+        out.questions = (Array.isArray(o.questions) ? o.questions : [])
+            .filter((q) => typeof q === "string" && q.trim() !== "")
+            .slice(0, LOCAL_APPLY_CAPS.questions)
+            .map((q) => q.trim().slice(0, LOCAL_APPLY_CAPS.questionChars));
+    }
+    if (outcome === "failed")
+        out.error = str(o.error, 1000) ?? "The run failed without a reason.";
+    return { result: out };
+}

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/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"',

package/dist/browser-runner/runner.js

@@ -16,6 +16,8 @@ import { LocalBrowserRuntime } from "./local-browser/runtime.js";
 import { LOCAL_BROWSER_TASK_TYPE } from "./local-browser/contract.js";
 import { LocalArtifactRuntime } from "./local-artifact/runtime.js";
 import { LOCAL_ARTIFACT_TASK_TYPE } from "./local-artifact/contract.js";
+import { LocalApplyRuntime } from "./local-apply/runtime.js";
+import { LOCAL_APPLY_TASK_TYPE } from "./local-apply/contract.js";
 import { WORKFLOW_DRIVEN_TASKS } from "./task-types.js";
 /** True for a plain object. */
 function isRecord(value) {
@@ -81,6 +83,8 @@ export class LocalRunner {
     localBrowser;
     /** Local artifact generation (#956): the Application Tailor's résumé + cover letter, from the owner's own files. */
     localArtifact;
+    /** Local application execution (#957): a signed-in CLI filling one application through the apply bridge. */
+    localApply;
     /** 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). */
@@ -90,20 +94,18 @@ 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() };
-            },
-        });
+        // `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.
+        const 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() };
+        };
+        this.localBrowser = new LocalBrowserRuntime({ dataDir: config.dataDir, selfUrl: () => this.selfUrl, browserFor });
         this.localArtifact = new LocalArtifactRuntime({ dataDir: config.dataDir });
+        this.localApply = new LocalApplyRuntime({ dataDir: config.dataDir, selfUrl: () => this.selfUrl, browserFor });
         // 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();
@@ -118,7 +120,7 @@ export class LocalRunner {
             runtimePlane: "pags",
             runnerRole: "tool-executor",
             capabilities: [...CAPABILITIES, ...CodingRuntime.capabilities()],
-            taskTypes: ["echo", "browser.open", "job.apply_agent", "site_builder_runtime", LOCAL_BROWSER_TASK_TYPE, LOCAL_ARTIFACT_TASK_TYPE, ...CodingRuntime.taskTypes()],
+            taskTypes: ["echo", "browser.open", "job.apply_agent", "site_builder_runtime", LOCAL_BROWSER_TASK_TYPE, LOCAL_ARTIFACT_TASK_TYPE, LOCAL_APPLY_TASK_TYPE, ...CodingRuntime.taskTypes()],
             approvalRequiredFor: [...APPROVAL_REQUIRED_TASKS],
         };
     }
@@ -256,6 +258,7 @@ export class LocalRunner {
     async close() {
         this.localBrowser.closeAll();
         this.localArtifact.closeAll();
+        this.localApply.closeAll();
         try {
             this.coding.closeAll();
         }

package/dist/browser-runner/server.js

@@ -12,7 +12,11 @@ export function createRunnerServer(runner) {
             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))
+                const runId = String(body.runId ?? "");
+                // The same forwarder serves application runs (#957); each runtime knows only its own tokens.
+                if (runner.localApply.authorizeBridge(runId, token))
+                    return json(res, 200, await runner.localApply.bridge(body));
+                if (!runner.localBrowser.authorizeBridge(runId, token))
                     return json(res, 401, { error: "Unauthorized" });
                 return json(res, 200, await runner.localBrowser.bridge(body));
             }
@@ -187,6 +191,19 @@ async function route(runner, req, res) {
     if (req.method === "POST" && path === "/local-artifact/cancel") {
         return json(res, 200, runner.localArtifact.cancel(await readJson(req)));
     }
+    // Local application execution (#957) — run, status, resume, cancel; PULL like research.
+    if (req.method === "POST" && path === "/local-apply/run") {
+        return json(res, 202, runner.localApply.start(await readJson(req)));
+    }
+    if (req.method === "POST" && path === "/local-apply/status") {
+        return json(res, 200, runner.localApply.status(await readJson(req)));
+    }
+    if (req.method === "POST" && path === "/local-apply/resume") {
+        return json(res, 200, runner.localApply.resume(await readJson(req)));
+    }
+    if (req.method === "POST" && path === "/local-apply/cancel") {
+        return json(res, 200, runner.localApply.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/package.json

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