pi-agent-browser-native 0.2.72 → 0.2.74

package/dist/extensions/agent-browser/lib/command-taxonomy.js

@@ -81,6 +81,12 @@ const COMMAND_CAPABILITIES = [
         command: "errors",
         readOnlyDiagnosticSessionTarget: true,
     },
+    {
+        command: "eval",
+        invalidatesBatchRefs: true,
+        navigationObservable: true,
+        triggersPostMutationSnapshot: true,
+    },
     {
         command: "fill",
         eligibleForElectronHealthProbe: true,
@@ -305,6 +311,11 @@ export function isElectronPostCommandHealthCommand(command) {
 export function isNavigationObservableCommandName(command) {
     return hasCommandCapability(command, "navigationObservable");
 }
+export function isUnverifiedPageTransitionCommand(command, subcommand) {
+    return ["back", "connect", "eval", "forward", "reload"].includes(command ?? "")
+        || (command === "state" && subcommand === "load")
+        || (command === "tab" && subcommand !== undefined && !["list", "new"].includes(subcommand));
+}
 export function isPageMutationCommand(command) {
     return hasCommandCapability(command, "triggersPostMutationSnapshot");
 }

package/dist/extensions/agent-browser/lib/electron/cdp.js

@@ -33,11 +33,11 @@ export function parseCdpTargets(value) {
         webSocketDebuggerUrl: asString(target.webSocketDebuggerUrl),
     }));
 }
