pi-agent-browser-native 0.9.3 → 0.9.4

package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-page-state.js

@@ -0,0 +1,121 @@
+import { isCloseCommand } from "../../command-taxonomy.js";
+import { buildPageTransitionRefSnapshotInvalidation, } from "../../session-page-state.js";
+import { inspectManagedSessionDaemon } from "./managed-session-daemon-policy.js";
+import { getSessionContextKey } from "./session-state.js";
+export async function inspectPreparationGeneration(process, identity) {
+    return inspectManagedSessionDaemon({
+        ...process,
+        namespace: identity.namespace,
+        sessionName: identity.sessionName,
+        includeGeneration: true,
+        headedManagedAutosaveInterval: identity.owned?.headedManagedAutosaveInterval ??
+            (identity.owned?.headedManagedAutosaveDisabled === true ? "0" : undefined),
+    });
+}
+function consumeConfirmedCapture(state, update, key) {
+    const confirmed = key !== undefined && key !== "" ? state.sessionPageState.getReadConfirmation(key) : undefined;
+    if (confirmed?.refSnapshotFresh !== true) {
+        return false;
+    }
+    // ponytail: reuse the approved capture for one call; DOM-only renames after that sample are not resampled on this use.
+    const consumed = { ...confirmed };
+    delete consumed.refSnapshotFresh;
+    state.sessionPageState.applyReadConfirmation(consumed, update);
+    state.observedBrowserEffects = { ...state.observedBrowserEffects, readConfirmation: consumed };
+    return true;
+}
+function generationInspectionEligible(plan, browserIndependent, page) {
+    if (browserIndependent || isCloseCommand(plan.commandInfo.command)) {
+        return false;
+    }
+    return ((page.priorRefSnapshotState?.refIds.length ?? 0) > 0 &&
+        page.sessionStateKey !== undefined &&
+        page.sessionStateKey !== "" &&
+        plan.sessionName !== undefined &&
+        plan.sessionName !== "");
+}
+async function reconcileGeneration(pageState, process, request) {
+    const { page, plan, session } = request;
+    const snapshot = page.priorRefSnapshotState;
+    const key = page.sessionStateKey;
+    const name = plan.sessionName;
+    if (!generationInspectionEligible(plan, session.browserIndependent, page) ||
+        snapshot === undefined ||
+        key === undefined ||
+        name === undefined) {
+        return { ...page, nativeGenerationChanged: false };
+    }
+    const daemon = await inspectPreparationGeneration(process, {
+        namespace: plan.namespace,
+        sessionName: name,
+        owned: session.ownedManagedSession,
+    });
+    pageState.bindSnapshotGeneration(key, daemon.status === "active" ? daemon.generation : undefined);
+    const generationKnown = daemon.status === "active" && daemon.generation !== undefined;
+    if (generationKnown && snapshot.generation === daemon.generation) {
+        return { ...page, nativeGenerationChanged: false };
+    }
+    const nativeGenerationChanged = generationKnown && snapshot.generation !== undefined;
+    const invalidation = buildPageTransitionRefSnapshotInvalidation("The native browser generation changed or could not be verified. Take a new complete snapshot before using refs, even when the URL is unchanged.");
+    pageState.applyRefSnapshotInvalidation({
+        invalidation,
+        sessionName: key,
+        update: request.update,
+    });
+    return {
+        ...page,
+        nativeGenerationChanged,
+        priorRefSnapshotState: undefined,
+        priorRefSnapshotInvalidation: invalidation,
+    };
+}
+function coldSessionEligible(request) {
+    const nativeCold = request.inactive || request.page.nativeGenerationChanged || request.reopenPending;
+    return (!request.browserIndependent &&
+        nativeCold &&
+        request.restoreEligible &&
+        request.preserveAttachedBrowserSession !== true);
+}
+export async function preparePageState(state, process, request) {
+    const { plan, session, update } = request;
+    const key = getSessionContextKey(plan.sessionName, plan.namespace);
+    const pageState = state.sessionPageState;
+    const prior = pageState.get(key);
+    const page = await reconcileGeneration(pageState, process, {
+        plan,
+        session,
+        update,
+        page: {
+            sessionStateKey: key,
+            priorSessionTabTarget: prior.tabTarget,
+            priorSessionTabTargetUnknown: prior.tabTargetUnknown,
+            sessionTabPinningReason: prior.pinningReason,
+            priorRefSnapshotState: prior.refSnapshot,
+            priorRefSnapshotInvalidation: prior.refSnapshotInvalidation,
+            reuseConfirmedCapture: consumeConfirmedCapture(state, update, key),
+            coldManagedSession: false,
+        },
+    });
+    const coldManagedSession = coldSessionEligible({
+        browserIndependent: session.browserIndependent,
+        ...request,
+        page,
+        reopenPending: prior.tabReopenPending === true,
+        restoreEligible: session.recordedOwnedSession !== undefined &&
+            page.sessionTabPinningReason === "restore" &&
+            session.ownedManagedSession?.restoreDecision === "enabled" &&
+            !state.managedSessionRestoreState.isDisabled(plan.sessionName, plan.namespace),
+    });
+    if (!coldManagedSession || key === undefined || key === "") {
+        return { ...page, coldManagedSession };
+    }
+    pageState.setTabReopenPending({ pending: true, sessionName: key, update });
+    const invalidation = buildPageTransitionRefSnapshotInvalidation("The managed browser shut down. Reopening its URL reloads the page; run snapshot -i before using page-scoped refs.");
+    pageState.applyRefSnapshotInvalidation({ invalidation, sessionName: key, update });
+    return {
+        ...page,
+        coldManagedSession,
+        priorRefSnapshotState: undefined,
+        priorRefSnapshotInvalidation: invalidation,
+    };
+}

