pi-agent-browser-native 0.9.2 → 0.9.4

package/dist/extensions/agent-browser/lib/orchestration/browser-run/final-result-missing-binary.js

@@ -0,0 +1,89 @@
+import { cleanupElectronLaunchResources, } from "../../electron/cleanup.js";
+import { buildAgentBrowserResultCategoryDetails } from "../../results/categories.js";
+import { applyNamespaceToNextActions } from "../../results/next-actions.js";
+import { buildManagedSessionFreshFailureNextActions, buildManagedSessionOutcome, formatManagedSessionOutcomeText, } from "./session-state.js";
+export function buildMissingBinaryMessage() {
+    return [
+        "agent-browser is required but was not found on PATH.",
+        "This project does not bundle agent-browser.",
+        "Run `pi-agent-browser-doctor` for package/PATH diagnostics, then install agent-browser using the upstream docs:",
+        "- https://agent-browser.dev/",
+        "- https://github.com/vercel-labs/agent-browser",
+    ].join("\n");
+}
+export function isMissingAgentBrowserBinary(processResult) {
+    return processResult.spawnError?.message.includes("ENOENT") === true;
+}
+function missingBinaryOutcome(options) {
+    return buildManagedSessionOutcome({
+        activeAfter: options.managedSessionActive,
+        activeBefore: options.managedSessionActive,
+        attemptedSessionName: options.executionPlan.managedSessionName,
+        command: options.executionPlan.commandInfo.command,
+        currentSessionName: options.managedSessionName,
+        currentSessionNamespace: options.managedSessionNamespace,
+        previousSessionName: options.managedSessionName,
+        sessionMode: options.sessionMode,
+        succeeded: false,
+    });
+}
+function missingBinaryDetails(options, managedSessionOutcome, cleanup) {
+    const actions = applyNamespaceToNextActions(buildManagedSessionFreshFailureNextActions(managedSessionOutcome), options.executionPlan.namespace) ?? [];
+    const errorText = buildMissingBinaryMessage();
+    return {
+        agentBrowserStarted: options.processResult.agentBrowserStarted,
+        args: options.redactedArgs,
+        compatibilityWorkaround: options.compatibilityWorkaround,
+        effectiveArgs: options.redactedProcessArgs,
+        electron: cleanup?.record
+            ? {
+                action: "launch",
+                cleanup,
+                launch: cleanup.record,
+                status: "failed",
+                targets: options.electronLaunch?.targets,
+                version: options.electronLaunch?.version,
+            }
+            : undefined,
+        managedSessionOutcome,
+        namespace: options.executionPlan.namespace,
+        nextActions: actions.length > 0 ? actions : undefined,
+        sessionMode: options.sessionMode,
+        sessionTabCorrection: options.sessionTabCorrection,
+        ...buildAgentBrowserResultCategoryDetails({
+            args: options.redactedProcessArgs,
+            command: options.executionPlan.commandInfo.command,
+            errorText,
+            failureCategory: "missing-binary",
+            spawnError: options.spawnError,
+            succeeded: false,
+        }),
+        spawnError: options.spawnError,
+    };
+}
+export async function buildMissingBinaryFailureResult(options) {
+    if (!isMissingAgentBrowserBinary(options.processResult)) {
+        return undefined;
+    }
+    const spawnError = options.processResult.spawnError.message;
+    const outcome = missingBinaryOutcome(options);
+    const cleanup = options.electronLaunch
+        ? await cleanupElectronLaunchResources({
+            child: options.electronLaunch.child,
+            record: options.electronLaunch.record,
+            timeoutMs: options.implicitSessionCloseTimeoutMs,
+        })
+        : undefined;
+    const text = [
+        buildMissingBinaryMessage(),
+        formatManagedSessionOutcomeText(outcome),
+        cleanup ? `Electron cleanup after failed attach: ${cleanup.summary}` : undefined,
+    ]
+        .filter((part) => part !== undefined && part.length > 0)
+        .join("\n\n");
+    return {
+        content: [{ type: "text", text }],
+        details: missingBinaryDetails({ ...options, spawnError }, outcome, cleanup),
+        isError: true,
+    };
+}

package/dist/extensions/agent-browser/lib/orchestration/browser-run/final-result-recovery.js

