@proagentstore/cli 0.4.52 → 0.4.54

package/dist/browser-runner/commit-guard.js

@@ -0,0 +1,127 @@
+/**
+ * The commit guard AT THE ACT BOUNDARY — the runner half of #627 / #629.
+ *
+ * ── Why it has to be here
+ *
+ * `dryRun` and `readOnly` were enforced entirely in the cloud, on `action.name`: a string the MODEL
+ * wrote ABOUT the element. This process is the one that actually clicks, and it clicks by `ref`
+ * ({@link https://github.com/microsoft/playwright-mcp} `browser_click({ element, target })` — only
+ * `target` locates; `element` is a human-readable description). So the guard tested a story about
+ * the act while the act went somewhere else entirely, and the runner — the only party holding the
+ * DOM, and therefore the only one that can KNOW whether a control submits — had never been told
+ * that a run was a rehearsal at all: `grep -rn dryRun packages/browser-runner/src` returned eight
+ * hits and every one of them was the orphaned-browser reaper's unrelated `--dry-run` flag.
+ *
+ * A nameless click had already submitted a real application during a run the owner asked to be a
+ * test. The fix at the time made an EMPTY name a refusal, which left a WRONG name — a paraphrase,
+ * an `aria-label` the model rewrote, a page in French — behaving exactly as before.
+ *
+ * ── What is a fact here and what is still a guess
+ *
+ * FACT (`read_only`): whether the targeted control submits a form, and whether that form is a POST.
+ * Language-independent, label-independent, and not something the brain can talk its way past. A
+ * GET form is a search — the read-only prompt explicitly allows finding things — so only POST is
+ * refused. Enter and Space are checked against the FOCUSED element the same way.
+ *
+ * GUESS (both rehearsal modes): which of several POST submits on a multi-page ATS is the FINAL one.
+ * Nothing in the DOM says so — "Save and Continue" on page 3 and "Submit application" on page 6 are
+ * the same kind of control — and a rehearsal must be able to walk the whole form. So a rehearsal
+ * still decides on a LABEL. What changed is whose label: the element's own accessible name, read
+ * back out of the live DOM, instead of the model's claim about it, and a vocabulary that is not
+ * English-only. That residual is recorded on the issue rather than papered over.
+ */
+/**
+ * The FLOOR vocabulary, used only when the cloud sent none. It is deliberately the read-only
+ * (widest) set: a runner that has been told "read_only" but not told the words must not fail open.
+ * The authoritative list is `workers/api/src/lib/commit-guard.ts`, and `commit-guard.test.ts` there
+ * asserts this file still parses as a regex, so a copy that rots is a red build rather than a
+ * silent downgrade.
+ */
+export const FALLBACK_COMMIT_RE = /\b(confirm|accept|submit|send|post|publish|delete|remove|pay|purchase|buy|apply|approve|agree|save)\b|(?<![\p{L}\p{N}])(envoyer|soumettre|valider|absenden|abschicken|senden|einreichen|enviar|invia|inviare|verstuur|versturen|verzenden|indienen|skicka|wy[śs]lij|g[öo]nder|kirim|отправить)(?![\p{L}\p{N}])|提交|送出|确认|確認|送信|提出|제출|보내기|إرسال|تقديم/iu;
+/** Compile the policy the cloud sent, falling back to the floor above. A malformed pattern must
+ *  NOT disarm the guard — it falls back rather than throwing, because the caller is about to act. */
+export function commitLabelRe(spec) {
+    if (!spec?.labels)
+        return FALLBACK_COMMIT_RE;
+    try {
+        return new RegExp(spec.labels, spec.flags || "iu");
+    }
+    catch {
+        return FALLBACK_COMMIT_RE;
+    }
+}
+/** Keys that submit a focused form. `NumpadEnter` submits identically and was matched by nothing. */
+export const SUBMIT_KEY_RE = /^(enter|return|numpadenter)$/i;
+/** Space activates the focused control, including a submit button. */
+export const ACTIVATE_KEY_RE = /^(space|spacebar|\s)$/i;
+/** The probe evaluated ON the targeted element. Kept as source text because it crosses into the
+ *  page through the standard `browser_evaluate` tool, which takes a function expression. */
+export const ELEMENT_PROBE_FN = `el => {
+  var btn = (el.closest && el.closest('button,input,a,[role=button]')) || el;
+  var tag = (btn.tagName || '').toLowerCase();
+  var type = ((btn.getAttribute && btn.getAttribute('type')) || '').toLowerCase();
+  var form = btn.form || (btn.closest && btn.closest('form')) || null;
+  var submits = !!form && ((tag === 'button' && type !== 'button' && type !== 'reset') || (tag === 'input' && (type === 'submit' || type === 'image')));
+  var name = (btn.getAttribute && btn.getAttribute('aria-label')) || btn.value || btn.innerText || btn.textContent || '';
+  return { submits: submits, method: form ? ((form.getAttribute('method') || 'get').toLowerCase()) : '', tag: tag, type: type, name: String(name).replace(/\\s+/g, ' ').trim().slice(0, 160) };
+}`;
+/** The probe for a keypress: there is no ref, so it reads whatever has focus. */
+export const FOCUS_PROBE_FN = `(() => {
+  var el = document.activeElement;
+  if (!el) return { inForm: false, method: '', tag: '', type: '', name: '' };
+  var form = el.form || (el.closest && el.closest('form')) || null;
+  var name = (el.getAttribute && el.getAttribute('aria-label')) || el.value || el.innerText || el.textContent || '';
+  return { inForm: !!form, method: form ? ((form.getAttribute('method') || 'get').toLowerCase()) : '', tag: (el.tagName || '').toLowerCase(), type: ((el.getAttribute && el.getAttribute('type')) || '').toLowerCase(), name: String(name).replace(/\\s+/g, ' ').trim().slice(0, 160) };
+})()`;
+/**
+ * May this click reach the page? Returns the refusal to hand back to the brain, or null.
+ *
+ * `facts` is null when the element could not be probed (an evaluate that failed, a ref the page no
+ * longer has). That is not treated as permission: in read-only it is refused outright, and in a
+ * rehearsal it falls back to the claimed name, which is the behaviour that shipped.
+ */
+export function refuseClick(spec, facts, claimedName, re) {
+    const claimed = (claimedName ?? "").trim();
+    const real = (facts?.name ?? "").trim();
+    if (spec.mode === "read_only") {
+        if (!facts) {
+            return "BLOCKED by the runner — this agent is READ-ONLY and that element could not be read from the page, so the click cannot be shown to be safe. Re-read the snapshot and target an element from it.";
+        }
+        if (facts.submits && facts.method === "post") {
+            return `BLOCKED by the runner — this agent is READ-ONLY and "${real || claimed || facts.tag}" submits a form (POST) on this page. That is a change, whatever the control is called. Report what you can already see with finish.`;
+        }
+    }
+    const hit = [real, claimed].find((n) => n && re.test(n));
+    if (!hit)
+        return null;
+    return spec.mode === "read_only"
+        ? `BLOCKED by the runner — this agent is READ-ONLY and can never perform "${hit}". Report what you can already see with finish.`
+        : `BLOCKED by the runner — this is a REHEARSAL and "${hit}" commits. The page never received the click. Call finish now instead of retrying.`;
+}
+/**
+ * May this keypress reach the page?
+ *
+ * Read-only only. A rehearsal's Enter is decided by the cloud loop, which holds the one piece of
+ * state that makes the call — an Enter immediately after an arrow key is an autocomplete ACCEPT,
+ * not a submit — and this process cannot tell a JS listbox that will swallow the key from a form
+ * that will take it.
+ */
+export function refuseKey(spec, key, focus) {
+    if (spec.mode !== "read_only")
+        return null;
+    const k = (key ?? "").trim();
+    const submitKey = SUBMIT_KEY_RE.test(k);
+    const activateKey = ACTIVATE_KEY_RE.test(k);
+    if (!submitKey && !activateKey)
+        return null;
+    if (!focus) {
+        return `BLOCKED by the runner — this agent is READ-ONLY and the focused element could not be read, so pressing ${k || "Enter"} cannot be shown to be safe.`;
+    }
+    if (submitKey && focus.inForm && focus.method === "post") {
+        return `BLOCKED by the runner — this agent is READ-ONLY and pressing ${k} submits the form this field belongs to (POST). A search or filter that only reads (GET) is fine; this one writes. Report what you can already see with finish.`;
+    }
+    if (activateKey && (focus.tag === "button" || focus.type === "submit") && focus.method === "post") {
+        return `BLOCKED by the runner — this agent is READ-ONLY and Space activates "${focus.name || "the focused button"}", which submits a form (POST).`;
+    }
+    return null;
+}

