pi-agent-browser-native 0.2.48 → 0.2.49

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

@@ -0,0 +1,119 @@
+/**
+ * Purpose: Compile semanticAction shorthand inputs into upstream agent-browser commands.
+ * Responsibilities: Validate shorthand locator/action fields and expose compiled-command helpers.
+ * Scope: semanticAction mode only.
+ */
+import { isRecord } from "../parsing.js";
+import { getSelectValues } from "./shared.js";
+import { AGENT_BROWSER_SEMANTIC_ACTIONS, AGENT_BROWSER_SEMANTIC_LOCATORS, } from "./types.js";
+export function getCompiledSemanticActionCommandIndex(compiled) {
+    return compiled.args[0] === "--session" ? 2 : 0;
+}
+export function getCompiledSemanticActionSessionPrefix(compiled) {
+    const commandIndex = getCompiledSemanticActionCommandIndex(compiled);
+    return commandIndex > 0 ? compiled.args.slice(0, commandIndex) : [];
+}
+export function isCompiledSemanticActionFindCommand(compiled) {
+    if (!compiled)
+        return false;
+    return compiled.args[getCompiledSemanticActionCommandIndex(compiled)] === "find";
+}
+export function compileAgentBrowserSemanticAction(input) {
+    if (!isRecord(input)) {
+        return { error: "semanticAction must be an object." };
+    }
+    const action = input.action;
+    const locator = input.locator;
+    const value = input.value;
+    const values = input.values;
+    const selector = input.selector;
+    const text = input.text;
+    const role = input.role;
+    const name = input.name;
+    const session = input.session;
+    if (typeof action !== "string" || !AGENT_BROWSER_SEMANTIC_ACTIONS.includes(action)) {
+        return { error: `semanticAction.action must be one of: ${AGENT_BROWSER_SEMANTIC_ACTIONS.join(", ")}.` };
+    }
+    if (session !== undefined && (typeof session !== "string" || session.trim().length === 0)) {
+        return { error: "semanticAction.session must be a non-empty string when provided." };
+    }
+    if (action === "select") {
+        if (locator !== undefined || role !== undefined || name !== undefined) {
+            return { error: "semanticAction.locator, role, and name are not supported for select; use selector plus value or values." };
+        }
+        if (text !== undefined) {
+            return { error: "semanticAction.text is not supported for select; use value or values for option values." };
+        }
+        if (typeof selector !== "string" || selector.trim().length === 0) {
+            return { error: "semanticAction.selector is required for select." };
+        }
+        const selectedValues = getSelectValues(input, "semanticAction");
+        if (selectedValues.error)
+            return { error: selectedValues.error };
+        const args = typeof session === "string" ? ["--session", session, "select", selector, ...selectedValues.values] : ["select", selector, ...selectedValues.values];
+        return { compiled: { action: "select", selector, values: selectedValues.values, args } };
+    }
+    if (values !== undefined) {
+        return { error: "semanticAction.values is only supported for select actions." };
+    }
+    if (selector !== undefined) {
+        if (typeof selector !== "string" || selector.trim().length === 0) {
+            return { error: "semanticAction.selector must be a non-empty string when provided." };
+        }
+        if (locator !== undefined || value !== undefined || role !== undefined || name !== undefined) {
+            return { error: "semanticAction.selector cannot be combined with locator, value, role, or name; use selector for a direct click/check/fill target or locator fields for find-based actions." };
+        }
+        if (text !== undefined && typeof text !== "string") {
+            return { error: "semanticAction.text must be a string when provided." };
+        }
+        if (action === "fill" && (typeof text !== "string" || text.length === 0)) {
+            return { error: `semanticAction.text is required for ${action}.` };
+        }
+        if (action !== "fill" && text !== undefined) {
+            return { error: "semanticAction.text is only supported for fill actions." };
+        }
+        const directArgs = typeof session === "string" ? ["--session", session, action, selector] : [action, selector];
+        if (action === "fill")
+            directArgs.push(text);
+        return { compiled: { action: action, selector, args: directArgs } };
+    }
+    if (typeof locator !== "string" || !AGENT_BROWSER_SEMANTIC_LOCATORS.includes(locator)) {
+        return { error: `semanticAction.locator must be one of: ${AGENT_BROWSER_SEMANTIC_LOCATORS.join(", ")}.` };
+    }
+    if (value !== undefined && (typeof value !== "string" || value.trim().length === 0)) {
+        return { error: "semanticAction.value must be a non-empty string when provided." };
+    }
+    if (role !== undefined && (typeof role !== "string" || role.trim().length === 0)) {
+        return { error: "semanticAction.role must be a non-empty string when provided." };
+    }
+    const locatorValue = locator === "role" && typeof role === "string" ? role : value;
+    if (typeof locatorValue !== "string" || locatorValue.trim().length === 0) {
+        return { error: locator === "role" ? "semanticAction.value or semanticAction.role must be a non-empty string for locator=role." : "semanticAction.value must be a non-empty string." };
+    }
+    if (text !== undefined && typeof text !== "string") {
+        return { error: "semanticAction.text must be a string when provided." };
+    }
+    if (action === "fill" && (typeof text !== "string" || text.length === 0)) {
+        return { error: `semanticAction.text is required for ${action}.` };
+    }
+    if (action !== "fill" && text !== undefined) {
+        return { error: "semanticAction.text is only supported for fill actions." };
+    }
+    if (role !== undefined && locator !== "role") {
+        return { error: "semanticAction.role is only supported for locator=role." };
+    }
+    if (role !== undefined && value !== undefined && role !== value) {
+        return { error: "semanticAction.role must match value when both are provided for locator=role." };
+    }
+    if (name !== undefined && (locator !== "role" || typeof name !== "string" || name.length === 0)) {
+        return { error: "semanticAction.name is only supported as a non-empty string for locator=role." };
+    }
+    const args = typeof session === "string" ? ["--session", session, "find", locator, locatorValue, action] : ["find", locator, locatorValue, action];
+    if (action === "fill") {
+        args.push(text);
+    }
+    if (locator === "role" && typeof name === "string") {
+        args.push("--name", name);
+    }
+    return { compiled: { action: action, locator: locator, args } };
+}

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

