pi-agent-browser-native 0.9.2 → 0.9.4

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

@@ -0,0 +1,144 @@
+import { buildAgentBrowserNextActions } from "../../results/action-recommendations.js";
+import { appendUniqueAgentBrowserNextActions, isStandaloneSnapshotNextAction, withOptionalSessionArgs, } from "../../results/next-actions.js";
+import { buildElectronLifecycleNextActions, buildElectronMismatchNextActions, buildElectronRefFreshnessNextActions, buildManagedSessionFreshFailureNextActions, } from "./session-state.js";
+import { buildOverlayBlockerNextActions } from "./overlay-diagnostics.js";
+import { buildFillVerificationNextActions } from "./fill-diagnostics.js";
+import { buildSelectorTextVisibilityNextActions } from "./text-visibility-diagnostics.js";
+import { buildElectronBroadGetTextScopeNextActions, buildSourceLookupElectronNextActions, } from "./electron-text-diagnostics.js";
+import { buildClickDispatchNextActions } from "./click-dispatch.js";
+import { buildComboboxFocusNextActions, buildScrollNoopNextActions, } from "./interaction-diagnostics.js";
+import { buildPageRecoveryActions, buildSelectorRecoveryActions, buildSemanticActionCandidateActions, buildStaleSemanticRetry, } from "./final-result-action-recovery.js";
+import { buildDialogTimeoutNextActions, buildTimeoutPartialProgressNextActions, } from "./final-result-timeout.js";
+function addElectronRecovery(prior, options) {
+    const actions = [...prior];
+    const healthRecord = options.electronPostCommandHealth
+        ? options.electronLaunchRecords.get(options.electronPostCommandHealth.launchId)
+        : undefined;
+    if (healthRecord) {
+        appendUniqueAgentBrowserNextActions(actions, buildElectronLifecycleNextActions(healthRecord));
+    }
+    const mismatchRecord = options.electronSessionMismatch
+        ? options.electronLaunchRecords.get(options.electronSessionMismatch.launchId)
+        : undefined;
+    if (mismatchRecord) {
+        appendUniqueAgentBrowserNextActions(actions, buildElectronMismatchNextActions(mismatchRecord, options.electronSessionMismatch?.liveTarget));
+    }
+    return actions;
+}
+function addObservationRecovery(prior, options) {
+    const actions = [...prior];
+    const sessionName = options.executionPlan.sessionName;
+    if (options.overlayBlockerDiagnostic) {
+        actions.push(...buildOverlayBlockerNextActions({
+            diagnostic: options.overlayBlockerDiagnostic,
+            sessionName,
+        }));
+    }
+    if (options.fillVerificationDiagnostic) {
+        appendUniqueAgentBrowserNextActions(actions, buildFillVerificationNextActions(options.fillVerificationDiagnostic, sessionName));
+    }
+    if (options.electronRefFreshnessDiagnostic) {
+        appendUniqueAgentBrowserNextActions(actions, buildElectronRefFreshnessNextActions(sessionName));
+    }
+    if (options.selectorTextVisibilityDiagnostics.length > 0) {
+        actions.push(...buildSelectorTextVisibilityNextActions({
+            diagnostics: options.selectorTextVisibilityDiagnostics,
+            sessionName,
+        }));
+    }
+    if (options.electronBroadGetTextScopeDiagnostics.length > 0) {
+        actions.push(...buildElectronBroadGetTextScopeNextActions({
+            diagnostics: options.electronBroadGetTextScopeDiagnostics,
+            sessionName,
+        }));
+    }
+    if (options.sourceLookup?.electronContext) {
+        appendUniqueAgentBrowserNextActions(actions, buildSourceLookupElectronNextActions(options.sourceLookup));
+    }
+    return actions;
+}
+function addInteractionRecovery(prior, options) {
+    const actions = [...prior];
+    const sessionName = options.executionPlan.sessionName;
+    if (options.clickDispatchDiagnostic) {
+        actions.push(...buildClickDispatchNextActions({
+            commandTokens: options.commandTokens,
+            diagnostic: options.clickDispatchDiagnostic,
+            sessionName,
+        }));
+    }
+    if (options.scrollNoopDiagnostic) {
+        actions.push(...buildScrollNoopNextActions(sessionName));
+    }
+    if (options.comboboxFocusDiagnostic) {
+        actions.push(...buildComboboxFocusNextActions(sessionName));
+    }
+    if (options.managedSessionOutcome) {
+        appendUniqueAgentBrowserNextActions(actions, buildManagedSessionFreshFailureNextActions(options.managedSessionOutcome));
+    }
+    return actions;
+}
+function addInterruptionRecovery(prior, options) {
+    let actions = [...prior];
+    if (options.currentSessionTabTargetUnknown === true &&
+        ["aborted", "parse-failure"].includes(options.categoryDetails.failureCategory ?? "")) {
+        actions = actions.filter((action) => !isStandaloneSnapshotNextAction(action));
+        appendUniqueAgentBrowserNextActions(actions, [
+            {
+                id: "verify-page-target-after-interruption",
+                tool: "agent_browser",
+                params: {
+                    args: withOptionalSessionArgs(options.executionPlan.sessionName, ["batch", "--bail"]),
+                    stdin: JSON.stringify([
+                        ["get", "url"],
+                        ["snapshot", "-i"],
+                    ]),
+                },
+                reason: "Verify the current URL and inspect the page after an interrupted operation.",
+                safety: "Read-only recovery. The mutation may already have happened; inspect before deciding whether to retry.",
+            },
+        ]);
+    }
+    if (options.categoryDetails.failureCategory === "timeout" && options.processResult.timedOut) {
+        if (options.currentSessionTabTargetUnknown === true) {
+            actions = actions.filter((action) => !isStandaloneSnapshotNextAction(action));
+        }
+        appendUniqueAgentBrowserNextActions(actions, buildTimeoutPartialProgressNextActions(options));
+        appendUniqueAgentBrowserNextActions(actions, buildDialogTimeoutNextActions({
+            command: options.executionPlan.commandInfo.command,
+            sessionName: options.executionPlan.sessionName,
+        }));
+    }
+    return actions;
+}
+export function buildResultNextActions(options) {
+    if (options.presentation.recordingRecovery || options.presentation.readConfirmation) {
+        return options.presentation.nextActions === undefined
+            ? undefined
+            : [...options.presentation.nextActions];
+    }
+    let actions = buildPageRecoveryActions(options);
+    actions.push(...buildSelectorRecoveryActions(options));
+    actions = addElectronRecovery(actions, options);
+    if (options.categoryDetails.failureCategory === "selector-not-found" &&
+        options.redactedCompiledSemanticAction) {
+        actions.push(...buildSemanticActionCandidateActions(options.redactedCompiledSemanticAction));
+    }
+    actions = addObservationRecovery(actions, options);
+    actions = addInteractionRecovery(actions, options);
+    actions = addInterruptionRecovery(actions, options);
+    actions.push(...buildStaleSemanticRetry(options));
+    if (options.electronLaunchRecord) {
+        actions.push(...(buildAgentBrowserNextActions({
+            electron: {
+                launchId: options.electronLaunchRecord.launchId,
+                sessionName: options.electronLaunchRecord.sessionName,
+                status: options.electronLaunchRecord.cleanupState,
+            },
+            failureCategory: options.categoryDetails.failureCategory,
+            resultCategory: options.categoryDetails.resultCategory,
+            successCategory: options.categoryDetails.successCategory,
+        }) ?? []));
+    }
+    return actions.length > 0 ? actions : undefined;
+}

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

