pi-agent-browser-native 0.5.0 → 0.6.5

package/dist/extensions/agent-browser/lib/results/presentation/registry.js

@@ -197,7 +197,7 @@ export function formatPresentationSummary(commandInfo, data, compiledSemanticAct
                 return semanticSummary;
         }
         const navigationSummary = getNavigationSummary(data);
-        if (navigationSummary && isNavigationObservableCommand(presentationCommandInfo.command)) {
+        if (navigationSummary && isNavigationObservableCommand(presentationCommandInfo.command, presentationCommandInfo.subcommand)) {
             const navigationText = formatNavigationSummary(navigationSummary);
             if (navigationText) {
                 return `${presentationCommandInfo.command ?? "navigation"} → ${navigationText.split("\n", 1)[0] ?? navigationText}`;
@@ -242,7 +242,7 @@ export function formatPresentationContentText(commandInfo, data, compiledSemanti
     }
     const presentationCommandInfo = resolvePresentationCommandInfo(commandInfo, compiledSemanticAction);
     const navigationSummary = getNavigationSummary(data);
-    if (navigationSummary && isNavigationObservableCommand(presentationCommandInfo.command)) {
+    if (navigationSummary && isNavigationObservableCommand(presentationCommandInfo.command, presentationCommandInfo.subcommand)) {
         const navigationText = formatNavigationSummary(navigationSummary);
         if (navigationText) {
             const actionText = formatNavigationActionResult(data);

package/dist/extensions/agent-browser/lib/results/presentation.js

@@ -1,13 +1,13 @@
 import { isRecord } from "../parsing.js";
-import { extractUpstreamCommandTokens } from "../runtime.js";
+import { extractUpstreamCommandTokens, parseCommandInfo, redactInvocationArgs } from "../runtime.js";
 import { buildAgentBrowserNextActions } from "./action-recommendations.js";
 import { buildAgentBrowserResultCategoryDetails } from "./categories.js";
 import { detectConfirmationRequired } from "./confirmation.js";
 import { buildSnapshotPresentation } from "./snapshot.js";
 import { parseJsonPreviewString, redactModelFacingText, stringifyModelFacing } from "./presentation/common.js";
 import { applyArtifactManifest, attachInlineImage, buildArtifactVerificationSummary, buildManifestEntriesForFileArtifacts, classifyPresentationSuccessCategory, extractFileArtifacts, extractImagePath, formatArtifactMetadataLines, formatArtifactSummary, formatMissingArtifactFailureText, getSavedFileDetails, hasMissingFileArtifact, isManifestFileArtifact, } from "./presentation/artifacts.js";
-import { buildBatchPresentation, isAgentBrowserBatchResultArray } from "./presentation/batch.js";
-import { getPresentationPaths } from "./presentation/content.js";
+import { buildBatchPresentation, isAgentBrowserBatchResultArray, redactBatchStepErrorData } from "./presentation/batch.js";
+import { getPresentationPaths, isStringArray } from "./presentation/content.js";
 import { buildNetworkRequestsNextActions, buildStreamNextActions, enrichStreamStatusData, formatNetworkRouteDiagnosticsText, redactPresentationData, } from "./presentation/diagnostics.js";
 import { buildErrorPresentation } from "./presentation/errors.js";
 import { compactLargePresentationOutput } from "./presentation/large-output.js";
@@ -31,6 +31,23 @@ function mergeNextActions(...groups) {
 function shouldAddAnnotatedScreenshotGuidance(commandInfo, args) {
     return commandInfo.command === "screenshot" && (args?.includes("--annotate") ?? false);
 }
+function getKeyboardInsertTextWarning(commandInfo) {
+    if (commandInfo.command !== "keyboard" || commandInfo.subcommand !== "inserttext")
+        return undefined;
+    return "Input dispatch warning: keyboard inserttext skips key events. A DOM value change does not prove a framework-controlled editor accepted it; verify application state before saving, or use keyboard type when real key events are required.";
+}
+function redactBatchSpillData(data) {
+    return data.map((row) => {
+        const command = isStringArray(row.command) ? row.command : undefined;
+        const commandInfo = parseCommandInfo(command ?? []);
+        return {
+            ...row,
+            command: command ? redactInvocationArgs(command) : row.command,
+            error: row.error === undefined ? undefined : redactBatchStepErrorData(command, row.error),
+            result: row.result === undefined ? undefined : redactPresentationData(commandInfo, row.result),
+        };
+    });
+}
 export async function buildToolPresentation(options) {
     const { args, artifactManifest, artifactRequest, commandInfo, compiledSemanticAction, cwd, envelope, errorText, namespace, networkRouteDiagnostics, networkRoutes, persistentArtifactStore, sessionName, } = options;
     const commandInfoWithTokens = commandInfo.commandTokens || !args ? commandInfo : { ...commandInfo, commandTokens: extractUpstreamCommandTokens(args) };
@@ -39,7 +56,9 @@ export async function buildToolPresentation(options) {
         return buildErrorPresentation({ args, commandInfo, errorText, sessionName });
     }
     const data = enrichStreamStatusData(commandInfoWithTokens, envelope?.data);
-    const presentationData = redactPresentationData(commandInfoWithTokens, data);
+    const presentationData = commandInfo.command === "batch" && isAgentBrowserBatchResultArray(data)
+        ? redactBatchSpillData(data)
+        : redactPresentationData(commandInfoWithTokens, data);
     const artifacts = await extractFileArtifacts({ artifactManifest, artifactMaxUpdatedAtMs: options.artifactMaxUpdatedAtMs, artifactMinUpdatedAtMs: options.artifactMinUpdatedAtMs, artifactRequest, commandInfo: presentationCommandInfo, cwd, data, namespace, sessionName });
     const artifactVerification = buildArtifactVerificationSummary(artifacts);
     const artifactSummary = formatArtifactSummary(artifacts);
@@ -95,6 +114,10 @@ export async function buildToolPresentation(options) {
         const guidance = "Annotated screenshot note: dense pages can produce overlapping labels. If the labels are noisy, capture a scoped element screenshot, take a non-annotated screenshot, or use snapshot -i high-value refs as the machine-readable map.";
         presentation.content[0] = { ...presentation.content[0], text: `${presentation.content[0].text}\n\n${guidance}` };
     }
+    const keyboardInsertTextWarning = getKeyboardInsertTextWarning(commandInfoWithTokens);
+    if (keyboardInsertTextWarning && presentation.content[0]?.type === "text") {
+        presentation.content[0] = { ...presentation.content[0], text: `${presentation.content[0].text}\n\n${keyboardInsertTextWarning}` };
+    }
     const imagePath = artifactRequest?.absolutePath ?? extractImagePath(commandInfo, cwd, data);
     const presentationWithImage = imagePath ? await attachInlineImage(presentation, imagePath) : presentation;
     const compactedPresentation = await compactLargePresentationOutput({
@@ -159,6 +182,7 @@ export async function buildToolPresentation(options) {
         resultCategory: presentationWithManifest.resultCategory ?? "success",
         savedFilePath: presentationWithManifest.savedFilePath,
         sessionName,
+        subcommand: presentationCommandInfo.subcommand,
         successCategory: presentationWithManifest.successCategory,
     });
     const networkNextActions = commandInfoWithTokens.command === "network" && commandInfoWithTokens.subcommand === "requests" && presentationWithManifest.resultCategory === "success"
@@ -174,5 +198,8 @@ export async function buildToolPresentation(options) {
         savedFilePath: presentationWithManifest.savedFilePath,
         summary: presentationWithManifest.summary,
     });
+    if (presentationWithManifest.pageChangeSummary?.observed === false && presentationCommandInfo.command !== "batch" && presentationWithManifest.content[0]?.type === "text") {
+        presentationWithManifest.content[0] = { ...presentationWithManifest.content[0], text: `${presentationWithManifest.content[0].text}\n\nAction dispatched; application change unverified. Verify the expected URL, text, state, or external receipt before relying on it.` };
+    }
     return sanitizeModelFacingPresentation(presentationWithManifest);
 }

package/dist/extensions/agent-browser/lib/results/recovery-actions.js

@@ -60,7 +60,7 @@ export function buildRecoveryNextActions(recovery) {
                 args: sessionArgs(["get", "url"]),
                 id: AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS.connectedSessionGetUrl,
                 reason: "Verify the attached page URL before any page-content inspection.",
-                safety: "Read-only URL lookup. The wrapper keeps page inspection blocked if the active target is a local file page or the URL cannot be verified.",
+                safety: "Read-only URL lookup. The wrapper keeps page inspection blocked if the active target URL cannot be verified.",
             }),
             buildNextToolAction({
                 args: sessionArgs(["tab", "list"]),

package/dist/extensions/agent-browser/lib/results/recovery-next-actions.js

@@ -17,6 +17,15 @@ export function buildNoActivePageNextActions(sessionName) {
         resultCategory: "failure",
     }) ?? [];
 }
+export function buildPendingWebMcpNextActions(sessionName) {
+    return [{
+            id: "verify-page-target-after-pending-webmcp",
+            params: { args: withOptionalSessionArgs(sessionName, ["get", "url"]) },
+            reason: "Verify the current page target before taking a fresh snapshot; use webmcp result or cancel to settle the detached invocation.",
+            safety: "Read-only URL inspection. It does not settle the pending page tool, which may still mutate or navigate later.",
+            tool: "agent_browser",
+        }];
+}
 export function buildSessionTabRecoveryNextActions(options) {
     const resultCategory = options.resultCategory ?? "success";
     return buildAgentBrowserNextActions({

package/dist/extensions/agent-browser/lib/results/selector-recovery.js

@@ -9,7 +9,7 @@ const SELECTOR_RECOVERY_ACTION_NAMES = new Set(["check", "click", "fill", "selec
 const VISIBLE_REF_FALLBACK_CANDIDATE_LIMIT = 3;
 const EDITABLE_CONTROL_ROLES = new Set(["combobox", "searchbox", "textbox"]);
 const RICH_INPUT_RECOVERY_EDITABLE_ROLES = new Set(["searchbox", "textbox"]);
-const RICH_INPUT_RECOVERY_HINT = "After the editable ref is focused, use keyboard inserttext or keyboard type with the intended text in a separate call, and do not press Enter or otherwise submit unless the user flow explicitly calls for it.";
+const RICH_INPUT_RECOVERY_HINT = "After the editable ref is focused, use keyboard type when a framework-controlled editor requires real key events. keyboard inserttext is paste-like and needs separate application-state verification. Do not press Enter or otherwise submit unless the user flow explicitly calls for it.";
 function isSelectorRecoveryActionName(action) {
     return SELECTOR_RECOVERY_ACTION_NAMES.has(action);
 }
@@ -225,7 +225,7 @@ export function buildRichInputRecoveryNextActions(options) {
         const clickId = getAgentBrowserRichInputRecoveryNextActionId("click", index, candidateCount);
         const safety = ambiguous
             ? `Several editable refs share the same exact name. Inspect the current snapshot and use only the ${candidate.ref} ${candidate.role} if it is clearly the intended input. No fill text or submit key is included.`
-            : "Does not include fill text or submit the form. After focus/click succeeds, use keyboard inserttext or keyboard type with the intended text only if this is the right input.";
+            : "Does not include fill text or submit the form. After focus/click succeeds, use keyboard type for framework-controlled editors; use keyboard inserttext only with separate application-state verification.";
         return [
             {
                 id: focusId,
@@ -251,7 +251,7 @@ export function formatRichInputRecoveryText(diagnostic) {
         "Rich input recovery:",
         ...diagnostic.candidates.map((candidate, index) => {
             const [focusId, clickId] = diagnostic.nextActionIds.slice(index * 2, index * 2 + 2);
-            return `- ${candidate.ref} ${candidate.role} ${JSON.stringify(candidate.name)}: use ${focusId} or ${clickId}; then use keyboard inserttext/type with the intended text.`;
+            return `- ${candidate.ref} ${candidate.role} ${JSON.stringify(candidate.name)}: use ${focusId} or ${clickId}; then use keyboard type for framework-controlled editors, or paste-like keyboard inserttext only with separate application-state verification.`;
         }),
         `- ${diagnostic.inputMethodHint}`,
     ].join("\n");

package/dist/extensions/agent-browser/lib/results/snapshot-spill.js

@@ -1,9 +1,10 @@
+import { redactSensitiveValue } from "../runtime.js";
 import { writePersistentSessionArtifactFile, writeSecureTempFile } from "../temp.js";
 import { buildEvictedSessionArtifactEntries, formatSessionArtifactRetentionSummary, mergeSessionArtifactManifest, } from "./artifact-manifest.js";
 const SNAPSHOT_SPILL_FILE_PREFIX = "pi-agent-browser-snapshot";
 export async function writeSnapshotSpillFile(data, persistentArtifactStore) {
     const options = {
-        content: JSON.stringify(data, null, 2),
+        content: JSON.stringify(redactSensitiveValue(data), null, 2),
         prefix: SNAPSHOT_SPILL_FILE_PREFIX,
         suffix: ".json",
     };

package/dist/extensions/agent-browser/lib/results/snapshot.js

@@ -162,12 +162,12 @@ export async function buildSnapshotPresentation(data, persistentArtifactStore =
         ...(roleCountsText ? [`Top roles: ${roleCountsText}`] : []),
         "",
         "Compact snapshot view.",
-        "Viewport note: compact snapshots are DOM/signal-prioritized, not guaranteed to start with the currently scrolled viewport; use the full raw snapshot, a screenshot, or listed high-value refs when viewport context matters.",
+        "Viewport note: compact snapshots are DOM/signal-prioritized, not guaranteed to start with the currently scrolled viewport; use the full redacted snapshot, a screenshot, or listed high-value refs when viewport context matters.",
     ];
     if (fallbackPreview) {
         lines.push("", "Compact outline:", ...(fallbackPreview.lines.length > 0 ? fallbackPreview.lines : ["(no interactive elements)"]));
         if (fallbackPreview.omittedCount > 0) {
-            lines.push(`- ... (${fallbackPreview.omittedCount} additional snapshot lines omitted; ${fullOutputPath ? `full output path: ${fullOutputPath}` : "the full raw snapshot was omitted"})`);
+            lines.push(`- ... (${fallbackPreview.omittedCount} additional snapshot lines omitted; ${fullOutputPath ? `full output path: ${fullOutputPath}` : "the full redacted snapshot was omitted"})`);
         }
     }
     else {
@@ -204,8 +204,8 @@ export async function buildSnapshotPresentation(data, persistentArtifactStore =
         }
     }
     lines.push("", fullOutputPath
-        ? `Full raw snapshot path: ${fullOutputPath}`
-        : `Full raw snapshot unavailable: ${spillErrorText ?? "temp spill file could not be created."}`);
+        ? `Full redacted snapshot path: ${fullOutputPath}`
+        : `Full redacted snapshot unavailable: ${spillErrorText ?? "temp spill file could not be created."}`);
     const manifestFields = applySnapshotArtifactManifest({
         baseManifest: artifactManifest,
         command: "snapshot",

package/dist/extensions/agent-browser/lib/runtime.js

@@ -2,9 +2,8 @@ import { createHash, randomUUID } from "node:crypto";
 import { basename } from "node:path";
 import { extractUpstreamCommandTokens, findCommandStartIndex, parseArgvDescriptor, parseCommandInfo, } from "./argv-descriptor.js";
 import { batchHasSuccessfulCloseAll, getSuccessfulBatchCloseLifecycle } from "./batch-lifecycle.js";
-import { canonicalizeAgentBrowserNamespace, extractExplicitNamespace, extractExplicitSessionName, getAgentBrowserSessionIdentityKey, getBooleanFlagValue, GLOBAL_VALUE_FLAGS_ALLOWING_DASH_VALUE, isAgentBrowserSessionIdentityKeyInNamespace, isUpstreamEnvFlagEnabled, PREVALIDATED_VALUE_FLAGS, resolveAgentBrowserNamespace, scanUpstreamGlobalFlagOccurrences, } from "./argv-grammar.js";
+import { canonicalizeAgentBrowserNamespace, extractExplicitNamespace, extractExplicitSessionName, getAgentBrowserSessionIdentityKey, getBooleanFlagValue, GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES, GLOBAL_VALUE_FLAGS_ALLOWING_DASH_VALUE, isAgentBrowserSessionIdentityKeyInNamespace, isUpstreamEnvFlagEnabled, PREVALIDATED_VALUE_FLAGS, resolveAgentBrowserNamespace, scanUpstreamGlobalFlagOccurrences, } from "./argv-grammar.js";
 import { needsManagedSession } from "./command-policy.js";
-import { isWrapperManagedSessionName, redactManagedSessionRestoreKeys } from "./managed-session-capabilities.js";
 import { isCloseAllCommand, isCloseCommand, isOpenNavigationCommand } from "./command-taxonomy.js";
 import { hasLaunchScopedFlagToken, LAUNCH_SCOPED_FLAG_DEFINITIONS, LAUNCH_SCOPED_FLAG_LABEL, } from "./launch-scoped-flags.js";
 import { MANAGED_SESSION_NAME_PREFIX, } from "./managed-session-restore.js";
@@ -21,7 +20,9 @@ const DEFAULT_IMPLICIT_SESSION_IDLE_TIMEOUT_MS = 15 * 60 * 1000;
 const DEFAULT_IMPLICIT_SESSION_CLOSE_TIMEOUT_MS = 5_000;
 const INSPECTION_FLAGS = new Set(["--help", "-h", "--version", "-V"]);
 const SENSITIVE_VALUE_FLAGS = new Set(["--body", "--headers", "--password", "--proxy"]);
-const SENSITIVE_QUERY_PARAM_PATTERN = /^(?:access(?:_|-)?token|api(?:_|-)?key|auth|authorization|bearer|client(?:_|-)?secret|code|cookie|id(?:_|-)?token|key|pass(?:word)?|refresh(?:_|-)?token|secret|sentry(?:_|-)?key|session(?:_|-)?id|sig(?:nature)?|token|write(?:_|-)?key)$/i;
+const SENSITIVE_QUERY_PARAM_PATTERN = /^(?:access(?:_|-)?token|api(?:_|-)?key|auth|authorization|bearer|client(?:_|-)?secret|code|cookie|id(?:_|-)?token|key|pass(?:word)?|refresh(?:_|-)?token|relay(?:_|-)?state|saml(?:_|-)?request|saml(?:_|-)?response|secret|sentry(?:_|-)?key|session(?:_|-)?id|sig(?:nature)?|token|write(?:_|-)?key)$/i;
+const AUTH_STATE_QUERY_PARAM_PATTERN = /^(?:nonce|state)$/i;
+const AUTH_URL_CONTEXT_PATTERN = /(?:^|[./_-])(?:auth|authorize|callback|login|oauth2?|oidc|saml|sso)(?:[./?#_-]|$)/i;
 const SENSITIVE_FIELD_NAME_PATTERN = /^(?:[A-Za-z0-9_-]*(?:api[_-]?key|access[_-]?key|private[_-]?key|secret(?:[_-]?(?:key|access[_-]?key))?|token|password|passwd|credentials?|database[_-]?url|db[_-]?url|connection[_-]?string|mongo(?:db)?[_-]?uri|redis[_-]?url)|[A-Za-z0-9]*(?:apiKey|ApiKey|apikey|privateKey|PrivateKey|databaseUrl|DatabaseUrl|dbUrl|DbUrl|connectionString|ConnectionString|mongoUri|MongoUri|mongodbUri|MongodbUri|mongoDbUri|MongoDbUri|redisUrl|RedisUrl|Token|Secret|Password|Credential|Credentials)|auth(?:orization)?|bearer|client(?:_|-)?secret|cookie|id(?:_|-)?token|pass(?:word)?|proxy(?:_|-)?authorization|refresh(?:_|-)?token|sentry(?:_|-)?key|session(?:_|-)?id|set(?:_|-)?cookie|sig(?:nature)?|write(?:_|-)?key|x(?:_|-)?api(?:_|-)?key)$/i;
 const ENV_SECRET_ASSIGNMENT_PATTERN = /\b((?:export\s+)?([A-Za-z_][A-Za-z0-9_-]*)(\s*[:=]\s*))(?:"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|[^\s,;]+)/g;
 const DEFAULT_HEADLESS_COMPAT_USER_AGENT_BY_PLATFORM = {
@@ -49,48 +50,57 @@ function redactUrlToken(token) {
     catch {
         return token;
     }
-    let mutated = false;
-    if (parsed.username.length > 0) {
+    if (parsed.username.length > 0)
         parsed.username = "[REDACTED]";
-        mutated = true;
-    }
-    if (parsed.password.length > 0) {
+    if (parsed.password.length > 0)
         parsed.password = "[REDACTED]";
-        mutated = true;
-    }
+    const hashText = parsed.hash.startsWith("#") ? parsed.hash.slice(1) : parsed.hash;
+    const hashParams = hashText.includes("=") ? new URLSearchParams(hashText) : undefined;
+    const authContext = AUTH_URL_CONTEXT_PATTERN.test(`${parsed.hostname}${parsed.pathname}`)
+        || [...parsed.searchParams.keys(), ...(hashParams?.keys() ?? [])].some(shouldRedactQueryParam);
     for (const [name] of parsed.searchParams) {
-        if (shouldRedactQueryParam(name)) {
+        if (shouldRedactQueryParam(name) || (authContext && AUTH_STATE_QUERY_PARAM_PATTERN.test(name))) {
             parsed.searchParams.set(name, "[REDACTED]");
-            mutated = true;
         }
     }
-    const hashText = parsed.hash.startsWith("#") ? parsed.hash.slice(1) : parsed.hash;
-    if (hashText.includes("=")) {
-        const hashParams = new URLSearchParams(hashText);
+    if (hashParams) {
+        let hashMutated = false;
         for (const [name] of hashParams) {
-            if (shouldRedactQueryParam(name)) {
+            if (shouldRedactQueryParam(name) || (authContext && AUTH_STATE_QUERY_PARAM_PATTERN.test(name))) {
                 hashParams.set(name, "[REDACTED]");
-                mutated = true;
+                hashMutated = true;
             }
         }
-        if (mutated) {
+        if (hashMutated)
             parsed.hash = `#${hashParams.toString()}`;
-        }
     }
     return parsed.toString();
 }
 function redactLooseUrlParameterText(text) {
-    return text.replace(/([?#&])([^=&#\s]+)=([^&#\s]*)/g, (match, separator, rawName) => {
-        let name = rawName;
-        try {
-            name = decodeURIComponent(rawName.replace(/\+/g, " "));
-        }
-        catch {
-            // Keep the raw name when percent decoding fails.
-        }
-        if (!shouldRedactQueryParam(name))
-            return match;
-        return `${separator}${rawName}=[REDACTED]`;
+    return text.replace(/(?<![^\s"'`<>\])}])[^\s"'`<>\])}]*[?#&][^\s"'`<>\])}]*/g, (token) => {
+        const queryNames = [...token.matchAll(/[?#&]([^=&#\s"'`<>\])}]+)=/g)].map((match) => {
+            try {
+                return decodeURIComponent((match[1] ?? "").replace(/\+/g, " "));
+            }
+            catch {
+                return match[1] ?? "";
+            }
+        });
+        const authContext = AUTH_URL_CONTEXT_PATTERN.test(token) || queryNames.some(shouldRedactQueryParam);
+        return token.replace(/([?#&])([^=&#\s"'`<>\])}]+)=([^&#\s"'`<>\])}]*)/g, (match, separator, rawName, rawValue) => {
+            if (rawValue === "[REDACTED" || rawValue === "[REDACTED]" || /%5Bredacted%5D/i.test(rawValue))
+                return match;
+            let name = rawName;
+            try {
+                name = decodeURIComponent(rawName.replace(/\+/g, " "));
+            }
+            catch {
+                // Keep the raw name when percent decoding fails.
+            }
+            if (!shouldRedactQueryParam(name) && !(authContext && AUTH_STATE_QUERY_PARAM_PATTERN.test(name)))
+                return match;
+            return `${separator}${rawName}=[REDACTED]`;
+        });
     });
 }
 function redactLooseUrlUserinfo(text) {
@@ -226,7 +236,7 @@ function redactEnvSecretAssignments(text) {
     });
 }
 export function redactSensitiveText(text) {
-    return redactEmbeddedStructuredText(redactEnvSecretAssignments(redactStandaloneBasicCredential(redactBearerCredentials(redactLooseUrlUserinfo(redactLooseUrlMatches(redactManagedSessionRestoreKeys(text))))
+    return redactEmbeddedStructuredText(redactEnvSecretAssignments(redactStandaloneBasicCredential(redactBearerCredentials(redactLooseUrlParameterText(redactLooseUrlUserinfo(redactLooseUrlMatches(text))))
         .replace(/\b(Authorization\s*:\s*Basic)\s+[^\s",]+/gi, "$1 [REDACTED]")
         .replace(/\b(Cookie|Set-Cookie)\s*:\s*[^\n\r"]+/gi, "$1: [REDACTED]"))));
 }
@@ -323,20 +333,6 @@ export function getImplicitSessionIdleTimeoutMs(env = getAgentBrowserProcessEnvi
 function countExplicitGlobalFlags(args, targetFlag) {
     return scanUpstreamGlobalFlagOccurrences(args, targetFlag).length;
 }
-function getUnsupportedLeadingIdentityAssignment(args) {
-    const commandStartIndex = findCommandStartIndex(args) ?? args.length;
-    for (let index = 0; index < commandStartIndex; index += 1) {
-        const token = args[index];
-        if (token.startsWith("--session="))
-            return "--session";
-        if (token.startsWith("--namespace="))
-            return "--namespace";
-        const flag = token.split("=", 1)[0] ?? token;
-        if (!token.includes("=") && PREVALIDATED_VALUE_FLAGS.has(flag))
-            index += 1;
-    }
-    return undefined;
-}
 export function getImplicitSessionCloseTimeoutMs(env = getAgentBrowserProcessEnvironment()) {
     return parseTimeoutMs(env[IMPLICIT_SESSION_CLOSE_TIMEOUT_ENV], 0) ?? DEFAULT_IMPLICIT_SESSION_CLOSE_TIMEOUT_MS;
 }
@@ -611,7 +607,7 @@ function getUnsupportedInlineWaitDownloadError(args) {
         return undefined;
     return `agent-browser ${TARGET_AGENT_BROWSER_VERSION} does not support \`wait --download=<path>\`. Pass the optional path as a separate argument: \`wait --download <path>\` (or \`wait -d <path>\`).`;
 }
-export function validateToolArgs(args) {
+export function validateToolArgs(args, options = {}) {
     if (args.length === 0) {
         return "`args` must contain at least one agent-browser command token.";
     }
@@ -623,27 +619,30 @@ export function validateToolArgs(args) {
     if (sessionModeArg) {
         return "Do not pass `--session-mode` in args. Use the top-level agent_browser `sessionMode` field instead, for example { args: [\"--profile\", \"Default\", \"open\", \"https://example.com\"], sessionMode: \"fresh\" }.";
     }
+    const inspection = !options.batchStep && isPlainTextInspectionArgs(args);
+    const invalidValueFlag = inspection ? undefined : getInvalidValueFlagDetails(args, !options.batchStep);
+    if (invalidValueFlag?.reason === "unsupported-assignment")
+        return formatInvalidValueFlagError(invalidValueFlag, options.batchStep);
     return getBareMcpValidationError(args) ?? getSingleKeyCommandValidationError(args) ?? getUnsupportedInlineWaitDownloadError(args);
 }
-function getInvalidValueFlagDetails(args) {
+function getInvalidValueFlagDetails(args, allowRestoreAssignment = true) {
     for (let index = 0; index < args.length; index += 1) {
         const token = args[index];
         if (!token.startsWith("-")) {
             continue;
         }
         const normalizedToken = token.split("=", 1)[0] ?? token;
-        if (!PREVALIDATED_VALUE_FLAGS.has(normalizedToken)) {
-            continue;
+        if (token.includes("=")
+            && (PREVALIDATED_VALUE_FLAGS.has(normalizedToken)
+                || GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES.has(normalizedToken)
+                || (!allowRestoreAssignment && normalizedToken === "--restore"))) {
+            return {
+                flag: normalizedToken,
+                index,
+                reason: "unsupported-assignment",
+            };
         }
-        if (token.includes("=")) {
-            const value = token.slice(token.indexOf("=") + 1).trim();
-            if (value.length === 0) {
-                return {
-                    flag: normalizedToken,
-                    index,
-                    reason: "missing-value",
-                };
-            }
+        if (!PREVALIDATED_VALUE_FLAGS.has(normalizedToken)) {
             continue;
         }
         const receivedToken = args[index + 1];
@@ -666,7 +665,15 @@ function getInvalidValueFlagDetails(args) {
     }
     return undefined;
 }
-function formatInvalidValueFlagError(details) {
+function formatInvalidValueFlagError(details, batchStep = false) {
+    if (details.reason === "unsupported-assignment") {
+        if (batchStep) {
+            return details.flag === "--restore"
+                ? "Global `--restore=<key>` belongs before `batch` in top-level args, not inside a batch step."
+                : `Global \`${details.flag}=<value>\` is not supported inside a batch step. Move \`${details.flag}\` and its value before \`batch\` as separate top-level args.`;
+        }
+        return `agent-browser ${TARGET_AGENT_BROWSER_VERSION} does not support \`${details.flag}=<value>\`. Pass \`${details.flag}\` and its value as separate arguments.`;
+    }
     if (details.reason === "unexpected-flag" && details.receivedToken) {
         return `Flag \`${details.flag}\` requires a value, but received \`${details.receivedToken}\` instead. Pass a non-flag value immediately after \`${details.flag}\`.`;
     }
@@ -779,7 +786,6 @@ export function getStartupScopedFlags(args) {
 }
 export function buildExecutionPlan(args, options) {
     const invalidValueFlag = getInvalidValueFlagDetails(args);
-    const unsupportedIdentityAssignment = getUnsupportedLeadingIdentityAssignment(args);
     const explicitNamespacePresent = scanUpstreamGlobalFlagOccurrences(args, "--namespace").length > 0;
     const explicitNamespace = extractExplicitNamespace(args);
     const managedSessionNamespace = canonicalizeAgentBrowserNamespace(options.managedSessionNamespace);
@@ -811,16 +817,6 @@ export function buildExecutionPlan(args, options) {
             validationError: formatInvalidValueFlagError(invalidValueFlag),
         };
     }
-    if (unsupportedIdentityAssignment) {
-        return {
-            commandInfo: {},
-            effectiveArgs,
-            plainTextInspection: false,
-            startupScopedFlags: [],
-            usedImplicitSession: false,
-            validationError: `${unsupportedIdentityAssignment}=... is not supported by agent-browser ${TARGET_AGENT_BROWSER_VERSION}. Pass ${unsupportedIdentityAssignment} and its value as separate arguments.`,
-        };
-    }
     for (const flag of ["--session", "--namespace"]) {
         if (countExplicitGlobalFlags(args, flag) <= 1)
             continue;
@@ -834,8 +830,13 @@ export function buildExecutionPlan(args, options) {
         };
     }
     const explicitSessionName = extractExplicitSessionName(args);
-    if (explicitSessionName && !isWrapperManagedSessionName(explicitSessionName)) {
-        namespace = resolveAgentBrowserNamespace(args, getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE);
+    if (explicitSessionName && !explicitNamespacePresent) {
+        const targetsCurrentManagedSession = options.managedSessionActive
+            && getAgentBrowserSessionIdentityKey(explicitSessionName, managedSessionNamespace)
+                === getAgentBrowserSessionIdentityKey(options.managedSessionName, managedSessionNamespace);
+        namespace = targetsCurrentManagedSession
+            ? managedSessionNamespace
+            : resolveAgentBrowserNamespace(args, getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE);
     }
     const shouldCreateFreshManagedSession = !explicitSessionName && options.sessionMode === "fresh" && commandInfo.command !== undefined && !isCloseCommand(commandInfo.command);
     let argsToAppend = args;

package/dist/extensions/agent-browser/lib/session-page-state.js

@@ -1,7 +1,7 @@
 import { extractUpstreamCommandTokens } from "./argv-descriptor.js";
 import { getAgentBrowserSessionIdentityKey, isAgentBrowserSessionIdentityKeyInNamespace } from "./argv-grammar.js";
 import { batchHasSuccessfulCloseAll, getSuccessfulBatchCloseLifecycle } from "./batch-lifecycle.js";
-import { isCloseAllCommand, isCloseCommand, isReadOnlyDiagnosticSessionTargetCommand, isRecordPageTransitionCommand, isUnverifiedPageTransitionCommand } from "./command-taxonomy.js";
+import { isCloseAllCommand, isCloseCommand, isReadOnlyDiagnosticSessionTargetCommand, isRecordPageTransitionCommand, isUnverifiedPageTransitionCommand, isWebMcpPageMutationCommand } from "./command-taxonomy.js";
 import { isRecord } from "./parsing.js";
 import { getEditableRefEvidence } from "./results/editable-ref-evidence.js";
 import { enrichSnapshotRefEntries, getSnapshotRefEntries } from "./results/snapshot-refs.js";
@@ -210,6 +210,14 @@ export function buildPageTransitionRefSnapshotInvalidation(summary) {
         summary: summary ?? "A recording command (record start, or record restart with a URL) replaced or navigated the active page and invalidated the prior snapshot. Run snapshot -i before using page-scoped refs.",
     };
 }
+export function getCommandRefSnapshotInvalidation(commandTokens) {
+    if (isRecordPageTransitionCommand(commandTokens))
+        return buildPageTransitionRefSnapshotInvalidation();
+    if (isWebMcpPageMutationCommand(commandTokens)) {
+        return buildPageTransitionRefSnapshotInvalidation("A WebMCP invoke, result, or cancel command can mutate, rerender, or navigate the page, so the prior snapshot refs were invalidated. Run snapshot -i before using page-scoped refs.");
+    }
+    return undefined;
+}
 export function isNoActivePageSnapshotFailure(command, text) {
     return command === "snapshot" && /\bno active page\b/i.test(text ?? "");
 }
@@ -226,8 +234,9 @@ export function extractLatestRefSnapshotStateFromBatchResults(data) {
             latestState = undefined;
             continue;
         }
-        if (isRecordPageTransitionCommand(commandTokens)) {
-            latestState = { invalidation: buildPageTransitionRefSnapshotInvalidation() };
+        const transitionInvalidation = getCommandRefSnapshotInvalidation(commandTokens);
+        if (transitionInvalidation) {
+            latestState = { invalidation: transitionInvalidation };
             continue;
         }
         if (name !== "snapshot")

package/dist/extensions/agent-browser/lib/temp.js

@@ -8,7 +8,6 @@ import { processStartIdentitiesMatch, readProcessStartIdentity } from "./process
 const TEMP_ROOT_PREFIX = "pi-agent-browser-";
 const TEMP_ROOT_MARKER_FILE_NAME = ".pi-agent-browser-owner.json";
 const TEMP_ROOT_MARKER_KIND = "pi-agent-browser-temp-root";
-const TEMP_ROOT_LEGACY_MARKER_VERSION = 1;
 const TEMP_ROOT_MARKER_VERSION = 2;
 const STALE_TEMP_ROOT_MAX_AGE_MS = 24 * 60 * 60 * 1_000;
 const TEMP_ROOT_MAX_BYTES_ENV = "PI_AGENT_BROWSER_TEMP_ROOT_MAX_BYTES";
@@ -39,7 +38,7 @@ function isProtectedTempChildName(value) {
 function isTempRootOwnershipRecord(value) {
     if (!isRecord(value))
         return false;
-    if (value.kind !== TEMP_ROOT_MARKER_KIND || ![TEMP_ROOT_LEGACY_MARKER_VERSION, TEMP_ROOT_MARKER_VERSION].includes(value.version))
+    if (value.kind !== TEMP_ROOT_MARKER_KIND || value.version !== TEMP_ROOT_MARKER_VERSION)
         return false;
     if (!isPositiveFiniteNumber(value.createdAtMs))
         return false;

package/dist/extensions/agent-browser/lib/upstream-version.js

@@ -1,14 +1,14 @@
-import { TARGET_AGENT_BROWSER_VERSION, TARGET_AGENT_BROWSER_VERSION_LABEL } from "../../../scripts/agent-browser-target.mjs";
-export { TARGET_AGENT_BROWSER_VERSION, TARGET_AGENT_BROWSER_VERSION_LABEL };
+import { MINIMUM_AGENT_BROWSER_VERSION, MINIMUM_AGENT_BROWSER_VERSION_LABEL, SUPPORTED_AGENT_BROWSER_VERSION_LABEL, TARGET_AGENT_BROWSER_VERSION, TARGET_AGENT_BROWSER_VERSION_LABEL, isSupportedAgentBrowserVersion, } from "../../../scripts/agent-browser-target.mjs";
+export { MINIMUM_AGENT_BROWSER_VERSION, MINIMUM_AGENT_BROWSER_VERSION_LABEL, SUPPORTED_AGENT_BROWSER_VERSION_LABEL, TARGET_AGENT_BROWSER_VERSION, TARGET_AGENT_BROWSER_VERSION_LABEL, isSupportedAgentBrowserVersion, };
 export function parseAgentBrowserVersionOutput(stdout) {
     const match = stdout.trim().match(/^agent-browser\s+(\S+)$/);
     return match?.[1];
 }
 export function getAgentBrowserVersionValidationError(stdout) {
     const observed = parseAgentBrowserVersionOutput(stdout);
-    if (observed === TARGET_AGENT_BROWSER_VERSION)
+    if (observed && isSupportedAgentBrowserVersion(observed))
         return undefined;
     return observed
-        ? `Installed agent-browser ${observed} does not match this extension's exact ${TARGET_AGENT_BROWSER_VERSION} capability baseline. Install ${TARGET_AGENT_BROWSER_VERSION_LABEL}, run pi-agent-browser-doctor, then reload Pi.`
-        : `agent-browser --version returned an unrecognized value; expected exactly ${JSON.stringify(TARGET_AGENT_BROWSER_VERSION_LABEL)}. Run pi-agent-browser-doctor and install the exact supported upstream version.`;
+        ? `Installed agent-browser ${observed} is unsupported; stable versions must be at least ${MINIMUM_AGENT_BROWSER_VERSION_LABEL}. Install ${TARGET_AGENT_BROWSER_VERSION_LABEL} (recommended), run pi-agent-browser-doctor, then reload Pi.`
+        : `agent-browser --version returned an unrecognized value; expected ${SUPPORTED_AGENT_BROWSER_VERSION_LABEL}. Run pi-agent-browser-doctor and install a supported upstream version.`;
 }