@@ -0,0 +1,42 @@
+/**
+ * Purpose: Hold tiny shared parsing helpers for structured agent_browser input modes.
+ * Responsibilities: Normalize common select values, batch result rows, and workspace scan limits.
+ * Scope: Generic input-mode helpers only; mode-specific policy stays in the owning module.
+ */
+import { isRecord } from "../parsing.js";
+import { SOURCE_LOOKUP_DEFAULT_MAX_WORKSPACE_FILES, SOURCE_LOOKUP_MAX_WORKSPACE_FILES } from "./types.js";
+export function getSelectValues(input, context) {
+    const rawValue = input.value;
+    const rawValues = input.values;
+    if (rawValue !== undefined && rawValues !== undefined) {
+        return { error: `${context}.value and ${context}.values cannot both be provided for select.` };
+    }
+    if (rawValues !== undefined) {
+        if (!Array.isArray(rawValues) || rawValues.length === 0 || rawValues.some((value) => typeof value !== "string" || value.trim().length === 0)) {
+            return { error: `${context}.values must be a non-empty array of non-empty strings for select.` };
+        }
+        return { values: rawValues };
+    }
+    if (typeof rawValue === "string" && rawValue.trim().length > 0) {
+        return { values: [rawValue] };
+    }
+    return { error: `${context}.value or ${context}.values is required for select.` };
+}
+export function getBatchResultItems(data) {
+    return Array.isArray(data) ? data.filter(isRecord) : [];
+}
+export function getCommandNameFromBatchItem(item) {
+    const command = item.command;
+    return Array.isArray(command) && typeof command[0] === "string" ? command[0] : undefined;
+}
+export function validateLookupMaxWorkspaceFiles(value, fieldName) {
+    if (value === undefined)
+        return { value: SOURCE_LOOKUP_DEFAULT_MAX_WORKSPACE_FILES };
+    if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+        return { error: `${fieldName} must be a positive integer when provided.` };
+    }
+    if (value > SOURCE_LOOKUP_MAX_WORKSPACE_FILES) {
+        return { error: `${fieldName} must be ${SOURCE_LOOKUP_MAX_WORKSPACE_FILES} or less.` };
+    }
+    return { value };
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Purpose: Define structured agent_browser input-mode constants and TypeScript contracts.
+ * Responsibilities: Share schema enums and compiled input-mode result types across input-mode modules.
+ * Scope: Types and constants only; validation and compilation live in sibling modules.
+ */
+export const DEFAULT_SESSION_MODE = "auto";
+export const AGENT_BROWSER_SEMANTIC_ACTIONS = ["check", "click", "fill", "select"];
+export const AGENT_BROWSER_SEMANTIC_LOCATORS = ["alt", "label", "placeholder", "role", "testid", "text", "title"];
+export const AGENT_BROWSER_JOB_TYPE_DELAYED_TEXT_MAX_CHARACTERS = 200;
+export const AGENT_BROWSER_JOB_STEP_ACTIONS = ["open", "click", "fill", "type", "select", "wait", "assertText", "assertUrl", "waitForDownload", "screenshot", "snapshot"];
+export const AGENT_BROWSER_QA_LOAD_STATES = ["domcontentloaded", "load", "networkidle"];
+export const AGENT_BROWSER_ELECTRON_ACTIONS = ["list", "launch", "status", "cleanup", "probe"];
+export const AGENT_BROWSER_ELECTRON_HANDOFFS = ["connect", "tabs", "snapshot"];
+export const AGENT_BROWSER_ELECTRON_TARGET_TYPES = ["page", "webview", "any"];
+export const AGENT_BROWSER_ELECTRON_LIST_FIELDS = new Set(["action", "query", "maxResults"]);
+export const AGENT_BROWSER_ELECTRON_PROBE_FIELDS = new Set(["action", "launchId", "timeoutMs"]);
+export const AGENT_BROWSER_ELECTRON_RESERVED_APP_ARGS = ["--user-data-dir", "--remote-debugging-port", "--remote-debugging-address", "--remote-debugging-pipe"];
+export const SOURCE_LOOKUP_WORKSPACE_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx"]);
+export const SOURCE_LOOKUP_IGNORED_DIRECTORIES = new Set([".git", "node_modules", "dist", "build", "coverage", ".next", "out", "tmp", "temp"]);
+export const SOURCE_LOOKUP_DEFAULT_MAX_WORKSPACE_FILES = 2_000;
+export const SOURCE_LOOKUP_MAX_WORKSPACE_FILES = 5_000;

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

