pi-agent-browser-native 0.9.2 → 0.9.4

package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-analysis.js

@@ -0,0 +1,191 @@
+import { analyzeNetworkSourceLookupResults, analyzeSourceLookupResults, redactNetworkSourceLookupAnalysis, } from "../../input-modes/lookups.js";
+import { analyzeQaPresetResults, analyzeQaPresetTimeout, buildQaCompactFailureText, buildQaCompactPassText, extractQaPageContext, } from "../../input-modes/job.js";
+import { extractNavigationSummaryFromData } from "./session-state.js";
+import { collectQaAttachedTarget, formatQaAttachedTargetText, getEvalResultWarning, getEvalStdinHint, getSourceLookupElectronContext, } from "./diagnostics.js";
+function analyzeQaEvidence(draft) {
+    const compiled = draft.input.prepared.compiledQaPreset;
+    if (!compiled) {
+        return;
+    }
+    let qa = draft.input.processResult.timedOut ? analyzeQaPresetTimeout(compiled) : undefined;
+    qa ??= analyzeQaPresetResults(draft.presentationEnvelope?.data, compiled);
+    if (qa?.passed === true && draft.presentation.resultCategory === "failure") {
+        qa = {
+            ...qa,
+            passed: false,
+            summary: draft.presentation.summary,
+            failedChecks: [...qa.failedChecks, draft.presentation.summary],
+        };
+    }
+    draft.qaPreset = qa;
+}
+async function collectQaAttachment(draft) {
+    if (draft.input.prepared.compiledQaPreset?.checks.attached !== true) {
+        return;
+    }
+    const { prepared, cwd, signal } = draft.input;
+    draft.qaAttachedTarget = await collectQaAttachedTarget({
+        currentTarget: draft.currentSessionTabTarget ?? prepared.priorSessionTabTarget,
+        cwd,
+        namespace: prepared.executionPlan.namespace,
+        sessionName: prepared.executionPlan.sessionName,
+        signal,
+    });
+}
+async function lookupSourceEvidence(draft) {
+    const { prepared } = draft.input;
+    const compiled = prepared.compiledSourceLookup;
+    if (!compiled) {
+        return;
+    }
+    const electronContext = getSourceLookupElectronContext({
+        currentTarget: draft.currentSessionTabTarget,
+        electronLaunchRecords: draft.input.state.electronLaunchRecords,
+        namespace: prepared.executionPlan.namespace,
+        priorTarget: prepared.priorSessionTabTarget,
+        sessionName: prepared.executionPlan.sessionName,
+    });
+    draft.sourceLookup = await analyzeSourceLookupResults(draft.presentationEnvelope?.data, compiled, draft.operationCwd, { electronContext, workspaceRoot: draft.operationCwd });
+}
+async function lookupNetworkSourceEvidence(draft) {
+    const compiled = draft.input.prepared.compiledNetworkSourceLookup;
+    if (!compiled) {
+        return;
+    }
+    draft.networkSourceLookup = redactNetworkSourceLookupAnalysis(await analyzeNetworkSourceLookupResults(draft.presentationEnvelope?.data, compiled, draft.operationCwd));
+}
+function prependLookupSummary(draft, text) {
+    const first = draft.presentation.content.at(0);
+    if (first?.type === "text") {
+        draft.presentation.content[0] = { ...first, text: `${text}\n\n${first.text}` };
+    }
+    else {
+        draft.presentation.content.unshift({ type: "text", text });
+    }
+}
+function compactFailedQa(draft) {
+    const qa = draft.qaPreset;
+    const compiled = draft.input.prepared.compiledQaPreset;
+    if (!qa || qa.passed || !compiled || draft.presentation.failureCategory === "artifact-missing") {
+        return;
+    }
+    draft.succeeded = false;
+    draft.presentation.failureCategory = "qa-failure";
+    draft.presentation.summary = qa.summary;
+    const text = buildQaCompactFailureText({
+        causalError: draft.presentation.batchFailure?.failedStep.text,
+        executedStepCount: draft.presentation.batchSteps?.length,
+        page: extractQaPageContext({
+            attachedTarget: draft.qaAttachedTarget,
+            batchData: draft.presentationEnvelope?.data,
+            compiled,
+        }),
+        plannedStepCount: compiled.steps.length,
+        qaPreset: qa,
+    });
+    const nonText = draft.presentation.content.filter((item) => item.type !== "text");
+    draft.presentation.content = [{ type: "text", text }, ...nonText];
+}
+function compactPassedQa(draft) {
+    const qa = draft.qaPreset;
+    const compiled = draft.input.prepared.compiledQaPreset;
+    if (qa?.passed !== true || !compiled || !draft.succeeded) {
+        return;
+    }
+    const text = buildQaCompactPassText({
+        artifactVerification: draft.presentation.artifactVerification,
+        batchStepCount: draft.presentation.batchSteps?.length ?? compiled.steps.length,
+        checks: compiled.checks,
+        page: extractQaPageContext({
+            attachedTarget: draft.qaAttachedTarget,
+            batchData: draft.presentationEnvelope?.data,
+            compiled,
+        }),
+        qaPreset: qa,
+    });
+    draft.presentation.summary = qa.summary;
+    const nonText = draft.presentation.content.filter((item) => item.type !== "text");
+    draft.presentation.content = [{ type: "text", text }, ...nonText];
+}
+export async function analyzeOutputChecks(draft) {
+    analyzeQaEvidence(draft);
+    await collectQaAttachment(draft);
+    await lookupSourceEvidence(draft);
+    await lookupNetworkSourceEvidence(draft);
+    if (draft.networkSourceLookup) {
+        prependLookupSummary(draft, draft.networkSourceLookup.summary);
+    }
+    if (draft.sourceLookup) {
+        prependLookupSummary(draft, draft.sourceLookup.summary);
+    }
+    compactFailedQa(draft);
+    compactPassedQa(draft);
+}
+function attachedDiagnosticsNotice(draft) {
+    const checks = draft.input.prepared.compiledQaPreset?.checks;
+    if (checks?.attached !== true || checks.diagnosticsResetAtStart) {
+        return;
+    }
+    if (!checks.checkNetwork && !checks.checkConsole && !checks.checkErrors) {
+        return;
+    }
+    return "Attached diagnostics: existing upstream session console/network/error buffers were preserved; rows may include events from before qa.attached started.";
+}
+function renderQaBanner(draft) {
+    const text = [
+        formatQaAttachedTargetText(draft.qaAttachedTarget),
+        attachedDiagnosticsNotice(draft),
+    ]
+        .filter((part) => typeof part === "string" && part.length > 0)
+        .join("\n");
+    if ((draft.qaPreset?.passed === true &&
+        draft.input.prepared.compiledQaPreset?.checks.attached === true) ||
+        text.length === 0) {
+        return;
+    }
+    const first = draft.presentation.content.at(0);
+    if (first?.type === "text") {
+        draft.presentation.content[0] = {
+            ...first,
+            text: draft.qaPreset?.passed === false ? `${first.text}\n\n${text}` : `${text}\n\n${first.text}`,
+        };
+    }
+    else {
+        draft.presentation.content.unshift({ type: "text", text });
+    }
+}
+export function renderAttachedQaBanner(draft) {
+    renderQaBanner(draft);
+    if (draft.managedSessionOutcome && draft.managedSessionOutcome.succeeded !== draft.succeeded) {
+        draft.managedSessionOutcome = { ...draft.managedSessionOutcome, succeeded: draft.succeeded };
+    }
+}
+function evalPageUrl(draft, summary) {
+    const key = draft.sessionStateKey;
+    const sessionUrl = key !== undefined && key.length > 0
+        ? draft.input.state.sessionPageState.get(key).tabTarget?.url
+        : undefined;
+    return (summary?.url ??
+        draft.currentSessionTabTarget?.url ??
+        draft.input.prepared.priorSessionTabTarget?.url ??
+        sessionUrl);
+}
+export function collectEvalGuidance(draft) {
+    const summary = draft.navigationSummary ?? extractNavigationSummaryFromData(draft.presentationEnvelope?.data);
+    const { prepared } = draft.input;
+    draft.evalStdinHint = getEvalStdinHint({
+        command: prepared.executionPlan.commandInfo.command,
+        data: draft.presentationEnvelope?.data,
+        stdin: prepared.runtimeToolStdin,
+    });
+    draft.evalResultWarning = getEvalResultWarning({
+        command: prepared.executionPlan.commandInfo.command,
+        data: draft.presentationEnvelope?.data,
+        navigationSummary: summary,
+        pageUrl: evalPageUrl(draft, summary),
+        stdin: prepared.runtimeToolStdin,
+    });
+    if (draft.readConfirmationEvent) {
+        draft.input.state.sessionPageState.applyReadConfirmation(draft.readConfirmationEvent, draft.input.sessionPageStateUpdate);
+    }
+}