package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-refs.js

@@ -0,0 +1,130 @@
+import { getCompiledSemanticActionSessionPrefix } from "../../input-modes/semantic-action.js";
+import { resolveVisibleRefActionFromSnapshot } from "../../results/selector-recovery.js";
+import { extractRefSnapshotFromData, normalizeComparableUrl } from "../../session-page-state.js";
+import { getGuardedRefUsage, runSessionCommandData } from "./session-state.js";
+function describeRef(snapshot, refId) {
+    const ref = snapshot?.refs?.[refId];
+    return ref ? `${ref.role} ${JSON.stringify(ref.name)}` : "not present";
+}
+function refChanged(previous, current, refId) {
+    const previousRef = previous.refs?.[refId];
+    const currentRef = current.refs?.[refId];
+    if (!current.refIds.includes(refId)) {
+        return true;
+    }
+    if (!previousRef || !currentRef) {
+        return previousRef !== currentRef;
+    }
+    return previousRef.role !== currentRef.role || previousRef.name !== currentRef.name;
+}
+function samePageFreshnessFailure(options) {
+    const previousUrl = normalizeComparableUrl(options.previousSnapshot.target?.url);
+    const currentUrl = normalizeComparableUrl(options.currentSnapshot.target?.url);
+    if (previousUrl === undefined ||
+        previousUrl === "" ||
+        currentUrl === undefined ||
+        currentUrl === "" ||
+        previousUrl !== currentUrl ||
+        currentUrl === "about:blank") {
+        return undefined;
+    }
+    const mismatchedRefs = options.refIds.filter((refId) => refChanged(options.previousSnapshot, options.currentSnapshot, refId));
+    if (mismatchedRefs.length === 0) {
+        return undefined;
+    }
+    const refText = mismatchedRefs.map((refId) => `@${refId}`).join(", ");
+    const evidence = mismatchedRefs
+        .map((refId) => `@${refId}: previous ${describeRef(options.previousSnapshot, refId)}, current ${describeRef(options.currentSnapshot, refId)}`)
+        .join("; ");
+    return {
+        message: `Ref ${refText} no longer matches the latest same-page snapshot. The page likely rerendered after the previous snapshot; run snapshot -i and retry with current refs. Evidence: ${evidence}.`,
+        refIds: mismatchedRefs,
+    };
+}
+function targetPrecludesFreshness(previousSnapshot, currentTarget) {
+    const previousUrl = normalizeComparableUrl(previousSnapshot.target?.url);
+    const currentUrl = normalizeComparableUrl(currentTarget?.url);
+    if (currentUrl === "about:blank") {
+        return true;
+    }
+    return (previousUrl !== undefined &&
+        previousUrl !== "" &&
+        currentUrl !== undefined &&
+        currentUrl !== "" &&
+        previousUrl !== currentUrl);
+}
+export async function collectSamePageRefFreshnessPreflight(options) {
+    const refIds = [...new Set(getGuardedRefUsage(options.commandTokens, options.stdin))];
+    if (!options.previousSnapshot ||
+        options.sessionName === undefined ||
+        options.sessionName === "" ||
+        refIds.length === 0) {
+        return undefined;
+    }
+    if (targetPrecludesFreshness(options.previousSnapshot, options.currentTarget)) {
+        return undefined;
+    }
+    const snapshotData = await runSessionCommandData({
+        args: ["snapshot", "-i"],
+        cwd: options.cwd,
+        namespace: options.namespace,
+        sessionName: options.sessionName,
+        signal: options.signal,
+    });
+    const currentSnapshot = extractRefSnapshotFromData(snapshotData);
+    if (!currentSnapshot) {
+        return undefined;
+    }
+    const snapshotWithTarget = {
+        ...currentSnapshot,
+        target: currentSnapshot.target ?? options.currentTarget,
+    };
+    const mismatch = samePageFreshnessFailure({
+        currentSnapshot: snapshotWithTarget,
+        previousSnapshot: options.previousSnapshot,
+        refIds,
+    });
+    return mismatch
+        ? { message: mismatch.message, refIds: mismatch.refIds, snapshot: snapshotWithTarget }
+        : undefined;
+}
+export function canResolveSemanticVisibleRef(compiled) {
+    if (compiled?.locator === undefined) {
+        return false;
+    }
+    if (compiled.action === "select") {
+        return true;
+    }
+    return compiled.locator === "role" && ["check", "click", "fill"].includes(compiled.action);
+}
+export function requiresResolvedSemanticVisibleRef(compiled) {
+    return compiled?.action === "select" && compiled.locator !== undefined;
+}
+export async function resolveSemanticActionVisibleRefArgs(options) {
+    if (!canResolveSemanticVisibleRef(options.compiled) ||
+        options.sessionName === undefined ||
+        options.sessionName === "") {
+        return undefined;
+    }
+    const snapshotData = options.refSnapshot
+        ? undefined
+        : await runSessionCommandData({
+            args: ["snapshot", "-i"],
+            cwd: options.cwd,
+            namespace: options.namespace,
+            sessionName: options.sessionName,
+            signal: options.signal,
+        });
+    const resolution = resolveVisibleRefActionFromSnapshot({
+        allowFill: true,
+        compiledAction: options.compiled,
+        refSnapshot: options.refSnapshot,
+        snapshotData,
+    });
+    return resolution
+        ? {
+            args: [...getCompiledSemanticActionSessionPrefix(options.compiled), ...resolution.args],
+            snapshot: resolution.snapshot,
+        }
+        : undefined;
+}