@@ -0,0 +1,10 @@
+/**
+ * Purpose: Re-export focused input-mode schema, compiler, and analysis modules for the agent_browser wrapper.
+ * Responsibilities: Preserve the extension entrypoint's import surface while keeping input-mode code split by concern.
+ * Scope: Barrel only; add behavior to focused files under ./input-modes/.
+ */
+export { AGENT_BROWSER_PARAMS } from "./input-modes/params.js";
+export { analyzeQaPresetResults, analyzeQaPresetTimeout, buildQaCompactPassText, compileAgentBrowserJob, compileAgentBrowserQaPreset, extractQaPageContext, isHttpOrHttpsUrl, } from "./input-modes/job.js";
+export { analyzeNetworkSourceLookupResults, analyzeSourceLookupResults, compileAgentBrowserNetworkSourceLookup, compileAgentBrowserSourceLookup, redactNetworkSourceLookupAnalysis, redactNetworkSourceLookupArgs, redactNetworkSourceLookupSurface, redactNetworkSourceLookupUrl, } from "./input-modes/lookups.js";
+export { compileAgentBrowserElectron } from "./input-modes/electron.js";
+export { compileAgentBrowserSemanticAction, getCompiledSemanticActionCommandIndex, getCompiledSemanticActionSessionPrefix, isCompiledSemanticActionFindCommand, } from "./input-modes/semantic-action.js";

