pi-agent-browser-native 0.9.2 → 0.9.4

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

@@ -1,264 +1,44 @@
 import { isRecord } from "../parsing.js";
-import { isHighValueControlEntry, selectHighValueControlEntries } from "./snapshot-high-value-controls.js";
-import { buildFallbackSnapshotOutline, buildRefLineOrderMap, buildSegmentPreview, buildSnapshotSegments, canUseStructuredSnapshotPreview, chooseAdditionalSegments, choosePrimarySegment, getMeaningfulSegmentLines, getSnapshotRolePriority, isChromeSectionName, isNoiseName, parseSnapshotLines, } from "./snapshot-segments.js";
-import { applySnapshotArtifactManifest, writeSnapshotSpillFile } from "./snapshot-spill.js";
-import { enrichSnapshotRefEntries, getFullSnapshotData, getSnapshotRefEntries, } from "./snapshot-refs.js";
-import { compareRefIds, countLines, truncateText } from "./text.js";
-const SNAPSHOT_INLINE_MAX_CHARS = 6_000;
-const SNAPSHOT_INLINE_MAX_LINES = 80;
-const SNAPSHOT_INLINE_MAX_REFS = 60;
-const SNAPSHOT_PRIMARY_PREVIEW_LINES = 8;
-const SNAPSHOT_SECTION_PREVIEW_LINES = 2;
-const SNAPSHOT_KEY_REF_MAX_LINES = 8;
-const SNAPSHOT_OTHER_REF_MAX_LINES = 4;
-const SNAPSHOT_HIGH_VALUE_REF_MAX_LINES = 10;
-const SNAPSHOT_ROLE_COUNT_MAX_ENTRIES = 4;
-const SNAPSHOT_NAME_MAX_CHARS = 96;
-function getSnapshotText(data) {
-    const full = getFullSnapshotData(data);
-    return typeof full?.snapshot === "string" ? full.snapshot : isRecord(data.snapshot) ? JSON.stringify(data.snapshot) : undefined;
-}
-function getSnapshotOrigin(data) {
-    return typeof data.origin === "string" ? data.origin : "(unknown origin)";
-}
-function getSnapshotRoleCounts(refEntries) {
-    const counts = {};
-    for (const entry of refEntries) {
-        counts[entry.role] = (counts[entry.role] ?? 0) + 1;
-    }
-    return counts;
-}
-function formatRoleCounts(roleCounts) {
-    const entries = Object.entries(roleCounts);
-    if (entries.length === 0)
-        return undefined;
-    const ordered = entries.sort((left, right) => {
-        if (right[1] !== left[1])
-            return right[1] - left[1];
-        return getSnapshotRolePriority(left[0]) - getSnapshotRolePriority(right[0]);
-    });
-    const visibleEntries = ordered.slice(0, SNAPSHOT_ROLE_COUNT_MAX_ENTRIES).map(([role, count]) => `${role} ${count}`);
-    const omittedEntries = Math.max(0, ordered.length - visibleEntries.length);
-    if (omittedEntries > 0) {
-        visibleEntries.push(`+${omittedEntries} more`);
-    }
-    return visibleEntries.join(", ");
-}
-function rankRefEntries(refEntries, previewRefIds, focusRefIds, lineOrderByRef) {
-    return [...refEntries].sort((left, right) => {
-        const leftBucket = previewRefIds.has(left.id) ? 0 : focusRefIds.has(left.id) ? 1 : 2;
-        const rightBucket = previewRefIds.has(right.id) ? 0 : focusRefIds.has(right.id) ? 1 : 2;
-        if (leftBucket !== rightBucket)
-            return leftBucket - rightBucket;
-        const rolePriority = getSnapshotRolePriority(left.role) - getSnapshotRolePriority(right.role);
-        if (rolePriority !== 0)
-            return rolePriority;
-        const leftHasName = left.name.length > 0 ? 0 : 1;
-        const rightHasName = right.name.length > 0 ? 0 : 1;
-        if (leftHasName !== rightHasName)
-            return leftHasName - rightHasName;
-        const leftLineOrder = lineOrderByRef.get(left.id) ?? Number.MAX_SAFE_INTEGER;
-        const rightLineOrder = lineOrderByRef.get(right.id) ?? Number.MAX_SAFE_INTEGER;
-        if (leftLineOrder !== rightLineOrder)
-            return leftLineOrder - rightLineOrder;
-        return compareRefIds(left.id, right.id);
-    });
-}
-function formatCompactRef(entry) {
-    const suffix = entry.name.length > 0 ? ` "${truncateText(entry.name, SNAPSHOT_NAME_MAX_CHARS)}"` : "";
-    return `- ${entry.id} ${entry.role}${suffix}`;
-}
+import { buildCompactSnapshotView } from "./snapshot-compact.js";
+import { formatRawSnapshotText, formatSnapshotSummary, getSnapshotText, } from "./snapshot-content.js";
+import { getSnapshotRefEntries } from "./snapshot-refs.js";
+import { applySnapshotArtifactManifest, writeSnapshotSpillFile, } from "./snapshot-spill.js";
+import { countLines, stringifyUnknown } from "./text.js";
+export { formatRawSnapshotText, formatSnapshotSummary } from "./snapshot-content.js";
 function shouldCompactSnapshot(rawText, data) {
-    const snapshot = getSnapshotText(data) ?? "";
-    const refEntries = getSnapshotRefEntries(data);
-    return (rawText.length > SNAPSHOT_INLINE_MAX_CHARS ||
-        countLines(snapshot) > SNAPSHOT_INLINE_MAX_LINES ||
-        refEntries.length > SNAPSHOT_INLINE_MAX_REFS);
-}
-export function formatSnapshotSummary(data) {
-    const origin = typeof data.origin === "string" ? data.origin : "page";
-    if (isRecord(data.snapshot) && data.snapshot.kind !== "full")
-        return `Snapshot ${data.snapshot.kind}: revision ${data.snapshot.revision} on ${origin}`;
-    const refs = getSnapshotRefEntries(data).length;
-    return `Snapshot: ${refs} refs on ${origin}`;
-}
-export function formatRawSnapshotText(data) {
-    const origin = getSnapshotOrigin(data);
-    const refs = getSnapshotRefEntries(data).length;
-    const snapshot = getSnapshotText(data);
-    if (isRecord(data.snapshot) && data.snapshot.kind !== "full")
-        return `Origin: ${origin}\n${formatSnapshotSummary(data)}\n\n${snapshot}`;
-    if (!snapshot) {
-        return `Origin: ${origin}\nRefs: ${refs}\n\n(no interactive elements)`;
-    }
-    return `Origin: ${origin}\nRefs: ${refs}\n\n${snapshot}`;
+    return (rawText.length > 6_000 ||
+        countLines(getSnapshotText(data) ?? "") > 80 ||
+        getSnapshotRefEntries(data).length > 60);
 }