package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-confirmation.js

@@ -0,0 +1,152 @@
+import { isStringArray } from "../../results/presentation/content.js";
+import { getAgentBrowserSessionIdentityKey } from "../../argv-grammar.js";
+import { isCloseCommand } from "../../command-taxonomy.js";
+import { isRecord } from "../../parsing.js";
+import { detectConfirmationRequired } from "../../results/confirmation.js";
+import { isSuccessfulNativeConfirmedClose, nextReadConfirmation, parseReadConfirmation, } from "../../read-confirmation.js";
+function confirmationRows(draft) {
+    const { prepared } = draft.input;
+    if (prepared.executionPlan.commandInfo.command !== "batch" ||
+        !Array.isArray(draft.presentationEnvelope?.data)) {
+        return [
+            {
+                tokens: prepared.commandTokens,
+                data: draft.presentationEnvelope?.data,
+                index: 0,
+                response: draft.presentationEnvelope,
+                succeeded: draft.presentationEnvelope?.success === true,
+            },
+        ];
+    }
+    return draft.presentationEnvelope.data.flatMap((row, index) => {
+        if (!isRecord(row)) {
+            return [];
+        }
+        const tokens = isStringArray(row.command)
+            ? row.command
+            : (draft.batchCommandSteps[index] ?? []);
+        return [{ tokens, data: row.result, index, response: row, succeeded: row.success === true }];
+    });
+}
+function matchesConfirmationDecision(row, id) {
+    return row.tokens.length === 2 && row.tokens[0] === "confirm" && row.tokens[1] === id;
+}
+function matchingGuardedConfirmation(draft, row) {
+    const current = draft.readConfirmation;
+    if (current?.state !== "pending" ||
+        current.source !== "native-guarded-action" ||
+        typeof current.command !== "string") {
+        return;
+    }
+    if (!matchesConfirmationDecision(row, current.id)) {
+        return;
+    }
+    if (!isRecord(row.data) || row.data.confirmed !== true || row.data.action !== current.action) {
+        return;
+    }
+    return current;
+}
+function recordConfirmedEffect(draft, row) {
+    const current = matchingGuardedConfirmation(draft, row);
+    if (!current || typeof current.command !== "string" || !isRecord(row.data)) {
+        return;
+    }
+    if (!isRecord(row.data.result) || detectConfirmationRequired(row.data)) {
+        return;
+    }
+    draft.confirmedEffects = [
+        ...draft.confirmedEffects,
+        {
+            command: current.command,
+            data: row.data.result.data,
+            index: row.index,
+            succeeded: row.succeeded && row.data.result.success === true,
+        },
+    ];
+}
+function applyConfirmedFailure(draft, row) {
+    if (row.tokens.length !== 2 || row.tokens[0] !== "confirm" || !isRecord(row.data)) {
+        return;
+    }
+    if (row.data.confirmed !== true ||
+        !isRecord(row.data.result) ||
+        row.data.result.success !== false) {
+        return;
+    }
+    draft.presentationEnvelope = failedConfirmationEnvelope(draft.presentationEnvelope, row.response, row.data.result.error);
+}
+function failedConfirmationEnvelope(envelope, response, error) {
+    if (!envelope || !response) {
+        return envelope;
+    }
+    if (response === envelope) {
+        return { ...envelope, success: false, error };
+    }
+    const data = envelope.data;
+    if (!Array.isArray(data)) {
+        return envelope;
+    }
+    const rows = [];
+    for (const item of data) {
+        rows.push(item === response ? { ...response, success: false, error } : item);
+    }
+    return { ...envelope, success: false, data: rows };
+}
+export function foldReadConfirmations(draft) {
+    const { prepared, state } = draft.input;
+    const sessionName = prepared.executionPlan.sessionName ?? "default";
+    draft.readConfirmation = state.sessionPageState.getReadConfirmation(getAgentBrowserSessionIdentityKey(sessionName, prepared.executionPlan.namespace));
+    for (const row of confirmationRows(draft)) {
+        recordConfirmedEffect(draft, row);
+        const transition = nextReadConfirmation({
+            commandTokens: row.tokens,
+            current: draft.readConfirmation,
+            data: row.data,
+            namespace: prepared.executionPlan.namespace,
+            sessionName,
+            succeeded: row.succeeded,
+        });
+        if (transition) {
+            draft.readConfirmationEvent = transition;
+            draft.readConfirmation = transition;
+        }
+        applyConfirmedFailure(draft, row);
+    }
+    observeDirectConfirmationEffect(draft);
+}
+export function observeHelperConfirmation(draft) {
+    const helperConfirmation = parseReadConfirmation(draft.input.state.observedBrowserEffects?.readConfirmation);
+    // Main pending installs this object; helpers can replace it while their awaits are pending.
+    draft.confirmationFromHelper =
+        draft.input.state.observedBrowserEffects?.readConfirmation !== draft.readConfirmationEvent;
+    if (draft.confirmationFromHelper && helperConfirmation?.state === "pending") {
+        draft.readConfirmationEvent = helperConfirmation;
+        draft.readConfirmation = helperConfirmation;
+        draft.succeeded = false;
+    }
+}
+export function observeFinalHelperConfirmation(draft) {
+    const finalHelperConfirmation = parseReadConfirmation(draft.input.state.observedBrowserEffects?.readConfirmation);
+    if (finalHelperConfirmation?.state === "pending") {
+        draft.confirmationFromHelper ||=
+            draft.input.state.observedBrowserEffects?.readConfirmation !== draft.readConfirmationEvent;
+        draft.readConfirmationEvent = finalHelperConfirmation;
+        draft.succeeded = false;
+    }
+}
+function observeDirectConfirmationEffect(draft) {
+    const { prepared, state } = draft.input;
+    draft.confirmedData =
+        prepared.commandTokens[0] === "confirm" ? draft.confirmedEffects[0]?.data : undefined;
+    draft.confirmedCommand =
+        prepared.commandTokens[0] === "confirm" ? draft.confirmedEffects[0]?.command : undefined;
+    draft.directClose =
+        isCloseCommand(prepared.executionPlan.commandInfo.command) ||
+            isSuccessfulNativeConfirmedClose(prepared.commandTokens, draft.presentationEnvelope?.data);
+    if (draft.readConfirmationEvent?.state === "pending") {
+        state.observedBrowserEffects = {
+            ...state.observedBrowserEffects,
+            readConfirmation: draft.readConfirmationEvent,
+        };
+    }
+}