@@ -0,0 +1,123 @@
+import { formatVisibleRefFallbackText, formatRichInputRecoveryText, } from "../../results/selector-recovery.js";
+import { redactSensitiveText } from "../../runtime-redaction.js";
+import { formatClickDispatchDiagnosticText } from "./click-dispatch.js";
+import { formatOverlayBlockerText } from "./overlay-diagnostics.js";
+import { formatFillVerificationText } from "./fill-diagnostics.js";
+import { formatSelectorTextVisibilityText } from "./text-visibility-diagnostics.js";
+import { formatElectronBroadGetTextScopeText } from "./electron-text-diagnostics.js";
+import { formatTimeoutPartialProgressText } from "./timeout-diagnostics.js";
+import { formatArtifactCleanupGuidanceText, formatComboboxFocusDiagnosticText, formatEvalResultWarningText, formatEvalStdinHintText, formatRecordingDependencyWarningText, formatScrollNoopDiagnosticText, } from "./diagnostics.js";
+import { formatElectronRefFreshnessText, formatManagedSessionOutcomeText, } from "./session-state.js";
+import { formatBrowserWindowText, formatReadExecutionText } from "./final-result-evidence.js";
+import { formatElectronLaunchText } from "./final-result-electron.js";
+import { buildJsonVisibleContent, readJsonWarnings, redactExactSensitiveText, } from "./final-result-redaction.js";
+const SEMANTIC_ACTION_CANDIDATE_ACTION_IDS = new Set([
+    "try-button-name-candidate",
+    "try-link-name-candidate",
+]);
+function formatSemanticActionCandidateText(actions) {
+    const candidates = actions?.filter((action) => SEMANTIC_ACTION_CANDIDATE_ACTION_IDS.has(action.id) && action.params?.args !== undefined) ?? [];
+    if (candidates.length === 0) {
+        return undefined;
+    }
+    return [
+        "Agent-browser candidate fallbacks:",
+        ...candidates.map((action) => `- ${action.id}: agent_browser ${JSON.stringify({ args: action.params?.args })} — ${action.reason}`),
+    ].join("\n");
+}
+export function formatAgentBrowserNextActionsText(nextActions) {
+    if (!nextActions || nextActions.length === 0) {
+        return undefined;
+    }
+    const lines = nextActions.map((action) => {
+        const payload = action.artifactPath !== undefined && action.artifactPath.length > 0
+            ? { artifactPath: action.artifactPath }
+            : action.params;
+        return `- ${action.id}${payload ? ` ${redactSensitiveText(JSON.stringify(payload))}` : ""}: ${redactSensitiveText(action.reason)}`;
+    });
+    return ["Next actions:", ...lines].join("\n");
+}
+function interactionDiagnosticText(options, nextActions) {
+    return [
+        formatVisibleRefFallbackText(options.visibleRefFallbackDiagnostic),
+        formatRichInputRecoveryText(options.richInputRecoveryDiagnostic),
+        formatSemanticActionCandidateText(nextActions),
+        options.clickDispatchDiagnostic
+            ? formatClickDispatchDiagnosticText(options.clickDispatchDiagnostic)
+            : undefined,
+        options.overlayBlockerDiagnostic
+            ? formatOverlayBlockerText(options.overlayBlockerDiagnostic)
+            : undefined,
+        formatFillVerificationText(options.fillVerificationDiagnostic),
+        formatElectronRefFreshnessText(options.electronRefFreshnessDiagnostic),
+        formatSelectorTextVisibilityText(options.selectorTextVisibilityDiagnostics),
+        formatElectronBroadGetTextScopeText(options.electronBroadGetTextScopeDiagnostics),
+        formatScrollNoopDiagnosticText(options.scrollNoopDiagnostic),
+        formatComboboxFocusDiagnosticText(options.comboboxFocusDiagnostic),
+    ];
+}
+function timeoutText(options) {
+    return options.timeoutPartialProgress
+        ? formatTimeoutPartialProgressText(options.timeoutPartialProgress, options.currentSessionTabTargetUnknown === true &&
+            !(options.sessionMode === "fresh" &&
+                options.timeoutPartialProgress.liveUrlRecovered !== true))
+        : undefined;
+}
+function appendedDiagnosticText(options, nextActions, lifecycle, browserWindow) {
+    const text = [
+        ...interactionDiagnosticText(options, nextActions),
+        formatRecordingDependencyWarningText(options.recordingDependencyWarning),
+        formatEvalStdinHintText(options.evalStdinHint),
+        formatEvalResultWarningText(options.evalResultWarning),
+        formatArtifactCleanupGuidanceText(options.artifactCleanup),
+        timeoutText(options),
+        formatManagedSessionOutcomeText(options.managedSessionOutcome),
+        formatReadExecutionText(options, lifecycle),
+        formatBrowserWindowText(browserWindow),
+        options.categoryDetails.resultCategory === "failure"
+            ? formatAgentBrowserNextActionsText(nextActions)
+            : undefined,
+    ]
+        .filter((item) => item !== undefined)
+        .join("\n\n");
+    return redactSensitiveText(redactExactSensitiveText(text, options.exactSensitiveValues));
+}
+function withAppendedText(content, text) {
+    if (text.length === 0 || content[0]?.type !== "text") {
+        return [...content];
+    }
+    return [{ ...content[0], text: `${content[0].text}\n\n${text}` }, ...content.slice(1)];
+}
+function withElectronHandoff(content, options) {
+    if (!options.electronLaunchRecord ||
+        !options.succeeded ||
+        options.userRequestedJson ||
+        content[0]?.type !== "text") {
+        return [...content];
+    }
+    const text = redactSensitiveText(formatElectronLaunchText({
+        handoff: options.electronHandoff,
+        record: options.electronLaunchRecord,
+        targets: options.electronLaunch?.targets ?? [],
+        upstreamText: content[0].text,
+    }));
+    return [{ ...content[0], text }, ...content.slice(1)];
+}
+export function buildFinalResultContent(options, details, nextActions, evidence) {
+    if (options.userRequestedJson && !options.plainTextInspection) {
+        const warnings = readJsonWarnings(options.redactedContent);
+        return {
+            content: buildJsonVisibleContent({
+                error: details.error,
+                details: { ...details, ...(warnings === undefined ? {} : { warnings }) },
+                presentation: options.presentation,
+                succeeded: options.succeeded,
+                warnings,
+            }),
+            warnings,
+        };
+    }
+    const diagnosticText = appendedDiagnosticText(options, nextActions, evidence.lifecycle, evidence.browserWindow);
+    const content = withAppendedText(options.redactedContent, diagnosticText);
+    return { content: withElectronHandoff(content, options) };
+}

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

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

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