package/dist/browser-runner/runner.js

@@ -6,6 +6,7 @@ import { pathToFileURL } from "node:url";
 import { captureScreenshotDataUrl, challengeSolved, detectHumanChallenge } from "./challenge.js";
 import { resolveRealChromeProfileDir, seedProfileCopy } from "./browser-profile.js";
 import { McpRuntime } from "./mcp-runtime.js";
+import { commitLabelRe, ELEMENT_PROBE_FN, FOCUS_PROBE_FN, refuseClick, refuseKey } from "./commit-guard.js";
 import { HumanHandoffError, RunnerInputError } from "./errors.js";
 import { RunnerStore } from "./store.js";
 import { CodingRuntime } from "./coding/runtime.js";
@@ -837,6 +838,46 @@ export class LocalRunner {
             return false;
         return null;
     }
+    /** Evaluate a function ON an element (by snapshot ref) and parse its JSON result. Never throws
+     *  — a null return means "the page could not be asked", which callers must not read as a yes. */
+    async evalJson(mcp, ref, label, fn) {
+        const res = await mcp.callTool("browser_evaluate", { element: label, target: ref, function: fn }).catch(() => null);
+        if (!res || res.isError)
+            return null;
+        const txt = mcp.textOf(res);
+        const i = txt.indexOf("### Result");
+        if (i < 0)
+            return null;
+        const after = txt.slice(i + "### Result".length).trim();
+        const end = after.indexOf("\n###");
+        const block = (end >= 0 ? after.slice(0, end) : after).trim();
+        try {
+            return JSON.parse(block);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * The commit guard, enforced HERE because this is the process that clicks (#627, #629).
+     *
+     * The cloud's pre-filter reads a label the model wrote; this one reads the element. For a
+     * read-only agent that is a DOM fact — does this control submit a POST form — which no label,
+     * in any language, can talk its way past. Returns the refusal to hand back to the brain.
+     */
+    async commitRefusal(mcp, page, action, guard) {
+        const re = commitLabelRe(guard);
+        if (action.action === "click") {
+            const ref = (action.ref || "").trim();
+            const facts = ref ? await this.evalJson(mcp, ref, action.name || action.role || "control", ELEMENT_PROBE_FN) : null;
+            return refuseClick(guard, facts, action.name, re);
+        }
+        if (action.action === "key") {
+            const focus = (await page.evaluate(FOCUS_PROBE_FN).catch(() => null));
+            return refuseKey(guard, action.key, focus);
+        }
+        return null;
+    }
     /** The snapshot ref the brain must target the element by (standard-tool `target`). */
     refOf(action) {
         const ref = (action.ref || "").trim();
@@ -943,7 +984,7 @@ export class LocalRunner {
      * element by its snapshot ref. A tool-level failure is thrown so the workflow
      * surfaces it to the brain as an `error` (which drives its self-correction).
      */
-    async browserAct(action, resumePath) {
+    async browserAct(action, resumePath, guard) {
         const page = await this.getActivePage();
         // Arm résumé auto-attach so a file chooser never blocks the flow (see method).
         // resumePath may be a signed URL (remote runner) or a local path — resolve to
@@ -970,9 +1011,19 @@ export class LocalRunner {
                 title: await active.title().catch(() => ""),
                 challenge: await detectHumanChallenge(active),
                 screenshot: await this.shot(active),
+                commitGuard: { supported: true, mode: guard?.mode },
             };
         }
         const mcp = await this.getMcp();
+        // BEFORE the tool call, never after: this is the last point at which the action is still
+        // only a proposal. `commitGuard.supported` on every reply is how the cloud learns that this
+        // enforcement exists here at all — measured from the runner's own answer, not guessed from
+        // a version number, because the published CLI upgrades on the field's schedule.
+        if (guard) {
+            const refusal = await this.commitRefusal(mcp, page, action, guard);
+            if (refusal)
+                throw new RunnerInputError(refusal);
+        }
         const res = await this.callBrowserTool(mcp, action);
         const text = mcp.textOf(res).trim();
         // A native page dialog (alert/confirm/beforeunload) puts the standard server
@@ -994,6 +1045,7 @@ export class LocalRunner {
                 challenge: await detectHumanChallenge(settled),
                 feedback: dialogMsg ? `a native dialog was accepted: "${dialogMsg}"` : "a native dialog was accepted",
                 screenshot: await this.shot(settled),
+                commitGuard: { supported: true, mode: guard?.mode },
             };
         }
         if (res.isError)
@@ -1027,6 +1079,7 @@ export class LocalRunner {
             challenge: await detectHumanChallenge(active),
             feedback: feedback || undefined,
             screenshot: await this.shot(active),
+            commitGuard: { supported: true, mode: guard?.mode },
         };
     }
     // ── Agent-driven application lifecycle (called by the remote Workflow brain) ──

package/dist/browser-runner/server.js

@@ -90,8 +90,12 @@ async function route(runner, req, res) {
         return json(res, 200, await runner.browserSnapshot(b.taskId));
     }
     if (req.method === "POST" && path === "/browser/act") {
+        // `guard` is the commit policy for THIS run (#627, #629) — a rehearsal or a read-only
+        // agent. It travels with every action rather than being registered once, because the
+        // runner serves many instances at once and a per-connection mode would be a second piece
+        // of state to get wrong.
         const body = await readJson(req);
-        return json(res, 200, await runner.browserAct(body, body.resumePath));
+        return json(res, 200, await runner.browserAct(body, body.resumePath, body.guard));
     }
     if (req.method === "POST" && path === "/browser/event") {
         const b = await readJson(req);

package/dist/browser-runner/test-job-server.js

@@ -1,9 +1,10 @@
 import { createServer, } from "node:http";
 export async function startTestJobServer(port = 0) {
     const submissions = [];
+    const searches = [];
     const server = createServer(async (req, res) => {
         try {
-            await route(req, res, submissions);
+            await route(req, res, submissions, searches);
         }
         catch (error) {
             html(res, 500, `<h1>Server Error</h1><pre>${escapeHtml(String(error))}</pre>`);
@@ -17,7 +18,10 @@ export async function startTestJobServer(port = 0) {
     return {
         url,
         jobUrl: `${url}/jobs/software-engineer`,
+        quickApplyUrl: `${url}/jobs/quick-apply`,
+        searchUrl: `${url}/search`,
         submissions,
+        searches,
         async close() {
             await new Promise((resolve, reject) => {
                 server.close((error) => (error ? reject(error) : resolve()));
@@ -36,7 +40,7 @@ export async function startTestJobServer(port = 0) {
         },
     };
 }
-async function route(req, res, submissions) {
+async function route(req, res, submissions, searches) {
     const url = new URL(req.url || "/", "http://127.0.0.1");
     if (req.method === "GET" && url.pathname === "/") {
         redirect(res, "/jobs/software-engineer");
@@ -51,6 +55,17 @@ async function route(req, res, submissions) {
         }));
         return;
     }
+    if (req.method === "GET" && url.pathname === "/jobs/quick-apply") {
+        html(res, 200, quickApplyPage());
+        return;
+    }
+    if (req.method === "GET" && url.pathname === "/search") {
+        const q = url.searchParams.get("q");
+        if (q !== null)
+            searches.push(q);
+        html(res, 200, searchPage(q));
+        return;
+    }
     if (req.method === "POST" && url.pathname === "/apply") {
         const submission = await parseApplication(req);
         submissions.unshift(submission);
@@ -125,6 +140,33 @@ function jobPage(opts = {}) {
     </main>
   `);
 }
+/** One click = one real application. No `required` attribute anywhere, so nothing but the guard
+ *  can stop the POST — a fixture where HTML validation did the stopping would prove nothing. */
+function quickApplyPage() {
+    return page("Postuler en 1 clic", `
+    <main>
+      <section class="job"><h1>Ingénieur logiciel</h1><p class="company">Fixture Labs</p></section>
+      <form action="/apply" method="post" enctype="multipart/form-data" class="application-form">
+        <input type="hidden" name="fullName" value="Sergey Ivochkin" />
+        <input type="hidden" name="email" value="sergey@example.com" />
+        <label>Recherche <input name="coverNote" aria-label="Recherche" /></label>
+        <button type="submit">Envoyer ma candidature</button>
+      </form>
+    </main>
+  `);
+}
+/** A GET search form: submitting it only READS. */
+function searchPage(q) {
+    return page("Recherche", `
+    <main>
+      <form action="/search" method="get">
+        <label>Search <input name="q" aria-label="Search" /></label>
+        <button type="submit">Search</button>
+      </form>
+      <p id="result">${q === null ? "no query" : `searched: ${escapeHtml(q)}`}</p>
+    </main>
+  `);
+}
 function successPage(submission) {
     return page("Application Received", `
     <main>

package/dist/index.js

@@ -1217,6 +1217,9 @@ function diffMembership(attached, eligible, thisNode, blocked = /* @__PURE__ */
 function shouldRegisterOnOpen(reconnect, alreadyRegistered) {
   return reconnect || !alreadyRegistered;
 }
+function pendingRegistrations(attached, registered) {
+  return [...attached].filter((id) => !registered.has(id));
+}
 function instanceLabel(inst) {
   const short = `${inst.id.slice(0, 8)}\u2026`;
   return inst.name ? `${inst.name} (${short})` : short;
@@ -1336,7 +1339,7 @@ async function connectViaRelay(instanceIds, localUrl, runnerToken, opts, force =
   };
   for (const id of instanceIds) attach(id, "");
   reportRegistration();
-  writeLine(registered.size === instanceIds.length ? `Runtime registered with PAGS \u2713 (${registered.size}/${instanceIds.length} agents)` : `Runtime registration incomplete: ${registered.size}/${instanceIds.length} agents \u2014 retried on each relay (re)connect.`);
+  writeLine(registered.size === instanceIds.length ? `Runtime registered with PAGS \u2713 (${registered.size}/${instanceIds.length} agents)` : `Runtime registration incomplete: ${registered.size}/${instanceIds.length} agents \u2014 retried on each relay (re)connect${watchInstances ? " and every 20s while this runs" : ""}.`);
   writeLine("");
   writeLine("\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550");
   writeLine(`  \u2705 CONNECTED \u2014 WebSocket relay \xB7 ${hostname3()}`);
@@ -1406,6 +1409,11 @@ async function connectViaRelay(instanceIds, localUrl, runnerToken, opts, force =
             attach(inst.id, instanceLabel(inst));
           }
           for (const id of toDetach) detach(id);
+          const pending = pendingRegistrations(attached.keys(), registered);
+          if (pending.length) {
+            for (const id of pending) await registerRuntime(id);
+            reportRegistration();
+          }
         } catch {
         }
         tick();

package/package.json

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