package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-diagnostics.js

@@ -0,0 +1,182 @@
+import { applyNetworkRouteRecords, buildNetworkRouteDiagnostics, } from "../../results/network-routes.js";
+import { buildElectronRefFreshnessDiagnostic } from "./session-state.js";
+import { buildScrollNoopDiagnostic, collectComboboxFocusDiagnostic, collectElectronBroadGetTextScopeDiagnostics, collectFillVerificationDiagnostic, collectOverlayBlockerDiagnostic, collectSnapshotOverlayBlockerDiagnostic, collectRecordingDependencyWarning, collectScrollPositionSnapshot, collectSelectorTextVisibilityDiagnostics, } from "./diagnostics.js";
+export async function collectPageDiagnostics(options) {
+    const fillVerificationDiagnostic = await verifyFilledInput(options);
+    const electronRefFreshnessDiagnostic = observeElectronRefFreshness(options);
+    const overlayBlockerDiagnostic = await observeOverlayBlockers(options);
+    const textScope = await observeExtractedTextScope(options);
+    const network = observeNetworkRouteEvidence(options);
+    const comboboxFocusDiagnostic = await observeComboboxFocus(options);
+    const recordingDependencyWarning = await collectRecordingDependencyWarning({
+        command: options.input.prepared.executionPlan.commandInfo.command,
+        commandTokens: options.input.prepared.commandTokens,
+        succeeded: options.succeeded,
+    });
+    const scrollNoopDiagnostic = await observeScrollMovement(options);
+    return {
+        diagnostics: {
+            fillVerificationDiagnostic,
+            electronRefFreshnessDiagnostic,
+            overlayBlockerDiagnostic,
+            ...textScope,
+            networkRouteDiagnostics: network.networkRouteDiagnostics,
+            comboboxFocusDiagnostic,
+            recordingDependencyWarning,
+            scrollNoopDiagnostic,
+        },
+        activeNetworkRoutes: network.activeNetworkRoutes,
+        networkRoutesBySession: network.networkRoutesBySession,
+    };
+}
+async function verifyFilledInput(options) {
+    if (!options.succeeded) {
+        return;
+    }
+    const refSnapshot = options.input.prepared.resolvedSemanticActionRefSnapshot ??
+        options.input.prepared.priorRefSnapshotState;
+    return collectFillVerificationDiagnostic({
+        commandTokens: options.input.prepared.commandTokens,
+        cwd: options.input.cwd,
+        forceValueVerification: options.electronRecordForCommand !== undefined,
+        namespace: options.input.prepared.executionPlan.namespace,
+        refSnapshot,
+        sessionName: options.input.prepared.executionPlan.sessionName,
+        signal: options.input.signal,
+    });
+}
+function observeElectronRefFreshness(options) {
+    if (!options.succeeded || !options.electronRecordForCommand) {
+        return;
+    }
+    return buildElectronRefFreshnessDiagnostic({
+        command: options.input.prepared.executionPlan.commandInfo.command,
+        commandTokens: options.input.prepared.commandTokens,
+        record: options.electronRecordForCommand,
+        sessionName: options.input.prepared.executionPlan.sessionName,
+        stdin: options.input.prepared.runtimeToolStdin,
+    });
+}
+function overlayProbeHasNoCompetingRecovery(options) {
+    return (!options.sessionTabCorrection &&
+        !options.aboutBlankSessionMismatch &&
+        !options.electronRecordForCommand &&
+        !options.clickDispatchDiagnostic);
+}
+async function observeOverlayBlockers(options) {
+    if (!options.succeeded) {
+        return;
+    }
+    const snapshotDiagnostic = options.input.prepared.executionPlan.commandInfo.command === "snapshot"
+        ? collectSnapshotOverlayBlockerDiagnostic(options.presentationEnvelope?.data)
+        : undefined;
+    if (snapshotDiagnostic || !overlayProbeHasNoCompetingRecovery(options)) {
+        return snapshotDiagnostic;
+    }
+    return collectOverlayBlockerDiagnostic({
+        command: options.input.prepared.executionPlan.commandInfo.command,
+        cwd: options.input.cwd,
+        data: options.presentationEnvelope?.data,
+        namespace: options.input.prepared.executionPlan.namespace,
+        navigationSummary: options.navigationSummary,
+        priorTarget: options.input.prepared.priorSessionTabTarget,
+        sessionName: options.input.prepared.executionPlan.sessionName,
+        signal: options.input.signal,
+    });
+}
+async function observeExtractedTextScope(options) {
+    if (!options.succeeded) {
+        return { selectorTextVisibilityDiagnostics: [], electronBroadGetTextScopeDiagnostics: [] };
+    }
+    const selectorTextVisibilityDiagnostics = await collectSelectorTextVisibilityDiagnostics({
+        commandInfo: options.input.prepared.executionPlan.commandInfo,
+        commandTokens: options.input.prepared.commandTokens,
+        cwd: options.input.cwd,
+        data: options.presentationEnvelope?.data,
+        namespace: options.input.prepared.executionPlan.namespace,
+        sessionName: options.input.prepared.executionPlan.sessionName,
+        signal: options.input.signal,
+    });
+    const electronBroadGetTextScopeDiagnostics = options.electronRecordForCommand
+        ? collectElectronBroadGetTextScopeDiagnostics({
+            commandInfo: options.input.prepared.executionPlan.commandInfo,
+            commandTokens: options.input.prepared.commandTokens,
+            currentTarget: options.currentSessionTabTarget,
+            data: options.presentationEnvelope?.data,
+            electronLaunchRecords: options.input.state.electronLaunchRecords,
+            namespace: options.input.prepared.executionPlan.namespace,
+            priorTarget: options.input.prepared.priorSessionTabTarget,
+            sessionName: options.input.prepared.executionPlan.sessionName,
+        })
+        : [];
+    return { selectorTextVisibilityDiagnostics, electronBroadGetTextScopeDiagnostics };
+}
+function observeNetworkRouteEvidence(options) {
+    const activeNetworkRoutes = options.sessionStateKey !== undefined && options.sessionStateKey.length > 0
+        ? options.networkRoutesBySession.get(options.sessionStateKey)
+        : undefined;
+    const plan = options.input.prepared.executionPlan;
+    const networkRouteDiagnostics = options.succeeded &&
+        plan.commandInfo.command === "network" &&
+        plan.commandInfo.subcommand === "requests" &&
+        plan.sessionName !== undefined &&
+        plan.sessionName.length > 0
+        ? buildNetworkRouteDiagnostics(options.presentationEnvelope?.data, activeNetworkRoutes)
+        : undefined;
+    const networkRoutesBySession = applyNetworkRouteState({
+        commandTokens: options.input.prepared.commandTokens,
+        routesBySession: options.networkRoutesBySession,
+        sessionName: options.sessionStateKey,
+        succeeded: options.succeeded,
+    });
+    return { activeNetworkRoutes, networkRouteDiagnostics, networkRoutesBySession };
+}
+async function observeComboboxFocus(options) {
+    if (!options.succeeded) {
+        return;
+    }
+    return collectComboboxFocusDiagnostic({
+        command: options.input.prepared.executionPlan.commandInfo.command,
+        commandTokens: options.input.prepared.commandTokens,
+        cwd: options.input.cwd,
+        namespace: options.input.prepared.executionPlan.namespace,
+        semanticAction: options.input.prepared.compiledSemanticAction,
+        sessionName: options.input.prepared.executionPlan.sessionName,
+        signal: options.input.signal,
+    });
+}
+async function observeScrollMovement(options) {
+    if (!options.succeeded || !options.input.prepared.shouldProbeScrollNoop) {
+        return;
+    }
+    return buildScrollNoopDiagnostic(options.input.prepared.scrollPositionBefore, await collectScrollPositionSnapshot({
+        cwd: options.input.cwd,
+        namespace: options.input.prepared.executionPlan.namespace,
+        sessionName: options.input.prepared.executionPlan.sessionName,
+        signal: options.input.signal,
+    }));
+}
+export function setNetworkRouteState(options) {
+    const sessionName = options.sessionName;
+    if (sessionName === undefined || sessionName.length === 0) {
+        return options.routesBySession;
+    }
+    if (options.routes === options.routesBySession.get(sessionName)) {
+        return options.routesBySession;
+    }
+    const next = new Map(options.routesBySession);
+    if (options.routes && options.routes.length > 0) {
+        next.set(sessionName, options.routes);
+    }
+    else {
+        next.delete(sessionName);
+    }
+    return next;
+}
+function applyNetworkRouteState(options) {
+    const sessionName = options.sessionName;
+    const routes = sessionName !== undefined && sessionName.length > 0
+        ? applyNetworkRouteRecords(options.routesBySession.get(sessionName), options.commandTokens, options.succeeded)
+        : undefined;
+    return setNetworkRouteState({ routes, routesBySession: options.routesBySession, sessionName });
+}

