pi-agent-browser-native 0.9.2 → 0.9.4

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

@@ -0,0 +1,93 @@
+import { parseArgvDescriptor } from "../../argv-descriptor.js";
+import { needsManagedSession } from "../../command-policy.js";
+import { isCloseCommand } from "../../command-taxonomy.js";
+import { acquireOwnedManagedSessionDaemonPolicy, inspectManagedSessionDaemon, } from "./managed-session-daemon-policy.js";
+import { planHasValidationError, withPlanValidationError, } from "./prepare-session-plan.js";
+function daemonReuseError(plan, session, policy) {
+    if (policy.error !== undefined && policy.error !== "") {
+        return policy.error;
+    }
+    if (isCloseCommand(plan.commandInfo.command) || policy.daemonStatus !== "active") {
+        return undefined;
+    }
+    if (session.offCurrentLaunchScopedFlags.length > 0) {
+        return `This older wrapper-owned session is already running, so launch-scoped flags ${session.offCurrentLaunchScopedFlags.join(", ")} would replace or be ignored by upstream agent-browser. Close it first, or remove the explicit --session and retry with sessionMode: "fresh".`;
+    }
+    if (session.offCurrentCompatibilityUpgrade) {
+        return 'This older wrapper-owned session is already running without the user agent required by this site. Close it first, or remove the explicit --session and retry with sessionMode: "fresh".';
+    }
+    return undefined;
+}
+function applyColdCompatibility(plan, session, context, status) {
+    if (isCloseCommand(plan.commandInfo.command) ||
+        status !== "inactive" ||
+        session.compatibilityUserAgent === undefined ||
+        session.compatibilityUserAgent === "" ||
+        session.compatibilityUserAgentApplied) {
+        return { plan, ownedManagedSession: context };
+    }
+    return {
+        ownedManagedSession: { ...context, compatibilityUserAgent: session.compatibilityUserAgent },
+        plan: {
+            ...plan,
+            effectiveArgs: ["--user-agent", session.compatibilityUserAgent, ...plan.effectiveArgs],
+        },
+    };
+}
+export async function prepareDaemonPolicy(process, electronLaunchRecord, planning) {
+    const { plan, session } = planning;
+    const context = session.ownedManagedSession;
+    if (session.browserIndependent || planHasValidationError(plan) || !context) {
+        return { plan, session, policy: { inactive: false } };
+    }
+    const policy = await acquireOwnedManagedSessionDaemonPolicy({
+        context,
+        electronLaunchRecord,
+        electronVerificationTimeoutMs: process.timeoutMs,
+        mode: isCloseCommand(plan.commandInfo.command) ? "close" : "reuse",
+        signal: process.signal,
+    });
+    const error = daemonReuseError(plan, session, policy);
+    const resolved = error !== undefined && error !== ""
+        ? { plan: withPlanValidationError(plan, error), ownedManagedSession: context }
+        : applyColdCompatibility(plan, session, context, policy.daemonStatus);
+    return {
+        plan: resolved.plan,
+        session: { ...session, ownedManagedSession: resolved.ownedManagedSession },
+        policy: {
+            lock: policy.lock,
+            inactive: policy.daemonStatus === "inactive",
+            cleanupOnlyReason: policy.error !== undefined && policy.error !== "" ? policy.cleanupOnlyReason : undefined,
+        },
+    };
+}
+function chromeStartupEligible(facts, plan, request) {
+    return (facts.chromeStartupArgs !== undefined &&
+        facts.preserveAttachedBrowserSession !== true &&
+        !request.browserIndependent &&
+        !planHasValidationError(plan) &&
+        !isCloseCommand(plan.commandInfo.command) &&
+        needsManagedSession(parseArgvDescriptor(request.preparedArgs.args), request.stdin));
+}
+export async function prepareChromeStartupArgs(facts, planning, request) {
+    if (!chromeStartupEligible(facts, planning.plan, {
+        ...request,
+        browserIndependent: planning.session.browserIndependent,
+    })) {
+        return undefined;
+    }
+    const { plan, session, policy } = planning;
+    let inactive = policy.inactive;
+    if (!session.ownedManagedSession) {
+        inactive =
+            facts.daemonInactive ??
+                (plan.sessionName !== undefined &&
+                    (await inspectManagedSessionDaemon({
+                        cwd: facts.cwd,
+                        signal: facts.signal,
+                        sessionName: plan.sessionName,
+                        namespace: plan.namespace,
+                    })).status === "inactive");
+    }
+    return inactive || facts.configuredChromeLaunch === true ? facts.chromeStartupArgs : undefined;
+}

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

