pi-agent-browser-native 0.2.76 → 0.3.0

package/dist/extensions/agent-browser/index.js

@@ -1,24 +1,18 @@
-/**
- * Purpose: Register the native agent_browser tool for pi so agents can invoke agent-browser without going through bash.
- * Responsibilities: Define the tool schema, inject thin wrapper behavior around the upstream CLI, manage extension-owned browser session convenience, and return pi-friendly content/details.
- * Scope: Native tool registration and orchestration only; the wrapper intentionally stays close to the upstream agent-browser CLI.
- * Usage: Loaded by pi through the package manifest in this package, or explicitly via `pi --no-extensions -e .` during local checkout development.
- * Invariants/Assumptions: agent-browser is installed separately on PATH, the wrapper targets the current locally installed upstream version only, and no backward-compatibility shims are provided.
- */
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Text } from "@earendil-works/pi-tui";
 import { PROJECT_RULE_PROMPT, buildBrowserDefaultProfileGuideline, buildBrowserExecutablePathGuideline, buildToolPromptGuidelines, } from "./lib/playbook.js";
 import { SessionPageState } from "./lib/session-page-state.js";
-import { canUseHeadlessCompatibilityUserAgent, createEphemeralSessionSeed, createFreshSessionName, createImplicitSessionName, extractCommandTokens, getImplicitSessionCloseTimeoutMs, getImplicitSessionIdleTimeoutMs, restoreManagedSessionStateFromBranch, validateToolArgs, } from "./lib/runtime.js";
-import { extractExplicitNamespace, extractExplicitSessionName, resolveAgentBrowserNamespace } from "./lib/argv-grammar.js";
+import { canUseHeadlessCompatibilityUserAgent, createEphemeralSessionSeed, createFreshSessionName, createImplicitSessionName, extractCommandTokens, getImplicitSessionCloseTimeoutMs, getImplicitSessionIdleTimeoutMs, isRestorableManagedSessionName, restoreManagedSessionStateFromBranch, validateToolArgs, } from "./lib/runtime.js";
+import { extractExplicitNamespace, extractExplicitSessionName, isUpstreamEnvFlagEnabled, resolveAgentBrowserNamespace } from "./lib/argv-grammar.js";
 import { cleanupManagedSessionRestoreConfig, ManagedSessionRestoreState } from "./lib/managed-session-restore.js";
 import { isRecord } from "./lib/parsing.js";
 import { buildPromptPolicy, getLatestUserPrompt, shouldAppendBrowserSystemPrompt } from "./lib/prompt-policy.js";
 import { isCloseCommand } from "./lib/command-taxonomy.js";
+import { hasLaunchScopedFlagToken } from "./lib/launch-scoped-flags.js";
 import { cleanupSecureTempArtifacts } from "./lib/temp.js";
-import { AGENT_BROWSER_PARAMS, } from "./lib/input-modes.js";
+import { AGENT_BROWSER_PARAMS } from "./lib/input-modes/params.js";
 import { parseAllowedDomainsPolicyFromArgs } from "./lib/navigation-policy.js";
 import { closeManagedSession, getSessionContextKey, runAgentBrowserTool } from "./lib/orchestration/browser-run/index.js";
 import { findElectronLaunchRecordForSession, getActiveElectronRecords } from "./lib/orchestration/browser-run/session-state.js";
@@ -111,6 +105,57 @@ function restoreManagedSessionCompatibilityWorkaroundFromBranch(branch, sessionN
     }
     return restored;
 }
