@proagentstore/cli 0.4.78 → 0.4.80

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 };
+}