@@ -0,0 +1,156 @@
+import { formatSessionArtifactRetentionSummary } from "../../results/artifact-manifest.js";
+import { alignPageChangeSummaryNextActionIds } from "../../results/next-actions.js";
+import { sanitizeVisibleRefFallbackDiagnostic } from "../../results/selector-recovery.js";
+import { buildElectronIdentifiers, buildSessionDetailFields } from "./session-state.js";
+import { getReadSource } from "./final-result-evidence.js";
+function compiledRequestDetails(options) {
+    return {
+        args: options.redactedArgs,
+        compiledElectron: options.redactedCompiledElectron,
+        compiledJob: options.redactedCompiledJob,
+        compiledQaPreset: options.redactedCompiledQaPreset,
+        compiledSourceLookup: options.redactedCompiledSourceLookup,
+        compiledNetworkSourceLookup: options.redactedCompiledNetworkSourceLookup,
+        compiledSemanticAction: options.redactedCompiledSemanticAction,
+        compatibilityWorkaround: options.compatibilityWorkaround,
+        effectiveArgs: options.redactedProcessArgs,
+    };
+}
+function artifactDetails(options) {
+    const presentation = options.presentation;
+    return {
+        artifactManifest: options.resultArtifactManifest,
+        artifactRetentionSummary: presentation.artifactRetentionSummary ??
+            (options.resultArtifactManifest
+                ? formatSessionArtifactRetentionSummary(options.resultArtifactManifest)
+                : undefined),
+        artifactCleanup: options.artifactCleanup,
+        artifactVerification: presentation.artifactVerification,
+        artifacts: presentation.artifacts,
+        fullOutputPath: options.parseFailureOutput.fullOutputPath ?? presentation.fullOutputPath,
+        fullOutputPaths: presentation.fullOutputPaths,
+        fullOutputUnavailable: options.parseFailureOutput.fullOutputUnavailable,
+        imagePath: presentation.imagePath,
+        imagePaths: presentation.imagePaths,
+        imageObservations: presentation.imageObservations,
+        savedFile: presentation.savedFile,
+        savedFilePath: presentation.savedFilePath,
+    };
+}
+function nativeObservationDetails(options, lifecycle, browserWindow) {
+    return {
+        batchFailure: options.presentation.batchFailure,
+        batchSteps: options.presentation.batchSteps,
+        command: options.executionPlan.commandInfo.command,
+        subcommand: options.executionPlan.commandInfo.subcommand,
+        data: options.presentation.data,
+        error: options.plainTextInspection ? undefined : options.presentationEnvelope?.error,
+        inspection: options.plainTextInspection || undefined,
+        agentBrowserStarted: options.processResult.agentBrowserStarted,
+        browserWindow,
+        lifecycle,
+        readSource: getReadSource(options),
+        recordingRecovery: options.presentation.recordingRecovery,
+        readConfirmation: options.presentation.readConfirmation,
+        exitCode: options.processResult.exitCode,
+        parseError: options.plainTextInspection ? undefined : options.parseError,
+        stderr: options.processResult.stderr,
+        stdout: options.plainTextInspection ? (options.inspectionText ?? "") : undefined,
+        summary: options.presentation.summary,
+        timedOut: options.processResult.timedOut || undefined,
+        timeoutMs: options.processResult.timeoutMs,
+    };
+}
+function sessionEvidenceDetails(options) {
+    return {
+        managedSessionHeadedAutosaveDisabled: options.managedSessionHeadedAutosaveDisabled,
+        managedSessionHeadedAutosaveInterval: options.managedSessionHeadedAutosaveInterval,
+        managedSessionOutcome: options.managedSessionOutcome,
+        sessionMode: options.sessionMode,
+        sessionTabCorrection: options.sessionTabCorrection,
+        sessionTabTarget: options.currentSessionTabTarget,
+        sessionTabTargetUnknown: options.currentSessionTabTargetUnknown,
+        refSnapshot: options.currentRefSnapshot,
+        refSnapshotInvalidation: options.currentRefSnapshotInvalidation,
+        namespace: options.executionPlan.namespace,
+        ...buildSessionDetailFields(options.executionPlan.sessionName, options.executionPlan.usedImplicitSession, options.executionPlan.namespace, options.managedSessionRestoreDisabled),
+        sessionRecoveryHint: options.redactedRecoveryHint,
+        startupScopedFlags: options.executionPlan.startupScopedFlags,
+        aboutBlankSessionMismatch: options.aboutBlankSessionMismatch,
+        openResultTabCorrection: options.openResultTabCorrection,
+        navigationSummary: options.navigationSummary,
+    };
+}
+function electronEvidenceDetails(options) {
+    return {
+        electron: options.electronLaunchRecord
+            ? {
+                action: "launch",
+                cleanup: options.electronFailedConnectCleanup,
+                handoff: options.electronHandoff,
+                identifiers: buildElectronIdentifiers(options.electronLaunchRecord),
+                launch: options.electronLaunchRecord,
+                profileIsolation: options.electronProfileIsolationDetails,
+                status: options.succeeded ? "succeeded" : "failed",
+                targets: options.electronLaunch?.targets,
+                version: options.electronLaunch?.version,
+            }
+            : undefined,
+        electronPostCommandHealth: options.electronPostCommandHealth,
+        electronRefFreshness: options.electronRefFreshnessDiagnostic,
+        electronSessionMismatch: options.electronSessionMismatch,
+        electronGetTextScopeWarning: options.electronBroadGetTextScopeDiagnostics[0],
+        electronGetTextScopeWarnings: options.electronBroadGetTextScopeDiagnostics.length > 1
+            ? options.electronBroadGetTextScopeDiagnostics
+            : undefined,
+    };
+}
+function interactionEvidenceDetails(options) {
+    return {
+        clickDispatch: options.clickDispatchDiagnostic,
+        overlayBlockers: options.overlayBlockerDiagnostic,
+        fillVerification: options.fillVerificationDiagnostic,
+        visibleRefFallback: options.visibleRefFallbackDiagnostic
+            ? sanitizeVisibleRefFallbackDiagnostic(options.visibleRefFallbackDiagnostic)
+            : undefined,
+        richInputRecovery: options.richInputRecoveryDiagnostic,
+        comboboxFocus: options.comboboxFocusDiagnostic,
+        recordingDependencyWarning: options.recordingDependencyWarning,
+        scrollNoop: options.scrollNoopDiagnostic,
+        selectorTextVisibility: options.selectorTextVisibilityDiagnostics[0],
+        selectorTextVisibilityAll: options.selectorTextVisibilityDiagnostics.length > 1
+            ? options.selectorTextVisibilityDiagnostics
+            : undefined,
+        evalStdinHint: options.evalStdinHint,
+        evalResultWarning: options.evalResultWarning,
+        timeoutPartialProgress: options.timeoutPartialProgress,
+    };
+}
+function pageChangeSummary(options, nextActions) {
+    const rawSummary = (options.scrollNoopDiagnostic || options.comboboxFocusDiagnostic) &&
+        options.presentation.pageChangeSummary
+        ? {
+            ...options.presentation.pageChangeSummary,
+            nextActionIds: nextActions?.map((action) => action.id),
+        }
+        : options.presentation.pageChangeSummary;
+    return alignPageChangeSummaryNextActionIds(rawSummary, nextActions);
+}
+export function buildAgentBrowserResultDetails(options, nextActions, lifecycle, browserWindow) {
+    return {
+        ...compiledRequestDetails(options),
+        ...artifactDetails(options),
+        ...nativeObservationDetails(options, lifecycle, browserWindow),
+        ...options.categoryDetails,
+        ...sessionEvidenceDetails(options),
+        ...electronEvidenceDetails(options),
+        ...interactionEvidenceDetails(options),
+        nextActions,
+        pageChangeSummary: pageChangeSummary(options, nextActions),
+        qaPreset: options.qaPreset,
+        qaAttachedTarget: options.qaAttachedTarget,
+        sourceLookup: options.sourceLookup,
+        networkSourceLookup: options.networkSourceLookup,
+        networkRouteDiagnostics: options.presentation.networkRouteDiagnostics,
+    };
+}

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