@@ -0,0 +1,97 @@
+import { extractExplicitSessionName } from "../../argv-grammar.js";
+import { buildAgentBrowserResultCategoryDetails } from "../../results/categories.js";
+import { buildRichInputRecoveryDiagnostic } from "../../results/selector-recovery.js";
+import { buildNoActivePageRefSnapshotInvalidation, isNoActivePageSnapshotFailure, } from "../../session-page-state.js";
+import { collectVisibleRefFallbackDiagnostic } from "./diagnostics.js";
+import { getSessionContextKey } from "./session-state.js";
+function recoveryFailureCategory(options) {
+    return (options.presentation.failureCategory ??
+        options.presentation.batchFailure?.failedStep.failureCategory ??
+        (options.electronPostCommandHealth ? "tab-drift" : undefined));
+}
+function classifyRecovery(options) {
+    return buildAgentBrowserResultCategoryDetails({
+        artifacts: options.presentation.artifacts,
+        args: options.redactedProcessArgs,
+        command: options.executionPlan.commandInfo.command,
+        confirmationRequired: options.presentation.summary.startsWith("Confirmation required"),
+        errorText: options.errorText ?? options.presentation.summary,
+        failureCategory: recoveryFailureCategory(options),
+        inspection: options.plainTextInspection,
+        parseError: options.parseError,
+        savedFile: options.presentation.savedFile,
+        spawnError: options.processResult.spawnError?.message,
+        succeeded: options.succeeded,
+        tabDrift: !options.succeeded &&
+            (options.aboutBlankSessionMismatch !== undefined ||
+                options.electronPostCommandHealth !== undefined ||
+                options.sessionTabCorrection !== undefined),
+        timedOut: options.processResult.timedOut,
+        validationError: undefined,
+    });
+}
+function applyFallbackSnapshot(options, snapshot, sessionKey) {
+    if (!snapshot || sessionKey === undefined || sessionKey.length === 0) {
+        return undefined;
+    }
+    return options.sessionPageState.applyRefSnapshot({
+        fallbackTarget: options.currentSessionTabTarget,
+        sessionName: sessionKey,
+        snapshot,
+        update: options.sessionPageStateUpdate,
+    });
+}
+function invalidateNoActivePage(options) {
+    const sessionKey = getSessionContextKey(options.executionPlan.sessionName, options.executionPlan.namespace);
+    if (sessionKey === undefined || sessionKey.length === 0) {
+        return undefined;
+    }
+    return options.sessionPageState.applyRefSnapshotInvalidation({
+        invalidation: buildNoActivePageRefSnapshotInvalidation(),
+        sessionName: sessionKey,
+        update: options.sessionPageStateUpdate,
+    });
+}
+function hasNoActivePage(options, category) {
+    return (category.resultCategory === "failure" &&
+        (isNoActivePageSnapshotFailure(options.executionPlan.commandInfo.command, options.errorText ?? options.presentation.summary) ||
+            options.batchRefSnapshotState?.invalidation?.reason === "no-active-page"));
+}
+export async function prepareFinalResultRecoveryState(options) {
+    const categoryDetails = classifyRecovery(options);
+    let { currentRefSnapshot, currentRefSnapshotInvalidation } = options;
+    let visibleRefFallbackDiagnostic;
+    const visibleRefFallbackSessionName = options.executionPlan.sessionName ?? extractExplicitSessionName(options.runtimeToolArgs);
+    if (categoryDetails.failureCategory === "selector-not-found") {
+        visibleRefFallbackDiagnostic = await collectVisibleRefFallbackDiagnostic({
+            commandTokens: options.presentation.batchFailure?.failedStep.command ?? options.commandTokens,
+            compiledSemanticAction: options.compiledSemanticAction,
+            cwd: options.cwd,
+            namespace: options.executionPlan.namespace,
+            sessionName: visibleRefFallbackSessionName,
+            signal: options.signal,
+        });
+        const update = applyFallbackSnapshot(options, visibleRefFallbackDiagnostic?.snapshot, getSessionContextKey(visibleRefFallbackSessionName, options.executionPlan.namespace));
+        if (update) {
+            currentRefSnapshot = update.refSnapshot;
+            currentRefSnapshotInvalidation = update.refSnapshotInvalidation;
+        }
+    }
+    const noActivePageSnapshotFailure = hasNoActivePage(options, categoryDetails);
+    if (noActivePageSnapshotFailure) {
+        const update = invalidateNoActivePage(options);
+        if (update) {
+            currentRefSnapshot = update.refSnapshot;
+            currentRefSnapshotInvalidation = update.refSnapshotInvalidation;
+        }
+    }
+    return {
+        categoryDetails,
+        currentRefSnapshot,
+        currentRefSnapshotInvalidation,
+        noActivePageSnapshotFailure,
+        richInputRecoveryDiagnostic: buildRichInputRecoveryDiagnostic(visibleRefFallbackDiagnostic),
+        visibleRefFallbackDiagnostic,
+        visibleRefFallbackSessionName,
+    };
+}

package/dist/extensions/agent-browser/lib/orchestration/browser-run/final-result-redaction.js

