pi-agent-browser-native 0.2.48 → 0.2.49

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

@@ -0,0 +1,440 @@
+/**
+ * Purpose: Compile and analyze experimental DOM/source and network source lookup input modes.
+ * Responsibilities: Build lookup batches, collect DOM/React/workspace candidates, and redact network lookup surfaces.
+ * Scope: Source lookup and network source lookup only.
+ */
+import { readFile, readdir } from "node:fs/promises";
+import { extname, join } from "node:path";
+import { isRecord } from "../parsing.js";
+import { redactInvocationArgs, redactSensitiveText } from "../runtime.js";
+import { getBatchResultItems, validateLookupMaxWorkspaceFiles } from "./shared.js";
+import { SOURCE_LOOKUP_DEFAULT_MAX_WORKSPACE_FILES, SOURCE_LOOKUP_IGNORED_DIRECTORIES, SOURCE_LOOKUP_MAX_WORKSPACE_FILES, SOURCE_LOOKUP_WORKSPACE_EXTENSIONS, } from "./types.js";
+export function compileAgentBrowserSourceLookup(input) {
+    if (!isRecord(input)) {
+        return { error: "sourceLookup must be an object." };
+    }
+    const selector = input.selector;
+    const reactFiberId = input.reactFiberId;
+    const componentName = input.componentName;
+    if (selector !== undefined && (typeof selector !== "string" || selector.trim().length === 0)) {
+        return { error: "sourceLookup.selector must be a non-empty string when provided." };
+    }
+    if (reactFiberId !== undefined && (typeof reactFiberId !== "string" || reactFiberId.trim().length === 0)) {
+        return { error: "sourceLookup.reactFiberId must be a non-empty string when provided." };
+    }
+    if (componentName !== undefined && (typeof componentName !== "string" || componentName.trim().length === 0)) {
+        return { error: "sourceLookup.componentName must be a non-empty string when provided." };
+    }
+    if (selector === undefined && reactFiberId === undefined && componentName === undefined) {
+        return { error: "sourceLookup requires selector, reactFiberId, or componentName." };
+    }
+    if (input.includeDomHints !== undefined && typeof input.includeDomHints !== "boolean") {
+        return { error: "sourceLookup.includeDomHints must be a boolean when provided." };
+    }
+    const rawMaxWorkspaceFiles = input.maxWorkspaceFiles;
+    if (rawMaxWorkspaceFiles !== undefined && (typeof rawMaxWorkspaceFiles !== "number" || !Number.isInteger(rawMaxWorkspaceFiles) || rawMaxWorkspaceFiles <= 0)) {
+        return { error: "sourceLookup.maxWorkspaceFiles must be a positive integer when provided." };
+    }
+    if (typeof rawMaxWorkspaceFiles === "number" && rawMaxWorkspaceFiles > SOURCE_LOOKUP_MAX_WORKSPACE_FILES) {
+        return { error: `sourceLookup.maxWorkspaceFiles must be ${SOURCE_LOOKUP_MAX_WORKSPACE_FILES} or less.` };
+    }
+    const includeDomHints = input.includeDomHints !== false;
+    const maxWorkspaceFiles = rawMaxWorkspaceFiles ?? SOURCE_LOOKUP_DEFAULT_MAX_WORKSPACE_FILES;
+    const steps = [];
+    if (typeof selector === "string") {
+        steps.push({ action: "dom", args: ["is", "visible", selector] });
+        if (includeDomHints) {
+            steps.push({ action: "dom", args: ["get", "html", selector] });
+        }
+    }
+    if (typeof reactFiberId === "string") {
+        steps.push({ action: "react", args: ["react", "inspect", reactFiberId] });
+    }
+    if (typeof componentName === "string") {
+        steps.push({ action: "react", args: ["react", "tree"] });
+    }
+    return {
+        compiled: {
+            args: ["batch"],
+            query: { componentName, includeDomHints, maxWorkspaceFiles, reactFiberId, selector },
+            stdin: JSON.stringify(steps.map((step) => step.args)),
+            steps,
+        },
+    };
+}
+function extractStringField(value, names) {
+    for (const name of names) {
+        const field = value[name];
+        if (typeof field === "string" && field.trim().length > 0)
+            return field;
+    }
+    return undefined;
+}
+function extractNumberField(value, names) {
+    for (const name of names) {
+        const field = value[name];
+        if (typeof field === "number" && Number.isFinite(field))
+            return field;
+        if (typeof field === "string" && /^\d+$/.test(field))
+            return Number(field);
+    }
+    return undefined;
+}
+function candidateKey(candidate) {
+    return [candidate.source, candidate.file ?? "", candidate.line ?? "", candidate.column ?? "", candidate.componentName ?? ""].join(":");
+}
+function addSourceLookupCandidate(candidates, candidate) {
+    if (!candidates.some((existing) => candidateKey(existing) === candidateKey(candidate))) {
+        candidates.push(candidate);
+    }
+}
+function collectSourceCandidatesFromValue(value, source, candidates, evidence, depth = 0) {
+    if (depth > 6 || value === undefined || value === null)
+        return;
+    if (typeof value === "string") {
+        const sourcePattern = /([A-Za-z0-9_./@-]+\.(?:tsx|jsx|ts|js))(?:[:#](\d+))?(?:[:#](\d+))?/g;
+        for (const match of value.matchAll(sourcePattern)) {
+            addSourceLookupCandidate(candidates, {
+                column: match[3] ? Number(match[3]) : undefined,
+                confidence: source === "react-inspect" ? "high" : "medium",
+                evidence,
+                file: match[1],
+                line: match[2] ? Number(match[2]) : undefined,
+                source,
+            });
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)
+            collectSourceCandidatesFromValue(item, source, candidates, evidence, depth + 1);
+        return;
+    }
+    if (!isRecord(value))
+        return;
+    const file = extractStringField(value, ["file", "fileName", "filename", "filePath", "path", "source", "url"]);
+    if (file && /\.(?:tsx|jsx|ts|js)(?:$|[:?#])/.test(file)) {
+        addSourceLookupCandidate(candidates, {
+            column: extractNumberField(value, ["column", "columnNumber", "col"]),
+            confidence: source === "react-inspect" ? "high" : "medium",
+            evidence,
+            file,
+            line: extractNumberField(value, ["line", "lineNumber"]),
+            source,
+        });
+    }
+    for (const nested of Object.values(value)) {
+        collectSourceCandidatesFromValue(nested, source, candidates, evidence, depth + 1);
+    }
+}
+function getHtmlAttributeValue(html, name) {
+    const pattern = new RegExp(`${name}=["']([^"']+)["']`, "i");
+    return pattern.exec(html)?.[1];
+}
+function collectDomSourceCandidates(html, candidates) {
+    if (typeof html !== "string")
+        return;
+    const file = getHtmlAttributeValue(html, "(?:data-source-file|data-file|data-component-file|data-source)");
+    if (file && /\.(?:tsx|jsx|ts|js)$/.test(file)) {
+        const line = getHtmlAttributeValue(html, "(?:data-source-line|data-line)");
+        const column = getHtmlAttributeValue(html, "(?:data-source-column|data-column)");
+        addSourceLookupCandidate(candidates, {
+            column: column && /^\d+$/.test(column) ? Number(column) : undefined,
+            confidence: "medium",
+            evidence: ["selector HTML contained source-like data attributes"],
+            file,
+            line: line && /^\d+$/.test(line) ? Number(line) : undefined,
+            source: "dom-attribute",
+        });
+    }
+    collectSourceCandidatesFromValue(html, "dom-attribute", candidates, ["selector HTML contained source-like text"]);
+}
+async function walkWorkspaceSourceFiles(root, maxFiles) {
+    const files = [];
+    async function visit(directory) {
+        if (files.length >= maxFiles)
+            return;
+        let entries;
+        try {
+            entries = await readdir(directory, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (files.length >= maxFiles)
+                return;
+            const path = join(directory, entry.name);
+            if (entry.isDirectory()) {
+                if (!SOURCE_LOOKUP_IGNORED_DIRECTORIES.has(entry.name))
+                    await visit(path);
+            }
+            else if (entry.isFile() && SOURCE_LOOKUP_WORKSPACE_EXTENSIONS.has(extname(entry.name))) {
+                files.push(path);
+            }
+        }
+    }
+    await visit(root);
+    return files;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+async function collectWorkspaceComponentCandidates(query, cwd, candidates, limitations) {
+    if (!query.componentName)
+        return;
+    const files = await walkWorkspaceSourceFiles(cwd, query.maxWorkspaceFiles);
+    if (files.length >= query.maxWorkspaceFiles) {
+        limitations.push(`Workspace source scan stopped at ${query.maxWorkspaceFiles} files.`);
+    }
+    const componentPattern = new RegExp(`(?:function|class)\\s+${escapeRegExp(query.componentName)}\\b|(?:const|let|var)\\s+${escapeRegExp(query.componentName)}\\s*=|export\\s+default\\s+function\\s+${escapeRegExp(query.componentName)}\\b`);
+    for (const file of files) {
+        let text;
+        try {
+            text = await readFile(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const match = componentPattern.exec(text);
+        if (!match)
+            continue;
+        const line = text.slice(0, match.index).split("\n").length;
+        addSourceLookupCandidate(candidates, {
+            componentName: query.componentName,
+            confidence: "low",
+            evidence: [`local workspace contains a matching ${query.componentName} declaration`],
+            file,
+            line,
+            source: "workspace-search",
+        });
+        if (candidates.filter((candidate) => candidate.source === "workspace-search").length >= 10)
+            break;
+    }
+}
+export async function analyzeSourceLookupResults(data, compiled, cwd, context) {
+    const items = getBatchResultItems(data);
+    const candidates = [];
+    const limitations = [
+        "Experimental lookup only reports candidates with evidence; it cannot guarantee a DOM node maps to one source file.",
+        "React source hints require the page to be opened with --enable react-devtools and source information from the app build.",
+    ];
+    let unsupported = false;
+    for (const item of items) {
+        const command = Array.isArray(item.command) ? item.command : [];
+        const result = isRecord(item.result) && "data" in item.result ? item.result.data : item.result;
+        if (item.success === false && command[0] === "react")
+            unsupported = true;
+        if (command[0] === "react" && command[1] === "inspect") {
+            collectSourceCandidatesFromValue(result, "react-inspect", candidates, ["react inspect returned source-like metadata"]);
+        }
+        if (command[0] === "get" && command[1] === "html") {
+            collectDomSourceCandidates(result, candidates);
+        }
+    }
+    await collectWorkspaceComponentCandidates(compiled.query, cwd, candidates, limitations);
+    const status = candidates.length > 0 ? "candidates-found" : unsupported ? "unsupported" : "no-candidates";
+    const electronContext = status === "no-candidates" ? context?.electronContext : undefined;
+    const workspaceRoot = context?.workspaceRoot ?? cwd;
+    if (electronContext) {
+        limitations.push(`Workspace source scan is limited to the Pi tool session cwd: ${workspaceRoot}.`, "Packaged Electron app code may live inside installed app resources or app.asar outside the workspace; the wrapper does not unpack asar files or scan app bundle resources.");
+    }
+    return {
+        candidates,
+        electronContext,
+        limitations,
+        status,
+        summary: candidates.length > 0
+            ? `Source lookup found ${candidates.length} candidate location(s).`
+            : unsupported
+                ? "Source lookup could not inspect React metadata in this session."
+                : electronContext
+                    ? `Source lookup found no candidate locations. The workspace scan was limited to ${workspaceRoot}; packaged Electron app code may live outside that cwd in app resources or app.asar.`
+                    : "Source lookup found no candidate locations.",
+        workspaceRoot: electronContext ? workspaceRoot : undefined,
+    };
+}
+export function compileAgentBrowserNetworkSourceLookup(input) {
+    if (!isRecord(input))
+        return { error: "networkSourceLookup must be an object." };
+    const filter = input.filter;
+    const requestId = input.requestId;
+    const session = input.session;
+    const url = input.url;
+    if (filter !== undefined && (typeof filter !== "string" || filter.trim().length === 0))
+        return { error: "networkSourceLookup.filter must be a non-empty string when provided." };
+    if (requestId !== undefined && (typeof requestId !== "string" || requestId.trim().length === 0))
+        return { error: "networkSourceLookup.requestId must be a non-empty string when provided." };
+    if (session !== undefined && (typeof session !== "string" || session.trim().length === 0))
+        return { error: "networkSourceLookup.session must be a non-empty string when provided." };
+    if (url !== undefined && (typeof url !== "string" || url.trim().length === 0))
+        return { error: "networkSourceLookup.url must be a non-empty string when provided." };
+    if (filter === undefined && requestId === undefined && url === undefined)
+        return { error: "networkSourceLookup requires requestId, filter, or url." };
+    const maxWorkspaceFiles = validateLookupMaxWorkspaceFiles(input.maxWorkspaceFiles, "networkSourceLookup.maxWorkspaceFiles");
+    if (maxWorkspaceFiles.error)
+        return { error: maxWorkspaceFiles.error };
+    const steps = [];
+    if (typeof requestId === "string") {
+        steps.push({ action: "network", args: ["network", "request", requestId] });
+    }
+    const effectiveFilter = typeof filter === "string" ? filter : typeof url === "string" ? url : undefined;
+    if (effectiveFilter) {
+        steps.push({ action: "network", args: ["network", "requests", "--filter", effectiveFilter] });
+    }
+    const args = typeof session === "string" ? ["--session", session, "batch"] : ["batch"];
+    return { compiled: { args, query: { filter, maxWorkspaceFiles: maxWorkspaceFiles.value, requestId, session, url }, stdin: JSON.stringify(steps.map((step) => step.args)), steps } };
+}
+function getResultPayload(item) {
+    return isRecord(item.result) && "data" in item.result ? item.result.data : item.result;
+}
+function networkRequestMatchesQuery(url, queryText) {
+    return queryText === undefined || url === undefined || url.includes(queryText) || queryText.includes(url);
+}
+function isFailedNetworkRecord(request) {
+    const status = typeof request.status === "number" ? request.status : undefined;
+    const error = typeof request.error === "string" ? request.error : undefined;
+    return request.failed === true || error !== undefined || (status !== undefined && status >= 400);
+}
+function getFailedNetworkRequests(data, queryText) {
+    const failed = [];
+    for (const item of getBatchResultItems(data)) {
+        const payload = getResultPayload(item);
+        const requests = isRecord(payload) && Array.isArray(payload.requests) ? payload.requests : Array.isArray(payload) ? payload : isRecord(payload) ? [payload] : [];
+        for (const request of requests) {
+            if (!isRecord(request))
+                continue;
+            const url = typeof request.url === "string" ? request.url : undefined;
+            if (!networkRequestMatchesQuery(url, queryText) || !isFailedNetworkRecord(request))
+                continue;
+            failed.push({
+                error: typeof request.error === "string" ? request.error : undefined,
+                method: typeof request.method === "string" ? request.method : undefined,
+                requestId: typeof request.id === "string" ? request.id : typeof request.requestId === "string" ? request.requestId : undefined,
+                status: typeof request.status === "number" ? request.status : undefined,
+                url,
+            });
+        }
+    }
+    return failed;
+}
+function addNetworkCandidate(candidates, candidate) {
+    const key = [candidate.source, candidate.file ?? "", candidate.line ?? "", candidate.requestUrl ?? ""].join(":");
+    if (!candidates.some((existing) => [existing.source, existing.file ?? "", existing.line ?? "", existing.requestUrl ?? ""].join(":") === key))
+        candidates.push(candidate);
+}
+function collectInitiatorCandidates(data, failedRequests, candidates) {
+    const failedRequestIds = new Set(failedRequests.map((request) => request.requestId).filter((value) => value !== undefined));
+    const failedRequestUrls = new Set(failedRequests.map((request) => request.url).filter((value) => value !== undefined));
+    for (const item of getBatchResultItems(data)) {
+        const payload = getResultPayload(item);
+        const requestValues = isRecord(payload) && Array.isArray(payload.requests) ? payload.requests : [payload];
+        for (const value of requestValues) {
+            if (!isRecord(value))
+                continue;
+            const requestUrl = typeof value.url === "string" ? value.url : undefined;
+            const requestId = typeof value.id === "string" ? value.id : typeof value.requestId === "string" ? value.requestId : undefined;
+            const correlatesWithFailedRequest = (requestId !== undefined && failedRequestIds.has(requestId)) || (requestUrl !== undefined && failedRequestUrls.has(requestUrl));
+            if (!correlatesWithFailedRequest && !isFailedNetworkRecord(value))
+                continue;
+            for (const field of [value.initiator, value.stack, value.source, value.trace]) {
+                const localCandidates = [];
+                collectSourceCandidatesFromValue(field, "dom-attribute", localCandidates, ["failed network request included source-like initiator metadata"]);
+                for (const candidate of localCandidates) {
+                    addNetworkCandidate(candidates, { confidence: "medium", evidence: candidate.evidence, file: candidate.file, line: candidate.line, requestUrl, source: "initiator" });
+                }
+            }
+        }
+    }
+}
+async function collectWorkspaceRequestCandidates(query, failedRequests, cwd, candidates, limitations) {
+    const needles = [...new Set([query.url, query.filter, ...failedRequests.map((request) => request.url)].filter((value) => typeof value === "string" && value.length > 0).flatMap((value) => {
+            try {
+                const parsed = new URL(value);
+                return [value, parsed.pathname].filter((item) => item && item !== "/");
+            }
+            catch {
+                return [value];
+            }
+        }))].slice(0, 8);
+    if (needles.length === 0)
+        return;
+    const files = await walkWorkspaceSourceFiles(cwd, query.maxWorkspaceFiles);
+    if (files.length >= query.maxWorkspaceFiles)
+        limitations.push(`Workspace source scan stopped at ${query.maxWorkspaceFiles} files.`);
+    for (const file of files) {
+        let text;
+        try {
+            text = await readFile(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const needle of needles) {
+            const index = text.indexOf(needle);
+            if (index === -1)
+                continue;
+            addNetworkCandidate(candidates, { confidence: "low", evidence: [`local workspace contains request URL literal ${needle}`], file, line: text.slice(0, index).split("\n").length, requestUrl: needle, source: "workspace-search" });
+            if (candidates.filter((candidate) => candidate.source === "workspace-search").length >= 10)
+                return;
+        }
+    }
+}
+export function redactNetworkSourceLookupUrl(value) {
+    if (!value)
+        return value;
+    try {
+        const isRelative = value.startsWith("/");
+        const url = new URL(value, isRelative ? "https://redacted.invalid" : undefined);
+        url.username = url.username ? "[REDACTED]" : "";
+        url.password = url.password ? "[REDACTED]" : "";
+        for (const key of [...url.searchParams.keys()]) {
+            url.searchParams.set(key, "[REDACTED]");
+        }
+        if (/(?:token|secret|password|passwd|pwd|key|auth|session|jwt|credential)/i.test(url.hash)) {
+            url.hash = "#[REDACTED]";
+        }
+        return isRelative ? `${url.pathname}${url.search}${url.hash}` : url.toString();
+    }
+    catch {
+        return redactSensitiveText(value
+            .replace(/([a-z][a-z0-9+.-]*:\/\/)\S+:\S+@/gi, "$1[REDACTED]@")
+            .replace(/([?&][^=]+)=([^&#\s"'\]]+)/g, "$1=[REDACTED]"));
+    }
+}
+export function redactNetworkSourceLookupArgs(args) {
+    return redactInvocationArgs(args).map((arg) => redactNetworkSourceLookupUrl(arg) ?? arg);
+}
+export function redactNetworkSourceLookupSurface(value) {
+    if (typeof value === "string")
+        return redactNetworkSourceLookupUrl(value) ?? value;
+    if (Array.isArray(value))
+        return value.map((item) => redactNetworkSourceLookupSurface(item));
+    if (!isRecord(value))
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, redactNetworkSourceLookupSurface(item)]));
+}
+export function redactNetworkSourceLookupAnalysis(analysis) {
+    return {
+        ...analysis,
+        candidates: analysis.candidates.map((candidate) => ({
+            ...candidate,
+            evidence: candidate.evidence.map((item) => redactNetworkSourceLookupUrl(item) ?? redactSensitiveText(item)),
+            file: redactNetworkSourceLookupUrl(candidate.file),
+            requestUrl: redactNetworkSourceLookupUrl(candidate.requestUrl),
+        })),
+        failedRequests: analysis.failedRequests.map((request) => ({ ...request, error: redactNetworkSourceLookupUrl(request.error), url: redactNetworkSourceLookupUrl(request.url) })),
+    };
+}
+export async function analyzeNetworkSourceLookupResults(data, compiled, cwd) {
+    const limitations = [
+        "Experimental network source hints report candidates only; failed requests can be triggered indirectly by frameworks, caches, service workers, or third-party scripts.",
+        "Initiator/source-map metadata is upstream/browser-build dependent and may be absent.",
+    ];
+    const failedRequests = getFailedNetworkRequests(data, compiled.query.url ?? compiled.query.filter);
+    const candidates = [];
+    collectInitiatorCandidates(data, failedRequests, candidates);
+    await collectWorkspaceRequestCandidates(compiled.query, failedRequests, cwd, candidates, limitations);
+    const status = failedRequests.length === 0 ? "no-failed-requests" : candidates.length > 0 ? "failed-requests-found" : "no-candidates";
+    return { candidates, failedRequests, limitations, status, summary: failedRequests.length === 0 ? "Network source lookup found no failed requests." : candidates.length > 0 ? `Network source lookup found ${failedRequests.length} failed request(s) and ${candidates.length} candidate source hint(s).` : `Network source lookup found ${failedRequests.length} failed request(s) but no source candidates.` };
+}

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

@@ -0,0 +1,164 @@
+/**
+ * Purpose: Define the Pi tool input schema for the native agent_browser wrapper.
+ * Responsibilities: Keep TypeBox schema construction separate from runtime execution and input-mode compilers.
+ * Scope: Schema-only; behavioral validation lives in the mode compilers.
+ */
+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";
+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.",
+            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 })),
+        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." })),
+            }, { 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." })),
+            }, { 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." })),
+        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." })),
+        networkSourceLookup: Type.Optional(Type.Object({
+            filter: Type.Optional(Type.String({ description: "Optional upstream network requests filter pattern." })),
+            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." })),
+        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 })),
+            }, { additionalProperties: false }),
+            Type.Object({
+                action: StringEnum(["launch"], { description: "Launch an Electron app with an isolated wrapper-owned profile." }),
+                appPath: Type.String({ description: "Electron launch target: macOS .app bundle path. Exactly one launch target is required for electron.launch.", minLength: 1 }),
+                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." })),
+            }, { additionalProperties: false }),
+            Type.Object({
+                action: StringEnum(["launch"], { description: "Launch an Electron app with an isolated wrapper-owned profile." }),
+                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 }),
+                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." })),
+            }, { additionalProperties: false }),
+            Type.Object({
+                action: StringEnum(["launch"], { description: "Launch an Electron app with an isolated wrapper-owned profile." }),
+                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 }),
+                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." })),
+            }, { additionalProperties: false }),
+            Type.Object({
+                action: StringEnum(["launch"], { description: "Launch an Electron app with an isolated wrapper-owned profile." }),
+                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 }),
+                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." })),
+            }, { additionalProperties: false }),
+            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 })),
+            }, { 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 })),
+            }, { 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 })),
+            }, { 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 })),
+            }, { additionalProperties: false }),
+        ], { description: "Electron wrapper action. Fields are action-specific and unsupported fields are 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." })),
+            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." })),
+            }, { 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 })),
+        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 --profile, --executable-path, --session-name, --cdp, --state, --auto-connect, --init-script, --enable, -p/--provider, or iOS --device apply and later auto calls follow the new browser.",
+            default: DEFAULT_SESSION_MODE,
+        })),
+    }, { additionalProperties: false });
+}
+export const AGENT_BROWSER_PARAMS = createAgentBrowserParamsSchema();