+function restoreManagedSessionHeadedAutosaveDisabledFromBranch(branch, sessionName, namespace) {
+    let restored = false;
+    const targetKey = getSessionContextKey(sessionName, namespace);
+    for (const entry of branch) {
+        if (!isRecord(entry) || entry.type !== "message")
+            continue;
+        const message = isRecord(entry.message) ? entry.message : undefined;
+        if (!message || message.toolName !== "agent_browser")
+            continue;
+        const details = isRecord(message.details) ? message.details : undefined;
+        if (!details)
+            continue;
+        if (getSessionContextKey(typeof details.sessionName === "string" ? details.sessionName : undefined, typeof details.namespace === "string" ? details.namespace : undefined) !== targetKey)
+            continue;
+        const outcome = getManagedSessionOutcome(details);
+        const activeAfterFailure = outcome?.activeAfter === true
+            && typeof outcome.currentSessionName === "string"
+            && getSessionContextKey(outcome.currentSessionName, typeof outcome.currentSessionNamespace === "string" ? outcome.currentSessionNamespace : undefined) === targetKey;
+        if ((getSuccessfulToolResult(details, message) || activeAfterFailure) && typeof details.managedSessionHeadedAutosaveDisabled === "boolean") {
+            restored = details.managedSessionHeadedAutosaveDisabled;
+        }
+    }
+    return restored;
+}
+function restoreManagedSessionHeadedAutosaveIntervalFromBranch(branch, sessionName, namespace) {
+    let restored;
+    const targetKey = getSessionContextKey(sessionName, namespace);
+    for (const entry of branch) {
+        if (!isRecord(entry) || entry.type !== "message")
+            continue;
+        const message = isRecord(entry.message) ? entry.message : undefined;
+        if (!message || message.toolName !== "agent_browser")
+            continue;
+        const details = isRecord(message.details) ? message.details : undefined;
+        if (!details)
+            continue;
+        if (getSessionContextKey(typeof details.sessionName === "string" ? details.sessionName : undefined, typeof details.namespace === "string" ? details.namespace : undefined) !== targetKey)
+            continue;
+        const outcome = getManagedSessionOutcome(details);
+        const activeAfterFailure = outcome?.activeAfter === true
+            && typeof outcome.currentSessionName === "string"
+            && getSessionContextKey(outcome.currentSessionName, typeof outcome.currentSessionNamespace === "string" ? outcome.currentSessionNamespace : undefined) === targetKey;
+        if (!getSuccessfulToolResult(details, message) && !activeAfterFailure)
+            continue;
+        if (typeof details.managedSessionHeadedAutosaveInterval === "string")
+            restored = details.managedSessionHeadedAutosaveInterval;
+        else if (details.managedSessionHeadedAutosaveDisabled === true)
+            restored = "0";
+    }
+    return restored;
+}
 function getToolResultArgs(details) {
     if (Array.isArray(details.args) && details.args.every((arg) => typeof arg === "string"))
         return details.args;
@@ -118,6 +163,42 @@ function getToolResultArgs(details) {
         return details.effectiveArgs;
     return [];
 }
+function isAttachedBrowserInvocation(args, env = process.env) {
+    const autoConnectEnv = env.AGENT_BROWSER_AUTO_CONNECT;
+    return extractCommandTokens(args)[0] === "connect"
+        || hasLaunchScopedFlagToken(args, "--cdp")
+        || hasLaunchScopedFlagToken(args, "--auto-connect")
+        || env.AGENT_BROWSER_CDP !== undefined
+        || isUpstreamEnvFlagEnabled(autoConnectEnv);
+}
+function restoreAttachedSessionKeysFromBranch(branch) {
+    const attachedSessionKeys = new Set();
+    for (const entry of branch) {
+        if (!isRecord(entry) || entry.type !== "message")
+            continue;
+        const message = isRecord(entry.message) ? entry.message : undefined;
+        if (!message || message.toolName !== "agent_browser")
+            continue;
+        const details = isRecord(message.details) ? message.details : undefined;
+        if (!details)
+            continue;
+        const managedSessionOutcome = isRecord(details.managedSessionOutcome) ? details.managedSessionOutcome : undefined;
+        const retainedFailedAttachment = details.attachedBrowserSession === true && managedSessionOutcome?.activeAfter === true;
+        if (!getSuccessfulToolResult(details, message) && !retainedFailedAttachment)
+            continue;
+        const args = getToolResultArgs(details);
+        const sessionName = typeof details.sessionName === "string" ? details.sessionName : extractExplicitSessionName(args);
+        if (!sessionName)
+            continue;
+        const namespace = typeof details.namespace === "string" ? details.namespace : extractExplicitNamespace(args);
+        const sessionKey = getSessionContextKey(sessionName, namespace) ?? sessionName;
+        if (isCloseCommand(extractCommandTokens(args)[0]))
+            attachedSessionKeys.delete(sessionKey);
+        else if (details.attachedBrowserSession === true || isAttachedBrowserInvocation(args, {}))
+            attachedSessionKeys.add(sessionKey);
+    }
+    return attachedSessionKeys;
+}
 function restoreAllowedDomainsBySessionFromBranch(branch) {
     const restoredPolicies = new Map();
     for (const entry of branch) {
@@ -179,7 +260,9 @@ function trackOwnedManagedSession(sessions, sessionName, cwd, options = {}) {
     const key = getSessionContextKey(sessionName, options.namespace) ?? sessionName;
     const existing = sessions.get(key);
     const branchOwned = existing && !existing.branchOwned ? false : options.branchOwned === true;
-    sessions.set(key, { branchOwned, cwd, namespace: options.namespace, sessionName });
+    const headedManagedAutosaveDisabled = options.headedManagedAutosaveDisabled ?? existing?.headedManagedAutosaveDisabled;
+    const headedManagedAutosaveInterval = options.headedManagedAutosaveInterval ?? existing?.headedManagedAutosaveInterval;
+    sessions.set(key, { branchOwned, cwd, headedManagedAutosaveDisabled, headedManagedAutosaveInterval, namespace: options.namespace, sessionName });
 }
 function untrackOwnedManagedSession(sessions, sessionName, namespace) {
     if (!sessionName)
@@ -210,7 +293,11 @@ function syncOwnedManagedSessionsFromResult(sessions, result, cwd) {
     const attemptedSessionName = typeof outcome.attemptedSessionName === "string" ? outcome.attemptedSessionName : undefined;
     if (outcome.activeAfter === true && (status === "created" || status === "replaced" || status === "unchanged")) {
         const namespace = isRecord(details) && typeof details.namespace === "string" ? details.namespace : undefined;
-        trackOwnedManagedSession(sessions, currentSessionName, cwd, { namespace });
+        trackOwnedManagedSession(sessions, currentSessionName, cwd, {
+            headedManagedAutosaveDisabled: details?.managedSessionHeadedAutosaveDisabled === true,
+            headedManagedAutosaveInterval: typeof details?.managedSessionHeadedAutosaveInterval === "string" ? details.managedSessionHeadedAutosaveInterval : undefined,
+            namespace,
+        });
     }
     if (succeeded && status === "closed") {
         untrackOwnedManagedSession(sessions, attemptedSessionName ?? currentSessionName);
@@ -345,10 +432,18 @@ function setBranchRankForString(map, value, rank) {
     if (typeof value === "string" && value.length > 0)
         map.set(value, rank);
 }
+function setBranchManagedSessionActive(events, sessionName, namespace, rank) {
+    if (typeof sessionName !== "string" || sessionName.length === 0)
+        return;
+    const key = getSessionContextKey(sessionName, namespace) ?? sessionName;
+    events.managedSessionActiveIdentities.set(key, { namespace, sessionName });
+    events.managedSessionActiveRanks.set(key, rank);
+}
 function collectBranchManagedResourceEvents(branch) {
     const events = {
         electronLaunchActiveRanks: new Map(),
         electronLaunchCleanupRanks: new Map(),
+        managedSessionActiveIdentities: new Map(),
         managedSessionActiveRanks: new Map(),
         managedSessionCloseRanks: new Map(),
     };
@@ -377,17 +472,17 @@ function collectBranchManagedResourceEvents(branch) {
         const outcomeCurrentSessionName = typeof outcome?.currentSessionName === "string" ? outcome.currentSessionName : undefined;
         const outcomeAttemptedSessionName = typeof outcome?.attemptedSessionName === "string" ? outcome.attemptedSessionName : undefined;
         if (outcomeSucceeded && outcome.activeAfter === true && (outcomeStatus === "created" || outcomeStatus === "replaced" || outcomeStatus === "unchanged")) {
-            setBranchRankForString(events.managedSessionActiveRanks, getSessionContextKey(outcomeCurrentSessionName, namespace), eventRank);
+            setBranchManagedSessionActive(events, outcomeCurrentSessionName, namespace, eventRank);
         }
         if (outcomeSucceeded && outcomeStatus === "closed") {
             setBranchRankForString(events.managedSessionCloseRanks, getSessionContextKey(outcomeAttemptedSessionName ?? outcomeCurrentSessionName ?? sessionName, namespace), eventRank);
         }
-        if (outcomeSucceeded && outcomeStatus === "replaced") {
+        if (outcome && outcomeStatus === "replaced" && outcome.replacedSessionClosed !== false) {
             const replacedSessionNamespace = typeof outcome.replacedSessionNamespace === "string" ? outcome.replacedSessionNamespace : namespace;
             setBranchRankForString(events.managedSessionCloseRanks, getSessionContextKey(typeof outcome.replacedSessionName === "string" ? outcome.replacedSessionName : undefined, replacedSessionNamespace), eventRank);
         }
-        if (succeeded && !isCloseCommand(command) && sessionName && (usedImplicitSession || sessionMode === "fresh")) {
-            events.managedSessionActiveRanks.set(getSessionContextKey(sessionName, namespace) ?? sessionName, eventRank);
+        if (succeeded && !isCloseCommand(command) && sessionName && (usedImplicitSession || sessionMode === "fresh" || details.managedSessionHeadedAutosaveDisabled === true || typeof details.managedSessionHeadedAutosaveInterval === "string")) {
+            setBranchManagedSessionActive(events, sessionName, namespace, eventRank);
         }
         if (succeeded && isCloseCommand(command)) {
             setBranchRankForString(events.managedSessionCloseRanks, getSessionContextKey(explicitSessionName ?? sessionName ?? outcomeAttemptedSessionName ?? outcomeCurrentSessionName, namespace), eventRank);
@@ -433,18 +528,18 @@ function syncElectronCleanupManagedSessions(sessions, cleanupResults) {
         untrackOwnedManagedSession(sessions, sessionName);
     }
 }
-async function closeOwnedManagedSessionsExcept(sessions, restoreState, keepSessionName, timeoutMs, keepNamespace) {
+async function closeOwnedManagedSessionsExcept(sessions, restoreState, keepSessionName, timeoutMs, attachedSessionKeys, keepNamespace) {
     const keepKey = getSessionContextKey(keepSessionName, keepNamespace);
     for (const [key, owner] of [...sessions]) {
         if (key === keepKey)
             continue;
-        const error = await closeManagedSession({ cwd: owner.cwd, namespace: owner.namespace, restoreState, sessionName: owner.sessionName, timeoutMs });
+        const error = await closeManagedSession({ cwd: owner.cwd, headedManagedAutosaveInterval: owner.headedManagedAutosaveInterval, namespace: owner.namespace, preserveAttachedBrowserSession: attachedSessionKeys.has(key), restoreState, sessionName: owner.sessionName, timeoutMs });
         if (!error)
             sessions.delete(key);
     }
 }
-async function closeOwnedManagedSessions(sessions, restoreState, timeoutMs) {
-    await closeOwnedManagedSessionsExcept(sessions, restoreState, undefined, timeoutMs);
+async function closeOwnedManagedSessions(sessions, restoreState, timeoutMs, attachedSessionKeys) {
+    await closeOwnedManagedSessionsExcept(sessions, restoreState, undefined, timeoutMs, attachedSessionKeys);
 }
 function getOffBranchOwnedElectronLaunchRecords(ownedRecords, branchRecords) {
     const activeBranchLaunchIds = new Set(getActiveElectronRecords(branchRecords).map((record) => record.launchId));
@@ -577,6 +672,8 @@ export default function agentBrowserExtension(pi) {
     let managedSessionActive = false;
     let managedSessionBaseName = createImplicitSessionName(undefined, process.cwd(), ephemeralSessionSeed);
     let managedSessionCompatibilityWorkaround;
+    let managedSessionHeadedAutosaveDisabled = false;
+    let managedSessionHeadedAutosaveInterval;
     let managedSessionName = managedSessionBaseName;
     let managedSessionCwd = process.cwd();
     let managedSessionNamespace;
@@ -585,6 +682,7 @@ export default function agentBrowserExtension(pi) {
     let traceOwners = new Map();
     let artifactManifest;
     let allowedDomainsBySession = new Map();
+    let attachedSessionKeys = new Set();
     let networkRoutesBySession = new Map();
     let electronLaunchRecords = new Map();
     let ownedElectronLaunchRecords = new Map();
@@ -600,6 +698,7 @@ export default function agentBrowserExtension(pi) {
         const key = getSessionContextKey(sessionName, namespace) ?? sessionName;
         allowedDomainsBySession = new Map(allowedDomainsBySession);
         allowedDomainsBySession.delete(key);
+        attachedSessionKeys.delete(key);
         networkRoutesBySession = new Map(networkRoutesBySession);
         networkRoutesBySession.delete(key);
         sessionPageState.clearSession(key);
@@ -610,6 +709,7 @@ export default function agentBrowserExtension(pi) {
         const previousManagedSessionActive = managedSessionActive;
         const previousManagedSessionName = managedSessionName;
         const previousFreshSessionOrdinal = freshSessionOrdinal;
+        const previousAttachedSessionKeys = attachedSessionKeys;
         managedSessionBaseName = createImplicitSessionName(ctx.sessionManager.getSessionId(), ctx.cwd, ephemeralSessionSeed);
         const branch = ctx.sessionManager.getBranch();
         const branchResourceEvents = collectBranchManagedResourceEvents(branch);
@@ -640,14 +740,24 @@ export default function agentBrowserExtension(pi) {
         managedSessionCompatibilityWorkaround = managedSessionActive
             ? restoreManagedSessionCompatibilityWorkaroundFromBranch(branch, managedSessionName, managedSessionNamespace)
             : undefined;
+        managedSessionHeadedAutosaveDisabled = managedSessionActive
+            && restoreManagedSessionHeadedAutosaveDisabledFromBranch(branch, managedSessionName, managedSessionNamespace);
+        managedSessionHeadedAutosaveInterval = managedSessionActive
+            ? restoreManagedSessionHeadedAutosaveIntervalFromBranch(branch, managedSessionName, managedSessionNamespace)
+            : undefined;
         managedSessionCwd = ctx.cwd;
         freshSessionOrdinal = nextFreshSessionOrdinal;
         sessionPageState = SessionPageState.fromBranch(branch);
         traceOwners = new Map();
         artifactManifest = restoreArtifactManifestFromBranch(branch);
         allowedDomainsBySession = restoreAllowedDomainsBySessionFromBranch(branch);
+        attachedSessionKeys = restoreAttachedSessionKeysFromBranch(branch);
         networkRoutesBySession = new Map();
         electronLaunchRecords = restoreElectronLaunchRecordsFromBranch(branch);
+        for (const record of getActiveElectronRecords(electronLaunchRecords)) {
+            if (record.sessionName)
+                attachedSessionKeys.add(getSessionContextKey(record.sessionName) ?? record.sessionName);
+        }
         if (options.resetRuntimeOwnership) {
             ownedManagedSessions.clear();
             ownedElectronLaunchRecords = new Map();
@@ -659,13 +769,57 @@ export default function agentBrowserExtension(pi) {
             }
             removeInactiveOwnedElectronLaunchRecords(ownedElectronLaunchRecords, branchOwnedElectronLaunchIds, electronLaunchRecords, branchResourceEvents.electronLaunchActiveRanks, branchResourceEvents.electronLaunchCleanupRanks);
         }
+        for (const [sessionKey, identity] of branchResourceEvents.managedSessionActiveIdentities) {
+            const activeRank = branchResourceEvents.managedSessionActiveRanks.get(sessionKey);
+            const closeRank = branchResourceEvents.managedSessionCloseRanks.get(sessionKey);
+            if (activeRank === undefined || (closeRank !== undefined && closeRank >= activeRank))
+                continue;
+            if (!isRestorableManagedSessionName(identity.sessionName, managedSessionBaseName))
+                continue;
+            trackOwnedManagedSession(ownedManagedSessions, identity.sessionName, ctx.cwd, {
+                branchOwned: true,
+                headedManagedAutosaveDisabled: restoreManagedSessionHeadedAutosaveDisabledFromBranch(branch, identity.sessionName, identity.namespace),
+                headedManagedAutosaveInterval: restoreManagedSessionHeadedAutosaveIntervalFromBranch(branch, identity.sessionName, identity.namespace),
+                namespace: identity.namespace,
+            });
+        }
         if (restoredState.active) {
-            trackOwnedManagedSession(ownedManagedSessions, restoredState.sessionName, ctx.cwd, { branchOwned: true, namespace: restoredState.namespace });
+            trackOwnedManagedSession(ownedManagedSessions, restoredState.sessionName, ctx.cwd, {
+                branchOwned: true,
+                headedManagedAutosaveDisabled: managedSessionHeadedAutosaveDisabled,
+                headedManagedAutosaveInterval: managedSessionHeadedAutosaveInterval,
+                namespace: restoredState.namespace,
+            });
+        }
+        for (const record of getActiveElectronRecords(electronLaunchRecords)) {
+            if (!record.sessionName || !isRestorableManagedSessionName(record.sessionName, managedSessionBaseName))
+                continue;
+            const sessionKey = getSessionContextKey(record.sessionName) ?? record.sessionName;
+            const activeRank = branchResourceEvents.managedSessionActiveRanks.get(sessionKey);
+            const closeRank = branchResourceEvents.managedSessionCloseRanks.get(sessionKey);
+            if (activeRank === undefined || (closeRank !== undefined && closeRank >= activeRank))
+                continue;
+            trackOwnedManagedSession(ownedManagedSessions, record.sessionName, ctx.cwd, {
+                branchOwned: true,
+                headedManagedAutosaveDisabled: restoreManagedSessionHeadedAutosaveDisabledFromBranch(branch, record.sessionName),
+                headedManagedAutosaveInterval: restoreManagedSessionHeadedAutosaveIntervalFromBranch(branch, record.sessionName),
+            });
         }
         mergeActiveElectronLaunchRecords(ownedElectronLaunchRecords, electronLaunchRecords, {
             branchOwnedLaunchIds: branchOwnedElectronLaunchIds,
             markBranchOwned: true,
         });
+        if (!options.resetRuntimeOwnership) {
+            for (const sessionKey of previousAttachedSessionKeys) {
+                if (ownedManagedSessions.has(sessionKey))
+                    attachedSessionKeys.add(sessionKey);
+            }
+            for (const record of ownedElectronLaunchRecords.values()) {
+                const sessionKey = getSessionContextKey(record.sessionName);
+                if (sessionKey && previousAttachedSessionKeys.has(sessionKey))
+                    attachedSessionKeys.add(sessionKey);
+            }
+        }
     };
     const registerWebSearchToolIfAvailable = (configState) => {
         if (webSearchToolRegistered || !canRegisterWebSearchTool(configState))
@@ -707,10 +861,12 @@ export default function agentBrowserExtension(pi) {
                 ? ownedElectronLaunchRecords
                 : getOffBranchOwnedElectronLaunchRecords(ownedElectronLaunchRecords, electronLaunchRecords);
             const electronCleanupResults = await cleanupActiveElectronHostLaunches({
+                attachedSessionKeys,
                 cwd: shutdownCwd,
                 electronChildProcesses,
                 electronLaunchRecords: electronRecordsToCleanup,
                 managedSessionRestoreState,
+                ownedManagedSessions,
                 timeoutMs: implicitSessionCloseTimeoutMs,
             });
             preservedElectronProfileDirs = [...new Set([
@@ -719,19 +875,22 @@ export default function agentBrowserExtension(pi) {
                 ])];
             syncElectronCleanupManagedSessions(ownedManagedSessions, electronCleanupResults);
             if (quitting) {
-                await closeOwnedManagedSessions(ownedManagedSessions, managedSessionRestoreState, implicitSessionCloseTimeoutMs);
+                await closeOwnedManagedSessions(ownedManagedSessions, managedSessionRestoreState, implicitSessionCloseTimeoutMs, attachedSessionKeys);
             }
             else {
-                await closeOwnedManagedSessionsExcept(ownedManagedSessions, managedSessionRestoreState, managedSessionActive ? managedSessionName : undefined, implicitSessionCloseTimeoutMs, managedSessionActive ? managedSessionNamespace : undefined);
+                await closeOwnedManagedSessionsExcept(ownedManagedSessions, managedSessionRestoreState, managedSessionActive ? managedSessionName : undefined, implicitSessionCloseTimeoutMs, attachedSessionKeys, managedSessionActive ? managedSessionNamespace : undefined);
             }
         });
         managedSessionActive = false;
         managedSessionCompatibilityWorkaround = undefined;
+        managedSessionHeadedAutosaveDisabled = false;
+        managedSessionHeadedAutosaveInterval = undefined;
         managedSessionNamespace = undefined;
         sessionPageState.reset();
         traceOwners = new Map();
         artifactManifest = undefined;
         allowedDomainsBySession = new Map();
+        attachedSessionKeys = new Set();
         networkRoutesBySession = new Map();
         electronLaunchRecords = new Map();
         ownedElectronLaunchRecords = new Map();
@@ -822,6 +981,7 @@ export default function agentBrowserExtension(pi) {
                     ownedRecords: ownedElectronLaunchRecords,
                 });
                 const electronHostResult = await handleElectronHostInput({
+                    attachedSessionKeys,
                     compiledElectron,
                     cwd: ctx.cwd,
                     electronChildProcesses,
@@ -831,6 +991,7 @@ export default function agentBrowserExtension(pi) {
                     managedSessionName,
                     managedSessionNamespace,
                     managedSessionRestoreState,
+                    ownedManagedSessions,
                     redactedCompiledElectron,
                     sessionPageState,
                     signal,
@@ -858,6 +1019,8 @@ export default function agentBrowserExtension(pi) {
                         if (closedSessionName === managedSessionName) {
                             managedSessionActive = false;
                             managedSessionCompatibilityWorkaround = undefined;
+                            managedSessionHeadedAutosaveDisabled = false;
+                            managedSessionHeadedAutosaveInterval = undefined;
                             managedSessionNamespace = undefined;
                             freshSessionOrdinal += 1;
                             managedSessionName = createFreshSessionName(managedSessionBaseName, ephemeralSessionSeed, freshSessionOrdinal);
@@ -891,6 +1054,7 @@ export default function agentBrowserExtension(pi) {
                 const browserRunState = {
                     allowedDomainsBySession,
                     artifactManifest,
+                    attachedSessionKeys,
                     closedManagedSessionNames: new Set(),
                     electronChildProcesses,
                     electronLaunchRecords,
@@ -899,6 +1063,8 @@ export default function agentBrowserExtension(pi) {
                     managedSessionActive,
                     managedSessionBaseName,
                     managedSessionCompatibilityWorkaround,
+                    managedSessionHeadedAutosaveDisabled,
+                    managedSessionHeadedAutosaveInterval,
                     managedSessionCwd,
                     managedSessionName,
                     managedSessionNamespace,
@@ -911,6 +1077,14 @@ export default function agentBrowserExtension(pi) {
                 const initialAllowedDomainsBySession = browserRunState.allowedDomainsBySession;
                 const initialArtifactManifest = browserRunState.artifactManifest;
                 const initialNetworkRoutesBySession = browserRunState.networkRoutesBySession;
+                const attachedSessionRequested = isAttachedBrowserInvocation(toolArgs)
+                    || (resolvedInput.kind === "electron" && resolvedInput.compiledElectron.action === "launch");
+                const allocatesFreshManagedSession = explicitSessionName === undefined
+                    && (params.sessionMode === "fresh" || (resolvedInput.kind === "electron" && resolvedInput.compiledElectron.action === "launch"));
+                const reusableSessionKey = allocatesFreshManagedSession
+                    ? undefined
+                    : callerOwnedSessionQueueKey ?? getSessionContextKey(browserRunState.managedSessionName, browserRunState.managedSessionNamespace);
+                const attachedSessionKnown = reusableSessionKey !== undefined && attachedSessionKeys.has(reusableSessionKey);
                 let result = await runAgentBrowserTool({
                     ctx,
                     cwd: ctx.cwd,
@@ -921,12 +1095,34 @@ export default function agentBrowserExtension(pi) {
                     input: resolvedInput,
                     onUpdate,
                     params,
+                    establishAttachedBrowserSession: attachedSessionRequested && !attachedSessionKnown,
+                    preserveAttachedBrowserSession: attachedSessionRequested || attachedSessionKnown,
                     promptPolicy,
                     sessionPageStateUpdate,
                     signal,
                     state: browserRunState,
                 });
                 const branchRestoreStillCurrent = branchRestoreGenerationAtStart === branchRestoreGeneration;
+                if (branchRestoreStillCurrent) {
+                    const resultDetails = isRecord(result.details) ? result.details : undefined;
+                    const resultSessionName = typeof resultDetails?.sessionName === "string"
+                        ? resultDetails.sessionName
+                        : extractExplicitSessionName(toolArgs);
+                    const resultNamespace = typeof resultDetails?.namespace === "string"
+                        ? resultDetails.namespace
+                        : resolveAgentBrowserNamespace(toolArgs, process.env.AGENT_BROWSER_NAMESPACE);
+                    const resultSessionKey = getSessionContextKey(resultSessionName, resultNamespace) ?? resultSessionName;
+                    const managedSessionOutcome = isRecord(resultDetails?.managedSessionOutcome) ? resultDetails.managedSessionOutcome : undefined;
+                    const attachedSessionRemainsActive = result.isError !== true
+                        || (attachedSessionRequested && managedSessionOutcome?.activeAfter === true);
+                    const closesAttachedSession = result.isError !== true && isCloseCommand(extractCommandTokens(toolArgs)[0]);
+                    if (resultSessionKey && closesAttachedSession)
+                        attachedSessionKeys.delete(resultSessionKey);
+                    else if (resultSessionKey && attachedSessionRemainsActive && (attachedSessionRequested || attachedSessionKnown)) {
+                        attachedSessionKeys.add(resultSessionKey);
+                        result = { ...result, details: { ...(resultDetails ?? {}), attachedBrowserSession: true } };
+                    }
+                }
                 if (branchRestoreStillCurrent) {
                     allowedDomainsBySession = mergeBrowserRunMap(allowedDomainsBySession, initialAllowedDomainsBySession, browserRunState.allowedDomainsBySession);
                     networkRoutesBySession = mergeBrowserRunMap(networkRoutesBySession, initialNetworkRoutesBySession, browserRunState.networkRoutesBySession);
@@ -947,6 +1143,8 @@ export default function agentBrowserExtension(pi) {
                     freshSessionOrdinal = Math.max(freshSessionOrdinal, browserRunState.freshSessionOrdinal);
                     managedSessionActive = browserRunState.managedSessionActive;
                     managedSessionCompatibilityWorkaround = browserRunState.managedSessionCompatibilityWorkaround;
+                    managedSessionHeadedAutosaveDisabled = browserRunState.managedSessionHeadedAutosaveDisabled === true;
+                    managedSessionHeadedAutosaveInterval = browserRunState.managedSessionHeadedAutosaveInterval;
                     managedSessionCwd = browserRunState.managedSessionCwd;
                     managedSessionName = browserRunState.managedSessionName;
                     managedSessionNamespace = browserRunState.managedSessionNamespace;

package/dist/extensions/agent-browser/lib/argv-descriptor.js

@@ -1,8 +1,3 @@
-/**
- * Purpose: Parse raw agent-browser argv once into a stable command descriptor for planners and policy.
- * Responsibilities: Own command-token extraction, command/subcommand identification, and descriptor construction.
- * Scope: Pure argv parsing; runtime planning and session policy consume descriptors instead of re-parsing tokens.
- */
 import { GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES, VALUE_FLAGS, optionalGlobalValueFlagConsumesNext } from "./argv-grammar.js";
 import { isOpenNavigationCommand } from "./command-taxonomy.js";
 function isBooleanLiteral(token) {

package/dist/extensions/agent-browser/lib/argv-grammar.js

@@ -1,8 +1,3 @@
-/**
- * Purpose: Shared argv flag-shape metadata and helpers for command discovery and sessionless policy checks.
- * Responsibilities: Own global/command value-flag sets and boolean/value-flag validation used during argv parsing.
- * Scope: Pure token grammar; command semantics and subprocess execution live elsewhere.
- */
 import { isKnownCommandToken } from "./command-taxonomy.js";
 export const GLOBAL_VALUE_FLAGS = [
     "--session",
@@ -125,6 +120,10 @@ export function getBooleanFlagValue(args, flag) {
 export function isBooleanFlagEnabled(args, flag) {
     return getBooleanFlagValue(args, flag) ?? false;
 }
+/** Match upstream env_var_is_truthy exactly: lowercase only, without trimming or accepting "off". */
+export function isUpstreamEnvFlagEnabled(value) {
+    return value !== undefined && !["", "0", "false", "no"].includes(value.toLowerCase());
+}
 /** Mirror upstream sanitize_session_component for namespace/socket/state identity. */
 export function canonicalizeAgentBrowserNamespace(value) {
     if (value === undefined)

package/dist/extensions/agent-browser/lib/command-policy.js

@@ -1,8 +1,3 @@
-/**
- * Purpose: Own upstream command-shape policies that decide whether the wrapper should allocate a managed browser session.
- * Responsibilities: Keep local/sessionless command grammar out of the runtime execution planner while preserving exact upstream shapes.
- * Scope: Pure argv-token policy; command discovery, subprocess execution, and presentation live in focused modules.
- */
 import { hasOnlyBooleanFlags, hasOnlyOptionFlags, isNonFlagToken, stripSessionlessShapeGlobalFlags } from "./argv-grammar.js";
 const SESSIONLESS_AUTH_SUBCOMMANDS = new Set(["save", "list", "show", "delete", "remove"]);
 const PLUGIN_SESSIONLESS_SUBCOMMANDS = new Set(["list", "show", "add", "run"]);

package/dist/extensions/agent-browser/lib/command-taxonomy.js

@@ -1,9 +1,3 @@
-/**
- * Purpose: Centralize upstream agent-browser command capabilities that wrapper behavior depends on.
- * Responsibilities: Normalize command aliases once and expose capability predicates for runtime planning,
- * session/ref guards, result recommendations, and presentation summaries without coupling unrelated behaviors.
- * Scope: Static command capability taxonomy only; command-shape parsing, spawning, and formatting live elsewhere.
- */
 const ADDITIONAL_COMMAND_TOKENS = [
     "a11y", "auth", "chat", "clipboard", "confirm", "connect", "dashboard", "deny", "device", "dialog", "diff", "doctor", "errors", "eval", "find", "frame", "get", "highlight", "inspect", "install", "is", "mcp", "plugin", "plugins", "profiles", "profiler", "react", "record", "removeinitscript", "session", "set", "skills", "snapshot", "state", "stream", "trace", "upgrade", "vitals", "wait", "web-vitals", "window",
 ];

package/dist/extensions/agent-browser/lib/config-policy.js

@@ -1,9 +1,4 @@
 // @ts-check
-/**
- * Purpose: Canonical pi-agent-browser-native config policy shared by runtime and setup CLI.
- * Responsibilities: Own config paths, provider descriptors, credential source parsing, layer validation/merge, status projection, and redacted summaries.
- * Scope: Pure configuration policy plus synchronous status loading; secret command execution and browser/web-search runtime calls live elsewhere.
- */
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";

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

@@ -1,9 +1,3 @@
-/**
- * Purpose: Load pi-agent-browser-native package configuration from Pi-scoped global, project, or explicit paths.
- * Responsibilities: Resolve config layers, resolve secrets without exposing values, and provide redacted status for tools/CLIs.
- * Scope: Package-owned configuration only; canonical config policy lives in config-policy.js, browser command execution and web-search API calls live in focused modules.
- * Invariants/Assumptions: Credential sources from loaded config are passed through to the runtime; command credentials are resolved lazily at execution time and displayed values stay redacted.
- */
 import { exec as execCallback } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import { promisify } from "node:util";

package/dist/extensions/agent-browser/lib/electron/cdp.js

@@ -1,10 +1,3 @@
-/**
- * Purpose: Parse and fetch Chrome DevTools Protocol metadata for wrapper-owned Electron launches.
- * Responsibilities: Normalize CDP version/target JSON and perform bounded localhost CDP JSON fetches.
- * Scope: Tiny Electron CDP boundary helpers only; launch, status, cleanup, and target selection stay in their owning modules.
- * Usage: Imported by Electron launch and cleanup paths when polling `/json/version` and `/json/list`.
- * Invariants/Assumptions: Malformed or unavailable CDP endpoints return undefined/empty metadata rather than throwing, matching prior caller behavior.
- */
 import { isRecord } from "../parsing.js";
 const ELECTRON_CDP_FETCH_TIMEOUT_MS = 1_000;
 function asString(value) {
@@ -49,3 +42,9 @@ export async function fetchCdpJson(url, signal) {
         clearTimeout(timeout);
     }
 }
+export function boundElectronProbeString(value, maxLength = 240) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return undefined;
+    return trimmed.length > maxLength ? `${trimmed.slice(0, Math.max(0, maxLength - 3))}...` : trimmed;
+}

package/dist/extensions/agent-browser/lib/electron/cleanup.js

@@ -1,10 +1,3 @@
-/**
- * Purpose: Inspect and clean wrapper-owned Electron launch resources.
- * Responsibilities: Report CDP liveness/targets without mutation and remove only tracked process/profile resources during explicit or shutdown cleanup.
- * Scope: Host-side Electron status and resource cleanup only; upstream managed-session close remains in the extension entrypoint.
- * Usage: Called by electron.status, electron.cleanup, and session_shutdown handling.
- * Invariants/Assumptions: Cleanup operates only on launch records produced by this wrapper and prefers partial cleanup reporting over killing or deleting untracked resources.
- */
 import { execFile } from "node:child_process";
 import { rm } from "node:fs/promises";
 import { promisify } from "node:util";

package/dist/extensions/agent-browser/lib/electron/discovery.js

@@ -1,10 +1,3 @@
-/**
- * Purpose: Discover installed Electron desktop applications without invoking upstream agent-browser.
- * Responsibilities: Scan bounded macOS app bundles and Linux .desktop launchers, apply Electron framework evidence gates, and return small platform-tagged app metadata.
- * Scope: Discovery only; launch, cleanup, status, and CDP attachment live in later Electron lifecycle work items.
- * Usage: Called by the agent_browser top-level electron.list shorthand and directly by tests through parameterized scan locations.
- * Invariants/Assumptions: Discovery is best-effort, missing scan roots are ignored, malformed .desktop files are skipped, and results are capped before they reach model-visible output.
- */
 import { constants as fsConstants } from "node:fs";
 import { access, readdir, readFile, realpath, stat } from "node:fs/promises";
 import { homedir } from "node:os";

package/dist/extensions/agent-browser/lib/electron/launch.js

@@ -1,10 +1,3 @@
-/**
- * Purpose: Launch wrapper-owned Electron applications and discover their CDP endpoint.
- * Responsibilities: Resolve Electron targets, enforce caller-owned allow/deny policy, create isolated userDataDir profiles, launch with remote debugging on an OS-chosen port, poll DevToolsActivePort, and read bounded CDP version/target metadata.
- * Scope: Host-side Electron lifecycle setup only; upstream agent-browser attach/presentation stays in the extension entrypoint.
- * Usage: Called by the agent_browser electron.launch shorthand before routing through upstream `connect`.
- * Invariants/Assumptions: The wrapper only launches targets with Electron framework evidence, always uses an isolated temp profile, never accepts a caller-supplied remote debugging port, and cleans any spawned process/profile when cancellation interrupts readiness.
- */
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { readFile, rm } from "node:fs/promises";

package/dist/extensions/agent-browser/lib/input-modes/electron.js

@@ -1,8 +1,3 @@
-/**
- * Purpose: Compile top-level Electron wrapper inputs into validated Electron actions.
- * Responsibilities: Enforce action-specific fields, launch-target rules, and wrapper-owned flag safety.
- * Scope: Electron input-mode validation only; launch/probe/cleanup execution stays in the extension entrypoint.
- */
 import { isRecord } from "../parsing.js";
 import { AGENT_BROWSER_ELECTRON_ACTIONS, AGENT_BROWSER_ELECTRON_HANDOFFS, AGENT_BROWSER_ELECTRON_LIST_FIELDS, AGENT_BROWSER_ELECTRON_PROBE_FIELDS, AGENT_BROWSER_ELECTRON_RESERVED_APP_ARGS, AGENT_BROWSER_ELECTRON_TARGET_TYPES, } from "./types.js";
 function validateOptionalNonEmptyString(input, fieldName) {

package/dist/extensions/agent-browser/lib/input-modes/job.js

@@ -1,8 +1,3 @@
-/**
- * Purpose: Compile constrained job and lightweight QA wrapper inputs to upstream batch commands.
- * Responsibilities: Validate job/QA fields, produce argv/stdin, and summarize QA diagnostic results.
- * Scope: Job and QA modes only.
- */
 import { isRecord } from "../parsing.js";
 import { summarizeNetworkFailures } from "../results/network.js";
 import { getBatchResultItems, getCommandNameFromBatchItem, getSelectValues } from "./shared.js";

package/dist/extensions/agent-browser/lib/input-modes/lookups.js

@@ -1,8 +1,3 @@
-/**
- * Purpose: Compile and analyze experimental DOM/source and network source lookup input modes.
- * Responsibilities: Build lookup batches, collect DOM/React/workspace candidates, and redact network lookup surfaces.
- * Scope: Source lookup and network source lookup only.
- */
 import { readFile, readdir } from "node:fs/promises";
 import { extname, join } from "node:path";
 import { isRecord } from "../parsing.js";