@@ -0,0 +1,106 @@
+import { isRecord } from "../../parsing.js";
+import { redactInvocationArgs, redactSensitiveText, redactSensitiveValue, } from "../../runtime-redaction.js";
+import { projectAgentBrowserObservation } from "../../results/presentation/content.js";
+export function redactExactSensitiveText(text, sensitiveValues) {
+    let redacted = text;
+    for (const value of sensitiveValues) {
+        redacted = redacted.split(value).join("[REDACTED]");
+    }
+    return redacted;
+}
+export function redactExactSensitiveValue(value, sensitiveValues) {
+    if (sensitiveValues.length === 0) {
+        return value;
+    }
+    if (typeof value === "string") {
+        return redactExactSensitiveText(value, sensitiveValues);
+    }
+    if (Array.isArray(value)) {
+        const entries = value;
+        return entries.map((item) => redactExactSensitiveValue(item, sensitiveValues));
+    }
+    if (!isRecord(value)) {
+        return value;
+    }
+    return Object.fromEntries(Object.entries(value).map(([key, entryValue]) => [
+        key,
+        redactExactSensitiveValue(entryValue, sensitiveValues),
+    ]));
+}
+export function redactToolDetails(details, sensitiveValues) {
+    const redacted = redactSensitiveValue(redactExactSensitiveValue(details, sensitiveValues));
+    if (!isRecord(redacted)) {
+        throw new Error("Browser result details must remain an object after redaction.");
+    }
+    return redacted;
+}
+export function redactRecoveryHint(recoveryHint) {
+    if (!recoveryHint) {
+        return undefined;
+    }
+    const exampleArgs = redactInvocationArgs(recoveryHint.exampleArgs);
+    return {
+        ...recoveryHint,
+        exampleArgs,
+        exampleParams: { ...recoveryHint.exampleParams, args: exampleArgs },
+    };
+}
+export function buildJsonVisibleContent(options) {
+    const { error, presentation, succeeded, warnings } = options;
+    const payload = projectAgentBrowserObservation({
+        ...presentation,
+        ...options.details,
+        error,
+        warnings: warnings !== undefined && warnings.length > 0 ? warnings : undefined,
+    }, succeeded);
+    const images = presentation.content.filter((item) => item.type === "image");
+    return [{ type: "text", text: JSON.stringify(payload, null, 2) }, ...images];
+}
+function warningLines(text) {
+    return text === undefined || text.length === 0 ? undefined : [text];
+}
+function contentWithWarnings(options) {
+    if (options.userRequestedJson && !options.plainTextInspection) {
+        return buildJsonVisibleContent({
+            error: options.presentationEnvelope?.error,
+            presentation: options.presentation,
+            succeeded: options.succeeded,
+            warnings: warningLines(options.warningText),
+        });
+    }
+    const content = [...options.presentation.content];
+    if (options.warningText === undefined ||
+        options.warningText.length === 0 ||
+        options.userRequestedJson) {
+        return content;
+    }
+    if (content[0]?.type === "text") {
+        content[0] = { ...content[0], text: `${options.warningText}\n\n${content[0].text}` };
+    }
+    else {
+        content.unshift({ type: "text", text: options.warningText });
+    }
+    return content;
+}
+export function buildRedactedPresentationContent(options) {
+    return contentWithWarnings(options).map((item) => {
+        if (item.type !== "text") {
+            return item;
+        }
+        const text = options.userRequestedJson && !options.plainTextInspection
+            ? JSON.stringify(redactExactSensitiveValue(JSON.parse(item.text), options.exactSensitiveValues), null, 2)
+            : redactSensitiveText(redactExactSensitiveText(item.text, options.exactSensitiveValues));
+        return { type: "text", text };
+    });
+}
+export function readJsonWarnings(content) {
+    if (content[0]?.type !== "text") {
+        return undefined;
+    }
+    const prior = JSON.parse(content[0].text);
+    if (!isRecord(prior) || !Array.isArray(prior.warnings)) {
+        return undefined;
+    }
+    const warnings = prior.warnings;
+    return warnings;
+}

package/dist/extensions/agent-browser/lib/orchestration/browser-run/final-result-timeout.js