-export async function fetchCdpJson(url) {
+export async function fetchCdpJson(url, signal) {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), ELECTRON_CDP_FETCH_TIMEOUT_MS);
     try {
-        const response = await fetch(url, { signal: controller.signal });
+        const response = await fetch(url, { signal: signal ? AbortSignal.any([signal, controller.signal]) : controller.signal });
         if (!response.ok)
             return undefined;
         return await response.json();

package/dist/extensions/agent-browser/lib/electron/launch.js

@@ -3,7 +3,7 @@
  * Responsibilities: Resolve Electron targets, enforce caller-owned allow/deny policy, create isolated userDataDir profiles, launch with remote debugging on an OS-chosen port, poll DevToolsActivePort, and read bounded CDP version/target metadata.
  * Scope: Host-side Electron lifecycle setup only; upstream agent-browser attach/presentation stays in the extension entrypoint.
  * Usage: Called by the agent_browser electron.launch shorthand before routing through upstream `connect`.
- * Invariants/Assumptions: The wrapper only launches targets with Electron framework evidence, always uses an isolated temp profile, and never accepts a caller-supplied remote debugging port.
+ * Invariants/Assumptions: The wrapper only launches targets with Electron framework evidence, always uses an isolated temp profile, never accepts a caller-supplied remote debugging port, and cleans any spawned process/profile when cancellation interrupts readiness.
  */
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
@@ -24,8 +24,18 @@ function normalizeTimeoutMs(timeoutMs) {
         return ELECTRON_LAUNCH_DEFAULT_TIMEOUT_MS;
     return Math.min(timeoutMs, ELECTRON_LAUNCH_MAX_TIMEOUT_MS);
 }
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+function sleep(ms, signal) {
+    if (signal?.aborted)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const timer = setTimeout(done, ms);
+        function done() {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", done);
+            resolve();
+        }
+        signal?.addEventListener("abort", done, { once: true });
+    });
 }
 function normalizeIdentifier(value) {
     const trimmed = value?.trim().toLowerCase();
@@ -110,6 +120,8 @@ async function readDevToolsActivePort(userDataDir) {
 async function pollDevToolsActivePort(options) {
     let devToolsActivePort;
     while (Date.now() <= options.deadlineMs) {
+        if (options.signal?.aborted)
+            return { devToolsActivePort, failure: "aborted" };
         const spawnError = options.getSpawnError();
         if (spawnError)
             return { devToolsActivePort, failure: "spawn-error", spawnError };
@@ -120,20 +132,24 @@ async function pollDevToolsActivePort(options) {
         if (exit.code !== null || exit.signal !== null) {
             return { devToolsActivePort, failure: exit.code === 0 ? "single-instance-conflict" : "spawn-error" };
         }
-        await sleep(ELECTRON_DEVTOOLS_POLL_INTERVAL_MS);
+        await sleep(ELECTRON_DEVTOOLS_POLL_INTERVAL_MS, options.signal);
     }
     return { devToolsActivePort, failure: "timeout" };
 }
-async function pollCdpMetadata(port, deadlineMs) {
+async function pollCdpMetadata(port, deadlineMs, signal) {
     while (Date.now() <= deadlineMs) {
-        const version = parseCdpVersion(await fetchCdpJson(`http://127.0.0.1:${port}/json/version`));
+        if (signal?.aborted)
+            return { aborted: true };
+        const version = parseCdpVersion(await fetchCdpJson(`http://127.0.0.1:${port}/json/version`, signal));
+        if (signal?.aborted)
+            return { aborted: true };
         if (version) {
-            const targets = parseCdpTargets(await fetchCdpJson(`http://127.0.0.1:${port}/json/list`));
-            return { targets, version };
+            const targets = parseCdpTargets(await fetchCdpJson(`http://127.0.0.1:${port}/json/list`, signal));
+            return signal?.aborted ? { aborted: true } : { aborted: false, metadata: { targets, version } };
         }
-        await sleep(ELECTRON_DEVTOOLS_POLL_INTERVAL_MS);
+        await sleep(ELECTRON_DEVTOOLS_POLL_INTERVAL_MS, signal);
     }
-    return undefined;
+    return { aborted: false };
 }
 function buildLaunchArgs(userDataDir, appArgs) {
     return [
@@ -210,6 +226,8 @@ function buildLaunchRecord(options) {
 function launchFailureMessage(reason, target, detail) {
     const label = target ? `${target.name} (${target.appPath ?? target.executablePath})` : "target";
     switch (reason) {
+        case "aborted":
+            return `Electron launch was aborted${target ? ` before ${label} finished starting` : " before the app started"}.`;
         case "non-electron-target":
             return `Electron launch rejected: ${label} does not have Electron framework evidence.`;
         case "policy-blocked":
@@ -226,7 +244,11 @@ function launchFailureMessage(reason, target, detail) {
 }
 export async function launchElectronApp(options) {
     const appArgs = options.appArgs ?? [];
+    if (options.signal?.aborted)
+        return { ok: false, failure: { appArgs, error: launchFailureMessage("aborted", undefined), reason: "aborted" } };
     const target = await resolveElectronLaunchTarget(options);
+    if (options.signal?.aborted)
+        return { ok: false, failure: { appArgs, error: launchFailureMessage("aborted", target), reason: "aborted", target } };
     if (!target) {
         return {
             ok: false,
@@ -254,6 +276,16 @@ export async function launchElectronApp(options) {
     const startedAtMs = Date.now();
     const deadlineMs = startedAtMs + timeoutMs;
     const userDataDir = await createSecureTempDirectory(ELECTRON_PROFILE_DIR_PREFIX);
+    if (options.signal?.aborted) {
+        let cleanupError;
+        try {
+            await rm(userDataDir, { force: true, recursive: true });
+        }
+        catch (error) {
+            cleanupError = error instanceof Error ? error.message : String(error);
+        }
+        return { ok: false, failure: { appArgs, cleanupError, error: launchFailureMessage("aborted", target), reason: "aborted", target, userDataDir } };
+    }
     let cleanupError;
     let spawnError;
     let exitCode = null;
@@ -312,15 +344,19 @@ export async function launchElectronApp(options) {
         deadlineMs,
         getChildExit: () => ({ code: exitCode, signal: exitSignal }),
         getSpawnError: () => spawnError,
+        signal: options.signal,
         userDataDir,
     });
     if (!portResult.port) {
         return fail(portResult.failure ?? "timeout", portResult.spawnError?.message, { devToolsActivePort: portResult.devToolsActivePort });
     }
-    const metadata = await pollCdpMetadata(portResult.port, deadlineMs);
-    if (!metadata) {
+    const metadataResult = await pollCdpMetadata(portResult.port, deadlineMs, options.signal);
+    if (metadataResult.aborted)
+        return fail("aborted", undefined, { devToolsActivePort: portResult.devToolsActivePort, port: portResult.port });
+    if (!metadataResult.metadata) {
         return fail("port-not-found", undefined, { cdpVersionReached: false, devToolsActivePort: portResult.devToolsActivePort, port: portResult.port });
     }
+    const metadata = metadataResult.metadata;
     const record = buildLaunchRecord({
         createdAtMs: Date.now(),
         pid: child.pid,

package/dist/extensions/agent-browser/lib/input-modes/params.js

@@ -7,138 +7,136 @@ import { JsonSchema } from "../json-schema.js";
 import { StringEnum as localStringEnum } from "../string-enum-schema.js";
 import { ELECTRON_DISCOVERY_DEFAULT_MAX_RESULTS, ELECTRON_DISCOVERY_MAX_RESULTS, } from "../electron/discovery.js";
 import { AGENT_BROWSER_ELECTRON_HANDOFFS, AGENT_BROWSER_ELECTRON_TARGET_TYPES, AGENT_BROWSER_JOB_STEP_ACTIONS, AGENT_BROWSER_JOB_TYPE_DELAYED_TEXT_MAX_CHARACTERS, AGENT_BROWSER_QA_LOAD_STATES, AGENT_BROWSER_SEMANTIC_ACTIONS, AGENT_BROWSER_SEMANTIC_LOCATORS, DEFAULT_SESSION_MODE, SOURCE_LOOKUP_MAX_WORKSPACE_FILES, } from "./types.js";
+// Keep descriptions terse: Pi sends this schema every turn; workflows belong in prompt guidance and docs.
 // ponytail: the four electron.launch variants differ only in their single target field
-// (appPath/appName/bundleId/executablePath); the action literal and the shared optional
-// launch fields are identical, so a helper keeps the duplicate schema blocks in sync.
+// (appPath/appName/bundleId/executablePath); the action literal and shared launch fields
+// are identical, so this helper keeps the schema variants in sync.
 function electronLaunchVariant(Type, StringEnum, targetField) {
     return Type.Object({
-        action: StringEnum(["launch"], { description: "Launch an Electron app with an isolated wrapper-owned profile." }),
+        action: StringEnum(["launch"]),
         ...targetField,
-        appArgs: Type.Optional(Type.Array(Type.String({ description: "Argument passed to the Electron application.", minLength: 1 }), { description: "Optional Electron app argv. Wrapper-owned lifecycle/debug flags are rejected." })),
-        handoff: Type.Optional(StringEnum(AGENT_BROWSER_ELECTRON_HANDOFFS, { description: "Post-launch handoff depth. Defaults to snapshot." })),
-        targetType: Type.Optional(StringEnum(AGENT_BROWSER_ELECTRON_TARGET_TYPES, { description: "Preferred CDP target type. Defaults to page." })),
-        timeoutMs: Type.Optional(Type.Integer({ description: "Bounded launch timeout in milliseconds.", minimum: 1 })),
-        allow: Type.Optional(Type.Array(Type.String({ description: "App identifier allowed by the caller for electron.launch.", minLength: 1 }), { description: "Optional caller-owned allow list for electron.launch policy checks." })),
-        deny: Type.Optional(Type.Array(Type.String({ description: "App identifier denied by the caller for electron.launch.", minLength: 1 }), { description: "Optional caller-owned deny list for electron.launch policy checks; deny wins over allow." })),
+        appArgs: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+        handoff: Type.Optional(StringEnum(AGENT_BROWSER_ELECTRON_HANDOFFS)),
+        targetType: Type.Optional(StringEnum(AGENT_BROWSER_ELECTRON_TARGET_TYPES)),
+        timeoutMs: Type.Optional(Type.Integer({ minimum: 1 })),
+        allow: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+        deny: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
     }, { additionalProperties: false });
 }
 export function createAgentBrowserParamsSchema(Type = JsonSchema, StringEnum = localStringEnum) {
     return Type.Object({
-        args: Type.Optional(Type.Array(Type.String({ description: "Exact agent-browser CLI arguments, excluding the binary name. Do not pass --json; the wrapper injects it. First-call recipe: open → snapshot -i → click/fill @eN → snapshot -i." }), {
-            description: "Exact agent-browser CLI arguments, excluding the binary name and any shell operators. Required unless semanticAction, job, qa, sourceLookup, networkSourceLookup, or electron is provided. Do not include --json (wrapper injects it). Typical first calls: open, snapshot -i, click/fill current @refs, then snapshot -i again after navigation or DOM changes.",
+        args: Type.Optional(Type.Array(Type.String(), {
+            description: "Raw agent-browser argv only: no binary, shell operators, or --json. Start with open → snapshot -i → act on current @refs; re-snapshot after page changes.",
             minItems: 1,
         })),
         semanticAction: Type.Optional(Type.Object({
-            action: StringEnum(AGENT_BROWSER_SEMANTIC_ACTIONS, {
-                description: "Intent action to compile to an existing agent-browser find command, direct selector/ref command, or upstream select when action=select.",
-            }),
-            locator: Type.Optional(StringEnum(AGENT_BROWSER_SEMANTIC_LOCATORS, {
-                description: "Upstream find locator family to use for check/click/fill actions.",
-            })),
-            value: Type.Optional(Type.String({ description: "Locator value for find actions, or a single option value for select actions. For locator=role, role may be supplied instead." })),
-            values: Type.Optional(Type.Array(Type.String({ description: "Option value for select actions." }), { description: "One or more option values for select actions.", minItems: 1 })),
-            selector: Type.Optional(Type.String({ description: "Selector or @ref for direct click/check/fill actions, or for select actions compiled to select <selector> <value...>." })),
-            text: Type.Optional(Type.String({ description: "Text/value argument for fill actions." })),
-            role: Type.Optional(Type.String({ description: "Role locator value for locator=role. May be used instead of value; when both are set they must match." })),
-            name: Type.Optional(Type.String({ description: "Accessible name filter for locator=role; compiles to --name <name>." })),
-            session: Type.Optional(Type.String({ description: "Optional upstream session name; prepends --session <name> before the compiled command." })),
-        }, { additionalProperties: false })),
+            action: StringEnum(AGENT_BROWSER_SEMANTIC_ACTIONS),
+            locator: Type.Optional(StringEnum(AGENT_BROWSER_SEMANTIC_LOCATORS, { description: "Locator for check/click/fill." })),
+            value: Type.Optional(Type.String({ description: "Locator value, or one select option." })),
+            values: Type.Optional(Type.Array(Type.String(), { description: "Select options.", minItems: 1 })),
+            selector: Type.Optional(Type.String({ description: "Direct selector or @ref." })),
+            text: Type.Optional(Type.String({ description: "Fill text." })),
+            role: Type.Optional(Type.String({ description: "Role locator; alternative to value." })),
+            name: Type.Optional(Type.String({ description: "Accessible name." })),
+            session: Type.Optional(Type.String({ description: "Upstream session name." })),
+        }, { additionalProperties: false, description: "Stable locator or direct-selector action." })),
         qa: Type.Optional(Type.Union([
             Type.Object({
-                attached: Type.Literal(true, { description: "Run the QA preset against the currently attached session instead of opening qa.url." }),
-                expectedText: Type.Optional(Type.Union([Type.String(), Type.Array(Type.String())], { description: "Text that must appear on the page." })),
-                expectedSelector: Type.Optional(Type.String({ description: "Selector or @ref that must appear on the page." })),
-                screenshotPath: Type.Optional(Type.String({ description: "Optional evidence screenshot path captured at the end of the QA preset." })),
-                checkConsole: Type.Optional(Type.Boolean({ description: "Whether to inspect console messages and fail on console errors. Defaults to false for qa.attached because upstream buffers may predate the check." })),
-                checkErrors: Type.Optional(Type.Boolean({ description: "Whether to inspect page errors and fail when errors are present. Defaults to false for qa.attached because upstream buffers may predate the check." })),
-                checkNetwork: Type.Optional(Type.Boolean({ description: "Whether to inspect network requests and fail on actionable request failures; benign icon misses warn. Defaults to false for qa.attached because upstream buffers may predate the check." })),
-                loadState: Type.Optional(StringEnum(AGENT_BROWSER_QA_LOAD_STATES, { description: "Page readiness state for the QA preset before assertions and diagnostics. Defaults to domcontentloaded; use networkidle only for pages without long-lived background requests." })),
+                attached: Type.Literal(true),
+                expectedText: Type.Optional(Type.Union([Type.String(), Type.Array(Type.String())])),
+                expectedSelector: Type.Optional(Type.String()),
+                screenshotPath: Type.Optional(Type.String()),
+                checkConsole: Type.Optional(Type.Boolean()),
+                checkErrors: Type.Optional(Type.Boolean()),
+                checkNetwork: Type.Optional(Type.Boolean()),
+                loadState: Type.Optional(StringEnum(AGENT_BROWSER_QA_LOAD_STATES)),
             }, { additionalProperties: false }),
             Type.Object({
-                url: Type.String({ description: "URL to open for a lightweight QA preset." }),
-                attached: Type.Optional(Type.Literal(false, { description: "When omitted or false, qa.url is required and opened before checks." })),
-                expectedText: Type.Optional(Type.Union([Type.String(), Type.Array(Type.String())], { description: "Text that must appear on the page." })),
-                expectedSelector: Type.Optional(Type.String({ description: "Selector or @ref that must appear on the page." })),
-                screenshotPath: Type.Optional(Type.String({ description: "Optional evidence screenshot path captured at the end of the QA preset." })),
-                checkConsole: Type.Optional(Type.Boolean({ description: "Whether to fail on console error messages. Defaults to true." })),
-                checkErrors: Type.Optional(Type.Boolean({ description: "Whether to fail on page errors. Defaults to true." })),
-                checkNetwork: Type.Optional(Type.Boolean({ description: "Whether to inspect network requests and fail on actionable request failures; benign icon misses warn. Defaults to true." })),
-                loadState: Type.Optional(StringEnum(AGENT_BROWSER_QA_LOAD_STATES, { description: "Page readiness state for the QA preset before assertions and diagnostics. Defaults to domcontentloaded; use networkidle only for pages without long-lived background requests." })),
+                url: Type.String(),
+                attached: Type.Optional(Type.Literal(false)),
+                expectedText: Type.Optional(Type.Union([Type.String(), Type.Array(Type.String())])),
+                expectedSelector: Type.Optional(Type.String()),
+                screenshotPath: Type.Optional(Type.String()),
+                checkConsole: Type.Optional(Type.Boolean()),
+                checkErrors: Type.Optional(Type.Boolean()),
+                checkNetwork: Type.Optional(Type.Boolean()),
+                loadState: Type.Optional(StringEnum(AGENT_BROWSER_QA_LOAD_STATES)),
             }, { additionalProperties: false }),
-        ], { description: "Lightweight QA preset. Use qa.url to open a URL, or qa.attached=true to check the current attached session without opening a URL." })),
+        ], { description: "QA a URL or current session (attached=true). Default readiness: domcontentloaded; use networkidle only without long-lived requests. URL diagnostics default on, attached diagnostics off." })),
         sourceLookup: Type.Optional(Type.Object({
-            selector: Type.Optional(Type.String({ description: "Visible selector or @ref whose DOM metadata should be inspected for source hints." })),
-            reactFiberId: Type.Optional(Type.String({ description: "React fiber id to inspect with upstream react inspect. Requires a session opened with --enable react-devtools." })),
-            componentName: Type.Optional(Type.String({ description: "Component name to correlate with react tree output and bounded local workspace search." })),
-            includeDomHints: Type.Optional(Type.Boolean({ description: "Whether selector lookups should inspect DOM HTML attributes for source-like metadata. Defaults to true." })),
-            maxWorkspaceFiles: Type.Optional(Type.Number({ description: "Maximum local source files to scan when componentName is provided. Defaults to 2000 and cannot exceed 5000.", minimum: 1, maximum: SOURCE_LOOKUP_MAX_WORKSPACE_FILES })),
-        }, { additionalProperties: false, description: "EXPERIMENTAL: local UI-to-source candidates only (confidence/evidence, not guaranteed mappings). Compiles to batch; mutually exclusive with other input modes." })),
+            selector: Type.Optional(Type.String({ description: "Visible selector or @ref." })),
+            reactFiberId: Type.Optional(Type.String({ description: "React fiber id; requires --enable react-devtools." })),
+            componentName: Type.Optional(Type.String({ description: "Component for local source search." })),
+            includeDomHints: Type.Optional(Type.Boolean({ description: "Inspect DOM source hints; default true." })),
+            maxWorkspaceFiles: Type.Optional(Type.Number({ description: "Source scan cap; default 2000.", minimum: 1, maximum: SOURCE_LOOKUP_MAX_WORKSPACE_FILES })),
+        }, { additionalProperties: false, description: "EXPERIMENTAL UI-to-source candidates; not guaranteed mappings." })),
         networkSourceLookup: Type.Optional(Type.Object({
-            filter: Type.Optional(Type.String({ description: "Optional upstream network requests filter pattern." })),
-            namespace: Type.Optional(Type.String({ description: "Optional upstream namespace; prepends --namespace <name> before the generated batch." })),
-            requestId: Type.Optional(Type.String({ description: "Optional network request id to inspect with network request <id>." })),
-            session: Type.Optional(Type.String({ description: "Optional upstream session name; prepends --session <name> before the generated batch." })),
-            url: Type.Optional(Type.String({ description: "Optional failed request URL or URL fragment to correlate with local source." })),
-            maxWorkspaceFiles: Type.Optional(Type.Number({ description: "Maximum local source files to scan for URL literals. Defaults to 2000 and cannot exceed 5000.", minimum: 1, maximum: SOURCE_LOOKUP_MAX_WORKSPACE_FILES })),
-        }, { additionalProperties: false, description: "EXPERIMENTAL: failed-request-to-source candidates only (initiator metadata and bounded workspace URL literals; not definitive blame). Compiles to batch; mutually exclusive with other input modes." })),
+            filter: Type.Optional(Type.String({ description: "Network request filter." })),
+            namespace: Type.Optional(Type.String()),
+            requestId: Type.Optional(Type.String({ description: "Request id to inspect." })),
+            session: Type.Optional(Type.String()),
+            url: Type.Optional(Type.String({ description: "Failed URL or fragment." })),
+            maxWorkspaceFiles: Type.Optional(Type.Number({ description: "Source scan cap; default 2000.", minimum: 1, maximum: SOURCE_LOOKUP_MAX_WORKSPACE_FILES })),
+        }, { additionalProperties: false, description: "EXPERIMENTAL failed-request-to-source candidates; not proof." })),
         electron: Type.Optional(Type.Union([
             Type.Object({
-                action: StringEnum(["list"], { description: "List discovered Electron apps." }),
-                query: Type.Optional(Type.String({ description: "Optional case-insensitive substring filter for electron.list across app name, bundle id, desktop id, and paths.", minLength: 1 })),
-                maxResults: Type.Optional(Type.Integer({ description: `Maximum electron.list apps to return. Defaults to ${ELECTRON_DISCOVERY_DEFAULT_MAX_RESULTS}; values above ${ELECTRON_DISCOVERY_MAX_RESULTS} are clamped.`, minimum: 1 })),
+                action: StringEnum(["list"]),
+                query: Type.Optional(Type.String({ description: "Case-insensitive app filter.", minLength: 1 })),
+                maxResults: Type.Optional(Type.Integer({ description: `Result cap; default ${ELECTRON_DISCOVERY_DEFAULT_MAX_RESULTS}, values over ${ELECTRON_DISCOVERY_MAX_RESULTS} are clamped.`, minimum: 1 })),
             }, { additionalProperties: false }),
-            electronLaunchVariant(Type, StringEnum, { appPath: Type.String({ description: "Electron launch target: macOS .app bundle path. Exactly one launch target is required for electron.launch.", minLength: 1 }) }),
-            electronLaunchVariant(Type, StringEnum, { appName: Type.String({ description: "Electron launch target: app display name discovered by electron.list. Exactly one launch target is required for electron.launch.", minLength: 1 }) }),
-            electronLaunchVariant(Type, StringEnum, { bundleId: Type.String({ description: "Electron launch target: macOS bundle identifier discovered by electron.list. Exactly one launch target is required for electron.launch.", minLength: 1 }) }),
-            electronLaunchVariant(Type, StringEnum, { executablePath: Type.String({ description: "Electron launch target: executable path. Discovery is not required when this is provided. Exactly one launch target is required for electron.launch.", minLength: 1 }) }),
+            electronLaunchVariant(Type, StringEnum, { appPath: Type.String({ description: "macOS .app path.", minLength: 1 }) }),
+            electronLaunchVariant(Type, StringEnum, { appName: Type.String({ description: "Name from electron.list.", minLength: 1 }) }),
+            electronLaunchVariant(Type, StringEnum, { bundleId: Type.String({ description: "Bundle id from electron.list.", minLength: 1 }) }),
+            electronLaunchVariant(Type, StringEnum, { executablePath: Type.String({ description: "Executable path.", minLength: 1 }) }),
             Type.Object({
-                action: StringEnum(["status", "cleanup"], { description: "Inspect or cleanup one wrapper-tracked Electron launch by launchId." }),
-                launchId: Type.String({ description: "Wrapper launch id for electron.status and electron.cleanup.", minLength: 1 }),
-                timeoutMs: Type.Optional(Type.Integer({ description: "Bounded status/cleanup timeout in milliseconds.", minimum: 1 })),
+                action: StringEnum(["status", "cleanup"]),
+                launchId: Type.String({ description: "Tracked launch id.", minLength: 1 }),
+                timeoutMs: Type.Optional(Type.Integer({ minimum: 1 })),
             }, { additionalProperties: false }),
             Type.Object({
-                action: StringEnum(["status", "cleanup"], { description: "Inspect or cleanup all wrapper-tracked Electron launches." }),
-                all: Type.Literal(true, { description: "Apply electron.status or electron.cleanup to all wrapper-owned launches." }),
-                timeoutMs: Type.Optional(Type.Integer({ description: "Bounded status/cleanup timeout in milliseconds.", minimum: 1 })),
+                action: StringEnum(["status", "cleanup"]),
+                all: Type.Literal(true),
+                timeoutMs: Type.Optional(Type.Integer({ minimum: 1 })),
             }, { additionalProperties: false }),
             Type.Object({
-                action: StringEnum(["status", "cleanup"], { description: "Inspect or cleanup the only active wrapper-tracked Electron launch." }),
-                timeoutMs: Type.Optional(Type.Integer({ description: "Bounded status/cleanup timeout in milliseconds.", minimum: 1 })),
+                action: StringEnum(["status", "cleanup"]),
+                timeoutMs: Type.Optional(Type.Integer({ minimum: 1 })),
             }, { additionalProperties: false }),
             Type.Object({
-                action: StringEnum(["probe"], { description: "Probe the current attached Electron managed session; launchId is accepted for launch-scoped follow-up actions." }),
-                launchId: Type.Optional(Type.String({ description: "Wrapper launch id for electron.probe follow-up targeting.", minLength: 1 })),
-                timeoutMs: Type.Optional(Type.Integer({ description: "Bounded probe timeout in milliseconds.", minimum: 1 })),
+                action: StringEnum(["probe"]),
+                launchId: Type.Optional(Type.String({ description: "Tracked launch id.", minLength: 1 })),
+                timeoutMs: Type.Optional(Type.Integer({ minimum: 1 })),
             }, { additionalProperties: false }),
-        ], { description: "Electron wrapper action. Fields are action-specific and unsupported fields are rejected." })),
+        ], { description: "Electron discovery, isolated-profile launch, status, probe, or cleanup. Launch defaults: handoff=snapshot, targetType=page; deny wins over allow; lifecycle/debug appArgs rejected." })),
         job: Type.Optional(Type.Object({
-            failFast: Type.Optional(Type.Boolean({ description: "Stop the compiled batch on the first failed job step. Defaults to true so later mutating steps do not run after setup/assertion failures." })),
+            failFast: Type.Optional(Type.Boolean({ description: "Stop on first failure; default true." })),
             steps: Type.Array(Type.Object({
-                action: StringEnum(AGENT_BROWSER_JOB_STEP_ACTIONS, {
-                    description: "Constrained one-call job step compiled to existing upstream batch commands.",
-                }),
-                url: Type.Optional(Type.String({ description: "URL for open steps; exact URL or * / ** glob-style URL pattern for assertUrl steps." })),
-                loadState: Type.Optional(StringEnum(AGENT_BROWSER_QA_LOAD_STATES, { description: "Optional readiness wait to insert immediately after an open step; use domcontentloaded/load/networkidle when the next job step needs page hydration evidence before clicking or reading." })),
-                selector: Type.Optional(Type.String({ description: "Selector or @ref for click/fill/type/select-like steps; omit when using semantic locator fields on click/fill steps." })),
-                locator: Type.Optional(StringEnum(AGENT_BROWSER_SEMANTIC_LOCATORS, { description: "Semantic locator for click/fill steps when selector is omitted." })),
-                role: Type.Optional(Type.String({ description: "Role locator value for click/fill steps when locator is role." })),
-                name: Type.Optional(Type.String({ description: "Accessible name filter for role locator click/fill steps." })),
-                text: Type.Optional(Type.String({ description: "Text for fill steps or visible text for assertText steps." })),
-                value: Type.Optional(Type.String({ description: "Single option value for select steps, or locator value for semantic click/fill steps." })),
-                values: Type.Optional(Type.Array(Type.String({ description: "Option value for select steps." }), { description: "One or more option values for select steps.", minItems: 1 })),
-                path: Type.Optional(Type.String({ description: "Artifact/download path for waitForDownload or screenshot steps." })),
-                delayMs: Type.Optional(Type.Integer({ description: `Optional per-character delay for type steps; when set, the job compiles to focus/keyboard type/wait steps instead of instant fill-like typing, capped at ${AGENT_BROWSER_JOB_TYPE_DELAYED_TEXT_MAX_CHARACTERS} characters.`, minimum: 1 })),
-                press: Type.Optional(Type.String({ description: "Optional key to press after a type step, for example Enter." })),
-                milliseconds: Type.Optional(Type.Number({ description: "Milliseconds for wait steps." })),
+                action: StringEnum(AGENT_BROWSER_JOB_STEP_ACTIONS),
+                url: Type.Optional(Type.String({ description: "Open URL or assertUrl glob." })),
+                loadState: Type.Optional(StringEnum(AGENT_BROWSER_QA_LOAD_STATES, { description: "Readiness wait after open." })),
+                selector: Type.Optional(Type.String({ description: "Selector or @ref." })),
+                locator: Type.Optional(StringEnum(AGENT_BROWSER_SEMANTIC_LOCATORS, { description: "Locator when selector is omitted." })),
+                role: Type.Optional(Type.String({ description: "Role locator." })),
+                name: Type.Optional(Type.String({ description: "Accessible name." })),
+                text: Type.Optional(Type.String({ description: "Fill text or assertText target." })),
+                value: Type.Optional(Type.String({ description: "Select option or locator value." })),
+                values: Type.Optional(Type.Array(Type.String(), { description: "Select options.", minItems: 1 })),
+                path: Type.Optional(Type.String({ description: "Download or screenshot path." })),
+                delayMs: Type.Optional(Type.Integer({ description: `Per-character type delay; text is capped at ${AGENT_BROWSER_JOB_TYPE_DELAYED_TEXT_MAX_CHARACTERS} characters.`, minimum: 1 })),
+                press: Type.Optional(Type.String({ description: "Key to press after typing." })),
+                milliseconds: Type.Optional(Type.Number({ description: "Wait duration in milliseconds." })),
             }, { additionalProperties: false }), { minItems: 1 }),
-        }, { additionalProperties: false })),
-        stdin: Type.Optional(Type.String({ description: "Optional raw stdin content; only supported for batch, eval --stdin, auth save --password-stdin, and is generated internally by job, qa, sourceLookup, or networkSourceLookup mode. Do not use with electron mode." })),
-        outputPath: Type.Optional(Type.String({ description: "Optional workspace-relative or absolute file path that receives the model-facing command data/result after the browser command completes. Useful for eval/get/snapshot captures that should become durable local artifacts.", minLength: 1 })),
-        timeoutMs: Type.Optional(Type.Integer({ description: "Optional per-call wrapper subprocess watchdog in milliseconds for browser CLI args/job/qa/source lookup calls. Use for long opens or large output captures; explicit long wait steps are forwarded, so set timeoutMs above the wait duration plus a small grace window when overriding the derived watchdog. Electron actions use electron.timeoutMs instead.", minimum: 1 })),
+        }, { additionalProperties: false, description: "Constrained multi-step batch." })),
+        stdin: Type.Optional(Type.String({ description: "Raw stdin for batch, eval --stdin, or auth save --password-stdin; unavailable with structured modes and electron." })),
+        outputPath: Type.Optional(Type.String({ description: "Workspace-relative or absolute result path.", minLength: 1 })),
+        timeoutMs: Type.Optional(Type.Integer({ description: "Wrapper timeout in ms; exceed explicit waits. Electron uses electron.timeoutMs.", minimum: 1 })),
         sessionMode: Type.Optional(StringEnum(["auto", "fresh"], {
-            description: "Session handling mode. `auto` reuses the extension-managed pi-scoped session when possible. `fresh` switches that managed session to a fresh upstream launch so launch-scoped flags like --namespace, --restore, --restore-save, restore check flags, --profile, --executable-path, --webgpu, --session-name, --cdp, --state, --auto-connect, --init-script, --enable, -p/--provider, or iOS --device apply and later auto calls follow the new browser.",
+            description: "auto reuses the managed session; fresh starts one for launch-only flags, then makes it the managed session.",
             default: DEFAULT_SESSION_MODE,
         })),
-    }, { additionalProperties: false });
+    }, {
+        additionalProperties: false,
+        description: "Choose one input mode: args, semanticAction, job, qa, sourceLookup, networkSourceLookup, or electron.",
+    });
 }
 export const AGENT_BROWSER_PARAMS = createAgentBrowserParamsSchema();