@@ -0,0 +1,42 @@
+import { buildAgentBrowserResultCategoryDetails } from "../../results/categories.js";
+import { buildSessionDetailFields } from "./session-state.js";
+export function preparationFailure(request) {
+    return {
+        kind: "early-result",
+        statePatch: request.statePatch,
+        result: {
+            content: [{ type: "text", text: request.message }],
+            details: { ...request.details },
+            isError: true,
+        },
+    };
+}
+export function preparationSessionDetails(restoreDisabled, plan) {
+    return buildSessionDetailFields(plan.sessionName, plan.usedImplicitSession, plan.namespace, restoreDisabled);
+}
+export function categorizedGuardFailure(restoreDisabled, request, failure) {
+    return preparationFailure({
+        message: failure.message,
+        statePatch: request.statePatch,
+        details: {
+            args: request.redactedArgs,
+            ...(failure.omitCommand === true ? {} : { command: request.plan.commandInfo.command }),
+            compatibilityWorkaround: request.plan.compatibilityWorkaround,
+            effectiveArgs: request.effectiveArgs,
+            sessionMode: request.sessionMode,
+            ...buildAgentBrowserResultCategoryDetails({
+                args: request.effectiveArgs,
+                command: request.plan.commandInfo.command,
+                errorText: failure.message,
+                failureCategory: failure.failureCategory,
+                succeeded: false,
+                validationError: failure.validationError,
+            }),
+            ...(failure.validationError !== undefined
+                ? { validationError: failure.validationError }
+                : {}),
+            ...preparationSessionDetails(restoreDisabled, request.plan),
+            ...failure.details,
+        },
+    });
+}

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