package/dist/extensions/agent-browser/lib/json-schema.js

@@ -0,0 +1,58 @@
+/**
+ * Purpose: Build the small JSON Schema subset used by Pi tool schemas without importing TypeBox at runtime.
+ * Responsibilities: Preserve plain JSON Schema objects Pi consumes while keeping extension startup cheap.
+ * Scope: Schema construction only; runtime validation still belongs to Pi and the tool input compilers.
+ */
+const OPTIONAL_SCHEMA = Symbol("pi-agent-browser-optional-schema");
+function withOptions(schema, options) {
+    return { ...schema, ...(options ?? {}) };
+}
+function literalType(value) {
+    const valueType = typeof value;
+    return valueType === "string" || valueType === "number" || valueType === "boolean" ? valueType : undefined;
+}
+function propertySchema(schema) {
+    const clone = { ...schema };
+    delete clone[OPTIONAL_SCHEMA];
+    return clone;
+}
+export const JsonSchema = {
+    Array(items, options) {
+        return withOptions({ type: "array", items }, options);
+    },
+    Boolean(options) {
+        return withOptions({ type: "boolean" }, options);
+    },
+    Integer(options) {
+        return withOptions({ type: "integer" }, options);
+    },
+    Literal(value, options) {
+        const type = literalType(value);
+        return withOptions(type ? { type, const: value } : { const: value }, options);
+    },
+    Number(options) {
+        return withOptions({ type: "number" }, options);
+    },
+    Object(properties, options) {
+        const required = globalThis.Object.entries(properties)
+            .filter(([, schema]) => schema[OPTIONAL_SCHEMA] !== true)
+            .map(([key]) => key);
+        return withOptions({
+            type: "object",
+            properties: globalThis.Object.fromEntries(globalThis.Object.entries(properties).map(([key, schema]) => [key, propertySchema(schema)])),
+            ...(required.length > 0 ? { required } : {}),
+        }, options);
+    },
+    Optional(schema) {
+        return { ...schema, [OPTIONAL_SCHEMA]: true };
+    },
+    String(options) {
+        return withOptions({ type: "string" }, options);
+    },
+    Union(types, options) {
+        return withOptions({ anyOf: types }, options);
+    },
+    Unsafe(schema) {
+        return schema;
+    },
+};

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

@@ -0,0 +1,59 @@
+/**
+ * Purpose: Canonical launch-scoped agent-browser flag metadata shared by runtime planning and agent-facing guidance.
+ * Responsibilities: Define which upstream flags require a fresh launch, explain why, and expose stable guidance labels.
+ * Scope: Metadata only; argv parsing and execution planning live in runtime.ts.
+ */
+export const LAUNCH_SCOPED_FLAG_DEFINITIONS = [
+    {
+        flag: "--auto-connect",
+        reason: "attaches to an already-running browser at launch time instead of reusing an existing named session",
+    },
+    {
+        flag: "--cdp",
+        reason: "selects the browser/CDP endpoint used when an upstream session is launched",
+    },
+    {
+        flag: "--enable",
+        reason: "selects built-in page init scripts before the upstream browser session is launched",
+    },
+    {
+        flag: "--executable-path",
+        reason: "selects the browser executable used for the upstream launch",
+    },
+    {
+        flag: "--init-script",
+        reason: "registers page init scripts before the upstream browser session is launched",
+    },
+    {
+        flag: "--device",
+        reason: "selects the provider device for the upstream launch",
+    },
+    {
+        flag: "--profile",
+        reason: "selects Chrome profile state for the upstream launch",
+    },
+    {
+        flag: "--provider",
+        reason: "selects the upstream browser provider for the launch",
+    },
+    {
+        flag: "-p",
+        reason: "selects the upstream browser provider for the launch",
+    },
+    {
+        flag: "--session-name",
+        reason: "selects upstream saved auth/session state for the launch",
+    },
+    {
+        flag: "--state",
+        reason: "loads persisted upstream browser/auth state at launch time",
+    },
+];
+export const LAUNCH_SCOPED_FLAGS = LAUNCH_SCOPED_FLAG_DEFINITIONS.map((definition) => definition.flag);
+export const LAUNCH_SCOPED_FLAG_LABEL = LAUNCH_SCOPED_FLAGS.join(", ");
+/**
+ * The subset of launch-scoped flags that can restore browser/auth state with pre-existing tabs
+ * and are plausible wrong-active-tab sources after a fresh launch. These trigger post-open
+ * tab-correction (the `tab list` + re-select cycle).
+ */
+export const LAUNCH_SCOPED_TAB_CORRECTION_FLAGS = new Set(["--profile", "--session-name", "--state"]);