package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-resources.js

@@ -0,0 +1,114 @@
+import { cleanupElectronLaunchResources } from "../../electron/cleanup.js";
+import { launchElectronApp } from "../../electron/launch.js";
+import { redactSensitiveText } from "../../runtime-redaction.js";
+import { buildAgentBrowserResultCategoryDetails } from "../../results/categories.js";
+import { buildElectronHostFailureResult, getElectronLaunchFailureCategory, } from "./final-result.js";
+import { buildManagedSessionOutcome } from "./session-state.js";
+import { prepareAgentBrowserArgs } from "./prepare-artifacts.js";
+import { preparationFailure } from "./prepare-failure.js";
+export async function prepareElectronLaunch(facts, input, freshSessionName) {
+    const compiled = input.compiledElectron;
+    if (compiled?.action !== "launch") {
+        return {};
+    }
+    const launched = await launchElectronApp({ ...compiled, signal: facts.signal });
+    if (!launched.ok) {
+        const managedSessionOutcome = buildManagedSessionOutcome({
+            activeAfter: facts.managedSessionActive,
+            activeBefore: facts.managedSessionActive,
+            attemptedSessionName: freshSessionName,
+            command: "connect",
+            currentSessionName: facts.managedSessionName,
+            previousSessionName: facts.managedSessionName,
+            sessionMode: "fresh",
+            succeeded: false,
+        });
+        return {
+            earlyResult: {
+                kind: "early-result",
+                result: buildElectronHostFailureResult({
+                    compiledElectron: input.redactedCompiledElectron ?? compiled,
+                    errorText: launched.failure.error,
+                    failureCategory: getElectronLaunchFailureCategory(launched.failure),
+                    launchFailure: launched.failure,
+                    managedSessionOutcome,
+                    status: launched.failure.reason,
+                }),
+            },
+        };
+    }
+    return {
+        electronLaunch: {
+            ...launched.value,
+            record: { ...launched.value.record, ownerSessionId: facts.getOwnerSessionId() },
+        },
+    };
+}
+async function cleanupPreparationElectron(state, launch, timeoutMs) {
+    try {
+        const cleanup = await cleanupElectronLaunchResources({
+            child: launch.child,
+            record: launch.record,
+            timeoutMs,
+        });
+        if (cleanup.partial) {
+            state.electronLaunchRecords.set(cleanup.launchId, cleanup.record);
+            state.electronChildProcesses.set(cleanup.launchId, launch.child);
+        }
+    }
+    catch {
+        state.electronLaunchRecords.set(launch.record.launchId, launch.record);
+        state.electronChildProcesses.set(launch.record.launchId, launch.child);
+    }
+}
+export async function cleanupPreparationResources(state, resources) {
+    // Release native execution ownership before tearing down the task-owned Electron process.
+    await resources.lock?.release();
+    if (resources.electronLaunch) {
+        await cleanupPreparationElectron(state, resources.electronLaunch, resources.timeoutMs);
+    }
+}
+function artifactDirectoryFailure(error, path, redactedArgs) {
+    const guidance = "Choose a writable artifact path whose parent components are directories. Use absolute paths in raw batch artifact rows.";
+    const validationError = redactSensitiveText(`Could not prepare artifact directory ${path}: ${error.message}. ${guidance}`);
+    return preparationFailure({
+        message: validationError,
+        details: {
+            agentBrowserStarted: false,
+            args: redactedArgs,
+            nextActions: [
+                {
+                    artifactPath: redactSensitiveText(path),
+                    id: "verify-artifact-path",
+                    reason: guidance,
+                    safety: "The requested browser command did not run; inspect the directory with host file tools before retrying.",
+                    tool: "agent_browser",
+                },
+            ],
+            ...buildAgentBrowserResultCategoryDetails({
+                args: redactedArgs,
+                succeeded: false,
+                validationError,
+            }),
+            validationError,
+        },
+    });
+}
+export async function prepareArtifactArguments(process, request) {
+    try {
+        return {
+            preparedArgs: await prepareAgentBrowserArgs(request.args, request.stdin, process.cwd),
+        };
+    }
+    catch (error) {
+        process.signal?.throwIfAborted();
+        if (!(error instanceof Error) ||
+            !("syscall" in error) ||
+            error.syscall !== "mkdir" ||
+            !("path" in error) ||
+            typeof error.path !== "string") {
+            throw error;
+        }
+        return { earlyResult: artifactDirectoryFailure(error, error.path, request.redactedArgs) };
+    }
+}