@@ -0,0 +1,242 @@
+import { prepareAgentBrowserSpawnArgs } from "../../process.js";
+import { redactInvocationArgs } from "../../runtime-redaction.js";
+import { buildAgentBrowserResultCategoryDetails } from "../../results/categories.js";
+import { applyNamespaceToNextActions } from "../../results/next-actions.js";
+import { buildSessionAwareStaleRefNextActions, buildSessionTabRecoveryNextActions, } from "../../results/recovery-next-actions.js";
+import { buildStaleRefPreflight, getTraceOwnerGuardMessage } from "./session-state.js";
+import { formatAgentBrowserNextActionsText, redactRecoveryHint } from "./final-result.js";
+import { validateQaAttachedPrecondition } from "./diagnostics.js";
+import { findRequestedArtifactCloseViolation } from "./prompt-guards.js";
+import { collectSamePageRefFreshnessPreflight } from "./prepare-refs.js";
+import { getExactSensitiveStdinValues, validateStdinCommandContract } from "./prepare-input.js";
+import { categorizedGuardFailure, preparationFailure, preparationSessionDetails, } from "./prepare-failure.js";
+export function prepareGuardEvidence(preserveAttachedBrowserSession, context) {
+    const plan = context.semantic.selection.executionPlan;
+    return {
+        redactedEffectiveArgs: redactInvocationArgs(prepareAgentBrowserSpawnArgs(plan.effectiveArgs, undefined, preserveAttachedBrowserSession, context.chromeStartupArgs)),
+        redactedRecoveryHint: redactRecoveryHint(plan.recoveryHint),
+        statePatch: plan.managedSessionName === context.freshSessionName
+            ? { freshSessionOrdinal: context.freshSessionOrdinal + 1 }
+            : {},
+        exactSensitiveValues: getExactSensitiveStdinValues({
+            command: plan.commandInfo.command,
+            commandTokens: context.semantic.commandTokens,
+            stdin: context.stdin,
+        }),
+    };
+}
+function guardRequest(context, evidence) {
+    return {
+        plan: context.semantic.selection.executionPlan,
+        redactedArgs: context.input.redactedArgs,
+        effectiveArgs: evidence.redactedEffectiveArgs,
+        sessionMode: context.sessionMode,
+        statePatch: evidence.statePatch,
+    };
+}
+function planRecoveryActions(context, tabError) {
+    const { selection, scrollRecovery } = context.semantic;
+    const plan = selection.executionPlan;
+    return applyNamespaceToNextActions(tabError
+        ? buildSessionTabRecoveryNextActions({
+            kind: "tab-drift",
+            resultCategory: "failure",
+            sessionName: plan.sessionName,
+            tabCorrection: selection.sessionTabCorrection,
+            target: selection.page.priorSessionTabTarget,
+        })
+        : scrollRecovery?.nextActions, plan.namespace);
+}
+function planFailure(restoreDisabled, context, evidence, cleanup) {
+    const { selection } = context.semantic;
+    const { executionPlan: plan, page } = selection;
+    const error = plan.validationError;
+    if (error === undefined || error === "") {
+        return undefined;
+    }
+    const tabError = selection.sessionTabSelectionError !== undefined && selection.sessionTabSelectionError !== "";
+    const nextActions = planRecoveryActions(context, tabError);
+    const nextActionsText = formatAgentBrowserNextActionsText(nextActions);
+    const input = context.input;
+    return preparationFailure({
+        message: [error, nextActionsText]
+            .filter((text) => text !== undefined)
+            .join("\n\n"),
+        statePatch: evidence.statePatch,
+        details: {
+            args: input.redactedArgs,
+            compiledElectron: input.redactedCompiledElectron,
+            compiledJob: input.redactedCompiledJob,
+            compiledQaPreset: input.redactedCompiledQaPreset,
+            compiledSourceLookup: input.redactedCompiledSourceLookup,
+            compiledNetworkSourceLookup: input.redactedCompiledNetworkSourceLookup,
+            invalidValueFlag: plan.invalidValueFlag,
+            managedSessionCleanupOnlyReason: cleanup.reason,
+            ...preparationSessionDetails(restoreDisabled, plan),
+            ...(cleanup.reason !== undefined ? { namespace: cleanup.namespace ?? "" } : {}),
+            nextActions,
+            sessionMode: context.sessionMode,
+            sessionRecoveryHint: evidence.redactedRecoveryHint,
+            startupScopedFlags: plan.startupScopedFlags,
+            ...(tabError
+                ? {
+                    effectiveArgs: evidence.redactedEffectiveArgs,
+                    sessionTabCorrection: selection.sessionTabCorrection,
+                }
+                : {}),
+            ...(page.coldManagedSession
+                ? { refSnapshotInvalidation: page.priorRefSnapshotInvalidation }
+                : {}),
+            ...buildAgentBrowserResultCategoryDetails({
+                args: input.redactedArgs,
+                command: plan.commandInfo.command,
+                errorText: error,
+                failureCategory: tabError ? "tab-drift" : undefined,
+                succeeded: false,
+                validationError: error,
+            }),
+            validationError: error,
+        },
+    });
+}
+function synchronousGuards(traceOwners, restoreDisabled, context, evidence) {
+    const plan = context.semantic.selection.executionPlan;
+    const traceError = getTraceOwnerGuardMessage({
+        command: plan.commandInfo.command,
+        sessionName: context.semantic.selection.page.sessionStateKey,
+        subcommand: plan.commandInfo.subcommand,
+        traceOwners,
+    });
+    const error = traceError !== undefined && traceError !== ""
+        ? traceError
+        : validateStdinCommandContract({
+            command: plan.commandInfo.command,
+            commandTokens: context.semantic.commandTokens,
+            stdin: context.stdin,
+        });
+    return error !== undefined && error !== ""
+        ? categorizedGuardFailure(restoreDisabled, guardRequest(context, evidence), {
+            message: error,
+            validationError: error,
+        })
+        : undefined;
+}
+async function artifactCloseGuard(artifactManifest, facts, context, evidence) {
+    const violation = await findRequestedArtifactCloseViolation({
+        artifactManifest,
+        command: context.semantic.selection.executionPlan.commandInfo.command,
+        cwd: facts.cwd,
+        promptPolicy: facts.promptPolicy,
+    });
+    return violation
+        ? categorizedGuardFailure(facts.isRestoreDisabled(), guardRequest(context, evidence), {
+            message: violation.message,
+            validationError: violation.message,
+            failureCategory: "policy-blocked",
+            details: { promptGuard: violation },
+        })
+        : undefined;
+}
+function staleRefFailure(restoreDisabled, context, evidence, request) {
+    const plan = context.semantic.selection.executionPlan;
+    return categorizedGuardFailure(restoreDisabled, guardRequest(context, evidence), {
+        message: request.stale.message,
+        failureCategory: "stale-ref",
+        details: {
+            nextActions: applyNamespaceToNextActions(buildSessionAwareStaleRefNextActions(plan.sessionName), plan.namespace),
+            refIds: request.stale.refIds,
+            refSnapshot: request.stale.snapshot,
+            ...(request.includeInvalidation
+                ? { refSnapshotInvalidation: request.stale.snapshotInvalidation }
+                : {}),
+        },
+    });
+}
+async function refGuards(owners, facts, context, evidence) {
+    const { commandTokens, resolvedSnapshot, selection } = context.semantic;
+    const { page, executionPlan: plan } = selection;
+    const stale = buildStaleRefPreflight({
+        commandTokens,
+        currentTarget: page.priorSessionTabTarget,
+        requireExactTargetUrl: page.reuseConfirmedCapture,
+        refSnapshot: resolvedSnapshot ?? page.priorRefSnapshotState,
+        refSnapshotInvalidation: resolvedSnapshot ? undefined : page.priorRefSnapshotInvalidation,
+        stdin: context.stdin,
+    });
+    if (stale) {
+        return staleRefFailure(facts.isRestoreDisabled(), context, evidence, {
+            stale,
+            includeInvalidation: true,
+        });
+    }
+    const freshness = await collectSamePageRefFreshnessPreflight({
+        commandTokens,
+        cwd: facts.cwd,
+        currentTarget: page.priorSessionTabTarget,
+        previousSnapshot: resolvedSnapshot || page.reuseConfirmedCapture ? undefined : page.priorRefSnapshotState,
+        stdin: context.stdin,
+        namespace: plan.namespace,
+        sessionName: plan.sessionName,
+        signal: facts.signal,
+    });
+    if (!freshness) {
+        return undefined;
+    }
+    if (freshness.snapshot && page.sessionStateKey !== undefined && page.sessionStateKey !== "") {
+        owners.pageState.applyRefSnapshot({
+            fallbackTarget: page.priorSessionTabTarget,
+            sessionName: page.sessionStateKey,
+            snapshot: freshness.snapshot,
+            update: owners.update,
+        });
+    }
+    return staleRefFailure(facts.isRestoreDisabled(), context, evidence, {
+        stale: freshness,
+        includeInvalidation: false,
+    });
+}
+async function qaAttachedGuard(facts, context, evidence) {
+    if (context.input.compiledQaPreset?.checks.attached !== true) {
+        return undefined;
+    }
+    const plan = context.semantic.selection.executionPlan;
+    const failure = await validateQaAttachedPrecondition({
+        cwd: facts.cwd,
+        namespace: plan.namespace,
+        sessionName: plan.sessionName,
+        signal: facts.signal,
+    });
+    return failure
+        ? categorizedGuardFailure(facts.isRestoreDisabled(), guardRequest(context, evidence), {
+            omitCommand: true,
+            message: failure.error,
+            validationError: failure.error,
+            details: {
+                compiledQaPreset: context.input.redactedCompiledQaPreset,
+                nextActions: applyNamespaceToNextActions(failure.nextActions, plan.namespace),
+            },
+        })
+        : undefined;
+}
+export async function validatePreparationGuards(owners, facts, context, evidence) {
+    const invalidPlan = planFailure(facts.isRestoreDisabled(), context, evidence, {
+        reason: context.policy.cleanupOnlyReason,
+        namespace: context.session.ownedManagedSession?.namespace,
+    });
+    if (invalidPlan) {
+        return invalidPlan;
+    }
+    const synchronous = synchronousGuards(owners.traceOwners, facts.isRestoreDisabled(), context, evidence);
+    if (synchronous) {
+        return synchronous;
+    }
+    const artifact = await artifactCloseGuard(owners.artifactManifest, facts, context, evidence);
+    if (artifact) {
+        return artifact;
+    }
+    const refs = await refGuards(owners, facts, context, evidence);
+    if (refs) {
+        return refs;
+    }
+    return qaAttachedGuard(facts, context, evidence);
+}

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