@@ -0,0 +1,110 @@
+import { withOptionalSessionArgs } from "../../results/next-actions.js";
+function verifyTimeoutTarget(sessionName, stepIndex) {
+    return {
+        id: "verify-page-target-after-timeout",
+        params: {
+            args: withOptionalSessionArgs(sessionName, ["batch", "--bail"]),
+            stdin: JSON.stringify([
+                ["get", "url"],
+                ["snapshot", "-i"],
+            ]),
+        },
+        reason: `Verify the current URL, then inspect the page after timeout${stepIndex === undefined ? "" : ` before considering a retry of step ${stepIndex}`}.`,
+        safety: "Fail-fast read-only recovery: snapshot runs only after get url succeeds, satisfying the wrapper page-target guard without trusting the planned URL.",
+        tool: "agent_browser",
+    };
+}
+function retryTimeoutStep(options, freshSessionAbandoned) {
+    const retry = options.timeoutPartialProgress?.retryStep?.retry;
+    if (!retry) {
+        return [];
+    }
+    const stepIndex = options.timeoutPartialProgress.retryStep.index;
+    return [
+        {
+            id: "retry-timeout-step",
+            params: freshSessionAbandoned
+                ? { ...retry, sessionMode: "fresh" }
+                : {
+                    ...retry,
+                    args: withOptionalSessionArgs(options.executionPlan.sessionName, [...retry.args]),
+                },
+            reason: freshSessionAbandoned
+                ? `Consider retrying the single timed-out step ${stepIndex} in a fresh browser session because the timed-out fresh session was not proven live.`
+                : `Consider retrying the single timed-out step ${stepIndex} against the current browser session.`,
+            safety: "Only read-only or idempotent timeout steps get executable retry args; inspect current page/artifact state before using the action.",
+            tool: "agent_browser",
+        },
+    ];
+}
+function verifyUnknownTimeoutTarget(options, freshSessionAbandoned) {
+    const sessionName = options.executionPlan.sessionName;
+    if (options.currentSessionTabTargetUnknown === true &&
+        !freshSessionAbandoned &&
+        sessionName !== undefined &&
+        sessionName.length > 0) {
+        return [verifyTimeoutTarget(sessionName, options.timeoutPartialProgress?.retryStep?.index)];
+    }
+    return [];
+}
+function inspectTimeoutPage(options, freshSessionAbandoned) {
+    const sessionName = options.executionPlan.sessionName;
+    if (!options.timeoutPartialProgress ||
+        freshSessionAbandoned ||
+        sessionName === undefined ||
+        sessionName.length === 0) {
+        return [];
+    }
+    const stepIndex = options.timeoutPartialProgress.retryStep?.index;
+    return [
+        {
+            id: "inspect-current-page-after-timeout",
+            params: { args: withOptionalSessionArgs(sessionName, ["snapshot", "-i"]) },
+            reason: `Inspect the current page after timeout before deciding how to resume${stepIndex === undefined ? "" : ` with step ${stepIndex}`}.`,
+            safety: "Read details.timeoutPartialProgress first. Do not blindly retry mutating steps such as clicks, fills, key presses, selects, or checks; split the remaining flow into shorter batches around the next navigation or DOM mutation boundary.",
+            tool: "agent_browser",
+        },
+    ];
+}
+export function buildTimeoutPartialProgressNextActions(options) {
+    if (options.executionPlan.commandInfo.command === "session" &&
+        options.executionPlan.commandInfo.subcommand === "info") {
+        return [];
+    }
+    const freshSessionAbandoned = options.sessionMode === "fresh" && options.timeoutPartialProgress?.liveUrlRecovered !== true;
+    const verification = verifyUnknownTimeoutTarget(options, freshSessionAbandoned);
+    if (verification.length > 0) {
+        return verification;
+    }
+    const retry = retryTimeoutStep(options, freshSessionAbandoned);
+    return retry.length > 0 ? retry : inspectTimeoutPage(options, freshSessionAbandoned);
+}
+export function buildDialogTimeoutNextActions(options) {
+    if (options.command === undefined ||
+        !["dialog", "click", "tap", "find", "eval"].includes(options.command)) {
+        return [];
+    }
+    return [
+        {
+            id: "inspect-dialog-after-timeout",
+            params: { args: withOptionalSessionArgs(options.sessionName, ["dialog", "status"]) },
+            reason: "Check whether a blocking JavaScript dialog is pending after the timed-out interaction.",
+            safety: "Read-only dialog status; this wrapper bounds dialog commands so recovery attempts do not wait for the full default watchdog.",
+            tool: "agent_browser",
+        },
+        {
+            id: "dismiss-dialog-after-timeout",
+            params: { args: withOptionalSessionArgs(options.sessionName, ["dialog", "dismiss"]) },
+            reason: "Dismiss a pending alert/confirm/prompt when the workflow can safely abandon the dialog.",
+            safety: "Only run when dismissing/canceling the dialog is acceptable for the user flow.",
+            tool: "agent_browser",
+        },
+        {
+            id: "recover-fresh-session-after-dialog-timeout",
+            params: { args: ["open", "about:blank"], sessionMode: "fresh" },
+            reason: "Start a clean browser session if the current session remains blocked behind a JavaScript dialog.",
+            safety: "Replace about:blank with the intended recovery URL; this abandons the blocked managed session.",
+            tool: "agent_browser",
+        },
+    ];
+}