pi-agent-browser-native 0.2.76 → 0.3.0

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

@@ -1,25 +1,26 @@
 import { copyFile, mkdir } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
+import { getBooleanFlagValue, isUpstreamEnvFlagEnabled } from "../../argv-grammar.js";
 import { isCloseCommand } from "../../command-taxonomy.js";
 import { cleanupElectronLaunchResources } from "../../electron/cleanup.js";
 import { launchElectronApp } from "../../electron/launch.js";
 import { pathExists } from "../../fs-utils.js";
-import { getCompiledSemanticActionSessionPrefix } from "../../input-modes.js";
+import { getCompiledSemanticActionSessionPrefix } from "../../input-modes/semantic-action.js";
 import { tryDirectAnchorDownload } from "./prepare/direct-anchor-download.js";
 import { tryNetworkRequestsPageFilter } from "./prepare/network-page-filter.js";
 import { tryContainerScroll, tryPageScrollTo } from "./prepare/scroll-shims.js";
 import { trySnapshotFilter } from "./prepare/snapshot-filter.js";
 import { commandTimeoutNeedsActivePageUrl, getCommandAwareProcessTimeoutMs } from "./prepare/wait-timeouts.js";
-import { getPersistentSessionArtifactStore } from "./session-artifacts.js";
-import { buildAgentBrowserResultCategoryDetails } from "../../results.js";
+import { getPersistentSessionArtifactStore } from "./session-state.js";
+import { buildAgentBrowserResultCategoryDetails } from "../../results/categories.js";
 import { applyNamespaceToNextActions } from "../../results/next-actions.js";
 import { buildSessionAwareStaleRefNextActions, buildSessionTabRecoveryNextActions } from "../../results/recovery-next-actions.js";
 import { resolveVisibleRefActionFromSnapshot } from "../../results/selector-recovery.js";
 import { extractRefSnapshotFromData } from "../../session-page-state.js";
 import { buildExecutionPlan, createFreshSessionName, extractCommandTokens, getDefaultHeadlessCompatUserAgent, redactInvocationArgs, } from "../../runtime.js";
-import { buildOwnedManagedSessionRestoreContext, canonicalizeOwnedManagedSessionCloseArgs, withOwnedManagedSessionContext, } from "../../managed-session-restore.js";
+import { buildOwnedManagedSessionRestoreContext, canonicalizeOwnedManagedSessionCloseArgs, resolveExplicitAutosaveInterval, withOwnedManagedSessionContext, } from "../../managed-session-restore.js";
 import { getCallerOwnedSessionLivePageVerificationRequirement, getManagedSessionStateAccessValidationError, getManagedSessionTargetAccessValidationError, } from "../../managed-session-state-policy.js";
-import { acquireOwnedManagedSessionDaemonPolicy } from "./managed-session-daemon-policy.js";
+import { acquireOwnedManagedSessionDaemonPolicy, getRunningHeadedAutosavePolicyChangeError } from "./managed-session-daemon-policy.js";
 import { applyOpenResultTabCorrection, buildManagedSessionOutcome, buildPinnedBatchPlan, buildSessionDetailFields, buildStaleRefPreflight, getSessionContextKey, extractStringResultField, collectAnySessionTabSelection, collectSessionTabSelection, getGuardedRefUsage, getTraceOwnerGuardMessage, runSessionCommandData, shouldPinSessionTabForCommand, } from "./session-state.js";
 import { parseBatchStdinJsonArray } from "../batch-stdin.js";
 import { buildElectronHostFailureResult, getElectronLaunchFailureCategory, redactRecoveryHint } from "./final-result.js";