-export async function buildSnapshotPresentation(data, persistentArtifactStore = undefined, artifactManifest = undefined) {
-    const summary = formatSnapshotSummary(data);
-    const rawText = formatRawSnapshotText(data);
-    // Native partials are already compact patches, not accessibility trees.
-    // The ordinary large-output presenter handles truly oversized patches.
-    if ((isRecord(data.snapshot) && data.snapshot.kind !== "full") || !shouldCompactSnapshot(rawText, data)) {
-        return {
-            content: [{ type: "text", text: rawText }],
-            data,
-            summary,
-        };
-    }
-    let fullOutputPath;
-    let spill;
-    let spillErrorText;
+async function getSnapshotSpill(data, store) {
     try {
-        spill = await writeSnapshotSpillFile(data, persistentArtifactStore);
-        fullOutputPath = spill.path;
+        const spill = await writeSnapshotSpillFile(data, store);
+        return { spill, fullOutputPath: spill.path };
     }
     catch (error) {
-        spillErrorText = error instanceof Error ? error.message : String(error);
-    }
-    const snapshot = getSnapshotText(data) ?? "(no interactive elements)";
-    const snapshotLines = parseSnapshotLines(snapshot);
-    const refEntries = enrichSnapshotRefEntries(getSnapshotRefEntries(data), snapshotLines);
-    const roleCounts = getSnapshotRoleCounts(refEntries);
-    const roleCountsText = formatRoleCounts(roleCounts);
-    const useStructuredPreview = canUseStructuredSnapshotPreview(snapshotLines, refEntries);
-    const snapshotSegments = useStructuredPreview ? buildSnapshotSegments(snapshotLines) : [];
-    const primarySegment = useStructuredPreview ? choosePrimarySegment(snapshotSegments) : undefined;
-    const additionalSegments = useStructuredPreview ? chooseAdditionalSegments(snapshotSegments, primarySegment) : [];
-    const additionalSegmentCount = useStructuredPreview && primarySegment ? Math.max(0, snapshotSegments.length - 1) : 0;
-    const omittedAdditionalSectionCount = Math.max(0, additionalSegmentCount - additionalSegments.length);
-    const primaryPreview = primarySegment ? buildSegmentPreview(primarySegment, SNAPSHOT_PRIMARY_PREVIEW_LINES) : undefined;
-    const additionalPreviews = additionalSegments
-        .map((segment) => ({
-        preview: buildSegmentPreview(segment, SNAPSHOT_SECTION_PREVIEW_LINES),
-        segment,
-    }))
-        .filter(({ preview }) => preview.lines.length > 0);
-    const fallbackPreview = !useStructuredPreview || !primaryPreview || primaryPreview.lines.length === 0 ? buildFallbackSnapshotOutline(snapshotLines) : undefined;
-    const previewRefIds = new Set([
-        ...(primaryPreview?.refIds ?? []),
-        ...additionalPreviews.flatMap(({ preview }) => preview.refIds),
-        ...(fallbackPreview?.refIds ?? []),
-    ]);
-    const focusRefIds = new Set([
-        ...(useStructuredPreview && primarySegment
-            ? getMeaningfulSegmentLines(primarySegment).flatMap((line) => (line.ref ? [line.ref] : []))
-            : []),
-        ...(useStructuredPreview
-            ? additionalSegments.flatMap((segment) => getMeaningfulSegmentLines(segment).flatMap((line) => (line.ref ? [line.ref] : [])))
-            : []),
-        ...(fallbackPreview?.refIds ?? []),
-    ]);
-    const lineOrderByRef = useStructuredPreview ? buildRefLineOrderMap(snapshotLines) : new Map();
-    const rankedRefEntries = rankRefEntries(refEntries, previewRefIds, focusRefIds, lineOrderByRef);
-    const visibleRankedRefEntries = rankedRefEntries.filter((entry) => !isNoiseName(entry.name) && !isChromeSectionName(entry.name) && !(entry.role === "heading" && entry.name.length <= 2));
-    const keyRefEntries = visibleRankedRefEntries.slice(0, SNAPSHOT_KEY_REF_MAX_LINES);
-    const keyRefIdSet = new Set(keyRefEntries.map((entry) => entry.id));
-    const otherRefEntries = visibleRankedRefEntries
-        .filter((entry) => !keyRefIdSet.has(entry.id))
-        .slice(0, SNAPSHOT_OTHER_REF_MAX_LINES);
-    const displayedRefIdSet = new Set([...keyRefEntries, ...otherRefEntries].map((entry) => entry.id));
-    const omittedRefEntries = visibleRankedRefEntries.filter((entry) => !displayedRefIdSet.has(entry.id));
-    const highValueControlEntries = omittedRefEntries.filter((entry) => isHighValueControlEntry(entry) && !isNoiseName(entry.name) && !isChromeSectionName(entry.name));
-    const visibleHighValueControlEntries = selectHighValueControlEntries(highValueControlEntries, SNAPSHOT_HIGH_VALUE_REF_MAX_LINES);
-    const omittedHighValueControls = Math.max(0, highValueControlEntries.length - visibleHighValueControlEntries.length);
-    const omittedNonHighlightedRefs = Math.max(0, omittedRefEntries.length - highValueControlEntries.length);
-    const origin = getSnapshotOrigin(data);
-    const lines = [
-        `Origin: ${origin}`,
-        `Refs: ${refEntries.length}`,
-        ...(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 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 redacted snapshot was omitted"})`);
-        }
-    }
-    else {
-        lines.push("", "Primary content:", ...(primaryPreview?.lines ?? ["(no interactive elements)"]));
-        if ((primaryPreview?.omittedCount ?? 0) > 0) {
-            lines.push(`- ... (${primaryPreview?.omittedCount} more lines in this section)`);
-        }
-        if (additionalPreviews.length > 0) {
-            lines.push("", "Additional sections:");
-            additionalPreviews.forEach(({ preview }, index) => {
-                if (index > 0)
-                    lines.push("");
-                lines.push(...preview.lines);
-                if (preview.omittedCount > 0) {
-                    lines.push(`- ... (${preview.omittedCount} more lines in this section)`);
-                }
-            });
-            if (omittedAdditionalSectionCount > 0) {
-                lines.push(`- ... (${omittedAdditionalSectionCount} more sections omitted)`);
-            }
-        }
+        return { spillErrorText: error instanceof Error ? error.message : stringifyUnknown(error) };
     }
-    lines.push("", "Key refs:", ...(keyRefEntries.length > 0 ? keyRefEntries.map(formatCompactRef) : ["(no refs)"]));
-    if (otherRefEntries.length > 0) {
-        lines.push("", "Other refs:", ...otherRefEntries.map(formatCompactRef));
-    }
-    if (omittedNonHighlightedRefs > 0) {
-        lines.push(`- ... (${omittedNonHighlightedRefs} additional refs omitted)`);
-    }
-    if (visibleHighValueControlEntries.length > 0) {
-        lines.push("", "Omitted high-value controls:", ...visibleHighValueControlEntries.map(formatCompactRef));
-        if (omittedHighValueControls > 0) {
-            lines.push(`- ... (${omittedHighValueControls} additional high-value controls omitted)`);
-        }
+}
+export async function buildSnapshotPresentation(data, persistentArtifactStore, artifactManifest) {
+    const summary = formatSnapshotSummary(data);
+    const rawText = formatRawSnapshotText(data);
+    // Native partials are patches, not accessibility trees; large-output owns oversized patches.
+    if ((isRecord(data.snapshot) && data.snapshot.kind !== "full") ||
+        !shouldCompactSnapshot(rawText, data)) {
+        return { content: [{ type: "text", text: rawText }], data, summary };
     }
-    lines.push("", fullOutputPath
-        ? `Full redacted snapshot path: ${fullOutputPath}`
-        : `Full redacted snapshot unavailable: ${spillErrorText ?? "temp spill file could not be created."}`);
+    const { spill, fullOutputPath, spillErrorText } = await getSnapshotSpill(data, persistentArtifactStore);
+    const compact = buildCompactSnapshotView(data, fullOutputPath, spillErrorText);
     const manifestFields = applySnapshotArtifactManifest({
         baseManifest: artifactManifest,
         command: "snapshot",
         fullOutputPath,
         spill,
     });
-    if (manifestFields.artifactRetentionSummary) {
-        lines.push("", manifestFields.artifactRetentionSummary);
+    const notice = manifestFields.artifactRetentionSummary;
+    const text = compact.content.at(0);
+    if (notice !== undefined && notice.length > 0 && text?.type === "text") {
+        compact.content[0] = { type: "text", text: `${text.text}\n\n${notice}` };
     }
-    return {
-        ...manifestFields,
-        content: [{ type: "text", text: lines.join("\n") }],
-        data: {
-            compacted: true,
-            fullOutputPath,
-            origin,
-            previewMode: fallbackPreview ? "outline" : "structured",
-            viewportOrdering: "dom-signal-prioritized",
-            spillError: spillErrorText,
-            previewRefIds: [...previewRefIds],
-            highValueControlRefIds: visibleHighValueControlEntries.map((entry) => entry.id),
-            additionalSectionsOmitted: omittedAdditionalSectionCount,
-            previewSections: [
-                ...(primarySegment
-                    ? [
-                        {
-                            linesShown: primaryPreview?.lines.length ?? 0,
-                            omittedLines: primaryPreview?.omittedCount ?? 0,
-                            role: primarySegment.root.role,
-                            title: primarySegment.root.name,
-                        },
-                    ]
-                    : []),
-                ...additionalPreviews.map(({ preview, segment }) => ({
-                    linesShown: preview.lines.length,
-                    omittedLines: preview.omittedCount,
-                    role: segment.root.role,
-                    title: segment.root.name,
-                })),
-            ],
-            refCount: refEntries.length,
-            roleCounts,
-            snapshotLineCount: countLines(snapshot),
-            structuredPreviewUsed: !fallbackPreview,
-        },
-        fullOutputPath,
-        summary: `${summary} (compact)`,
-    };
+    return { ...manifestFields, ...compact, fullOutputPath, summary: `${summary} (compact)` };
 }

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

@@ -1,16 +1,26 @@
 export function stringifyUnknown(value) {
-    if (typeof value === "string")
+    if (typeof value === "string") {
         return value;
-    if (typeof value === "number" || typeof value === "boolean")
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
         return String(value);
-    if (value === null || value === undefined)
+    }
+    if (value === null || value === undefined) {
         return "";
+    }
     try {
-        return JSON.stringify(value, null, 2);
+        const serialized = JSON.stringify(value, null, 2);
+        return typeof serialized === "string" ? serialized : "";
     }
     catch {
+        return stringifyFallback(value);
+    }
+}
+function stringifyFallback(value) {
+    if (typeof value === "bigint" || typeof value === "symbol" || typeof value === "function") {
         return String(value);
     }
+    return Object.prototype.toString.call(value);
 }
 export function countLines(text) {
     return text.length === 0 ? 0 : text.split("\n").length;
@@ -19,8 +29,9 @@ export function normalizeWhitespace(text) {
     return text.replace(/\s+/g, " ").trim();
 }
 export function truncateText(text, maxChars) {
-    if (text.length <= maxChars)
+    if (text.length <= maxChars) {
         return text;
+    }
     return `${text.slice(0, Math.max(1, maxChars - 1))}…`;
 }
 export function compareRefIds(left, right) {

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

@@ -0,0 +1,133 @@
+import { parseArgvDescriptor } from "./argv-descriptor.js";
+import { GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES, GLOBAL_VALUE_FLAGS_ALLOWING_DASH_VALUE, PREVALIDATED_VALUE_FLAGS, stripUpstreamGlobalFlags, } from "./argv-grammar.js";
+import { isOpenNavigationCommand } from "./command-taxonomy.js";
+import { TARGET_AGENT_BROWSER_VERSION } from "./upstream-version.js";
+const INSPECTION_FLAGS = new Set(["--help", "-h", "--version", "-V"]);
+const SHELL_OPERATOR_TOKENS = new Set(["&&", "||", "|", ";", ">", ">>", "<"]);
+export function isPlainTextInspectionArgs(args) {
+    return args.some((token) => INSPECTION_FLAGS.has(token));
+}
+function getSingleKeyCommandValidationError(args) {
+    const { commandInfo, upstreamCommandTokens: tokens } = parseArgvDescriptor(args);
+    const command = commandInfo.command;
+    if (!["press", "key", "keydown", "keyup"].includes(command ?? "") || tokens.length === 2) {
+        return;
+    }
+    const label = command === "key" ? "key/press" : command;
+    return `agent-browser ${label ?? ""} accepts exactly one key argument. Do not pass a selector or ref to ${label ?? ""}; focus or click the target first, then run ${command ?? ""} <key> (for example: focus @e1, then press Enter).`;
+}
+function getBareMcpValidationError(args) {
+    const { commandInfo, upstreamCommandTokens: tokens } = parseArgvDescriptor(args);
+    if (commandInfo.command !== "mcp" || tokens.includes("--help") || tokens.includes("-h")) {
+        return;
+    }
+    return "agent-browser mcp starts a stdio MCP server for external MCP clients, not a one-shot native agent_browser tool workflow. Use the native agent_browser tool modes directly, or configure an MCP client to launch `agent-browser mcp`. Use `mcp --help` for help.";
+}
+function getUnsupportedInlineWaitDownloadError(args) {
+    const descriptor = parseArgvDescriptor(args);
+    if (descriptor.commandInfo.command !== "wait" ||
+        !descriptor.upstreamCommandTokens.some((token) => token.startsWith("--download="))) {
+        return;
+    }
+    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>\`).`;
+}
+function getBareNoSandboxValidationError(args, batchStep) {
+    // Native batch rows skip global parsing; --args is effective only on the outer CLI call.
+    const tokens = batchStep ? args : stripUpstreamGlobalFlags(args);
+    const command = tokens[0];
+    const leading = command === "--no-sandbox";
+    if (!leading &&
+        (!isOpenNavigationCommand(command) || !tokens.slice(1).includes("--no-sandbox"))) {
+        return;
+    }
+    const explanation = leading
+        ? "`--no-sandbox` is not an agent-browser command."
+        : `\`--no-sandbox\` is ignored as an option by \`${command}\`.`;
+    return `${explanation} It is a Chromium launch argument. Put it in top-level \`--args\` and start a fresh session: { args: ["--args", "--no-sandbox", "open", "https://example.com"], sessionMode: "fresh" }. For batch, put --args before batch, not inside a step.`;
+}
+function getForbiddenToolTokenError(args) {
+    const shellOperator = args.find((token) => SHELL_OPERATOR_TOKENS.has(token));
+    if (shellOperator !== undefined) {
+        return `Do not pass shell operators like \`${shellOperator}\`. Pass exact agent-browser CLI arguments only.`;
+    }
+    if (args.some((token) => token === "--session-mode" || token.startsWith("--session-mode="))) {
+        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" }.';
+    }
+    return;
+}
+export function validateToolArgs(args, options = {}) {
+    if (args.length === 0) {
+        return "`args` must contain at least one agent-browser command token.";
+    }
+    const forbidden = getForbiddenToolTokenError(args);
+    if (forbidden !== undefined) {
+        return forbidden;
+    }
+    return getNativeCommandShapeError(args, options.batchStep === true);
+}
+function getNativeCommandShapeError(args, batchStep) {
+    const inspection = !batchStep && isPlainTextInspectionArgs(args);
+    const invalidValueFlag = inspection ? undefined : getInvalidValueFlagDetails(args, !batchStep);
+    if (invalidValueFlag?.reason === "unsupported-assignment") {
+        return formatInvalidValueFlagError(invalidValueFlag, batchStep);
+    }
+    return ((inspection ? undefined : getBareNoSandboxValidationError(args, batchStep)) ??
+        getBareMcpValidationError(args) ??
+        getSingleKeyCommandValidationError(args) ??
+        getUnsupportedInlineWaitDownloadError(args));
+}
+function unsupportedAssignment(token, flag, allowRestoreAssignment) {
+    return (token.includes("=") &&
+        (PREVALIDATED_VALUE_FLAGS.has(flag) ||
+            GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES.has(flag) ||
+            (!allowRestoreAssignment && flag === "--restore")));
+}
+function valueFlagProblem(flag, receivedToken) {
+    if (receivedToken === undefined || (flag === "--args" && receivedToken.length === 0)) {
+        return "missing-value";
+    }
+    if (receivedToken.startsWith("-") && !GLOBAL_VALUE_FLAGS_ALLOWING_DASH_VALUE.has(flag)) {
+        return "unexpected-flag";
+    }
+    return;
+}
+export function getInvalidValueFlagDetails(args, allowRestoreAssignment = true) {
+    for (let index = 0; index < args.length; index += 1) {
+        const token = args[index];
+        if (!token.startsWith("-")) {
+            continue;
+        }
+        const flag = token.split("=", 1)[0] ?? token;
+        if (unsupportedAssignment(token, flag, allowRestoreAssignment)) {
+            return { flag, index, reason: "unsupported-assignment" };
+        }
+        if (!PREVALIDATED_VALUE_FLAGS.has(flag)) {
+            continue;
+        }
+        const receivedToken = args.at(index + 1);
+        const reason = valueFlagProblem(flag, receivedToken);
+        if (reason !== undefined) {
+            return reason === "unexpected-flag"
+                ? { flag, index, reason, receivedToken }
+                : { flag, index, reason };
+        }
+        index += 1;
+    }
+    return;
+}
+export 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 !== undefined &&
+        details.receivedToken.length > 0) {
+        return `Flag \`${details.flag}\` requires a value, but received \`${details.receivedToken}\` instead. Pass a non-flag value immediately after \`${details.flag}\`.`;
+    }
+    return `Flag \`${details.flag}\` requires a value immediately after it. Pass a non-flag token like \`${details.flag} demo\`.`;
+}

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

@@ -0,0 +1,81 @@
+import { getBooleanFlagValue, isUpstreamEnvFlagEnabled, scanUpstreamGlobalFlagOccurrences, } from "./argv-grammar.js";
+import { isOpenNavigationCommand } from "./command-taxonomy.js";
+import { getAgentBrowserProcessEnvironment } from "./process-environment.js";
+const OPENAI_HOSTS = new Set(["chat.com", "chat.openai.com", "chatgpt.com"]);
+const DEFAULT_USER_AGENT_BY_PLATFORM = {
+    darwin: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36",
+    linux: "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36",
+    win32: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36",
+};
+const FALLBACK_USER_AGENT = "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36";
+export function getDefaultHeadlessCompatUserAgent(platform = process.platform) {
+    return DEFAULT_USER_AGENT_BY_PLATFORM[platform] ?? FALLBACK_USER_AGENT;
+}
+function hasLaunchOverride(args, env) {
+    const flags = ["--user-agent", "--args", "--cdp", "--provider", "-p"];
+    return (flags.some((flag) => args.some((token) => token === flag || token.startsWith(`${flag}=`))) ||
+        [
+            env.AGENT_BROWSER_SESSION,
+            env.AGENT_BROWSER_USER_AGENT,
+            env.AGENT_BROWSER_ARGS,
+            env.AGENT_BROWSER_CDP,
+            env.AGENT_BROWSER_PROVIDER,
+        ].some((value) => value !== undefined));
+}
+function hasInteractiveLaunchMode(args, env) {
+    const modes = [
+        ["--headed", env.AGENT_BROWSER_HEADED],
+        ["--auto-connect", env.AGENT_BROWSER_AUTO_CONNECT],
+    ];
+    return modes.some(([flag, value]) => getBooleanFlagValue(args, flag) ?? isUpstreamEnvFlagEnabled(value));
+}
+export function canUseHeadlessCompatibilityUserAgent(args, env = getAgentBrowserProcessEnvironment()) {
+    if (hasLaunchOverride(args, env)) {
+        return false;
+    }
+    if (hasInteractiveLaunchMode(args, env)) {
+        return false;
+    }
+    const engine = scanUpstreamGlobalFlagOccurrences(args, "--engine").at(-1)?.value ?? env.AGENT_BROWSER_ENGINE;
+    return (engine ?? "chrome") === "chrome" || engine === "";
+}
+function parseNavigationUrl(url) {
+    if (url === undefined || url.length === 0) {
+        return;
+    }
+    try {
+        return new URL(url);
+    }
+    catch {
+        try {
+            return new URL(`https://${url}`);
+        }
+        catch {
+            return;
+        }
+    }
+}
+export function getCompatibilityWorkaround(args, commandInfo) {
+    if (!isOpenNavigationCommand(commandInfo.command) ||
+        !canUseHeadlessCompatibilityUserAgent(args)) {
+        return;
+    }
+    const target = parseNavigationUrl(commandInfo.subcommand);
+    if (!target || !["http:", "https:"].includes(target.protocol)) {
+        return;
+    }
+    const hostname = target.hostname.toLowerCase();
+    if (hostname === "dash.cloudflare.com") {
+        return {
+            id: "cloudflare-headless-user-agent",
+            reason: "Cloudflare Dashboard challenges the default headless Chrome user agent; inject a normal Chrome user agent so authenticated headless browsing reaches the dashboard instead of Turnstile.",
+        };
+    }
+    if (!OPENAI_HOSTS.has(hostname)) {
+        return;
+    }
+    return {
+        id: "chatgpt-headless-user-agent",
+        reason: "OpenAI web properties currently challenge the default headless Chrome user agent; inject a normal Chrome user agent to preserve the default headless workflow without requiring headed mode or auto-connect.",
+    };
+}

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

@@ -0,0 +1 @@
+export {};