package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-electron.js

@@ -0,0 +1,150 @@
+import { cleanupElectronLaunchResources } from "../../electron/cleanup.js";
+import { createFreshSessionName } from "../../runtime-session-identity.js";
+import { closeManagedSession } from "./managed-session-daemon-policy.js";
+import { buildManagedSessionOutcome } from "./session-state.js";
+import { collectElectronHandoff } from "./diagnostics.js";
+function handoffExceptionMessage(error) {
+    // Unstructured thrown objects may hold credentials; only an explicit public string is safe to retain.
+    return typeof error === "string" ? error : "Electron handoff failed with a non-Error exception.";
+}
+async function collectLaunchHandoff(draft, sessionName) {
+    const { prepared, cwd, signal } = draft.input;
+    const handoff = prepared.compiledElectron?.action === "launch" ? prepared.compiledElectron.handoff : "connect";
+    try {
+        return await collectElectronHandoff({
+            cwd,
+            handoff,
+            namespace: prepared.executionPlan.namespace,
+            sessionName,
+            signal,
+        });
+    }
+    catch (error) {
+        return {
+            error: error instanceof Error ? error.message : handoffExceptionMessage(error),
+            failureCategory: signal?.aborted === true ? "aborted" : "upstream-error",
+            handoff,
+        };
+    }
+}
+function recordElectronOwnership(draft, launch, record) {
+    draft.input.state.electronLaunchRecords.set(record.launchId, record);
+    draft.input.state.electronChildProcesses.set(record.launchId, launch.child);
+}
+function retireFailedElectronSession(draft, sessionName, sessionKey) {
+    draft.input.state.closedManagedSessionNames.add(sessionKey);
+    const routes = new Map(draft.networkRoutesBySession);
+    routes.delete(sessionKey);
+    draft.networkRoutesBySession = routes;
+    draft.input.state.sessionPageState.clearSession(sessionKey);
+    if (draft.managedSessionName !== sessionName ||
+        draft.managedSessionNamespace !== draft.input.prepared.executionPlan.namespace) {
+        return;
+    }
+    draft.managedSessionActive = false;
+    draft.freshSessionOrdinal += 1;
+    draft.managedSessionName = createFreshSessionName(draft.input.state.managedSessionBaseName, draft.input.state.ephemeralSessionSeed, draft.freshSessionOrdinal);
+    draft.managedSessionNamespace = undefined;
+}
+function failedHandoffOutcome(draft, sessionName) {
+    draft.managedSessionOutcome = buildManagedSessionOutcome({
+        activeAfter: draft.managedSessionActive,
+        activeBefore: draft.priorManagedSessionActive,
+        attemptedSessionName: sessionName,
+        command: draft.input.prepared.executionPlan.commandInfo.command,
+        currentSessionName: draft.managedSessionName,
+        currentSessionNamespace: draft.managedSessionNamespace,
+        previousSessionName: draft.priorManagedSessionName,
+        replacedSessionName: draft.replacedManagedSessionName,
+        replacedSessionNamespace: draft.priorManagedSessionNamespace,
+        sessionMode: draft.input.prepared.sessionMode,
+        succeeded: false,
+    });
+}
+async function cleanupFailedHandoff(draft, launch, record, sessionName) {
+    const sessionKey = draft.sessionStateKey ?? sessionName;
+    const { prepared, state, cwd, implicitSessionCloseTimeoutMs } = draft.input;
+    const closeError = await closeManagedSession({
+        confirmActions: state.sessionPageState.get(sessionKey).confirmActions ??
+            process.env.AGENT_BROWSER_CONFIRM_ACTIONS,
+        cwd,
+        headedManagedAutosaveInterval: prepared.ownedManagedSessionContext?.headedManagedAutosaveInterval,
+        namespace: prepared.executionPlan.namespace,
+        policyLock: prepared.managedSessionPolicyLock,
+        preserveAttachedBrowserSession: draft.input.preserveAttachedBrowserSession,
+        restoreState: state.managedSessionRestoreState,
+        sessionName,
+        timeoutMs: implicitSessionCloseTimeoutMs,
+    });
+    draft.electronFailedConnectCleanup = await cleanupElectronLaunchResources({
+        child: launch.child,
+        record,
+        timeoutMs: implicitSessionCloseTimeoutMs,
+    });
+    draft.electronLaunchRecord = draft.electronFailedConnectCleanup.record;
+    if (draft.electronFailedConnectCleanup.partial) {
+        recordElectronOwnership(draft, launch, draft.electronLaunchRecord);
+    }
+    else {
+        state.electronLaunchRecords.delete(draft.electronLaunchRecord.launchId);
+        state.electronChildProcesses.delete(draft.electronLaunchRecord.launchId);
+    }
+    if (closeError === undefined || closeError.length === 0) {
+        retireFailedElectronSession(draft, sessionName, sessionKey);
+    }
+    failedHandoffOutcome(draft, sessionName);
+}
+function applyHandoffSnapshot(draft, sessionName, handoff) {
+    const snapshot = handoff.refSnapshot;
+    if (!snapshot) {
+        return;
+    }
+    const sessionKey = draft.sessionStateKey ?? sessionName;
+    const { state, sessionPageStateUpdate } = draft.input;
+    const refUpdate = state.sessionPageState.applyRefSnapshot({
+        sessionName: sessionKey,
+        snapshot,
+        update: sessionPageStateUpdate,
+    });
+    draft.currentRefSnapshot = refUpdate.refSnapshot;
+    draft.currentRefSnapshotInvalidation = refUpdate.refSnapshotInvalidation;
+    if (snapshot.target) {
+        const targetUpdate = state.sessionPageState.applyTabTarget({
+            sessionName: sessionKey,
+            target: snapshot.target,
+            update: sessionPageStateUpdate,
+        });
+        draft.currentSessionTabTarget = targetUpdate.tabTarget;
+    }
+}
+export async function reconcileElectronHandoff(draft) {
+    const { prepared, implicitSessionCloseTimeoutMs } = draft.input;
+    draft.electronFailedConnectCleanup = prepared.electronFailedConnectCleanup;
+    draft.electronHandoff = prepared.electronHandoff;
+    const launch = prepared.electronLaunch;
+    if (!launch) {
+        return;
+    }
+    const sessionName = prepared.executionPlan.sessionName;
+    if (!draft.succeeded || sessionName === undefined || sessionName.length === 0) {
+        draft.electronFailedConnectCleanup = await cleanupElectronLaunchResources({
+            child: launch.child,
+            record: launch.record,
+            timeoutMs: implicitSessionCloseTimeoutMs,
+        });
+        draft.electronLaunchRecord = draft.electronFailedConnectCleanup.record;
+        return;
+    }
+    const record = { ...launch.record, namespace: prepared.executionPlan.namespace, sessionName };
+    draft.electronLaunchRecord = record;
+    const handoff = await collectLaunchHandoff(draft, sessionName);
+    draft.electronHandoff = handoff;
+    if (handoff.error !== undefined && handoff.error.length > 0) {
+        draft.succeeded = false;
+        draft.presentationEnvelope = { error: handoff.error, success: false };
+        await cleanupFailedHandoff(draft, launch, record, sessionName);
+        return;
+    }
+    recordElectronOwnership(draft, launch, record);
+    applyHandoffSnapshot(draft, sessionName, handoff);
+}

package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-lifecycle-contracts.js

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

package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-lifecycle-phase-contracts.js

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