@@ -0,0 +1,75 @@
+export function normalizeRunInput(input) {
+    const base = {
+        redactedArgs: input.redactedArgs,
+        toolArgs: input.toolArgs,
+        toolStdin: input.toolStdin,
+    };
+    switch (input.kind) {
+        case "electron":
+            return {
+                ...base,
+                compiledElectron: input.compiledElectron,
+                redactedCompiledElectron: input.redactedCompiledElectron,
+            };
+        case "networkSourceLookup":
+            return {
+                ...base,
+                compiledNetworkSourceLookup: input.compiledNetworkSourceLookup,
+                redactedCompiledNetworkSourceLookup: input.redactedCompiledNetworkSourceLookup,
+            };
+        case "qa":
+            return {
+                ...base,
+                compiledJob: input.compiledJob,
+                compiledQaPreset: input.compiledQaPreset,
+                redactedCompiledJob: input.redactedCompiledJob,
+                redactedCompiledQaPreset: input.redactedCompiledQaPreset,
+            };
+        case "semanticAction":
+            return {
+                ...base,
+                compiledSemanticAction: input.compiledSemanticAction,
+                redactedCompiledSemanticAction: input.redactedCompiledSemanticAction,
+            };
+        case "sourceLookup":
+            return {
+                ...base,
+                compiledSourceLookup: input.compiledSourceLookup,
+                redactedCompiledSourceLookup: input.redactedCompiledSourceLookup,
+            };
+        case "args":
+            return base;
+    }
+}
+export function buildInvocationPreview(effectiveArgs) {
+    const preview = effectiveArgs.join(" ");
+    return preview.length > 120 ? `${preview.slice(0, 117)}...` : preview;
+}
+function isPasswordStdinAuthSave(options) {
+    return (options.command === "auth" &&
+        options.commandTokens[1] === "save" &&
+        options.commandTokens.includes("--password-stdin"));
+}
+export function getExactSensitiveStdinValues(options) {
+    if (options.stdin === undefined || !isPasswordStdinAuthSave(options)) {
+        return [];
+    }
+    return [
+        ...new Set([options.stdin, options.stdin.trimEnd(), options.stdin.trim()].filter((value) => value.length > 0)),
+    ];
+}
+export function validateStdinCommandContract(options) {
+    if (options.stdin === undefined || options.command === "batch") {
+        return undefined;
+    }
+    if (options.command === "eval" && options.commandTokens.includes("--stdin")) {
+        return undefined;
+    }
+    if (isPasswordStdinAuthSave(options)) {
+        return undefined;
+    }
+    const commandLabel = options.command !== undefined && options.command !== ""
+        ? `\`${options.command}\``
+        : "the requested command";
+    return `agent_browser stdin is only supported for \`batch\`, \`eval --stdin\`, and \`auth save --password-stdin\`; remove stdin from ${commandLabel} or use one of those command forms.`;
+}

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