package/dist/extensions/agent-browser/lib/navigation-policy.js

@@ -0,0 +1,83 @@
+/**
+ * Purpose: Keep wrapper-side navigation policy parsing and evaluation small and explicit.
+ * Responsibilities: Parse allowed-domain argv values and detect final-page host escapes.
+ * Scope: Wrapper diagnostics only; upstream remains responsible for browser-time enforcement.
+ */
+function normalizeDomainEntry(value) {
+    let candidate = value.trim().toLowerCase();
+    if (!candidate)
+        return undefined;
+    try {
+        if (/^[a-z][a-z0-9+.-]*:\/\//i.test(candidate)) {
+            candidate = new URL(candidate).hostname;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    candidate = candidate.replace(/^\*\./, "").replace(/\.$/, "");
+    if (candidate.includes("/"))
+        candidate = candidate.split("/")[0] ?? "";
+    if (candidate.includes(":"))
+        candidate = candidate.split(":")[0] ?? "";
+    return candidate.length > 0 ? candidate : undefined;
+}
+function splitAllowedDomainsValue(value) {
+    return value.split(/[,\s]+/).map((entry) => entry.trim()).filter(Boolean);
+}
+export function parseAllowedDomainsPolicyFromArgs(args) {
+    const domains = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--allowed-domains") {
+            const value = args[index + 1];
+            if (value && !value.startsWith("-")) {
+                domains.push(...splitAllowedDomainsValue(value));
+                index += 1;
+            }
+            continue;
+        }
+        if (arg?.startsWith("--allowed-domains=")) {
+            domains.push(...splitAllowedDomainsValue(arg.slice("--allowed-domains=".length)));
+        }
+    }
+    const allowedDomains = [...new Set(domains.flatMap((domain) => {
+            const normalized = normalizeDomainEntry(domain);
+            return normalized ? [normalized] : [];
+        }))];
+    if (allowedDomains.length === 0)
+        return undefined;
+    return { allowedDomains, display: allowedDomains.join(", ") };
+}
+function normalizeObservedHost(url) {
+    try {
+        const parsed = new URL(url);
+        if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+            return undefined;
+        return parsed.hostname.toLowerCase().replace(/\.$/, "");
+    }
+    catch {
+        return undefined;
+    }
+}
+export function isHostAllowedByDomains(host, allowedDomains) {
+    const normalizedHost = host.toLowerCase().replace(/\.$/, "");
+    return allowedDomains.some((domain) => normalizedHost === domain || normalizedHost.endsWith(`.${domain}`));
+}
+export function getAllowedDomainsViolation(options) {
+    if (!options.policy || !options.url)
+        return undefined;
+    const observedHost = normalizeObservedHost(options.url);
+    if (!observedHost)
+        return undefined;
+    if (isHostAllowedByDomains(observedHost, options.policy.allowedDomains))
+        return undefined;
+    const summary = `Navigation policy blocked: --allowed-domains ${options.policy.display} does not allow ${observedHost} (${options.url}).`;
+    return {
+        allowedDomains: options.policy.allowedDomains,
+        allowedDisplay: options.policy.display,
+        observedHost,
+        observedUrl: options.url,
+        summary,
+    };
+}

package/dist/extensions/agent-browser/lib/orchestration/batch-stdin.js