@@ -0,0 +1,179 @@
+import { buildAgentBrowserResultCategoryDetails } from "../../results/categories.js";
+import { redactSensitiveText } from "../../runtime-redaction.js";
+import { redactToolDetails } from "./final-result-redaction.js";
+export function getElectronLaunchFailureCategory(failure) {
+    switch (failure.reason) {
+        case "aborted":
+            return "aborted";
+        case "policy-blocked":
+            return "policy-blocked";
+        case "timeout":
+            return "timeout";
+        case "non-electron-target":
+            return "validation-error";
+        case "port-not-found":
+        case "single-instance-conflict":
+        case "spawn-error":
+            return "upstream-error";
+    }
+}
+function pidState(pidAlive) {
+    if (pidAlive === undefined) {
+        return "state unknown";
+    }
+    return pidAlive ? "alive before cleanup" : "not alive before cleanup";
+}
+function formatProcessDiagnostics(diagnostics) {
+    const lines = [];
+    if (diagnostics.pid !== undefined) {
+        lines.push(`- PID: ${diagnostics.pid} (${pidState(diagnostics.pidAlive)}).`);
+    }
+    if (diagnostics.exitCode !== undefined || diagnostics.exitSignal !== undefined) {
+        const exitParts = [
+            diagnostics.exitCode !== undefined ? `code ${String(diagnostics.exitCode)}` : undefined,
+            diagnostics.exitSignal !== undefined &&
+                diagnostics.exitSignal !== null &&
+                diagnostics.exitSignal.length > 0
+                ? `signal ${diagnostics.exitSignal}`
+                : undefined,
+        ]
+            .filter(Boolean)
+            .join(", ");
+        lines.push(`- Process exit: ${exitParts.length > 0 ? exitParts : "not observed before cleanup"}.`);
+    }
+    return lines;
+}
+function formatActivePort(activePort) {
+    const error = activePort.error !== undefined && activePort.error.length > 0 ? ` (${activePort.error})` : "";
+    let state;
+    if (activePort.port !== undefined && activePort.port !== 0) {
+        state = `found port ${activePort.port}`;
+    }
+    else {
+        state = activePort.found ? `found but invalid${error}` : `missing${error}`;
+    }
+    return `- DevToolsActivePort: ${state} at ${activePort.path}.`;
+}
+function formatConnectionDiagnostics(diagnostics) {
+    const lines = [];
+    if (diagnostics.userDataDir !== undefined && diagnostics.userDataDir.length > 0) {
+        lines.push(`- Wrapper profile: ${diagnostics.userDataDir}`);
+    }
+    if (diagnostics.devToolsActivePort) {
+        lines.push(formatActivePort(diagnostics.devToolsActivePort));
+    }
+    if (diagnostics.cdpVersionReached === false) {
+        lines.push("- CDP /json/version: did not return a valid payload before timeout.");
+    }
+    if (diagnostics.timeoutMs !== undefined || diagnostics.elapsedMs !== undefined) {
+        lines.push(`- Timing: ${diagnostics.elapsedMs ?? "unknown"}ms elapsed${diagnostics.timeoutMs !== undefined ? ` of ${diagnostics.timeoutMs}ms timeout` : ""}.`);
+    }
+    if (!diagnostics.outputCaptured) {
+        lines.push("- App stdout/stderr: not captured by this wrapper launch path.");
+    }
+    return lines;
+}
+function formatElectronLaunchFailureDiagnostics(failure) {
+    const diagnostics = failure?.diagnostics;
+    if (!diagnostics) {
+        return undefined;
+    }
+    const lines = [
+        "Electron launch diagnostics:",
+        ...formatProcessDiagnostics(diagnostics),
+        ...formatConnectionDiagnostics(diagnostics),
+    ];
+    if (failure.reason !== "aborted") {
+        lines.push("Retry guidance: increase electron.timeoutMs, try targetType:'any', pass an explicit appPath/executablePath, quit any already-running singleton instance, then retry launch.");
+    }
+    return lines.join("\n");
+}
+export function buildElectronHostFailureResult(options) {
+    const text = [
+        options.errorText,
+        formatElectronLaunchFailureDiagnostics(options.launchFailure),
+        options.launchFailure?.cleanupError !== undefined &&
+            options.launchFailure.cleanupError.length > 0
+            ? `Electron launch cleanup warning: ${options.launchFailure.cleanupError}`
+            : undefined,
+    ]
+        .filter((item) => item !== undefined && item.length > 0)
+        .join("\n");
+    const details = {
+        args: [],
+        compiledElectron: options.compiledElectron,
+        electron: {
+            action: options.compiledElectron.action,
+            error: options.errorText,
+            failure: options.launchFailure,
+            status: options.status ?? "failed",
+        },
+        managedSessionOutcome: options.managedSessionOutcome,
+        ...buildAgentBrowserResultCategoryDetails({
+            args: [],
+            errorText: options.errorText,
+            failureCategory: options.failureCategory,
+            succeeded: false,
+            timedOut: options.failureCategory === "timeout",
+        }),
+        summary: options.errorText,
+    };
+    return {
+        content: [{ type: "text", text: redactSensitiveText(text) }],
+        details: redactToolDetails(details, []),
+        isError: true,
+    };
+}
+export function formatElectronTargetLines(targets, limit = 8) {
+    const shownTargets = targets.slice(0, limit);
+    const lines = shownTargets.map((target) => {
+        const typeTitle = [target.type, target.title].filter(Boolean).join(" ");
+        const fallback = target.id === undefined || target.id.length === 0 ? "target" : target.id;
+        const label = typeTitle.length > 0 ? typeTitle : fallback;
+        return `- ${label}${target.url !== undefined && target.url.length > 0 ? ` — ${target.url}` : ""}`;
+    });
+    if (targets.length > shownTargets.length) {
+        lines.push(`- ... ${targets.length - shownTargets.length} more target(s) omitted`);
+    }
+    return lines;
+}
+function formatSnapshotHandoff(handoff) {
+    if (handoff.refSnapshot && handoff.refSnapshot.refIds.length > 0) {
+        const retries = handoff.snapshotRetryCount;
+        return `Snapshot handoff: ${handoff.refSnapshot.refIds.length} interactive ref(s)${retries !== undefined && retries !== 0 ? ` after ${retries} retry attempt(s)` : ""}.`;
+    }
+    return "Snapshot handoff: no interactive refs returned after a short readiness retry; run snapshot -i once more before assuming the Electron UI is unusable.";
+}
+function formatHandoffText(handoff) {
+    switch (handoff?.handoff) {
+        case "snapshot":
+            return formatSnapshotHandoff(handoff);
+        case "tabs":
+            return "Tabs handoff completed: safer diagnostic starting point; no interactive refs were captured.";
+        case "connect":
+            return "Connect handoff completed: run snapshot -i before using interactive refs.";
+        case undefined:
+            return undefined;
+    }
+}
+export function formatElectronLaunchText(options) {
+    const lines = [
+        `Electron launch: ${options.record.appName} attached as ${options.record.sessionName ?? "managed session"} (launchId ${options.record.launchId}, port ${options.record.port}).`,
+        `Identifiers: launchId ${options.record.launchId} for electron.status/electron.cleanup/electron.probe; sessionName ${options.record.sessionName ?? "not attached"} for browser snapshot/tab commands.`,
+        "Profile note: electron.launch starts an isolated temporary profile; it does not reuse the app's normal signed-in profile or attach to an already-running authenticated app.",
+        "For already-authenticated desktop app content, do not stop here: if host tools are allowed and the app is not running, launch the normal app with --remote-debugging-port=<port>, verify the port, then run agent_browser connect <port>; if it is already running without a debug port, ask before relaunching it.",
+        ...formatElectronTargetLines(options.targets),
+    ];
+    const handoffText = formatHandoffText(options.handoff);
+    if (handoffText !== undefined) {
+        lines.push(handoffText);
+    }
+    lines.push(`Cleanup: use details.nextActions cleanup-electron-launch or call electron.cleanup with launchId ${options.record.launchId} when finished.`);
+    if (options.handoff?.error !== undefined && options.handoff.error.length > 0) {
+        lines.push(`Handoff warning: ${options.handoff.error}`);
+    }
+    if (options.upstreamText.trim().length > 0) {
+        lines.push("", options.upstreamText.trim());
+    }
+    return lines.join("\n");
+}

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

