@proagentstore/cli 0.4.95 → 0.4.96

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

@@ -35,6 +35,17 @@ export const LOCAL_APPLY_CANCEL_PATH = "/local-apply/cancel";
 export const LOCAL_APPLY_PREFLIGHT_PATH = "/local-apply/preflight";
 /** Delivers a cloud-persisted supervisory decision to one paused checkpoint. */
 export const LOCAL_APPLY_DIRECTIVE_PATH = "/local-apply/directive";
+/**
+ * A short-lived, owner-authorized view of the *existing* browser page for one local-apply run.
+ * The id is opaque and carries no browser/profile material.  It deliberately is not a task id:
+ * local-apply runs are not generic runner tasks.
+ */
+export const LOCAL_APPLY_HANDOFF_PATH = "/local-apply/handoff";
+export const LOCAL_APPLY_HANDOFF_STATUS_PATH = "/local-apply/handoff-status";
+export const LOCAL_APPLY_HANDOFF_FRAME_PATH = "/local-apply/handoff/frame";
+export const LOCAL_APPLY_HANDOFF_INPUT_PATH = "/local-apply/handoff/input";
+export const LOCAL_APPLY_HANDOFF_RESUME_PATH = "/local-apply/handoff/resume";
+export const LOCAL_APPLY_HANDOFF_END_PATH = "/local-apply/handoff/end";
 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"];