package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-semantic.js

@@ -0,0 +1,121 @@
+import { getExplicitSessionPageVerificationRequirement } from "../../page-target-validation.js";
+import { buildExecutionPlan, extractUpstreamCommandTokens } from "../../runtime.js";
+import { getUpstreamEffectiveBatchSteps } from "../batch-stdin.js";
+import { buildUnsupportedScrollIntoViewRecovery } from "./diagnostics.js";
+import { canResolveSemanticVisibleRef, requiresResolvedSemanticVisibleRef, resolveSemanticActionVisibleRefArgs, } from "./prepare-refs.js";
+import { callerOwnedExplicitSession, requiresLivePageVerification, verifyPreparationLivePage, verifyCommandLivePage, } from "./prepare-page-selection.js";
+import { planHasValidationError, withPlanValidationError } from "./prepare-session-plan.js";
+function semanticLocatorError(request, active) {
+    if (request.selection.executionPlan.managedSessionName === request.freshSessionName) {
+        return "semanticAction select with locator cannot resolve a current @ref in sessionMode fresh. Open the page first, then reuse that session, or pass selector plus value/values.";
+    }
+    return active
+        ? "semanticAction select with locator could not resolve to exactly one current visible combobox/listbox ref. Run snapshot -i and retry with selector or a more specific role/name."
+        : "semanticAction select with locator requires an active browser session so the wrapper can resolve a current @ref; open a page first or pass selector plus value/values.";
+}
+function rebuildSemanticPlan(facts, request, resolution) {
+    return {
+        ...request.selection,
+        executionPlan: buildExecutionPlan(resolution.args, {
+            freshSessionName: request.freshSessionName,
+            managedSessionActive: facts.managedSessionActive,
+            managedSessionCompatibilityWorkaround: facts.managedSessionCompatibilityWorkaround,
+            managedSessionName: facts.managedSessionName,
+            managedSessionNamespace: facts.managedSessionNamespace,
+            sessionMode: request.sessionMode,
+        }),
+    };
+}
+function hasLiveSemanticSession(managedSessionActive, preserveAttachedBrowserSession, routing, selection) {
+    return (managedSessionActive ||
+        selection.page.priorSessionTabTarget !== undefined ||
+        callerOwnedExplicitSession(routing.ownsSession, selection.executionPlan) ||
+        preserveAttachedBrowserSession === true);
+}
+async function currentSemanticRef(process, request) {
+    const { page, executionPlan: plan } = request.selection;
+    return resolveSemanticActionVisibleRefArgs({
+        compiled: request.input.compiledSemanticAction,
+        cwd: process.cwd,
+        namespace: plan.namespace,
+        refSnapshot: page.reuseConfirmedCapture &&
+            page.priorSessionTabTargetUnknown !== true &&
+            !page.priorRefSnapshotInvalidation
+            ? page.priorRefSnapshotState
+            : undefined,
+        sessionName: plan.sessionName,
+        signal: process.signal,
+    });
+}
+function finalizeSemanticResolution(facts, request, active, resolution) {
+    if (resolution) {
+        return rebuildSemanticPlan(facts, request, resolution);
+    }
+    if (!planHasValidationError(request.selection.executionPlan) &&
+        requiresResolvedSemanticVisibleRef(request.input.compiledSemanticAction)) {
+        return {
+            ...request.selection,
+            executionPlan: {
+                ...request.selection.executionPlan,
+                validationError: semanticLocatorError(request, active),
+            },
+        };
+    }
+    return request.selection;
+}
+async function resolveSemantic(process, facts, routing, request) {
+    let selection = request.selection;
+    const active = hasLiveSemanticSession(facts.managedSessionActive, process.preserveAttachedBrowserSession, routing, selection);
+    const mayResolve = selection.executionPlan.managedSessionName !== request.freshSessionName &&
+        active &&
+        canResolveSemanticVisibleRef(request.input.compiledSemanticAction);
+    if (!planHasValidationError(selection.executionPlan) &&
+        mayResolve &&
+        requiresLivePageVerification(process.preserveAttachedBrowserSession, routing, selection)) {
+        selection = await verifyPreparationLivePage(process, selection, {
+            args: ["snapshot", "-i"],
+            requirement: getExplicitSessionPageVerificationRequirement({ args: ["snapshot", "-i"] }),
+        });
+    }
+    let resolution;
+    if (!planHasValidationError(selection.executionPlan) && mayResolve) {
+        resolution = await currentSemanticRef(process, { ...request, selection });
+    }
+    selection = finalizeSemanticResolution(facts, { ...request, selection }, active, resolution);
+    return { selection, resolution };
+}
+export async function prepareSemanticAction(process, facts, routing, request) {
+    const semantic = await resolveSemantic(process, facts, routing, request);
+    let selection = semantic.selection;
+    const commandTokens = extractUpstreamCommandTokens(semantic.resolution ? semantic.resolution.args : request.preparedArgs.args);
+    const scrollRecovery = planHasValidationError(selection.executionPlan) || selection.executionPlan.plainTextInspection
+        ? undefined
+        : [commandTokens, ...getUpstreamEffectiveBatchSteps(commandTokens, request.stdin)]
+            .map((tokens) => buildUnsupportedScrollIntoViewRecovery({
+            commandTokens: tokens,
+            sessionName: selection.executionPlan.sessionName,
+        }))
+            .find((recovery) => recovery !== undefined);
+    if (scrollRecovery) {
+        selection = {
+            ...selection,
+            executionPlan: withPlanValidationError(selection.executionPlan, scrollRecovery.error),
+        };
+    }
+    const snapshot = semantic.resolution?.snapshot;
+    const resolvedSnapshot = snapshot
+        ? { ...snapshot, target: snapshot.target ?? selection.page.priorSessionTabTarget }
+        : undefined;
+    selection = await verifyCommandLivePage(process, routing, selection, {
+        commandTokens,
+        resolvedSnapshot,
+        stdin: request.stdin,
+    });
+    return {
+        selection,
+        commandTokens,
+        resolution: semantic.resolution,
+        resolvedSnapshot,
+        scrollRecovery,
+    };
+}