package/dist/extensions/agent-browser/lib/launch-scoped-flags.js

@@ -1,8 +1,10 @@
 /**
  * Purpose: Canonical launch-scoped agent-browser flag metadata shared by runtime planning and agent-facing guidance.
- * Responsibilities: Define which upstream flags require a fresh launch, explain why, and expose stable guidance labels.
- * Scope: Metadata only; argv parsing and execution planning live in runtime.ts.
+ * Responsibilities: Define which upstream flags require a fresh launch, explain why, expose stable guidance labels, and share launch-token detection used by runtime and managed restore policy.
+ * Scope: Launch-scoped metadata and token classification; broader execution planning lives in runtime.ts.
  */
+import { findCommandStartIndex } from "./argv-descriptor.js";
+import { isBooleanFlagEnabled, optionalGlobalValueFlagConsumesNext } from "./argv-grammar.js";
 export const LAUNCH_SCOPED_FLAG_DEFINITIONS = [
     {
         flag: "--auto-connect",
@@ -88,3 +90,87 @@ export const LAUNCH_SCOPED_FLAG_DEFINITIONS = [
 export const LAUNCH_SCOPED_FLAGS = LAUNCH_SCOPED_FLAG_DEFINITIONS.map((definition) => definition.flag);
 export const LAUNCH_SCOPED_FLAG_LABEL = LAUNCH_SCOPED_FLAGS.join(", ");
 export const OPEN_RESULT_TAB_CORRECTION_FLAGS = new Set(["--profile", "--restore", "--session-name", "--state"]);
+/** Launch modes that must never be combined with wrapper-managed restore state. */
+export const MANAGED_RESTORE_INCOMPATIBLE_FLAGS = [
+    "--restore",
+    "--restore-save",
+    "--restore-check-url",
+    "--restore-check-text",
+    "--restore-check-fn",
+    "--allowed-domains",
+    "--profile",
+    "--state",
+    "--cdp",
+    "--auto-connect",
+    "--session-name",
+    "--provider",
+    "-p",
+    "--executable-path",
+    "--extension",
+    "--init-script",
+    "--enable",
+    "--args",
+    "--user-agent",
+    "--proxy",
+    "--proxy-bypass",
+    "--ignore-https-errors",
+    "--allow-file-access",
+    "--webgpu",
+    "--device",
+    "--engine",
+];
+/** Nonempty upstream env defaults that can replace or mutate the browser receiving restored state. */
+export const MANAGED_RESTORE_INCOMPATIBLE_ENVS = [
+    "AGENT_BROWSER_RESTORE",
+    "AGENT_BROWSER_RESTORE_SAVE",
+    "AGENT_BROWSER_RESTORE_CHECK_URL",
+    "AGENT_BROWSER_RESTORE_CHECK_TEXT",
+    "AGENT_BROWSER_RESTORE_CHECK_FN",
+    "AGENT_BROWSER_ALLOWED_DOMAINS",
+    "AGENT_BROWSER_PROFILE",
+    "AGENT_BROWSER_STATE",
+    "AGENT_BROWSER_CDP",
+    "AGENT_BROWSER_NAMESPACE",
+    "AGENT_BROWSER_SESSION_NAME",
+    "AGENT_BROWSER_PROVIDER",
+    "AGENT_BROWSER_EXECUTABLE_PATH",
+    "AGENT_BROWSER_EXTENSIONS",
+    "AGENT_BROWSER_INIT_SCRIPTS",
+    "AGENT_BROWSER_ENABLE",
+    "AGENT_BROWSER_ARGS",
+    "AGENT_BROWSER_USER_AGENT",
+    "AGENT_BROWSER_PROXY",
+    "AGENT_BROWSER_PROXY_BYPASS",
+    "AGENT_BROWSER_PLUGINS",
+    "AGENT_BROWSER_IOS_DEVICE",
+    "AGENT_BROWSER_IOS_UDID",
+    "AGENT_BROWSER_ENGINE",
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "ALL_PROXY",
+    "http_proxy",
+    "https_proxy",
+    "all_proxy",
+];
+/** Boolean launch mutators block restore only when enabled. */
+export const MANAGED_RESTORE_INCOMPATIBLE_BOOLEAN_ENVS = [
+    "AGENT_BROWSER_AUTO_CONNECT",
+    "AGENT_BROWSER_IGNORE_HTTPS_ERRORS",
+    "AGENT_BROWSER_ALLOW_FILE_ACCESS",
+    "AGENT_BROWSER_WEBGPU",
+];
+export function hasLaunchScopedFlagToken(args, flag) {
+    const commandStartIndex = findCommandStartIndex(args);
+    const command = commandStartIndex === undefined ? undefined : args[commandStartIndex];
+    return args.some((token, index) => {
+        if (token !== flag && !token.startsWith(`${flag}=`))
+            return false;
+        if (flag === "--auto-connect")
+            return isBooleanFlagEnabled(args, flag);
+        if (flag === "--restore" && token === "--restore" && optionalGlobalValueFlagConsumesNext(flag, args[index + 1]))
+            return true;
+        if (flag === "--state" && command === "wait" && commandStartIndex !== undefined && index > commandStartIndex)
+            return false;
+        return true;
+    });
+}

package/dist/extensions/agent-browser/lib/managed-session-capabilities.js

@@ -0,0 +1,22 @@
+// Purpose: Identify and redact wrapper-owned managed restore capabilities.
+// Scope: Pure string helpers shared by storage, policy, and presentation paths.
+const MANAGED_SESSION_RESTORE_KEY_PATTERN = /piab-r(?:2)?-[a-f\d]{32}/gi;
+const MANAGED_SESSION_RESTORE_KEY_EXACT_PATTERN = /^piab-r2-[a-f\d]{32}$/i;
+const WRAPPER_MANAGED_SESSION_PREFIX = "piab-";
+export function isWrapperManagedSessionName(value) {
+    return typeof value === "string" && value.toLowerCase().startsWith(WRAPPER_MANAGED_SESSION_PREFIX);
+}
+export function isManagedSessionRestoreKey(value) {
+    return typeof value === "string" && MANAGED_SESSION_RESTORE_KEY_EXACT_PATTERN.test(value);
+}
+export function extractManagedSessionRestoreKeys(value) {
+    return [...new Set(value.match(MANAGED_SESSION_RESTORE_KEY_PATTERN)?.map((key) => key.toLowerCase()) ?? [])];
+}
+export function containsManagedSessionRestoreKey(value) {
+    MANAGED_SESSION_RESTORE_KEY_PATTERN.lastIndex = 0;
+    return MANAGED_SESSION_RESTORE_KEY_PATTERN.test(value);
+}
+export function redactManagedSessionRestoreKeys(value) {
+    MANAGED_SESSION_RESTORE_KEY_PATTERN.lastIndex = 0;
+    return value.replace(MANAGED_SESSION_RESTORE_KEY_PATTERN, "[REDACTED MANAGED STATE]");
+}