@@ -84,7 +95,7 @@ export const LOCAL_APPLY_BLOCK_REASONS = [
  * dispatch, naming the update, rather than silently producing the older behaviour (`apply.ts`
  * `runnerContractProblem`).
  *
- * ── Why it moved to 0.4.90 (#953)
+ * ── Why it moved to 0.4.96 (#1013)
  *
  * #953 adds the read-only `/local-apply/preflight` route used before an email lead can enter
  * tailoring. That route lives in `packages/browser-runner`, which ships INSIDE the published CLI.
@@ -92,15 +103,15 @@ export const LOCAL_APPLY_BLOCK_REASONS = [
  * not silently look equivalent to a current runner.
  *
  * A behaviour change in the runner is a CONTRACT change, because the cloud's decisions assume it.
- * So this floor moves with it: a machine that cannot observe a post-submit receipt is refused
- * with a sentence that says so, rather than reporting an unhelpful `submit_unconfirmed` state.
+ * So this floor moves with it: #1013's exact-page login/CAPTCHA handoff and post-submit receipt
+ * evidence are refused together rather than silently degrading to an unhelpful `submit_unconfirmed` state.
  *
  * Bump this when the runner's half of the contract changes again, together with the CLI version
  * that ships it — `policy.test.ts` pins the pair, so the floor cannot name a release that has not
  * been published. `cliAtLeast` treats an unreported version as capable, which is the convention
  * every MIN_CLI gate here follows.
  */
-export const LOCAL_APPLY_CONTRACT_MIN_CLI = "0.4.90";
+export const LOCAL_APPLY_CONTRACT_MIN_CLI = "0.4.96";
 export const LOCAL_APPLY_DIAGNOSTIC_CAUSES = ["bridge_unused", "engine_exited_nonzero", "timed_out", "no_engine_output", "submit_unconfirmed"];
 export const LOCAL_APPLY_CONFIRMATION_MARKERS = ["page_text", "url_receipt", "already_applied_notice"];
 export const LOCAL_APPLY_SIGNALS = [
@@ -140,6 +151,7 @@ export const LOCAL_APPLY_EVENT_TYPES = [
 export const LOCAL_APPLY_ENGINE_AUTHS = ["machine-login", "subscription", "api-key", "missing_login", "unknown"];
 export const LOCAL_APPLY_SUPERVISOR_DIRECTIVES = ["continue", "request_review", "stop"];
 export const LOCAL_APPLY_SUPERVISOR_PHASES = ["initial", "before_submit", "post_navigation", "uncertain"];
+export const LOCAL_APPLY_HANDOFF_TERMINAL_REASONS = ["unavailable", "profile_unavailable", "profile_mismatch", "page_lost", "expired", "run_ended", "runner_restarted"];
 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);

package/dist/browser-runner/local-apply/handoff-routes.js

@@ -0,0 +1,21 @@
+/**
+ * The local-apply takeover surface is separate from generic task takeover: every request carries
+ * the exact run/application/profile binding that the runtime verifies before it reaches a page.
+ */
+export async function routeLocalApplyHandoff(runtime, method, path, read) {
+    if (method !== "POST")
+        return undefined;
+    if (path === "/local-apply/handoff")
+        return runtime.handoff(await read());
+    if (path === "/local-apply/handoff-status")
+        return runtime.handoffStatus(await read());
+    if (path === "/local-apply/handoff/frame")
+        return runtime.handoffFrame(await read());
+    if (path === "/local-apply/handoff/input") {
+        await runtime.handoffInput(await read());
+        return { ok: true };
+    }
+    if (path === "/local-apply/handoff/end" || path === "/local-apply/handoff/resume")
+        return runtime.endHandoff(await read());
+    return undefined;
+}

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

@@ -0,0 +1,117 @@
+import { RunnerInputError } from "../errors.js";
+const SAFE_ID = /^[A-Za-z0-9_.:-]{1,300}$/;
+const HANDOFF_TTL_MS = 10 * 60 * 1000;
+/** Exact-page lifecycle only. It deliberately has no access to a bridge, browser credentials, or run output. */
+export class LocalApplyHandoffRuntime {
+    host;
+    constructor(host) {
+        this.host = host;
+    }
+    async handoff(raw) {
+        const request = this.parse(raw);
+        const run = this.host.get(request.runId);
+        this.assertBinding(run, request);
+        if (run.state === "ended")
+            return this.closed(run, request.handoffId, "run_ended");
+        if (run.handoff)
+            throw new RunnerInputError("A handoff already exists for this application run", 409);
+        if (!this.host.takeover)
+            return this.closed(run, request.handoffId, "unavailable");
+        try {
+            await this.host.takeover.open(request);
+        }
+        catch {
+            return this.closed(run, request.handoffId, "profile_unavailable");
+        }
+        run.handoff = { handoffId: request.handoffId, expiresAt: this.host.now() + (this.host.handoffTtlMs ?? HANDOFF_TTL_MS), state: "ready" };
+        return this.status(request);
+    }
+    async status(raw) {
+        const request = this.parse(raw);
+        const run = this.host.get(request.runId);
+        this.assertBinding(run, request);
+        if (run.state === "ended")
+            return this.closed(run, request.handoffId, "run_ended");
+        const handoff = run.handoff;
+        if (!handoff || handoff.handoffId !== request.handoffId)
+            return this.closed(run, request.handoffId, "unavailable");
+        if (handoff.state === "closed")
+            return this.response(run, handoff);
+        if (handoff.expiresAt <= this.host.now())
+            await this.close(run, "expired");
+        else if (!this.host.takeover || (await this.host.takeover.state(handoff.handoffId)) !== "ready")
+            await this.close(run, "page_lost");
+        return this.response(run, run.handoff);
+    }
+    async frame(raw) {
+        const { run, handoff } = await this.live(raw);
+        try {
+            return await this.host.takeover.frame(handoff.handoffId);
+        }
+        catch {
+            await this.close(run, "page_lost");
+            throw new RunnerInputError("The handoff page is no longer available", 409);
+        }
+    }
+    async input(raw) {
+        const o = raw && typeof raw === "object" ? raw : {};
+        const { run, handoff } = await this.live(o);
+        if (!o.input || typeof o.input !== "object")
+            throw new RunnerInputError("handoff input is required");
+        try {
+            await this.host.takeover.input(handoff.handoffId, o.input);
+        }
+        catch {
+            await this.close(run, "page_lost");
+            throw new RunnerInputError("The handoff page is no longer available", 409);
+        }
+    }
+    async end(raw) {
+        const request = this.parse(raw);
+        const run = this.host.get(request.runId);
+        this.assertBinding(run, request);
+        if (!run.handoff || run.handoff.handoffId !== request.handoffId)
+            return this.closed(run, request.handoffId, "unavailable");
+        await this.close(run, "unavailable");
+        return this.response(run, run.handoff);
+    }
+    parse(raw) {
+        const o = raw && typeof raw === "object" ? raw : {};
+        const handoffId = typeof o.handoffId === "string" ? o.handoffId : "";
+        const runId = typeof o.runId === "string" ? o.runId : "";
+        const applicationId = typeof o.applicationId === "string" ? o.applicationId : "";
+        const browserProfile = o.browserProfile === "default" || o.browserProfile === "isolated" ? o.browserProfile : null;
+        if (!SAFE_ID.test(handoffId) || !SAFE_ID.test(runId) || !SAFE_ID.test(applicationId) || !browserProfile)
+            throw new RunnerInputError("handoff needs opaque handoffId, runId, applicationId, and browserProfile");
+        return { handoffId, runId, applicationId, browserProfile };
+    }
+    assertBinding(run, request) {
+        if (run.envelope.applicationId !== request.applicationId || run.envelope.browserProfile !== request.browserProfile)
+            throw new RunnerInputError("The handoff does not match this application run", 403);
+    }
+    response(run, handoff) {
+        return { handoffId: handoff.handoffId, runId: run.envelope.runId, applicationId: run.envelope.applicationId, browserProfile: run.envelope.browserProfile, state: handoff.state, expiresAt: new Date(handoff.expiresAt).toISOString(), ...(handoff.terminalReason ? { terminalReason: handoff.terminalReason } : {}) };
+    }
+    closed(run, handoffId, terminalReason) {
+        const handoff = { handoffId, expiresAt: this.host.now(), state: "closed", terminalReason };
+        if (run.handoff?.handoffId === handoffId)
+            run.handoff = handoff;
+        return this.response(run, handoff);
+    }
+    async close(run, reason) {
+        const handoff = run.handoff;
+        if (!handoff || handoff.state === "closed")
+            return;
+        handoff.state = "closed";
+        handoff.terminalReason = reason;
+        if (this.host.takeover)
+            await this.host.takeover.end(handoff.handoffId).catch(() => undefined);
+    }
+    async live(raw) {
+        const status = await this.status(raw);
+        if (status.state !== "ready")
+            throw new RunnerInputError(`The handoff is closed (${status.terminalReason ?? "unavailable"})`, 409);
+        const run = this.host.get(status.runId);
+        return { run, handoff: run.handoff };
+    }
+}

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

@@ -37,6 +37,7 @@ import { ApplyBridge } from "./bridge.js";
 import { confirmationSignals } from "./confirmation.js";
 import { LOCAL_APPLY_AUTH_MODES, LOCAL_APPLY_CAPS, LOCAL_APPLY_ENGINES, LOCAL_APPLY_MODES, LOCAL_APPLY_TASK_TYPE, parseLocalApplyResult, } from "./contract.js";
 import { applyPrompt, buildApplyEngineSpec, observedApplyAuth } from "./engine.js";
+import { LocalApplyHandoffRuntime } from "./runtime-handoff.js";
 const MAX_EVENTS = 1000;
 const OUTPUT_LINES = 400;
 const SOURCE_BYTES = 256 * 1024;
@@ -169,6 +170,7 @@ function bridgeUnusedHelp(engine, d) {
 export class LocalApplyRuntime {
     deps;
     runs = new Map();
+    handoffs;
     /** Application fills that a restart would lose (#896) — their state is in this process. */
     liveWork() {
         return [...this.runs.values()].filter((r) => r.state !== "ended").map((r) => `an application fill (${r.envelope.applicationId.slice(0, 8)})`);
@@ -183,6 +185,7 @@ export class LocalApplyRuntime {
         this.now = deps.now ?? Date.now;
         this.spawn = deps.spawn ?? nodeSpawn;
         this.retentionMs = deps.retentionMs ?? 24 * 60 * 60 * 1000;
+        this.handoffs = new LocalApplyHandoffRuntime({ get: (runId) => this.get(runId), now: this.now, takeover: deps.takeover, handoffTtlMs: deps.handoffTtlMs });
         this.hydrateTerminalJournals();
     }
     /**
@@ -650,6 +653,12 @@ export class LocalApplyRuntime {
             ...(run.result ? { result: run.result } : {}),
         };
     }
+    /** A takeover only views the exact live page; it never authorizes the paused bridge. */
+    async handoff(raw) { return this.handoffs.handoff(raw); }
+    async handoffStatus(raw) { return this.handoffs.status(raw); }
+    async handoffFrame(raw) { return this.handoffs.frame(raw); }
+    async handoffInput(raw) { return this.handoffs.input(raw); }
+    async endHandoff(raw) { return this.handoffs.end(raw); }
     /** Does this token belong to this run? The bridge forwarder's only credential. */
     authorizeBridge(runId, token) {
         const run = this.runs.get(runId);
@@ -689,6 +698,10 @@ export class LocalApplyRuntime {
     end(run, r) {
         if (run.state === "ended")
             return;
+        // A terminal application outcome never means that a handoff succeeded.  Tear down only the
+        // live view and retain the explicit closed state for a caller that polls before restart.
+        if (run.handoff?.state === "ready")
+            void this.handoffs.close(run, "run_ended");
         if (run.state === "paused")
             this.release(run, "stopped");
         if (run.timer)

package/dist/browser-runner/local-apply/takeover-adapter.js

@@ -0,0 +1,28 @@
+import { RunnerInputError } from "../errors.js";
+const prefix = "local-apply:";
+export function isLocalApplyTakeover(id) { return id.startsWith(prefix); }
+/** Attach the bounded local-apply view to the runner's existing live-page takeover machinery. */
+export function createLocalApplyTakeoverAdapter(deps) {
+    const key = (handoffId) => `${prefix}${handoffId}`;
+    return {
+        async open(request) {
+            if (request.browserProfile !== "default")
+                throw new RunnerInputError("This browser profile has no live handoff page", 409);
+            const id = key(request.handoffId);
+            if (deps.get(id))
+                throw new RunnerInputError("A local application handoff already exists", 409);
+            // Do not create a page here: a destroyed page must remain a lost handoff, never look ready.
+            const page = deps.activePage();
+            if (!page || page.isClosed())
+                throw new RunnerInputError("The local application page is no longer available", 409);
+            deps.set(id, page);
+        },
+        async state(handoffId) {
+            const session = deps.get(key(handoffId));
+            return session && !session.page.isClosed() ? "ready" : "page_lost";
+        },
+        frame: (handoffId) => deps.frame(key(handoffId)),
+        input: (handoffId, input) => deps.input(key(handoffId), input),
+        end: (handoffId) => deps.end(key(handoffId)),
+    };
+}

package/dist/browser-runner/runner.js

@@ -18,6 +18,7 @@ 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 { createLocalApplyTakeoverAdapter, isLocalApplyTakeover } from "./local-apply/takeover-adapter.js";
 import { WORKFLOW_DRIVEN_TASKS } from "./task-types.js";
 /** True for a plain object. */
 function isRecord(value) {
@@ -105,7 +106,12 @@ export class LocalRunner {
         };
         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 });
+        this.localApply = new LocalApplyRuntime({
+            dataDir: config.dataDir,
+            selfUrl: () => this.selfUrl,
+            browserFor,
+            takeover: createLocalApplyTakeoverAdapter({ activePage: () => this.activePage, get: (id) => this.takeovers.get(id), set: (id, page) => this.takeovers.set(id, { page, reason: "local_apply", humanDone: false }), frame: (id) => this.takeoverFrame(id), input: (id, input) => this.takeoverInput(id, input), end: (id) => this.endTakeover(id) }),
+        });
         // 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();
@@ -365,7 +371,7 @@ export class LocalRunner {
     }
     /** Active human-takeover task ids (for status/discovery). */
     listTakeovers() {
-        return [...this.takeovers.keys()];
+        return [...this.takeovers.keys()].filter((id) => !isLocalApplyTakeover(id));
     }
     requireTakeover(taskId) {
         const session = this.takeovers.get(taskId);

package/dist/browser-runner/server.js

@@ -4,6 +4,7 @@ import { LocalRunner, RunnerInputError } from "./runner.js";
 import { probeGitSshIdentity } from "./coding/repo.js";
 import { checkEngine } from "./coding/engine-check.js";
 import { listGithubOrgs, listGithubRepos, searchGithubRepos, getGithubRepoDetail, getGithubCredentialScope } from "./coding/github-browse.js";
+import { routeLocalApplyHandoff } from "./local-apply/handoff-routes.js";
 export function createRunnerServer(runner) {
     return createServer(async (req, res) => {
         try {
@@ -226,7 +227,6 @@ async function route(runner, req, res) {
         return json(res, 200, runner.localArtifact.cancel(await readJson(req)));
     }
     // Local application execution (#957) — run, status, resume, cancel; PULL like research.
-    // The email-lead preflight is read-only and precedes Tailor material generation (#953).
     if (req.method === "POST" && path === "/local-apply/preflight") {
         return json(res, 200, await runner.localApply.preflight(await readJson(req)));
     }
@@ -236,6 +236,9 @@ async function route(runner, req, res) {
     if (req.method === "POST" && path === "/local-apply/status") {
         return json(res, 200, runner.localApply.status(await readJson(req)));
     }
+    const handoff = await routeLocalApplyHandoff(runner.localApply, req.method, path, () => readJson(req));
+    if (handoff)
+        return json(res, 200, handoff);
     if (req.method === "POST" && path === "/local-apply/resume") {
         return json(res, 200, runner.localApply.resume(await readJson(req)));
     }

package/dist/index.js

@@ -1875,8 +1875,7 @@ var RelayMutationAdmission = class {
   }
 };
 
-// src/commands/runner/relay.ts
-var MEMBERSHIP_SYNC_PATH = "/pags/membership/sync";
+// src/commands/runner/runner-work-observation.ts
 function observedRunnerWork(observation) {
   const sessions = observation.sessions;
   const work = observation.work;
@@ -1900,6 +1899,9 @@ function observedRunnerWork(observation) {
     ...Array.from({ length: localRuns }, (_v, i) => localDetail[i] || `local-run-${i + 1}`)
   ];
 }
+
+// src/commands/runner/relay.ts
+var MEMBERSHIP_SYNC_PATH = "/pags/membership/sync";
 var CLI_CONTROL_PATHS = /* @__PURE__ */ new Set([MEMBERSHIP_SYNC_PATH, RUNNER_UPDATE_PATH]);
 async function connectViaRelay(instanceIds, localUrl, runnerToken, opts, force = false, watchInstances = false) {
   const apiBase = pagsApiBase(opts.apiBase).replace(/^http/, "ws");

package/package.json

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