pi-agent-browser-native 0.9.3 → 0.9.5

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

@@ -0,0 +1,396 @@
+import { spawn } from "node:child_process";
+import { redactSensitiveText } from "../runtime.js";
+import { validateAgentBrowserScriptBrowserParams } from "./script-validation.js";
+import { describeScriptError, isScriptChildMessage, normalizeBrowserEnvelope, rejectedCallEnvelope, SCRIPT_FINAL_OUTPUT_MAX_BYTES, SCRIPT_IPC_CUMULATIVE_MAX_BYTES, SCRIPT_IPC_MESSAGE_MAX_BYTES, SCRIPT_MAX_CALLS, } from "./script-protocol.js";
+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(() => {
+            // Dispatch failures are returned as observations; this wait only bounds child exit.
+        }),
+        new Promise((resolve) => {
+            timer = setTimeout(resolve, timeoutMs);
+        }),
+    ]);
+    if (timer !== undefined) {
+        clearTimeout(timer);
+    }
+}
+function emissionData(emissions) {
+    if (emissions.length === 0) {
+        return undefined;
+    }
+    return emissions.length === 1 ? emissions[0] : emissions;
+}
+function serializeFinalOutput(value) {
+    if (value === undefined) {
+        return;
+    }
+    return JSON.stringify(value);
+}
+// One owner for child events, ordered dispatch, abort, and final reaping.
+class ScriptChildRun {
+    options;
+    child;
+    childExit;
+    resultPromise;
+    resolveResult;
+    stdoutBuffer = Buffer.alloc(0);
+    stderrBytes = 0;
+    cumulativeBytes = 0;
+    callCount = 0;
+    rejectedCallCount = 0;
+    ready = false;
+    stopping = false;
+    activeCallController;
+    emissions = [];
+    steps = [];
+    failures = [];
+    messages = [];
+    draining = false;
+    drainPromise = Promise.resolve();
+    timeout;
+    constructor(options, nodePath, workerPath) {
+        this.options = options;
+        this.child = spawn(nodePath, [
+            "--permission",
+            "--max-old-space-size=64",
+            workerPath,
+            String(SCRIPT_IPC_MESSAGE_MAX_BYTES),
+            String(SCRIPT_IPC_CUMULATIVE_MAX_BYTES),
+        ], { env: {}, stdio: ["pipe", "pipe", "pipe"] });
+        this.child.stdin.on("error", () => {
+            // The write callback and child lifecycle report pipe failure; consume the stream event.
+        });
+        this.resultPromise = new Promise((resolve) => {
+            this.resolveResult = resolve;
+        });
+        this.childExit = waitForChildExit(this.child);
+    }
+    run(timeoutMs) {
+        this.options.signal?.addEventListener("abort", this.abortListener, { once: true });
+        this.timeout = setTimeout(() => {
+            this.failFromEvent(`Script execution timed out after ${timeoutMs}ms.`, "timeout", {
+                timedOut: true,
+            });
+        }, timeoutMs);
+        this.child.stdout.on("data", (chunk) => {
+            this.receiveStdout(chunk);
+        });
+        this.child.stderr.on("data", (chunk) => {
+            this.stderrBytes += chunk.length;
+            if (this.stderrBytes > SCRIPT_IPC_MESSAGE_MAX_BYTES && !this.stopping) {
+                this.failFromEvent("Sandbox stderr limit exceeded.", "upstream-error");
+            }
+        });
+        this.child.once("error", () => {
+            if (!this.stopping) {
+                this.failFromEvent("Unable to start the script sandbox.", "upstream-error");
+            }
+        });
+        this.child.once("exit", () => {
+            if (!this.stopping) {
+                this.failFromEvent("Script sandbox exited before completion.", "upstream-error");
+            }
+        });
+        return this.resultPromise;
+    }
+    abortListener = () => {
+        const timedOut = this.options.signal?.reason instanceof Error &&
+            this.options.signal.reason.name === "TimeoutError";
+        this.failFromEvent(timedOut ? "Browser code deadline exceeded." : "Browser code was aborted.", timedOut ? "timeout" : "aborted", timedOut ? { timedOut: true } : { aborted: true });
+    };
+    result() {
+        return {
+            callCount: this.callCount,
+            emitCount: this.emissions.length,
+            failures: this.failures,
+            ok: true,
+            rejectedCallCount: this.rejectedCallCount,
+            steps: this.steps,
+        };
+    }
+    async send(message) {
+        const line = `${JSON.stringify(message)}\n`;
+        this.countBytes(Buffer.byteLength(line, "utf8"));
+        await new Promise((resolve, reject) => {
+            this.child.stdin.write(line, (error) => {
+                if (error !== undefined && error !== null) {
+                    reject(error);
+                }
+                else {
+                    resolve();
+                }
+            });
+        });
+    }
+    countBytes(bytes) {
+        if (bytes > SCRIPT_IPC_MESSAGE_MAX_BYTES ||
+            this.cumulativeBytes + bytes > SCRIPT_IPC_CUMULATIVE_MAX_BYTES) {
+            throw new Error("Script IPC limit exceeded.");
+        }
+        this.cumulativeBytes += bytes;
+    }
+    async finish(result, waitForDrain) {
+        if (this.stopping) {
+            return;
+        }
+        this.stopping = true;
+        if (this.timeout !== undefined) {
+            clearTimeout(this.timeout);
+        }
+        this.options.signal?.removeEventListener("abort", this.abortListener);
+        this.activeCallController?.abort(result.timedOut === true
+            ? new DOMException("Browser code deadline exceeded.", "TimeoutError")
+            : this.options.signal?.reason);
+        const killTimer = terminateChild(this.child);
+        try {
+            // The caller holds the browser lease until dispatch actually settles.
+            if (waitForDrain) {
+                await this.drainPromise;
+            }
+            await settleWithin(this.childExit, 1_000);
+        }
+        finally {
+            clearTimeout(killTimer);
+        }
+        this.resolveResult(result);
+    }
+    fail(error, failureCategory, flags = {}, waitForDrain = false) {
+        const result = this.result();
+        return this.finish({
+            ...result,
+            ...flags,
+            ...(this.emissions.length > 0 ? { data: emissionData(this.emissions) } : {}),
+            error,
+            failureCategory,
+            ok: false,
+        }, waitForDrain);
+    }
+    failFromEvent(message, category, flags = {}) {
+        this.fail(message, category, flags, true).catch((failure) => {
+            // This event-owned shutdown must settle the public result even if reaping fails.
+            this.resolveResult({
+                ...this.result(),
+                ...flags,
+                ok: false,
+                failureCategory: category,
+                error: `${message} ${failure instanceof Error ? failure.message : "Sandbox cleanup failed."}`,
+            });
+        });
+    }
+    async drainMessages() {
+        if (this.draining) {
+            return;
+        }
+        this.draining = true;
+        try {
+            while (!this.stopping && this.messages.length > 0) {
+                const message = this.messages.shift();
+                if (message === undefined) {
+                    break;
+                }
+                // Every reply/emit depends on the preceding message and browser dispatch.
+                // oxlint-disable-next-line no-await-in-loop
+                await this.handleMessage(message);
+            }
+        }
+        finally {
+            this.draining = false;
+            if (!this.stopping && this.messages.length > 0) {
+                this.scheduleDrain();
+            }
+        }
+    }
+    async handleMessage(message) {
+        if (message.type === "ready") {
+            if (this.ready) {
+                await this.fail("Sandbox sent a duplicate ready message.", "upstream-error");
+                return;
+            }
+            this.ready = true;
+            try {
+                await this.send({ code: this.options.code, type: "start" });
+            }
+            catch {
+                await this.fail("Unable to start the script sandbox.", "upstream-error");
+            }
+            return;
+        }
+        if (!this.ready) {
+            await this.fail("Sandbox sent a message before it was ready.", "upstream-error");
+            return;
+        }
+        switch (message.type) {
+            case "emit":
+                if (!Object.hasOwn(message, "value")) {
+                    await this.fail("emit(value) requires a JSON-serializable value; undefined and functions are not supported.", "validation-error");
+                }
+                else {
+                    this.emissions.push(message.value);
+                }
+                return;
+            case "image":
+                await this.emitImage(message.value);
+                return;
+            case "complete":
+                await this.complete(message);
+                return;
+            case "call":
+                await this.browserCall(message);
+                return;
+        }
+    }
+    async emitImage(value) {
+        try {
+            if (this.options.emitImage === undefined) {
+                throw new Error("Image emission is unavailable.");
+            }
+            await this.options.emitImage(value);
+        }
+        catch (error) {
+            await this.fail(error instanceof Error ? error.message : "Invalid image handle.", "validation-error");
+        }
+    }
+    async complete(message) {
+        if (message.error !== undefined) {
+            await this.fail(describeScriptError(message.error), "script-error");
+            return;
+        }
+        let data = emissionData(this.emissions);
+        if (this.emissions.length === 0 && message.hasValue === true) {
+            data = message.value;
+        }
+        let serialized;
+        try {
+            serialized = serializeFinalOutput(data);
+        }
+        catch {
+            await this.fail("Final script output must be JSON-serializable.", "validation-error");
+            return;
+        }
+        if (serialized !== undefined &&
+            Buffer.byteLength(serialized, "utf8") > SCRIPT_FINAL_OUTPUT_MAX_BYTES) {
+            await this.fail(`Final script output exceeds ${SCRIPT_FINAL_OUTPUT_MAX_BYTES} bytes.`, "validation-error");
+            return;
+        }
+        await this.finish({ ...this.result(), data }, false);
+    }
+    async dispatch(params) {
+        const validated = validateAgentBrowserScriptBrowserParams(params);
+        if (validated.params === undefined) {
+            this.rejectedCallCount += 1;
+            return rejectedCallEnvelope(validated.error ?? "Invalid script browser call.");
+        }
+        this.activeCallController = new AbortController();
+        try {
+            return normalizeBrowserEnvelope(await this.options.dispatch(validated.params, this.activeCallController.signal));
+        }
+        catch (error) {
+            return rejectedCallEnvelope(redactSensitiveText(error instanceof Error
+                ? error.message
+                : "The browser executor failed while dispatching this call."));
+        }
+        finally {
+            this.activeCallController = undefined;
+        }
+    }
+    async browserCall(message) {
+        this.callCount += 1;
+        if (this.callCount > SCRIPT_MAX_CALLS) {
+            await this.fail(`Script browser call limit exceeded (${SCRIPT_MAX_CALLS}).`, "validation-error");
+            return;
+        }
+        const envelope = await this.dispatch(message.params);
+        this.steps.push({
+            failureCategory: envelope.failureCategory,
+            index: this.callCount - 1,
+            ok: envelope.success,
+            resultCategory: envelope.resultCategory,
+            successCategory: envelope.successCategory,
+            summary: envelope.summary ??
+                (typeof envelope.error === "string" ? envelope.error : "Browser call completed."),
+        });
+        if (!envelope.success) {
+            this.failures.push({ ...envelope, index: this.callCount - 1 });
+        }
+        if (this.stopping) {
+            return;
+        }
+        try {
+            await this.send({ envelope, id: message.id, type: "response" });
+        }
+        catch {
+            await this.fail("Unable to return a browser result within the code IPC limit. Narrow the native extraction or use agent_browser with outputPath; already-dispatched effects are not rolled back.", "upstream-error");
+        }
+    }
+    scheduleDrain() {
+        if (this.draining || this.stopping) {
+            return;
+        }
+        this.drainPromise = this.drainMessages().catch((error) => {
+            // Unexpected drain failures still go through the same child termination owner.
+            return this.fail(error instanceof Error ? error.message : "Sandbox message dispatch failed.", "upstream-error");
+        });
+    }
+    receiveStdout(chunk) {
+        if (this.stopping) {
+            return;
+        }
+        this.stdoutBuffer = Buffer.concat([this.stdoutBuffer, chunk]);
+        if (this.stdoutBuffer.length > SCRIPT_IPC_MESSAGE_MAX_BYTES) {
+            this.failFromEvent("Script IPC message limit exceeded.", "validation-error");
+            return;
+        }
+        for (;;) {
+            const newline = this.stdoutBuffer.indexOf(10);
+            if (newline < 0) {
+                break;
+            }
+            const lineBuffer = this.stdoutBuffer.subarray(0, newline);
+            this.stdoutBuffer = this.stdoutBuffer.subarray(newline + 1);
+            try {
+                this.countBytes(lineBuffer.length + 1);
+            }
+            catch {
+                this.failFromEvent("Script IPC limit exceeded.", "validation-error");
+                return;
+            }
+            try {
+                const parsed = JSON.parse(lineBuffer.toString("utf8"));
+                if (!isScriptChildMessage(parsed)) {
+                    throw new Error("invalid message");
+                }
+                this.messages.push(parsed);
+            }
+            catch {
+                this.failFromEvent("Sandbox returned an invalid IPC message.", "upstream-error");
+                return;
+            }
+        }
+        this.scheduleDrain();
+    }
+}
+export function runScriptChild(options, nodePath, workerPath, timeoutMs) {
+    return new ScriptChildRun(options, nodePath, workerPath).run(timeoutMs);
+}

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