@@ -0,0 +1,92 @@
+import { isRecord } from "../../parsing.js";
+import { trySnapshotFilter } from "./prepare/snapshot-filter.js";
+import { tryNetworkRequestsPageFilter } from "./prepare/network-page-filter.js";
+import { tryContainerScroll, tryPageScrollTo } from "./prepare/scroll-shims.js";
+import { inspectPreparationGeneration } from "./prepare-page-state.js";
+function observationRequest(process, restoreDisabled, context, evidence) {
+    const plan = context.semantic.selection.executionPlan;
+    return {
+        commandTokens: [...context.semantic.commandTokens],
+        compatibilityWorkaround: plan.compatibilityWorkaround,
+        cwd: process.cwd,
+        effectiveArgs: [...evidence.redactedEffectiveArgs],
+        managedSessionRestoreDisabled: restoreDisabled,
+        redactedArgs: context.input.redactedArgs,
+        sessionMode: context.sessionMode,
+        namespace: plan.namespace,
+        sessionName: plan.sessionName,
+        signal: process.signal,
+        usedImplicitSession: plan.usedImplicitSession,
+    };
+}
+async function bindFilteredSnapshotGeneration(owners, process, context) {
+    const { page, executionPlan: plan } = context.semantic.selection;
+    const key = page.sessionStateKey;
+    if (key === undefined ||
+        key === "" ||
+        plan.sessionName === undefined ||
+        plan.sessionName === "") {
+        return;
+    }
+    const daemon = await inspectPreparationGeneration(process, {
+        namespace: plan.namespace,
+        sessionName: plan.sessionName,
+        owned: context.session.ownedManagedSession,
+    });
+    owners.pageState.bindSnapshotGeneration(key, daemon.status === "active" ? daemon.generation : undefined);
+    if (context.session.ownedManagedSession &&
+        daemon.status === "active" &&
+        daemon.generation !== undefined &&
+        daemon.generation !== "") {
+        owners.restoreState.recordDaemonRestoreKey(plan.sessionName, plan.namespace, daemon.restoreKey, daemon.generation);
+    }
+    return { refSnapshot: owners.pageState.get(key).refSnapshot };
+}
+async function filteredSnapshot(owners, process, context, evidence) {
+    const { page } = context.semantic.selection;
+    const result = await trySnapshotFilter({
+        ...observationRequest(process, () => owners.restoreState.isDisabled(context.semantic.selection.executionPlan.sessionName, context.semantic.selection.executionPlan.namespace), context, evidence),
+        modelVisible: process.modelVisible,
+        artifactManifest: owners.artifactManifest,
+        persistentArtifactStore: owners.artifactStore,
+        previousRefSnapshot: page.priorRefSnapshotState,
+        sessionStateKey: page.sessionStateKey,
+        sessionPageState: owners.pageState,
+        sessionPageStateUpdate: owners.update,
+    });
+    if (!result) {
+        return undefined;
+    }
+    const generation = await bindFilteredSnapshotGeneration(owners, process, context);
+    const toolResult = generation && isRecord(result.result.details)
+        ? { ...result.result, details: { ...result.result.details, ...generation } }
+        : result.result;
+    return {
+        kind: "early-result",
+        statePatch: {
+            ...evidence.statePatch,
+            artifactManifest: result.artifactManifest ?? evidence.statePatch.artifactManifest,
+        },
+        result: toolResult,
+    };
+}
+export async function prepareObservations(owners, process, context, evidence) {
+    const snapshot = await filteredSnapshot(owners, process, context, evidence);
+    if (snapshot) {
+        return snapshot;
+    }
+    const request = observationRequest(process, () => owners.restoreState.isDisabled(context.semantic.selection.executionPlan.sessionName, context.semantic.selection.executionPlan.namespace), context, evidence);
+    const network = await tryNetworkRequestsPageFilter(request);
+    if (network) {
+        return { kind: "early-result", statePatch: evidence.statePatch, result: network };
+    }
+    if (context.semantic.selection.executionPlan.startupScopedFlags.length !== 0) {
+        return undefined;
+    }
+    const container = await tryContainerScroll(request);
+    if (container) {
+        return { kind: "early-result", statePatch: evidence.statePatch, result: container };
+    }
+    const page = await tryPageScrollTo(request);
+    return page ? { kind: "early-result", statePatch: evidence.statePatch, result: page } : undefined;
+}