@@ -0,0 +1,39 @@
+import { isRecord } from "../../parsing.js";
+export function getReadSource(options) {
+    return options.executionPlan.commandInfo.command === "read" &&
+        isRecord(options.presentationEnvelope?.data) &&
+        typeof options.presentationEnvelope.data.source === "string"
+        ? options.presentationEnvelope.data.source
+        : undefined;
+}
+export function formatReadExecutionText(options, lifecycle) {
+    const source = getReadSource(options);
+    if (source === undefined || source.length === 0) {
+        return undefined;
+    }
+    return `Read execution: source ${source}; CLI started: ${options.processResult.agentBrowserStarted ? "yes" : "no"}; reported browserLaunched: ${lifecycle ? String(lifecycle.effectiveLaunch.browserLaunched) : "unknown"}; managed session outcome: ${options.managedSessionOutcome?.status ?? "not managed"}. An HTTP read does not establish shared-browser liveness; use session info for that.`;
+}
+function requestedOwnedHeadedWindow(options) {
+    return (options.headedLaunch &&
+        !options.preserveAttachedBrowserSession &&
+        !options.providerLaunch &&
+        options.succeeded);
+}
+export function buildBrowserWindowStatus(options, lifecycle) {
+    if (!requestedOwnedHeadedWindow(options) || lifecycle?.effectiveLaunch.browserLaunched !== true) {
+        return undefined;
+    }
+    const sessionName = options.executionPlan.managedSessionName;
+    if (sessionName === undefined ||
+        sessionName.length === 0 ||
+        !options.managedSessionOutcome ||
+        !["created", "replaced"].includes(options.managedSessionOutcome.status)) {
+        return undefined;
+    }
+    return { mode: "headed", ownership: "wrapper-managed", sessionName, visibility: "unverified" };
+}
+export function formatBrowserWindowText(browserWindow) {
+    return browserWindow
+        ? "Headed browser handoff: wrapper-managed headed window requested; desktop visibility unverified. If login is needed, ask the user to confirm they can see the window and finish signing in there, then continue with sessionMode auto."
+        : undefined;
+}