@@ -0,0 +1,86 @@
+import { isRecord } from "../parsing.js";
+export const SCRIPT_IPC_MESSAGE_MAX_BYTES = 1 * 1_024 * 1_024;
+export const SCRIPT_IPC_CUMULATIVE_MAX_BYTES = 8 * 1_024 * 1_024;
+export const SCRIPT_FINAL_OUTPUT_MAX_BYTES = 64 * 1_024;
+export const SCRIPT_MAX_CALLS = 25;
+export function isScriptChildMessage(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    switch (value.type) {
+        case "ready":
+        case "emit":
+        case "image":
+            return true;
+        case "call":
+            return typeof value.id === "number" && Number.isSafeInteger(value.id) && value.id > 0;
+        case "complete":
+            return ((value.error === undefined || isRecord(value.error)) &&
+                (value.hasValue === undefined || typeof value.hasValue === "boolean"));
+        default:
+            return false;
+    }
+}
+export 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}`;
+}
+export function rejectedCallEnvelope(error) {
+    return {
+        data: null,
+        error,
+        failureCategory: "validation-error",
+        success: false,
+        resultCategory: "failure",
+        summary: error,
+    };
+}
+function failureCategory(value) {
+    const categories = [
+        "aborted",
+        "artifact-missing",
+        "cleanup-failed",
+        "confirmation-required",
+        "download-not-verified",
+        "missing-binary",
+        "parse-failure",
+        "policy-blocked",
+        "qa-failure",
+        "selector-not-found",
+        "selector-unsupported",
+        "script-error",
+        "stale-ref",
+        "tab-drift",
+        "tab-gone",
+        "timeout",
+        "upstream-error",
+        "validation-error",
+    ];
+    return categories.find((category) => category === value);
+}
+function successCategory(value) {
+    const categories = [
+        "artifact-pending",
+        "artifact-saved",
+        "artifact-unverified",
+        "completed",
+        "inspection",
+    ];
+    return categories.find((category) => category === value);
+}
+export function normalizeBrowserEnvelope(value) {
+    if (!isRecord(value) ||
+        typeof value.success !== "boolean" ||
+        !["success", "failure"].includes(value.resultCategory)) {
+        return rejectedCallEnvelope("The browser executor returned an invalid code observation.");
+    }
+    return {
+        ...value,
+        failureCategory: failureCategory(value.failureCategory),
+        successCategory: successCategory(value.successCategory),
+        summary: typeof value.summary === "string" ? value.summary : undefined,
+    };
+}

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

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

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

@@ -0,0 +1,60 @@
+import { isRecord } from "../parsing.js";
+import { extractExplicitNamespace, extractExplicitSessionName, scanUpstreamGlobalFlagOccurrences, } from "../argv-grammar.js";
+import { extractUpstreamCommandTokens } from "../argv-descriptor.js";
+import { getUpstreamEffectiveBatchSteps } from "../orchestration/batch-stdin.js";
+import { isCloseAllCommand } from "../command-taxonomy.js";
+import { validateToolArgs } from "../runtime.js";
+import { isStringArray } from "./shared.js";
+function isOptionalTimeout(value) {
+    return (value === undefined || (typeof value === "number" && Number.isSafeInteger(value) && value > 0));
+}
+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 !== undefined) {
+        return {
+            error: `script browser(params) does not support ${unsupportedField}; use only args, stdin, and timeoutMs.`,
+        };
+    }
+    const { args, stdin, timeoutMs } = input;
+    if (!isStringArray(args) || args.length === 0) {
+        return { error: "script browser(params).args must be a non-empty string array." };
+    }
+    if (stdin !== undefined && typeof stdin !== "string") {
+        return { error: "script browser(params).stdin must be a string when provided." };
+    }
+    if (!isOptionalTimeout(timeoutMs)) {
+        return { error: "script browser(params).timeoutMs must be a positive integer when provided." };
+    }
+    const error = validateToolArgs(args);
+    return error !== undefined ? { error } : { params: { args, stdin, timeoutMs } };
+}
+function normalizeNamespace(namespace) {
+    return namespace === "" ? undefined : namespace;
+}
+export function bindBrowserCodeCall(params, identity) {
+    const args = [...params.args];
+    const explicitSession = extractExplicitSessionName(args);
+    const namespaceFlags = scanUpstreamGlobalFlagOccurrences(args, "--namespace");
+    const explicitNamespace = extractExplicitNamespace(args);
+    if ((explicitSession !== undefined && explicitSession !== identity.sessionName) ||
+        (namespaceFlags.length > 0 &&
+            normalizeNamespace(explicitNamespace) !== normalizeNamespace(identity.namespace))) {
+        throw new Error("A code call uses one browser identity. Set session/namespace on agent_browser_code to choose another browser.");
+    }
+    const tokens = extractUpstreamCommandTokens(args);
+    if (isCloseAllCommand(tokens) ||
+        getUpstreamEffectiveBatchSteps(tokens, params.stdin).some(isCloseAllCommand)) {
+        throw new Error("Run namespace-wide close --all directly with agent_browser, outside a session-scoped code call.");
+    }
+    return {
+        ...params,
+        args: [
+            ...(namespaceFlags.length === 0 ? ["--namespace", identity.namespace ?? ""] : []),
+            ...(explicitSession === undefined ? ["--session", identity.sessionName] : []),
+            ...args,
+        ],
+    };
+}