@@ -397,11 +398,27 @@ export async function prepareBrowserRun(options) {
         if (!executionPlan.validationError && managedStateAccessError)
             executionPlan = { ...executionPlan, recoveryHint: undefined, validationError: managedStateAccessError };
         const recordedOwnedSession = ownedSessionKey ? state.ownedManagedSessions.get(ownedSessionKey) : undefined;
+        const targetsCurrentManagedSession = state.managedSessionActive
+            && ownedSessionKey === getSessionContextKey(state.managedSessionName, state.managedSessionNamespace);
+        const retainedHeadedAutosaveDisabled = recordedOwnedSession?.headedManagedAutosaveDisabled === true
+            || (targetsCurrentManagedSession && state.managedSessionHeadedAutosaveDisabled === true);
+        const retainedHeadedAutosaveInterval = recordedOwnedSession?.headedManagedAutosaveInterval
+            ?? (targetsCurrentManagedSession ? state.managedSessionHeadedAutosaveInterval : undefined);
+        const explicitAutosaveInterval = resolveExplicitAutosaveInterval(process.env.AGENT_BROWSER_AUTOSAVE_INTERVAL_MS);
+        const autosavePolicyChangeError = getRunningHeadedAutosavePolicyChangeError(retainedHeadedAutosaveInterval, isCloseCommand(executionPlan.commandInfo.command));
+        if (!executionPlan.validationError && autosavePolicyChangeError) {
+            executionPlan = { ...executionPlan, recoveryHint: undefined, validationError: autosavePolicyChangeError };
+        }
+        const headedLaunch = getBooleanFlagValue(executionPlan.effectiveArgs, "--headed") ?? isUpstreamEnvFlagEnabled(process.env.AGENT_BROWSER_HEADED);
+        const headedManagedAutosaveDisabled = retainedHeadedAutosaveDisabled || (explicitAutosaveInterval === undefined && headedLaunch);
+        const headedManagedAutosaveInterval = retainedHeadedAutosaveInterval ?? (headedLaunch ? explicitAutosaveInterval ?? "0" : undefined);
         const ownedManagedSession = buildOwnedManagedSessionRestoreContext({
             args: executionPlan.effectiveArgs,
             cwd: recordedOwnedSession?.cwd ?? cwd,
             currentManagedSessionName: state.managedSessionName,
             currentManagedSessionNamespace: state.managedSessionNamespace,
+            headedManagedAutosaveDisabled,
+            headedManagedAutosaveInterval,
             managedSessionName: executionPlan.managedSessionName,
             namespace: executionPlan.namespace,
             recordedOwnedSession,
@@ -451,13 +468,18 @@ export async function prepareBrowserRun(options) {
             const priorRefSnapshotState = priorSessionPageState.refSnapshot;
             const priorRefSnapshotInvalidation = priorSessionPageState.refSnapshotInvalidation;
             let semanticActionVisibleRefResolution;
-            let callerOwnedLivePageVerified = false;
+            let livePageVerified = false;
             const isCallerOwnedExplicitSession = () => executionPlan.sessionName !== undefined
                 && executionPlan.usedImplicitSession === false
                 && ownedManagedSession === undefined;
-            const verifyCallerOwnedLivePage = async (options) => {
-                if (!options.requirement || !executionPlan.sessionName)
+            const requiresLivePageVerification = () => isCallerOwnedExplicitSession() || options.preserveAttachedBrowserSession === true;
+            const verifyLivePage = async (request) => {
+                if (!request.requirement || !executionPlan.sessionName)
+                    return;
+                if (options.establishAttachedBrowserSession) {
+                    executionPlan = { ...executionPlan, recoveryHint: undefined, validationError: request.requirement };
                     return;
+                }
                 let liveUrl;
                 try {
                     const liveUrlData = await runSessionCommandData({
@@ -475,27 +497,27 @@ export async function prepareBrowserRun(options) {
                         throw signal.reason ?? error;
                 }
                 if (liveUrl === undefined) {
-                    executionPlan = { ...executionPlan, recoveryHint: undefined, validationError: options.requirement };
+                    executionPlan = { ...executionPlan, recoveryHint: undefined, validationError: request.requirement };
                     return;
                 }
                 const livePageValidationError = getManagedSessionStateAccessValidationError({
-                    args: options.args,
+                    args: request.args,
                     currentPageUrl: liveUrl,
                     cwd,
                     pageUrlUnknown: false,
-                    stdin: options.stdin,
+                    stdin: request.stdin,
                 });
                 if (livePageValidationError) {
                     executionPlan = { ...executionPlan, recoveryHint: undefined, validationError: livePageValidationError };
                     return;
                 }
-                callerOwnedLivePageVerified = true;
+                livePageVerified = true;
                 priorSessionTabTarget ??= { url: liveUrl };
                 priorSessionTabTargetUnknown = undefined;
             };
             const mayResolveSemanticVisibleRef = executionPlan.managedSessionName !== freshSessionName && canResolveSemanticVisibleRef(compiledSemanticAction);
-            if (!executionPlan.validationError && mayResolveSemanticVisibleRef && isCallerOwnedExplicitSession()) {
-                await verifyCallerOwnedLivePage({
+            if (!executionPlan.validationError && mayResolveSemanticVisibleRef && requiresLivePageVerification()) {
+                await verifyLivePage({
                     args: ["snapshot", "-i"],
                     requirement: getCallerOwnedSessionLivePageVerificationRequirement({ args: ["snapshot", "-i"], cwd }),
                 });
@@ -530,21 +552,21 @@ export async function prepareBrowserRun(options) {
                 refSnapshotInvalidation: resolvedSemanticActionRefSnapshot ? undefined : priorRefSnapshotInvalidation,
                 stdin: runtimeToolStdin,
             });
-            const callerOwnedPageAccessEligible = !executionPlan.validationError
+            const livePageAccessEligible = !executionPlan.validationError
                 && preLiveStaleRefPreflight === undefined
                 && validateStdinCommandContract({ command: executionPlan.commandInfo.command, commandTokens, stdin: runtimeToolStdin }) === undefined
-                && isCallerOwnedExplicitSession();
-            const callerOwnedLivePageRequirement = callerOwnedPageAccessEligible
-                && !callerOwnedLivePageVerified
+                && requiresLivePageVerification();
+            const livePageRequirement = livePageAccessEligible
+                && !livePageVerified
                 ? getCallerOwnedSessionLivePageVerificationRequirement({
                     args: executionPlan.effectiveArgs,
                     cwd,
                     stdin: runtimeToolStdin,
                 })
                 : undefined;
-            await verifyCallerOwnedLivePage({
+            await verifyLivePage({
                 args: executionPlan.effectiveArgs,
-                requirement: callerOwnedLivePageRequirement,
+                requirement: livePageRequirement,
                 stdin: runtimeToolStdin,
             });
             const redactedEffectiveArgs = redactInvocationArgs(executionPlan.effectiveArgs);

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

@@ -5,8 +5,11 @@ import { OPEN_RESULT_TAB_CORRECTION_FLAGS } from "../../launch-scoped-flags.js";
 import { cleanupElectronLaunchResources, inspectElectronLaunchStatus } from "../../electron/cleanup.js";
 import { getAllowedDomainsViolation, parseAllowedDomainsPolicyFromArgs } from "../../navigation-policy.js";
 import { getManagedSessionResultingPageState, getObservedBrowserPageValidationError, managedSessionCommandRequiresLivePageVerification } from "../../managed-session-state-policy.js";
-import { analyzeNetworkSourceLookupResults, analyzeQaPresetResults, analyzeQaPresetTimeout, analyzeSourceLookupResults, buildQaCompactPassText, extractQaPageContext, redactNetworkSourceLookupAnalysis, } from "../../input-modes.js";
-import { applyNetworkRouteRecords, buildNetworkRouteDiagnostics, buildToolPresentation, getAgentBrowserErrorText, parseAgentBrowserEnvelope, } from "../../results.js";
+import { analyzeNetworkSourceLookupResults, analyzeSourceLookupResults, redactNetworkSourceLookupAnalysis } from "../../input-modes/lookups.js";
+import { analyzeQaPresetResults, analyzeQaPresetTimeout, buildQaCompactPassText, extractQaPageContext } from "../../input-modes/job.js";
+import { applyNetworkRouteRecords, buildNetworkRouteDiagnostics } from "../../results/network-routes.js";
+import { buildToolPresentation } from "../../results/presentation.js";
+import { getAgentBrowserErrorText, parseAgentBrowserEnvelope } from "../../results/envelope.js";
 import { getClipboardWritePayloadCandidates, redactClipboardPermissionEcho, redactClipboardPermissionErrorValue } from "../../results/presentation/errors.js";
 import { shouldCaptureSemanticActionNavigationSummary } from "../../results/presentation/semantic-action.js";
 import { commandExplicitlyTargetsAboutBlank, deriveSessionTabTarget, extractLatestRefSnapshotStateFromBatchResults, extractRefSnapshotFromData, extractSessionTabTargetFromBatchResults, extractSessionTabTargetFromCommandData, isAboutBlankSessionTabTarget, normalizeSessionTabTarget, } from "../../session-page-state.js";
@@ -19,7 +22,7 @@ import { applyOpenResultTabCorrection, buildAboutBlankRecoveryHint, buildAboutBl
 import { collectClickDispatchDiagnostic } from "./click-dispatch.js";
 import { buildScrollNoopDiagnostic, collectComboboxFocusDiagnostic, collectElectronBroadGetTextScopeDiagnostics, collectElectronHandoff, collectFillVerificationDiagnostic, collectNavigationSummary, collectOverlayBlockerDiagnostic, collectQaAttachedTarget, collectSnapshotOverlayBlockerDiagnostic, collectRecordingDependencyWarning, collectScrollPositionSnapshot, collectSelectorTextVisibilityDiagnostics, collectTimeoutPartialProgress, sleepMs, formatQaAttachedTargetText, getArtifactCleanupGuidance, getEvalResultWarning, getEvalStdinHint, getSourceLookupElectronContext, } from "./diagnostics.js";
 import { repairScreenshotData } from "./prepare.js";
-import { getPersistentSessionArtifactStore } from "./session-artifacts.js";
+import { getPersistentSessionArtifactStore } from "./session-state.js";
 import { buildFinalAgentBrowserToolResult, buildRedactedPresentationContent, buildWrapperRecoveryHint, prepareFinalResultRecoveryState, redactExactSensitiveValue, } from "./final-result.js";
 async function repairScreenshotArtifact(options) {
     const { cwd, envelope, request } = options;
@@ -105,6 +108,8 @@ export async function processBrowserOutput(input) {
     let freshSessionOrdinal = state.freshSessionOrdinal;
     let managedSessionActive = state.managedSessionActive;
     let managedSessionCompatibilityWorkaround = state.managedSessionCompatibilityWorkaround;
+    let managedSessionHeadedAutosaveDisabled = state.managedSessionHeadedAutosaveDisabled === true;
+    let managedSessionHeadedAutosaveInterval = state.managedSessionHeadedAutosaveInterval;
     let managedSessionCwd = state.managedSessionCwd;
     let managedSessionName = state.managedSessionName;
     let managedSessionNamespace = state.managedSessionNamespace;
@@ -327,6 +332,7 @@ export async function processBrowserOutput(input) {
         }
         const priorManagedSessionActive = managedSessionActive;
         const priorManagedSessionCwd = managedSessionCwd;
+        const priorManagedSessionHeadedAutosaveInterval = managedSessionHeadedAutosaveInterval;
         const priorManagedSessionName = managedSessionName;
         const priorManagedSessionNamespace = managedSessionNamespace;
         const commandClosesSession = isCloseCommand(prepared.executionPlan.commandInfo.command);
@@ -344,6 +350,7 @@ export async function processBrowserOutput(input) {
         const failedFreshDaemon = failedFreshSessionMayHaveStarted && prepared.executionPlan.sessionName
             ? await inspectManagedSessionDaemon({
                 cwd,
+                headedManagedAutosaveInterval: prepared.ownedManagedSessionContext?.headedManagedAutosaveInterval,
                 namespace: prepared.executionPlan.namespace,
                 sessionName: prepared.executionPlan.sessionName,
                 timeoutMs: Math.min(implicitSessionCloseTimeoutMs, 2_000),
@@ -368,9 +375,13 @@ export async function processBrowserOutput(input) {
                 === getAgentBrowserSessionIdentityKey(managedSessionName, managedSessionNamespace);
         if (!managedSessionActive) {
             managedSessionCompatibilityWorkaround = undefined;
+            managedSessionHeadedAutosaveDisabled = false;
+            managedSessionHeadedAutosaveInterval = undefined;
         }
         else if (managedTransitionSucceeded && executionTargetsManagedSession) {
             managedSessionCompatibilityWorkaround = prepared.compatibilityWorkaround;
+            managedSessionHeadedAutosaveDisabled = prepared.ownedManagedSessionContext?.headedManagedAutosaveDisabled === true;
+            managedSessionHeadedAutosaveInterval = prepared.ownedManagedSessionContext?.headedManagedAutosaveInterval;
         }
         if (commandClosesSession && succeeded && managedCloseSessionName === priorManagedSessionName && !managedSessionActive) {
             const daemonRestoreKey = state.managedSessionRestoreState.getDaemonRestoreKey(managedCloseSessionName, priorManagedSessionNamespace);
@@ -405,9 +416,21 @@ export async function processBrowserOutput(input) {
             networkRoutesBySession = new Map(networkRoutesBySession);
             networkRoutesBySession.delete(replacedSessionStateKey ?? replacedManagedSessionName);
             sessionPageState.clearSession(replacedSessionStateKey ?? replacedManagedSessionName);
-            const replacedCloseError = await closeManagedSession({ cwd: priorManagedSessionCwd, namespace: priorManagedSessionNamespace, restoreState: state.managedSessionRestoreState, sessionName: replacedManagedSessionName, timeoutMs: implicitSessionCloseTimeoutMs });
-            if (!replacedCloseError)
-                state.closedManagedSessionNames.add(replacedSessionStateKey ?? replacedManagedSessionName);
+            const replacedSessionKey = replacedSessionStateKey ?? replacedManagedSessionName;
+            const replacedCloseError = await closeManagedSession({ cwd: priorManagedSessionCwd, headedManagedAutosaveInterval: priorManagedSessionHeadedAutosaveInterval, namespace: priorManagedSessionNamespace, preserveAttachedBrowserSession: state.attachedSessionKeys.has(replacedSessionKey), restoreState: state.managedSessionRestoreState, sessionName: replacedManagedSessionName, timeoutMs: implicitSessionCloseTimeoutMs });
+            if (managedSessionOutcome) {
+                managedSessionOutcome = {
+                    ...managedSessionOutcome,
+                    replacedSessionClosed: !replacedCloseError,
+                    summary: replacedCloseError
+                        ? `${managedSessionOutcome.summary} Previous session ${replacedManagedSessionName} remains wrapper-owned because automatic close failed; retry an explicit close.`
+                        : managedSessionOutcome.summary,
+                };
+            }
+            if (!replacedCloseError) {
+                state.attachedSessionKeys.delete(replacedSessionKey);
+                state.closedManagedSessionNames.add(replacedSessionKey);
+            }
         }
         let electronLaunchRecord;
         let electronFailedConnectCleanup = prepared.electronFailedConnectCleanup;
@@ -431,7 +454,7 @@ export async function processBrowserOutput(input) {
                 if (electronHandoff.error) {
                     succeeded = false;
                     presentationEnvelope = { error: electronHandoff.error, success: false };
-                    const closeError = await closeManagedSession({ cwd, namespace: prepared.executionPlan.namespace, policyLock: prepared.managedSessionPolicyLock, restoreState: state.managedSessionRestoreState, sessionName: electronSessionName, timeoutMs: implicitSessionCloseTimeoutMs });
+                    const closeError = await closeManagedSession({ cwd, headedManagedAutosaveInterval: prepared.ownedManagedSessionContext?.headedManagedAutosaveInterval, namespace: prepared.executionPlan.namespace, policyLock: prepared.managedSessionPolicyLock, preserveAttachedBrowserSession: input.preserveAttachedBrowserSession, restoreState: state.managedSessionRestoreState, sessionName: electronSessionName, timeoutMs: implicitSessionCloseTimeoutMs });
                     electronFailedConnectCleanup = await cleanupElectronLaunchResources({ child: prepared.electronLaunch.child, record: electronLaunchRecord, timeoutMs: implicitSessionCloseTimeoutMs });
                     electronLaunchRecord = electronFailedConnectCleanup.record;
                     if (electronFailedConnectCleanup.partial) {
@@ -585,8 +608,16 @@ export async function processBrowserOutput(input) {
         if (sessionStateKey)
             currentSessionTabTarget = authoritativePageState?.tabTarget;
         const currentSessionTabTargetUnknown = authoritativePageState?.tabTargetUnknown === true ? true : undefined;
-        const result = buildFinalAgentBrowserToolResult({ aboutBlankSessionMismatch, artifactCleanup, categoryDetails: finalRecoveryState.categoryDetails, clickDispatchDiagnostic, commandTokens: prepared.commandTokens, comboboxFocusDiagnostic, compiledNetworkSourceLookup: prepared.compiledNetworkSourceLookup, compiledSemanticAction: prepared.compiledSemanticAction, compatibilityWorkaround: prepared.compatibilityWorkaround, currentRefSnapshot, currentRefSnapshotInvalidation, currentSessionTabTarget, currentSessionTabTargetUnknown, electronBroadGetTextScopeDiagnostics, electronFailedConnectCleanup, electronHandoff, electronLaunch: prepared.electronLaunch, electronLaunchRecord, electronLaunchRecords, electronPostCommandHealth, electronProfileIsolationDetails: input.electronProfileIsolationDetails, electronRefFreshnessDiagnostic, electronSessionMismatch, errorText, evalResultWarning, evalStdinHint, exactSensitiveValues: prepared.exactSensitiveValues, executionPlan: prepared.executionPlan, fillVerificationDiagnostic, inspectionText, managedSessionOutcome, managedSessionRestoreDisabled: state.managedSessionRestoreState.isDisabled(prepared.executionPlan.sessionName, prepared.executionPlan.namespace), navigationSummary, networkSourceLookup, noActivePageSnapshotFailure: finalRecoveryState.noActivePageSnapshotFailure, openResultTabCorrection, overlayBlockerDiagnostic, parseError, parseFailureOutput, parseSucceeded, plainTextInspection, presentation, presentationEnvelope, priorSessionTabTarget: prepared.priorSessionTabTarget, processResult, qaAttachedTarget, qaPreset, recordingDependencyWarning, redactedArgs: prepared.redactedArgs, redactedCompiledElectron: prepared.redactedCompiledElectron, redactedCompiledJob: prepared.redactedCompiledJob, redactedCompiledNetworkSourceLookup: prepared.redactedCompiledNetworkSourceLookup, redactedCompiledQaPreset: prepared.redactedCompiledQaPreset, redactedCompiledSemanticAction: prepared.redactedCompiledSemanticAction, redactedCompiledSourceLookup: prepared.redactedCompiledSourceLookup, redactedContent, redactedProcessArgs: prepared.redactedProcessArgs, redactedRecoveryHint: prepared.redactedRecoveryHint, resultArtifactManifest, richInputRecoveryDiagnostic: finalRecoveryState.richInputRecoveryDiagnostic, scrollNoopDiagnostic, selectorTextVisibilityDiagnostics, sessionMode: prepared.sessionMode, sessionTabCorrection, sourceLookup, succeeded, timeoutPartialProgress, userRequestedJson: prepared.userRequestedJson, visibleRefFallbackDiagnostic: finalRecoveryState.visibleRefFallbackDiagnostic, visibleRefFallbackSessionName: finalRecoveryState.visibleRefFallbackSessionName });
-        const statePatch = { allowedDomainsBySession, artifactManifest, freshSessionOrdinal, managedSessionActive, managedSessionCompatibilityWorkaround, managedSessionCwd, managedSessionName, managedSessionNamespace, networkRoutesBySession };
+        const resultRetainsPreparedManagedSession = !managedSessionOutcome || (managedSessionOutcome.activeAfter
+            && managedSessionOutcome.attemptedSessionName === managedSessionOutcome.currentSessionName);
+        const resultHeadedManagedAutosaveDisabled = prepared.ownedManagedSessionContext?.headedManagedAutosaveDisabled === true
+            && resultRetainsPreparedManagedSession
+            && !(commandClosesSession && succeeded);
+        const resultHeadedManagedAutosaveInterval = resultRetainsPreparedManagedSession && !(commandClosesSession && succeeded)
+            ? prepared.ownedManagedSessionContext?.headedManagedAutosaveInterval
+            : undefined;
+        const result = buildFinalAgentBrowserToolResult({ aboutBlankSessionMismatch, artifactCleanup, categoryDetails: finalRecoveryState.categoryDetails, clickDispatchDiagnostic, commandTokens: prepared.commandTokens, comboboxFocusDiagnostic, compiledNetworkSourceLookup: prepared.compiledNetworkSourceLookup, compiledSemanticAction: prepared.compiledSemanticAction, compatibilityWorkaround: prepared.compatibilityWorkaround, currentRefSnapshot, currentRefSnapshotInvalidation, currentSessionTabTarget, currentSessionTabTargetUnknown, electronBroadGetTextScopeDiagnostics, electronFailedConnectCleanup, electronHandoff, electronLaunch: prepared.electronLaunch, electronLaunchRecord, electronLaunchRecords, electronPostCommandHealth, electronProfileIsolationDetails: input.electronProfileIsolationDetails, electronRefFreshnessDiagnostic, electronSessionMismatch, errorText, evalResultWarning, evalStdinHint, exactSensitiveValues: prepared.exactSensitiveValues, executionPlan: prepared.executionPlan, fillVerificationDiagnostic, inspectionText, managedSessionHeadedAutosaveDisabled: resultHeadedManagedAutosaveDisabled || undefined, managedSessionHeadedAutosaveInterval: resultHeadedManagedAutosaveInterval, managedSessionOutcome, managedSessionRestoreDisabled: state.managedSessionRestoreState.isDisabled(prepared.executionPlan.sessionName, prepared.executionPlan.namespace), navigationSummary, networkSourceLookup, noActivePageSnapshotFailure: finalRecoveryState.noActivePageSnapshotFailure, openResultTabCorrection, overlayBlockerDiagnostic, parseError, parseFailureOutput, parseSucceeded, plainTextInspection, presentation, presentationEnvelope, priorSessionTabTarget: prepared.priorSessionTabTarget, processResult, qaAttachedTarget, qaPreset, recordingDependencyWarning, redactedArgs: prepared.redactedArgs, redactedCompiledElectron: prepared.redactedCompiledElectron, redactedCompiledJob: prepared.redactedCompiledJob, redactedCompiledNetworkSourceLookup: prepared.redactedCompiledNetworkSourceLookup, redactedCompiledQaPreset: prepared.redactedCompiledQaPreset, redactedCompiledSemanticAction: prepared.redactedCompiledSemanticAction, redactedCompiledSourceLookup: prepared.redactedCompiledSourceLookup, redactedContent, redactedProcessArgs: prepared.redactedProcessArgs, redactedRecoveryHint: prepared.redactedRecoveryHint, resultArtifactManifest, richInputRecoveryDiagnostic: finalRecoveryState.richInputRecoveryDiagnostic, scrollNoopDiagnostic, selectorTextVisibilityDiagnostics, sessionMode: prepared.sessionMode, sessionTabCorrection, sourceLookup, succeeded, timeoutPartialProgress, userRequestedJson: prepared.userRequestedJson, visibleRefFallbackDiagnostic: finalRecoveryState.visibleRefFallbackDiagnostic, visibleRefFallbackSessionName: finalRecoveryState.visibleRefFallbackSessionName });
+        const statePatch = { allowedDomainsBySession, artifactManifest, freshSessionOrdinal, managedSessionActive, managedSessionCompatibilityWorkaround, managedSessionHeadedAutosaveDisabled, managedSessionHeadedAutosaveInterval, managedSessionCwd, managedSessionName, managedSessionNamespace, networkRoutesBySession };
         return { result, statePatch };
     }
     finally {

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

@@ -1,6 +1,7 @@
 import { rm } from "node:fs/promises";
 import { runAgentBrowserProcess } from "../../process.js";
-import { buildAgentBrowserNextActions, parseAgentBrowserEnvelope } from "../../results.js";
+import { buildAgentBrowserNextActions } from "../../results/action-recommendations.js";
+import { parseAgentBrowserEnvelope } from "../../results/envelope.js";
 import { buildNextToolAction, withOptionalNamespaceArgs, withOptionalSessionArgs } from "../../results/next-actions.js";
 import { getSessionPageStateKey, isAboutBlankUrl, normalizeComparableUrl, normalizeSessionTabTarget, targetsMatch, } from "../../session-page-state.js";
 import { isCloseCommand, isElectronPostCommandHealthCommand, isNavigationObservableCommandName, isRefGuardedCommand, isRefInvalidatingBatchCommand, isSessionTabPinningExcludedCommand, isSessionTabPostCommandCorrectionExcludedCommand, } from "../../command-taxonomy.js";
@@ -21,6 +22,10 @@ export function applyBrowserRunStatePatch(state, patch) {
         state.managedSessionActive = patch.managedSessionActive;
     if ("managedSessionCompatibilityWorkaround" in patch)
         state.managedSessionCompatibilityWorkaround = patch.managedSessionCompatibilityWorkaround;
+    if (patch.managedSessionHeadedAutosaveDisabled !== undefined)
+        state.managedSessionHeadedAutosaveDisabled = patch.managedSessionHeadedAutosaveDisabled;
+    if ("managedSessionHeadedAutosaveInterval" in patch)
+        state.managedSessionHeadedAutosaveInterval = patch.managedSessionHeadedAutosaveInterval;
     if (patch.managedSessionCwd !== undefined)
         state.managedSessionCwd = patch.managedSessionCwd;
     if (patch.managedSessionName !== undefined)
@@ -136,6 +141,12 @@ function formatManagedSessionOutcomeRecoveryGuidance(outcome) {
 export function formatManagedSessionOutcomeText(outcome) {
     if (!outcome)
         return undefined;
+    if (outcome.replacedSessionClosed === false) {
+        const cleanupWarning = "Cleanup warning: Automatic close of the previous wrapper-managed session failed, so it remains wrapper-owned. Use details.managedSessionOutcome for its exact identity and close it explicitly when safe.";
+        return outcome.succeeded
+            ? ["Managed session outcome: The fresh browser became current.", cleanupWarning].join("\n")
+            : [formatManagedSessionOutcomeHeadline(outcome), formatManagedSessionOutcomeRecoveryGuidance(outcome), cleanupWarning].join("\n");
+    }
     if (outcome.status === "closed" && outcome.succeeded) {
         return [
             "Managed session outcome: The current wrapper-managed browser session was closed.",
@@ -753,3 +764,8 @@ export function formatElectronRefFreshnessText(diagnostic) {
     return diagnostic?.summary;
 }
 export { extractBatchResultCommand };
+export function getPersistentSessionArtifactStore(ctx) {
+    const sessionDir = typeof ctx.sessionManager.getSessionDir === "function" ? ctx.sessionManager.getSessionDir() : undefined;
+    const sessionId = ctx.sessionManager.getSessionId();
+    return sessionDir && sessionId ? { sessionDir, sessionId } : undefined;
+}

package/dist/extensions/agent-browser/lib/orchestration/electron-host/index.js

@@ -1,21 +1,18 @@
-/**
- * Purpose: Own wrapper-side Electron host orchestration for agent_browser structured electron input.
- * Responsibilities: Discover Electron apps, inspect/probe/cleanup wrapper-tracked Electron launches, and build Pi-facing Electron host results.
- * Scope: Electron host actions that do not spawn the main upstream browser command; generic agent_browser execution stays in browser-run.
- */
 import { cleanupElectronLaunchResources, inspectElectronLaunchStatus } from "../../electron/cleanup.js";
 import { discoverElectronApps } from "../../electron/discovery.js";
-import { boundElectronProbeString } from "../../electron/text.js";
+import { boundElectronProbeString } from "../../electron/cdp.js";
 import { buildOwnedManagedSessionRestoreContext, withOwnedManagedSessionContext, } from "../../managed-session-restore.js";
 import { getManagedSessionStateAccessValidationError } from "../../managed-session-state-policy.js";
 import { isRecord } from "../../parsing.js";
-import { buildAgentBrowserNextActions, buildAgentBrowserResultCategoryDetails } from "../../results.js";
+import { withAttachedBrowserSessionContext } from "../../process.js";
+import { buildAgentBrowserNextActions } from "../../results/action-recommendations.js";
+import { buildAgentBrowserResultCategoryDetails } from "../../results/categories.js";
 import { appendUniqueAgentBrowserNextActions } from "../../results/next-actions.js";
 import { extractRefSnapshotFromData, getSessionPageStateKey, isAboutBlankUrl, normalizeSessionTabTarget } from "../../session-page-state.js";
 import { redactSensitiveText } from "../../runtime.js";
 import { collectElectronManagedSessionTarget } from "../browser-run/diagnostics.js";
 import { buildElectronHostFailureResult, formatElectronTargetLines, redactToolDetails } from "../browser-run/final-result.js";
-import { acquireOwnedManagedSessionDaemonPolicy, closeManagedSession } from "../browser-run/managed-session-daemon-policy.js";
+import { acquireOwnedManagedSessionDaemonPolicy, closeManagedSession, getRunningHeadedAutosavePolicyChangeError } from "../browser-run/managed-session-daemon-policy.js";
 import { buildElectronIdentifiers, buildElectronMismatchNextActions, buildElectronSessionMismatch, extractStringResultField, findElectronLaunchRecordForSession, formatElectronSessionMismatchText, getActiveElectronRecords, getLiveElectronRendererTargets, runSessionCommandData, } from "../browser-run/session-state.js";
 const ELECTRON_PROFILE_ISOLATION_NOTE = "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.";
 const ELECTRON_EXISTING_AUTH_GUIDANCE = "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.";
@@ -397,9 +394,14 @@ function getElectronProbeSummary(probe) {
 class ElectronManagedSessionPolicyError extends Error {
 }
 async function withOwnedElectronManagedSessionPolicy(options, run) {
+    const autosavePolicyChangeError = getRunningHeadedAutosavePolicyChangeError(options.headedManagedAutosaveInterval);
+    if (autosavePolicyChangeError)
+        throw new ElectronManagedSessionPolicyError(autosavePolicyChangeError);
     const context = buildOwnedManagedSessionRestoreContext({
         args: ["--namespace", options.namespace ?? "", "--session", options.sessionName, ...options.args],
         cwd: options.cwd,
+        headedManagedAutosaveDisabled: options.headedManagedAutosaveDisabled,
+        headedManagedAutosaveInterval: options.headedManagedAutosaveInterval,
         managedSessionName: options.sessionName,
         namespace: options.namespace,
         restoreState: options.restoreState,
@@ -580,6 +582,8 @@ function buildElectronProbeResult(options) {
         },
         nextActions: nextActions.length > 0 ? nextActions : undefined,
         ...buildAgentBrowserResultCategoryDetails({ args: [], succeeded: true }),
+        managedSessionHeadedAutosaveDisabled: options.headedManagedAutosaveDisabled === true ? true : undefined,
+        managedSessionHeadedAutosaveInterval: options.headedManagedAutosaveInterval,
         namespace: options.namespace,
         refSnapshot: options.probe.refSnapshot,
         sessionName: options.probe.sessionName,
@@ -596,8 +600,10 @@ function buildElectronProbeResult(options) {
 export async function cleanupTrackedElectronHostLaunches(options) {
     const results = [];
     for (const record of options.records) {
+        const sessionKey = getSessionPageStateKey(record.sessionName) ?? record.sessionName;
+        const managedSessionOwner = sessionKey ? options.ownedManagedSessions.get(sessionKey) : undefined;
         const managedSessionCloseError = record.sessionName
-            ? await closeManagedSession({ cwd: options.cwd, restoreState: options.managedSessionRestoreState, sessionName: record.sessionName, timeoutMs: options.timeoutMs })
+            ? await closeManagedSession({ cwd: options.cwd, headedManagedAutosaveInterval: managedSessionOwner?.headedManagedAutosaveInterval, preserveAttachedBrowserSession: options.attachedSessionKeys.has(sessionKey ?? record.sessionName), restoreState: options.managedSessionRestoreState, sessionName: record.sessionName, timeoutMs: options.timeoutMs })
             : undefined;
         const managedSessionStep = record.sessionName
             ? managedSessionCloseError
@@ -640,7 +646,13 @@ export async function cleanupActiveElectronHostLaunches(options) {
         : [];
 }
 export async function handleElectronHostInput(options) {
-    const { compiledElectron, cwd, electronChildProcesses, electronLaunchRecords, implicitSessionCloseTimeoutMs, managedSessionActive, managedSessionName, managedSessionNamespace, managedSessionRestoreState, redactedCompiledElectron, sessionPageState, signal, } = options;
+    const currentSessionKey = getSessionPageStateKey(options.managedSessionName, options.managedSessionNamespace) ?? options.managedSessionName;
+    const preserveAttachedBrowserSession = options.attachedSessionKeys.has(currentSessionKey)
+        || [...options.electronLaunchRecords.values()].some((record) => record.sessionName !== undefined && options.attachedSessionKeys.has(getSessionPageStateKey(record.sessionName) ?? record.sessionName));
+    return await withAttachedBrowserSessionContext(preserveAttachedBrowserSession, () => handleElectronHostInputInContext(options));
+}
+async function handleElectronHostInputInContext(options) {
+    const { attachedSessionKeys, compiledElectron, cwd, electronChildProcesses, electronLaunchRecords, implicitSessionCloseTimeoutMs, managedSessionActive, managedSessionName, managedSessionNamespace, managedSessionRestoreState, ownedManagedSessions, redactedCompiledElectron, sessionPageState, signal, } = options;
     if (compiledElectron?.action === "list") {
         try {
             const discovery = await discoverElectronApps({ maxResults: compiledElectron.maxResults, query: compiledElectron.query });
@@ -658,13 +670,18 @@ export async function handleElectronHostInput(options) {
         const statuses = await Promise.all(records.map((record) => inspectElectronLaunchStatus(record)));
         const managedSessions = await Promise.all(records
             .filter((record) => typeof record.sessionName === "string")
-            .map((record) => collectOwnedElectronManagedSessionTarget({
-            cwd,
-            restoreState: managedSessionRestoreState,
-            sessionName: record.sessionName,
-            signal,
-            timeoutMs: compiledElectron.timeoutMs,
-        })));
+            .map((record) => {
+            const sessionKey = getSessionPageStateKey(record.sessionName) ?? record.sessionName;
+            return collectOwnedElectronManagedSessionTarget({
+                cwd,
+                headedManagedAutosaveDisabled: ownedManagedSessions.get(sessionKey)?.headedManagedAutosaveDisabled,
+                headedManagedAutosaveInterval: ownedManagedSessions.get(sessionKey)?.headedManagedAutosaveInterval,
+                restoreState: managedSessionRestoreState,
+                sessionName: record.sessionName,
+                signal,
+                timeoutMs: compiledElectron.timeoutMs,
+            });
+        }));
         const mismatches = managedSessions
             .map((managedSession) => {
             const record = records.find((candidate) => candidate.sessionName === managedSession.sessionName);
@@ -726,9 +743,14 @@ export async function handleElectronHostInput(options) {
             });
             if (fileAccessError)
                 throw new ElectronManagedSessionPolicyError(fileAccessError);
+            const managedSessionOwner = ownedManagedSessions.get(pageStateKey);
+            const headedManagedAutosaveDisabled = managedSessionOwner?.headedManagedAutosaveDisabled === true;
+            const headedManagedAutosaveInterval = managedSessionOwner?.headedManagedAutosaveInterval;
             const probe = await withOwnedElectronManagedSessionPolicy({
                 args: ["snapshot", "-i"],
                 cwd,
+                headedManagedAutosaveDisabled,
+                headedManagedAutosaveInterval,
                 namespace: probeNamespace,
                 restoreState: managedSessionRestoreState,
                 sessionName: probeSessionName,
@@ -772,6 +794,8 @@ export async function handleElectronHostInput(options) {
             }
             return buildElectronProbeResult({
                 compiledElectron: redactedCompiledElectron ?? compiledElectron,
+                headedManagedAutosaveDisabled,
+                headedManagedAutosaveInterval,
                 mismatch: sessionMismatch,
                 namespace: probeNamespace,
                 probe,
@@ -794,7 +818,7 @@ export async function handleElectronHostInput(options) {
         const selection = selectElectronRecords(compiledElectron, electronLaunchRecords);
         if (selection.error)
             return buildElectronHostFailureResult({ compiledElectron: redactedCompiledElectron ?? compiledElectron, errorText: selection.error, failureCategory: "validation-error" });
-        const cleanupResults = await cleanupTrackedElectronHostLaunches({ cwd, electronChildProcesses, electronLaunchRecords, managedSessionRestoreState, records: selection.records ?? [], timeoutMs: compiledElectron.timeoutMs ?? implicitSessionCloseTimeoutMs });
+        const cleanupResults = await cleanupTrackedElectronHostLaunches({ attachedSessionKeys, cwd, electronChildProcesses, electronLaunchRecords, managedSessionRestoreState, ownedManagedSessions, records: selection.records ?? [], timeoutMs: compiledElectron.timeoutMs ?? implicitSessionCloseTimeoutMs });
         return buildElectronCleanupResult(redactedCompiledElectron ?? compiledElectron, cleanupResults);
     }
     return undefined;

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

@@ -1,7 +1,10 @@
 import { parseArgvDescriptor } from "../argv-descriptor.js";
 import { validateToolArgs, redactInvocationArgs, redactSensitiveText } from "../runtime.js";
 import { buildAgentBrowserResultCategoryDetails } from "../results/categories.js";
-import { compileAgentBrowserElectron, compileAgentBrowserJob, compileAgentBrowserNetworkSourceLookup, compileAgentBrowserQaPreset, compileAgentBrowserSemanticAction, compileAgentBrowserSourceLookup, redactNetworkSourceLookupArgs, redactNetworkSourceLookupUrl, } from "../input-modes.js";
+import { compileAgentBrowserElectron } from "../input-modes/electron.js";
+import { compileAgentBrowserJob, compileAgentBrowserQaPreset } from "../input-modes/job.js";
+import { compileAgentBrowserNetworkSourceLookup, compileAgentBrowserSourceLookup, redactNetworkSourceLookupArgs, redactNetworkSourceLookupUrl } from "../input-modes/lookups.js";
+import { compileAgentBrowserSemanticAction } from "../input-modes/semantic-action.js";
 function redactCompiledElectron(compiled) {
     if (!compiled)
         return undefined;

package/dist/extensions/agent-browser/lib/orchestration/output-file.js

@@ -1,4 +1,4 @@
-import { mkdir, writeFile } from "node:fs/promises";
+import { mkdir, realpath, stat, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, resolve } from "node:path";
 import { getAgentBrowserStoragePathValidationError } from "../managed-session-state-policy.js";
 import { isRecord } from "../parsing.js";
@@ -31,6 +31,33 @@ function appendOutputFileNotice(result, message) {
 export function getAgentBrowserOutputPathValidationError(outputPath, cwd) {
     return outputPath ? getAgentBrowserStoragePathValidationError(normalizeRequestedOutputPath(outputPath), cwd) : undefined;
 }
+function getArtifactPaths(result, cwd) {
+    const details = isRecord(result.details) ? result.details : undefined;
+    if (!details || !Array.isArray(details.artifacts))
+        return [];
+    return details.artifacts.flatMap((artifact) => {
+        if (!isRecord(artifact))
+            return [];
+        const path = typeof artifact.absolutePath === "string" ? artifact.absolutePath : typeof artifact.path === "string" ? artifact.path : undefined;
+        return path ? [isAbsolute(path) ? path : resolve(cwd, path)] : [];
+    });
+}
+async function pathsReferToSameFile(left, right) {
+    if (resolve(left) === resolve(right))
+        return true;
+    try {
+        if (await realpath(left) === await realpath(right))
+            return true;
+    }
+    catch { }
+    try {
+        const [leftStat, rightStat] = await Promise.all([stat(left), stat(right)]);
+        return leftStat.dev === rightStat.dev && leftStat.ino === rightStat.ino;
+    }
+    catch {
+        return false;
+    }
+}
 export async function applyAgentBrowserOutputPath(options) {
     if (!options.outputPath)
         return options.result;
@@ -47,6 +74,20 @@ export async function applyAgentBrowserOutputPath(options) {
     const requestedPath = normalizeRequestedOutputPath(options.outputPath);
     const absolutePath = isAbsolute(requestedPath) ? requestedPath : resolve(options.cwd, requestedPath);
     const payload = getOutputPayload(options.result);
+    for (const artifactPath of getArtifactPaths(options.result, options.cwd)) {
+        if (!await pathsReferToSameFile(absolutePath, artifactPath))
+            continue;
+        const message = "outputPath resolves to the same file as a browser artifact destination; choose a separate outputPath or omit it. The browser artifact was preserved.";
+        const outputFile = { absolutePath, error: message, path: requestedPath, source: payload.source, status: "failed" };
+        const details = isRecord(options.result.details) ? { ...options.result.details } : {};
+        delete details.successCategory;
+        return {
+            ...options.result,
+            content: appendOutputFileNotice(options.result, `Output file rejected: ${message}`),
+            details: { ...details, failureCategory: "validation-error", outputFile, resultCategory: "failure" },
+            isError: true,
+        };
+    }
     try {
         const serialized = serializeOutputPayload(payload.value);
         await mkdir(dirname(absolutePath), { recursive: true });

package/dist/extensions/agent-browser/lib/parsing.js

@@ -1,10 +1,3 @@
-/**
- * Purpose: Centralize low-level boundary parsing helpers shared by runtime planning, temp-artifact lifecycle, and result rendering.
- * Responsibilities: Identify non-null object records and normalize positive-integer string configuration values.
- * Scope: Tiny generic parsing predicates only; module-specific validation and error handling stay with their owning modules.
- * Usage: Imported by agent-browser wrapper modules that parse untyped JSON, persisted state, or environment variables.
- * Invariants/Assumptions: Arrays intentionally count as records to preserve existing object-boundary semantics, and positive integers must be safe base-10 integer strings greater than zero.
- */
 export function isRecord(value) {
     return typeof value === "object" && value !== null;
 }

package/dist/extensions/agent-browser/lib/pi-tool-rendering.js

@@ -1,5 +1,8 @@
 import { getKeybindings, Text, truncateToWidth } from "@earendil-works/pi-tui";
-import { compileAgentBrowserElectron, compileAgentBrowserJob, compileAgentBrowserNetworkSourceLookup, compileAgentBrowserQaPreset, compileAgentBrowserSemanticAction, compileAgentBrowserSourceLookup, } from "./input-modes.js";
+import { compileAgentBrowserElectron } from "./input-modes/electron.js";
+import { compileAgentBrowserJob, compileAgentBrowserQaPreset } from "./input-modes/job.js";
+import { compileAgentBrowserNetworkSourceLookup, compileAgentBrowserSourceLookup } from "./input-modes/lookups.js";
+import { compileAgentBrowserSemanticAction } from "./input-modes/semantic-action.js";
 import { isRecord } from "./parsing.js";
 import { redactInvocationArgs } from "./runtime.js";
 const TUI_INVOCATION_PREVIEW_MAX_CHARS = 160;