pi-agent-browser-native 0.2.77 → 0.5.0

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

@@ -1,39 +1,24 @@
-/**
- * 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 { AGENT_BROWSER_SCRIPT_CODE_MAX_BYTES } from "./script.js";
 import { ELECTRON_DISCOVERY_DEFAULT_MAX_RESULTS, ELECTRON_DISCOVERY_MAX_RESULTS, } from "../electron/discovery.js";
 import { AGENT_BROWSER_ELECTRON_HANDOFFS, AGENT_BROWSER_ELECTRON_TARGET_TYPES, AGENT_BROWSER_JOB_STEP_ACTIONS, AGENT_BROWSER_JOB_TYPE_DELAYED_TEXT_MAX_CHARACTERS, AGENT_BROWSER_QA_LOAD_STATES, AGENT_BROWSER_SEMANTIC_ACTIONS, AGENT_BROWSER_SEMANTIC_LOCATORS, DEFAULT_SESSION_MODE, SOURCE_LOOKUP_MAX_WORKSPACE_FILES, } from "./types.js";
 // Keep descriptions terse: Pi sends this schema every turn; workflows belong in prompt guidance and docs.
-// ponytail: the four electron.launch variants differ only in their single target field
-// (appPath/appName/bundleId/executablePath); the action literal and shared launch fields
-// are identical, so this helper keeps the schema variants in sync.
-function electronLaunchVariant(Type, StringEnum, targetField) {
-    return Type.Object({
-        action: StringEnum(["launch"]),
-        ...targetField,
-        appArgs: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
-        handoff: Type.Optional(StringEnum(AGENT_BROWSER_ELECTRON_HANDOFFS)),
-        targetType: Type.Optional(StringEnum(AGENT_BROWSER_ELECTRON_TARGET_TYPES)),
-        timeoutMs: Type.Optional(Type.Integer({ minimum: 1 })),
-        allow: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
-        deny: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
-    }, { additionalProperties: false });
-}
 export function createAgentBrowserParamsSchema(Type = JsonSchema, StringEnum = localStringEnum) {
     return Type.Object({
+        script: Type.Optional(Type.String({
+            description: "One-shot JavaScript orchestration with async browser({ args, stdin?, timeoutMs? }) and emit(value); isolated session and no host access.",
+            maxLength: AGENT_BROWSER_SCRIPT_CODE_MAX_BYTES,
+        })),
         args: Type.Optional(Type.Array(Type.String(), {
             description: "Raw agent-browser argv only: no binary, shell operators, or --json. Start with open → snapshot -i → act on current @refs; re-snapshot after page changes.",
             minItems: 1,
         })),
         semanticAction: Type.Optional(Type.Object({
             action: StringEnum(AGENT_BROWSER_SEMANTIC_ACTIONS),
-            locator: Type.Optional(StringEnum(AGENT_BROWSER_SEMANTIC_LOCATORS, { description: "Locator for check/click/fill." })),
-            value: Type.Optional(Type.String({ description: "Locator value, or one select option." })),
-            values: Type.Optional(Type.Array(Type.String(), { description: "Select options.", minItems: 1 })),
+            locator: Type.Optional(StringEnum(AGENT_BROWSER_SEMANTIC_LOCATORS, { description: "Locator for check/click/fill; select supports role or label." })),
+            value: Type.Optional(Type.String({ description: "Locator value or one select option; for select by label, this is the label text." })),
+            values: Type.Optional(Type.Array(Type.String(), { description: "Select options; required for select by label.", minItems: 1 })),
             selector: Type.Optional(Type.String({ description: "Direct selector or @ref." })),
             text: Type.Optional(Type.String({ description: "Fill text." })),
             role: Type.Optional(Type.String({ description: "Role locator; alternative to value." })),
@@ -84,10 +69,19 @@ export function createAgentBrowserParamsSchema(Type = JsonSchema, StringEnum = l
                 query: Type.Optional(Type.String({ description: "Case-insensitive app filter.", minLength: 1 })),
                 maxResults: Type.Optional(Type.Integer({ description: `Result cap; default ${ELECTRON_DISCOVERY_DEFAULT_MAX_RESULTS}, values over ${ELECTRON_DISCOVERY_MAX_RESULTS} are clamped.`, minimum: 1 })),
             }, { additionalProperties: false }),
-            electronLaunchVariant(Type, StringEnum, { appPath: Type.String({ description: "macOS .app path.", minLength: 1 }) }),
-            electronLaunchVariant(Type, StringEnum, { appName: Type.String({ description: "Name from electron.list.", minLength: 1 }) }),
-            electronLaunchVariant(Type, StringEnum, { bundleId: Type.String({ description: "Bundle id from electron.list.", minLength: 1 }) }),
-            electronLaunchVariant(Type, StringEnum, { executablePath: Type.String({ description: "Executable path.", minLength: 1 }) }),
+            Type.Object({
+                action: StringEnum(["launch"]),
+                appPath: Type.Optional(Type.String({ description: "macOS .app path.", minLength: 1 })),
+                appName: Type.Optional(Type.String({ description: "Name from electron.list.", minLength: 1 })),
+                bundleId: Type.Optional(Type.String({ description: "Bundle id from electron.list.", minLength: 1 })),
+                executablePath: Type.Optional(Type.String({ description: "Executable path.", minLength: 1 })),
+                appArgs: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+                handoff: Type.Optional(StringEnum(AGENT_BROWSER_ELECTRON_HANDOFFS)),
+                targetType: Type.Optional(StringEnum(AGENT_BROWSER_ELECTRON_TARGET_TYPES)),
+                timeoutMs: Type.Optional(Type.Integer({ minimum: 1 })),
+                allow: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+                deny: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+            }, { additionalProperties: false }),
             Type.Object({
                 action: StringEnum(["status", "cleanup"]),
                 launchId: Type.String({ description: "Tracked launch id.", minLength: 1 }),
@@ -128,7 +122,7 @@ export function createAgentBrowserParamsSchema(Type = JsonSchema, StringEnum = l
             }, { additionalProperties: false }), { minItems: 1 }),
         }, { additionalProperties: false, description: "Constrained multi-step batch." })),
         stdin: Type.Optional(Type.String({ description: "Raw stdin for batch, eval --stdin, or auth save --password-stdin; unavailable with structured modes and electron." })),
-        outputPath: Type.Optional(Type.String({ description: "Workspace-relative or absolute result path.", minLength: 1 })),
+        outputPath: Type.Optional(Type.String({ description: "Workspace-relative or absolute result-data path; keep it distinct from screenshot, download, recording, and other browser artifact destinations.", minLength: 1 })),
         timeoutMs: Type.Optional(Type.Integer({ description: "Wrapper timeout in ms; exceed explicit waits. Electron uses electron.timeoutMs.", minimum: 1 })),
         sessionMode: Type.Optional(StringEnum(["auto", "fresh"], {
             description: "auto reuses the managed session; fresh starts one for launch-only flags, then makes it the managed session.",
@@ -136,7 +130,7 @@ export function createAgentBrowserParamsSchema(Type = JsonSchema, StringEnum = l
         })),
     }, {
         additionalProperties: false,
-        description: "Choose one input mode: args, semanticAction, job, qa, sourceLookup, networkSourceLookup, or electron.",
+        description: "Choose one input mode: script, args, semanticAction, job, qa, sourceLookup, networkSourceLookup, or electron.",
     });
 }
 export const AGENT_BROWSER_PARAMS = createAgentBrowserParamsSchema();

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

@@ -0,0 +1,462 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgvDescriptor } from "../argv-descriptor.js";
+import { getFlagName } from "../argv-grammar.js";
+import { needsManagedSession } from "../command-policy.js";
+import { isCloseCommand } from "../command-taxonomy.js";
+import { LAUNCH_SCOPED_FLAGS, MANAGED_RESTORE_INCOMPATIBLE_FLAGS } from "../launch-scoped-flags.js";
+import { isRecord } from "../parsing.js";
+import { validateToolArgs } from "../runtime.js";
+export const AGENT_BROWSER_SCRIPT_CODE_MAX_BYTES = 64 * 1_024;
+export const AGENT_BROWSER_SCRIPT_DEFAULT_TIMEOUT_MS = 120_000;
+export const AGENT_BROWSER_SCRIPT_NAMESPACE = "";
+export const AGENT_BROWSER_SCRIPT_MAX_TIMEOUT_MS = 300_000;
+export const AGENT_BROWSER_SCRIPT_MAX_CALLS = 25;
+export const AGENT_BROWSER_SCRIPT_FINAL_OUTPUT_MAX_BYTES = 64 * 1_024;
+export const AGENT_BROWSER_SCRIPT_IPC_MESSAGE_MAX_BYTES = 1 * 1_024 * 1_024;
+export const AGENT_BROWSER_SCRIPT_IPC_CUMULATIVE_MAX_BYTES = 8 * 1_024 * 1_024;
+export const AGENT_BROWSER_SCRIPT_SPILL_MAX_BYTES = 512 * 1_024;
+function findPackageRoot(startDir) {
+    let currentDir = startDir;
+    for (;;) {
+        if (existsSync(join(currentDir, "package.json")))
+            return currentDir;
+        const parentDir = dirname(currentDir);
+        if (parentDir === currentDir)
+            throw new Error("Unable to resolve the pi-agent-browser-native package root.");
+        currentDir = parentDir;
+    }
+}
+function resolveScriptWorkerPath() {
+    const workerPath = join(findPackageRoot(dirname(fileURLToPath(import.meta.url))), "dist", "extensions", "agent-browser", "script-worker.js");
+    if (!existsSync(workerPath))
+        throw new Error("Compiled script worker is missing; run npm run build or reinstall pi-agent-browser-native.");
+    return workerPath;
+}
+const SCRIPT_SESSION_NAME_PATTERN = /^piab-script-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const SCRIPT_ALLOWED_LAUNCH_FLAG = "--allowed-domains";
+const SCRIPT_FORBIDDEN_COMMANDS = new Set(["attach", "auth", "batch", "connect", "script", "session", "state"]);
+const SCRIPT_FORBIDDEN_FLAGS = new Set([
+    ...LAUNCH_SCOPED_FLAGS.filter((flag) => flag !== SCRIPT_ALLOWED_LAUNCH_FLAG),
+    ...MANAGED_RESTORE_INCOMPATIBLE_FLAGS.filter((flag) => flag !== SCRIPT_ALLOWED_LAUNCH_FLAG),
+    "--namespace",
+    "--session",
+]);
+export function compileAgentBrowserScript(input) {
+    if (typeof input !== "string")
+        return { error: "script must be a string." };
+    const bytes = Buffer.byteLength(input, "utf8");
+    return bytes > AGENT_BROWSER_SCRIPT_CODE_MAX_BYTES
+        ? { error: `script must be ${AGENT_BROWSER_SCRIPT_CODE_MAX_BYTES} bytes or less.` }
+        : { compiled: { code: input } };
+}
+export function createAgentBrowserScriptSessionName() {
+    return `piab-script-${randomUUID()}`;
+}
+export function createAgentBrowserScriptCloseArgs(sessionName) {
+    return ["--namespace", AGENT_BROWSER_SCRIPT_NAMESPACE, "--session", sessionName, "close"];
+}
+export function isAgentBrowserScriptSessionName(value) {
+    return typeof value === "string" && SCRIPT_SESSION_NAME_PATTERN.test(value);
+}
+function getScriptCallPolicyError(args) {
+    const descriptor = parseArgvDescriptor(args);
+    const command = descriptor.commandInfo.command;
+    if (!command)
+        return "script browser call args must contain an agent-browser command.";
+    if (isCloseCommand(command))
+        return "script browser calls cannot close, quit, or exit their isolated session.";
+    if (SCRIPT_FORBIDDEN_COMMANDS.has(command))
+        return `script browser calls cannot use ${command}.`;
+    if (!needsManagedSession(descriptor))
+        return `script browser calls cannot use sessionless/local command ${command}.`;
+    for (const token of args) {
+        const flag = getFlagName(token);
+        if (SCRIPT_FORBIDDEN_FLAGS.has(flag)) {
+            return `script browser calls cannot use ${flag}; the parent owns the isolated session identity and launch policy.`;
+        }
+    }
+    return undefined;
+}
+export function validateAgentBrowserScriptBrowserParams(input) {
+    if (!isRecord(input))
+        return { error: "script browser(params) requires an object." };
+    const unsupportedField = Object.keys(input).find((field) => !["args", "stdin", "timeoutMs"].includes(field));
+    if (unsupportedField)
+        return { error: `script browser(params) does not support ${unsupportedField}; use only args, stdin, and timeoutMs.` };
+    if (!Array.isArray(input.args) || input.args.length === 0 || input.args.some((arg) => typeof arg !== "string")) {
+        return { error: "script browser(params).args must be a non-empty string array." };
+    }
+    if (input.stdin !== undefined && typeof input.stdin !== "string") {
+        return { error: "script browser(params).stdin must be a string when provided." };
+    }
+    if (input.timeoutMs !== undefined && (typeof input.timeoutMs !== "number" || !Number.isSafeInteger(input.timeoutMs) || input.timeoutMs <= 0)) {
+        return { error: "script browser(params).timeoutMs must be a positive integer when provided." };
+    }
+    const params = {
+        args: input.args,
+        stdin: input.stdin,
+        timeoutMs: input.timeoutMs,
+    };
+    const policyError = getScriptCallPolicyError(params.args);
+    if (policyError)
+        return { error: policyError, policyBlocked: true };
+    const validationError = validateToolArgs(params.args);
+    return validationError ? { error: validationError } : { params };
+}
+function buildRejectedCallEnvelope(error, policyBlocked) {
+    return {
+        data: null,
+        details: { failureCategory: policyBlocked ? "policy-blocked" : "validation-error", resultCategory: "failure" },
+        error,
+        failureCategory: policyBlocked ? "policy-blocked" : "validation-error",
+        ok: false,
+        resultCategory: "failure",
+        summary: error,
+        text: error,
+    };
+}
+function normalizeBrowserEnvelope(value) {
+    if (!isRecord(value)
+        || typeof value.ok !== "boolean"
+        || typeof value.text !== "string"
+        || typeof value.summary !== "string"
+        || (value.resultCategory !== "success" && value.resultCategory !== "failure")) {
+        return buildRejectedCallEnvelope("The ordinary agent_browser executor returned an invalid script envelope.", false);
+    }
+    return {
+        data: value.data ?? null,
+        details: isRecord(value.details) ? value.details : undefined,
+        error: typeof value.error === "string" ? value.error : undefined,
+        failureCategory: value.failureCategory,
+        nextActions: Array.isArray(value.nextActions) ? value.nextActions : undefined,
+        ok: value.ok,
+        resultCategory: value.resultCategory,
+        successCategory: value.successCategory,
+        summary: value.summary,
+        text: value.text,
+    };
+}
+function buildStepSummary(index, envelope) {
+    return {
+        failureCategory: envelope.failureCategory,
+        index,
+        ok: envelope.ok,
+        resultCategory: envelope.resultCategory,
+        successCategory: envelope.successCategory,
+        summary: envelope.summary,
+    };
+}
+function buildFailedRun(options) {
+    return { ...options, ok: false };
+}
+function describeScriptError(error) {
+    const name = typeof error?.name === "string" && error.name.length > 0 ? error.name.slice(0, 80) : "Error";
+    const message = typeof error?.message === "string" && error.message.length > 0
+        ? error.message.replace(/[\r\n]+/g, " ").slice(0, 400)
+        : "Script execution failed.";
+    return `${name}: ${message}`;
+}
+function isScriptChildMessage(value) {
+    if (!isRecord(value) || typeof value.type !== "string")
+        return false;
+    if (value.type === "ready")
+        return true;
+    if (value.type === "call")
+        return typeof value.id === "number" && Number.isSafeInteger(value.id) && value.id > 0;
+    if (value.type === "emit")
+        return true;
+    return value.type === "complete";
+}
+function waitForChildExit(child) {
+    if (child.exitCode !== null || child.signalCode !== null)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        child.once("exit", () => resolve());
+        child.once("error", () => resolve());
+    });
+}
+function terminateChild(child) {
+    child.stdin.destroy();
+    if (child.exitCode === null && child.signalCode === null)
+        child.kill("SIGTERM");
+    return setTimeout(() => {
+        if (child.exitCode === null && child.signalCode === null)
+            child.kill("SIGKILL");
+    }, 250);
+}
+async function settleWithin(promise, timeoutMs) {
+    let timer;
+    await Promise.race([
+        promise.catch(() => undefined),
+        new Promise((resolve) => {
+            timer = setTimeout(resolve, timeoutMs);
+        }),
+    ]);
+    if (timer)
+        clearTimeout(timer);
+}
+function serializeFinalOutput(value) {
+    if (value === undefined)
+        return undefined;
+    return JSON.stringify(value);
+}
+export async function runAgentBrowserScript(options) {
+    const compiled = compileAgentBrowserScript(options.code);
+    if (compiled.error) {
+        return buildFailedRun({ callCount: 0, emitCount: 0, error: compiled.error, failureCategory: "validation-error", rejectedCallCount: 0, steps: [] });
+    }
+    const timeoutMs = options.timeoutMs ?? AGENT_BROWSER_SCRIPT_DEFAULT_TIMEOUT_MS;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > AGENT_BROWSER_SCRIPT_MAX_TIMEOUT_MS) {
+        return buildFailedRun({ callCount: 0, emitCount: 0, error: `script timeoutMs must be between 1 and ${AGENT_BROWSER_SCRIPT_MAX_TIMEOUT_MS}.`, failureCategory: "validation-error", rejectedCallCount: 0, steps: [] });
+    }
+    if (options.signal?.aborted) {
+        return buildFailedRun({ aborted: true, callCount: 0, emitCount: 0, error: "Script execution was aborted.", failureCategory: "aborted", rejectedCallCount: 0, steps: [] });
+    }
+    let workerPath;
+    try {
+        workerPath = resolveScriptWorkerPath();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Compiled script worker is missing.";
+        return buildFailedRun({ callCount: 0, emitCount: 0, error: message, failureCategory: "missing-binary", rejectedCallCount: 0, steps: [] });
+    }
+    const child = spawn(process.execPath, [
+        "--permission",
+        "--max-old-space-size=64",
+        workerPath,
+        String(AGENT_BROWSER_SCRIPT_IPC_MESSAGE_MAX_BYTES),
+        String(AGENT_BROWSER_SCRIPT_IPC_CUMULATIVE_MAX_BYTES),
+    ], {
+        env: {},
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    child.stdin.on("error", () => undefined);
+    let stdoutBuffer = Buffer.alloc(0);
+    let stderrBytes = 0;
+    let cumulativeBytes = 0;
+    let callCount = 0;
+    let rejectedCallCount = 0;
+    let leaseStarted = false;
+    let ready = false;
+    let stopping = false;
+    let activeCallController;
+    const emissions = [];
+    const steps = [];
+    const messages = [];
+    let draining = false;
+    let drainPromise = Promise.resolve();
+    let resolveResult;
+    const resultPromise = new Promise((resolve) => {
+        resolveResult = resolve;
+    });
+    const childExit = waitForChildExit(child);
+    let timeout;
+    let killTimer;
+    const sendParentMessage = async (message) => {
+        const line = `${JSON.stringify(message)}\n`;
+        const bytes = Buffer.byteLength(line, "utf8");
+        if (bytes > AGENT_BROWSER_SCRIPT_IPC_MESSAGE_MAX_BYTES || cumulativeBytes + bytes > AGENT_BROWSER_SCRIPT_IPC_CUMULATIVE_MAX_BYTES) {
+            throw new Error("Script IPC limit exceeded.");
+        }
+        cumulativeBytes += bytes;
+        await new Promise((resolve, reject) => {
+            child.stdin.write(line, (error) => error ? reject(error) : resolve());
+        });
+    };
+    const finish = async (result, waitForDrain) => {
+        if (stopping)
+            return;
+        stopping = true;
+        if (timeout)
+            clearTimeout(timeout);
+        options.signal?.removeEventListener("abort", abortListener);
+        activeCallController?.abort();
+        killTimer = terminateChild(child);
+        if (waitForDrain)
+            await settleWithin(drainPromise, 5_000);
+        await settleWithin(childExit, 1_000);
+        clearTimeout(killTimer);
+        resolveResult(result);
+    };
+    const fail = (error, failureCategory, flags = {}, waitForDrain = false) => finish(buildFailedRun({
+        ...flags,
+        callCount,
+        emitCount: emissions.length,
+        error,
+        failureCategory,
+        rejectedCallCount,
+        steps,
+    }), waitForDrain);
+    const abortListener = () => {
+        void fail("Script execution was aborted.", "aborted", { aborted: true }, true);
+    };
+    options.signal?.addEventListener("abort", abortListener, { once: true });
+    timeout = setTimeout(() => {
+        void fail(`Script execution timed out after ${timeoutMs}ms.`, "timeout", { timedOut: true }, true);
+    }, timeoutMs);
+    const drainMessages = async () => {
+        if (draining)
+            return;
+        draining = true;
+        try {
+            while (!stopping && messages.length > 0) {
+                const message = messages.shift();
+                if (message.type === "ready") {
+                    if (ready) {
+                        await fail("Sandbox sent a duplicate ready message.", "upstream-error");
+                        return;
+                    }
+                    ready = true;
+                    try {
+                        await sendParentMessage({ code: options.code, type: "start" });
+                    }
+                    catch {
+                        await fail("Unable to start the script sandbox.", "upstream-error");
+                        return;
+                    }
+                    continue;
+                }
+                if (!ready) {
+                    await fail("Sandbox sent a message before it was ready.", "upstream-error");
+                    return;
+                }
+                if (message.type === "emit") {
+                    if (!Object.hasOwn(message, "value")) {
+                        await fail("emit(value) requires a JSON-serializable value; undefined and functions are not supported.", "validation-error");
+                        return;
+                    }
+                    emissions.push(message.value);
+                    continue;
+                }
+                if (message.type === "complete") {
+                    if (message.error) {
+                        await fail(describeScriptError(message.error), "script-error");
+                        return;
+                    }
+                    const data = emissions.length === 0
+                        ? message.hasValue ? message.value : undefined
+                        : emissions.length === 1 ? emissions[0] : emissions;
+                    let serialized;
+                    try {
+                        serialized = serializeFinalOutput(data);
+                    }
+                    catch {
+                        await fail("Final script output must be JSON-serializable.", "validation-error");
+                        return;
+                    }
+                    if (serialized !== undefined && Buffer.byteLength(serialized, "utf8") > AGENT_BROWSER_SCRIPT_FINAL_OUTPUT_MAX_BYTES) {
+                        await fail(`Final script output exceeds ${AGENT_BROWSER_SCRIPT_FINAL_OUTPUT_MAX_BYTES} bytes.`, "validation-error");
+                        return;
+                    }
+                    await finish({ callCount, data, emitCount: emissions.length, ok: true, rejectedCallCount, steps }, false);
+                    return;
+                }
+                callCount += 1;
+                if (callCount > AGENT_BROWSER_SCRIPT_MAX_CALLS) {
+                    await fail(`Script browser call limit exceeded (${AGENT_BROWSER_SCRIPT_MAX_CALLS}).`, "validation-error");
+                    return;
+                }
+                const validated = validateAgentBrowserScriptBrowserParams(message.params);
+                let envelope;
+                if (!validated.params) {
+                    rejectedCallCount += 1;
+                    envelope = buildRejectedCallEnvelope(validated.error ?? "Invalid script browser call.", validated.policyBlocked === true);
+                }
+                else {
+                    if (!leaseStarted) {
+                        try {
+                            options.beforeFirstCall?.();
+                            leaseStarted = true;
+                        }
+                        catch {
+                            await fail("Unable to persist the isolated script session lease.", "upstream-error");
+                            return;
+                        }
+                    }
+                    activeCallController = new AbortController();
+                    try {
+                        envelope = normalizeBrowserEnvelope(await options.dispatch(validated.params, activeCallController.signal));
+                    }
+                    catch {
+                        envelope = buildRejectedCallEnvelope("The ordinary agent_browser executor failed while dispatching this call.", false);
+                    }
+                    finally {
+                        activeCallController = undefined;
+                    }
+                    if (stopping)
+                        return;
+                }
+                steps.push(buildStepSummary(callCount - 1, envelope));
+                try {
+                    await sendParentMessage({ envelope, id: message.id, type: "response" });
+                }
+                catch {
+                    await fail("Unable to return a browser result to the script sandbox.", "upstream-error");
+                    return;
+                }
+            }
+        }
+        finally {
+            draining = false;
+            if (!stopping && messages.length > 0)
+                scheduleDrain();
+        }
+    };
+    function scheduleDrain() {
+        if (draining || stopping)
+            return;
+        drainPromise = drainMessages();
+    }
+    child.stdout.on("data", (chunk) => {
+        if (stopping)
+            return;
+        stdoutBuffer = Buffer.concat([stdoutBuffer, chunk]);
+        if (stdoutBuffer.length > AGENT_BROWSER_SCRIPT_IPC_MESSAGE_MAX_BYTES) {
+            void fail("Script IPC message limit exceeded.", "validation-error", {}, true);
+            return;
+        }
+        for (;;) {
+            const newline = stdoutBuffer.indexOf(10);
+            if (newline < 0)
+                break;
+            const lineBuffer = stdoutBuffer.subarray(0, newline);
+            stdoutBuffer = stdoutBuffer.subarray(newline + 1);
+            const bytes = lineBuffer.length + 1;
+            if (bytes > AGENT_BROWSER_SCRIPT_IPC_MESSAGE_MAX_BYTES || cumulativeBytes + bytes > AGENT_BROWSER_SCRIPT_IPC_CUMULATIVE_MAX_BYTES) {
+                void fail("Script IPC limit exceeded.", "validation-error", {}, true);
+                return;
+            }
+            cumulativeBytes += bytes;
+            try {
+                const parsed = JSON.parse(lineBuffer.toString("utf8"));
+                if (!isScriptChildMessage(parsed))
+                    throw new Error("invalid message");
+                messages.push(parsed);
+            }
+            catch {
+                void fail("Sandbox returned an invalid IPC message.", "upstream-error", {}, true);
+                return;
+            }
+        }
+        scheduleDrain();
+    });
+    child.stderr.on("data", (chunk) => {
+        stderrBytes += chunk.length;
+        if (stderrBytes > AGENT_BROWSER_SCRIPT_IPC_MESSAGE_MAX_BYTES && !stopping) {
+            void fail("Sandbox stderr limit exceeded.", "upstream-error", {}, true);
+        }
+    });
+    child.once("error", () => {
+        if (!stopping)
+            void fail("Unable to start the script sandbox.", "upstream-error", {}, true);
+    });
+    child.once("exit", () => {
+        if (!stopping)
+            void fail("Script sandbox exited before completion.", "upstream-error", {}, true);
+    });
+    return await resultPromise;
+}

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

@@ -1,8 +1,3 @@
-/**
- * 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";
@@ -14,7 +9,7 @@ export function getCompiledSemanticActionSessionPrefix(compiled) {
     return commandIndex > 0 ? compiled.args.slice(0, commandIndex) : [];
 }
 export function isCompiledSemanticActionFindCommand(compiled) {
-    if (!compiled)
+    if (!compiled || compiled.action === "select")
         return false;
     return compiled.args[getCompiledSemanticActionCommandIndex(compiled)] === "find";
 }
@@ -29,7 +24,7 @@ export function compileAgentBrowserSemanticAction(input) {
     const selector = input.selector;
     const text = input.text;
     const role = input.role;
-    const name = input.name;
+    const name = typeof input.name === "string" && input.name.trim().length === 0 ? undefined : 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(", ")}.` };
@@ -38,20 +33,59 @@ export function compileAgentBrowserSemanticAction(input) {
         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." };
+        if (typeof selector === "string" && selector.trim().length > 0) {
+            if (locator !== undefined || role !== undefined || name !== undefined) {
+                return { error: "semanticAction.selector cannot be combined with locator, role, or name for select; use selector plus value/values, or locator fields plus values." };
+            }
+            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 (selector !== undefined) {
+            return { error: "semanticAction.selector must be a non-empty string when provided." };
+        }
+        if (locator === undefined) {
+            return { error: "semanticAction.selector or semanticAction.locator is required for select." };
+        }
+        if (locator !== "role" && locator !== "label") {
+            return { error: "semanticAction select locator must be role or label; use selector plus value/values for other targets." };
+        }
+        if (locator === "role") {
+            if (typeof role !== "string" || !/^(?:combobox|listbox)$/i.test(role)) {
+                return { error: "semanticAction.role must be combobox or listbox for locator=role select." };
+            }
+            if (typeof name !== "string" || name.trim().length === 0) {
+                return { error: "semanticAction.name is required for locator=role select." };
+            }
+            const optionValues = getSelectValues({ value, values }, "semanticAction");
+            if (optionValues.error)
+                return { error: optionValues.error };
+            const args = typeof session === "string"
+                ? ["--session", session, "find", "role", role, "select", ...optionValues.values, "--name", name]
+                : ["find", "role", role, "select", ...optionValues.values, "--name", name];
+            return { compiled: { action: "select", locator: "role", values: optionValues.values, args } };
+        }
+        if (typeof value !== "string" || value.trim().length === 0) {
+            return { error: "semanticAction.value must be the accessible label text for locator=label select." };
+        }
+        if (role !== undefined || name !== undefined) {
+            return { error: "semanticAction.role and name are only supported for locator=role select." };
+        }
+        const optionValues = getSelectValues({ values }, "semanticAction");
+        if (optionValues.error) {
+            return { error: optionValues.error.includes("required")
+                    ? "semanticAction.values is required for locator=label select (value is the label text)."
+                    : optionValues.error };
         }
-        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 } };
+        const args = typeof session === "string"
+            ? ["--session", session, "find", "label", value, "select", ...optionValues.values]
+            : ["find", "label", value, "select", ...optionValues.values];
+        return { compiled: { action: "select", locator: "label", values: optionValues.values, args } };
     }
     if (values !== undefined) {
         return { error: "semanticAction.values is only supported for select actions." };

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

@@ -1,8 +1,3 @@
-/**
- * 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) {

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

@@ -1,8 +1,3 @@
-/**
- * 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"];