@@ -0,0 +1,62 @@
+function validateUserBatchStep(step, index) {
+    if (!Array.isArray(step)) {
+        return {
+            error: `agent_browser batch stdin step ${index} must be a non-empty array of string command tokens.`,
+            ok: false,
+        };
+    }
+    if (step.length === 0) {
+        return {
+            error: `agent_browser batch stdin step ${index} must not be empty.`,
+            ok: false,
+        };
+    }
+    const invalidTokenIndex = step.findIndex((token) => typeof token !== "string");
+    if (invalidTokenIndex !== -1) {
+        return {
+            error: `agent_browser batch stdin step ${index} token ${invalidTokenIndex} must be a string.`,
+            ok: false,
+        };
+    }
+    return { ok: true, step: step };
+}
+export function parseBatchStdinJsonArray(stdin) {
+    if (stdin === undefined) {
+        return { steps: [] };
+    }
+    try {
+        const parsed = JSON.parse(stdin);
+        if (!Array.isArray(parsed)) {
+            return { error: "agent_browser batch stdin must be a JSON array of command steps." };
+        }
+        return { steps: parsed };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { error: `agent_browser batch stdin could not be parsed as JSON: ${message}` };
+    }
+}
+export function parseUserBatchStdin(stdin) {
+    const parsed = parseBatchStdinJsonArray(stdin);
+    if (parsed.error || parsed.steps === undefined) {
+        return parsed.error ? { error: parsed.error } : { steps: [] };
+    }
+    const steps = [];
+    for (const [index, rawStep] of parsed.steps.entries()) {
+        const validated = validateUserBatchStep(rawStep, index);
+        if (!validated.ok) {
+            return { error: validated.error };
+        }
+        steps.push(validated.step);
+    }
+    return { steps };
+}
+export function parseValidBatchStepEntries(stdin) {
+    const parsed = parseBatchStdinJsonArray(stdin);
+    if (parsed.error || parsed.steps === undefined)
+        return [];
+    return parsed.steps.flatMap((step, index) => {
+        const validated = validateUserBatchStep(step, index);
+        return validated.ok ? [{ index, step: validated.step }] : [];
+    });
+}

package/dist/extensions/agent-browser/lib/orchestration/browser-run/artifact-paths.js

@@ -0,0 +1,39 @@
+import { extname, isAbsolute } from "node:path";
+const SCREENSHOT_VALUE_FLAGS = new Set(["--screenshot-dir", "--screenshot-format", "--screenshot-quality"]);
+const SCREENSHOT_IMAGE_EXTENSIONS = new Set([".jpeg", ".jpg", ".png", ".webp"]);
+function isImagePathToken(token) {
+    const extension = extname(token).toLowerCase();
+    return SCREENSHOT_IMAGE_EXTENSIONS.has(extension);
+}
+export function getScreenshotPathTokenIndex(commandTokens) {
+    if (commandTokens[0] !== "screenshot") {
+        return undefined;
+    }
+    const positionalIndices = [];
+    for (let index = 1; index < commandTokens.length; index += 1) {
+        const token = commandTokens[index];
+        if (token === "--") {
+            for (let positionalIndex = index + 1; positionalIndex < commandTokens.length; positionalIndex += 1) {
+                positionalIndices.push(positionalIndex);
+            }
+            break;
+        }
+        if (token.startsWith("-")) {
+            const normalizedToken = token.split("=", 1)[0] ?? token;
+            if (SCREENSHOT_VALUE_FLAGS.has(normalizedToken) && !token.includes("=")) {
+                index += 1;
+            }
+            continue;
+        }
+        positionalIndices.push(index);
+    }
+    if (positionalIndices.length === 0) {
+        return undefined;
+    }
+    const candidateIndex = positionalIndices[positionalIndices.length - 1];
+    const candidate = commandTokens[candidateIndex];
+    if (positionalIndices.length >= 2 || isImagePathToken(candidate) || isAbsolute(candidate) || candidate.startsWith("./") || candidate.startsWith("../")) {
+        return candidateIndex;
+    }
+    return undefined;
+}