pi-agent-browser-native 0.9.2 → 0.9.4

package/dist/extensions/agent-browser/lib/orchestration/extension-host-coordination.js

@@ -0,0 +1,98 @@
+import { getActiveElectronRecords } from "./browser-run/session-state.js";
+import { buildValidationFailureResult } from "./input-plan.js";
+import { applyAgentBrowserOutputPath } from "./output-file.js";
+import { resolveBrowserExecutionIdentity, withBrowserExecutionLocks, } from "../managed-session-policy-lock.js";
+import { getArtifactPreflightValidationError } from "./extension-artifact-preflight.js";
+import { browserExecutionFailure } from "./extension-result-state.js";
+import { shouldSerializeElectronHostInput } from "./extension-electron-ownership.js";
+import { warnRecordingPersistence } from "./extension-recording.js";
+import { runElectronHostInput } from "./extension-host-run.js";
+class ElectronHostCoordinator {
+    runtime;
+    call;
+    constructor(runtime, call) {
+        this.runtime = runtime;
+        this.call = call;
+    }
+    async cleanup(signal) {
+        this.runtime.recordings.flush();
+        const path = this.call.outputPath;
+        const error = path !== undefined && path !== ""
+            ? getArtifactPreflightValidationError({
+                activeRecordingReservations: [...this.runtime.recordings.active.values()],
+                args: [],
+                cwd: this.call.operationCwd,
+                outputPath: path,
+            })
+            : undefined;
+        if (error !== undefined && error !== "") {
+            return warnRecordingPersistence(this.runtime.recordings.dirty, buildValidationFailureResult({
+                ...this.call.resolvedInput,
+                attemptedKind: this.call.resolvedInput.kind,
+                kind: "invalid",
+                status: "invalid",
+                validationError: error,
+            }));
+        }
+        const result = await runElectronHostInput(this.runtime, this.call, signal);
+        return result
+            ? applyAgentBrowserOutputPath({
+                cwd: this.call.operationCwd,
+                outputPath: path,
+                result: warnRecordingPersistence(this.runtime.recordings.dirty, result),
+            })
+            : result;
+    }
+    execute(signal = this.call.signal) {
+        return this.call.compiledElectron?.action === "cleanup"
+            ? this.runtime.artifacts.queue.run(() => this.cleanup(signal))
+            : runElectronHostInput(this.runtime, this.call, signal);
+    }
+    selectedSessions() {
+        const compiled = this.call.compiledElectron;
+        const records = this.runtime.electron.forHostInput({
+            compiledElectron: compiled,
+            ownerSessionId: this.call.ctx.sessionManager.getSessionId(),
+        });
+        const launchId = compiled && "launchId" in compiled ? compiled.launchId : undefined;
+        const selected = launchId !== undefined && launchId !== ""
+            ? [records.get(launchId)].filter((record) => record !== undefined)
+            : getActiveElectronRecords(records);
+        const sessions = selected.flatMap((record) => record.sessionName !== undefined && record.sessionName !== ""
+            ? [{ sessionName: record.sessionName, namespace: record.namespace }]
+            : []);
+        if (compiled?.action === "probe" &&
+            (launchId === undefined || launchId === "") &&
+            this.runtime.managed.active) {
+            sessions.push({
+                sessionName: this.runtime.managed.name,
+                namespace: this.runtime.managed.namespace,
+            });
+        }
+        return sessions;
+    }
+    async run() {
+        if (!shouldSerializeElectronHostInput(this.call.compiledElectron)) {
+            return this.execute();
+        }
+        const sessions = this.selectedSessions();
+        if (sessions.length === 0) {
+            return this.execute();
+        }
+        try {
+            const identities = await Promise.all(sessions.map((session) => resolveBrowserExecutionIdentity({ ...session, ownedManagedSession: true })));
+            return await withBrowserExecutionLocks({
+                identities,
+                signal: this.call.signal,
+                deadline: Date.now() + this.call.executionTimeoutMs,
+                waitOnly: true,
+            }, (signal) => this.execute(signal));
+        }
+        catch (error) {
+            return browserExecutionFailure(error, this.call.signal);
+        }
+    }
+}
+export function runCoordinatedElectronHostInput(runtime, call) {
+    return new ElectronHostCoordinator(runtime, call).run();
+}

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

@@ -0,0 +1,295 @@
+import { randomUUID } from "node:crypto";
+import { appendBrowserTransition, applyArtifactChanges, artifactChanges, browserStateEffects, } from "../browser-transcript.js";
+import { appendBrowserRecord } from "../browser-journal.js";
+import { createFreshSessionName } from "../runtime.js";
+import { getAgentBrowserSessionIdentityKey } from "../argv-grammar.js";
+import { isRecord } from "../parsing.js";
+import { inspectManagedSessionDaemon } from "./browser-run/managed-session-daemon-policy.js";
+import { getActiveElectronRecords, getSessionContextKey } from "./browser-run/session-state.js";
+import { handleElectronHostInput } from "./electron-host/index.js";
+import { formatSessionArtifactRetentionSummary } from "../results/artifact-manifest.js";
+import { browserExecutionFailure, invocationArtifactManifest, browserPageChanges, } from "./extension-result-state.js";
+import { getCleanupResultsClosedManagedSessionIdentities, isElectronLaunchRecord, syncElectronCleanupManagedSessions, } from "./extension-electron-ownership.js";
+class ElectronHostTransaction {
+    runtime;
+    call;
+    executionSignal;
+    electronHostLaunchRecords;
+    hostAffecting;
+    workingPageState;
+    priorPages;
+    priorManifest;
+    operationId;
+    launchId;
+    selected;
+    keys;
+    begin;
+    electronHostResult;
+    constructor(runtime, call, executionSignal = call.signal) {
+        this.runtime = runtime;
+        this.call = call;
+        this.executionSignal = executionSignal;
+        this.electronHostLaunchRecords = this.runtime.electron.forHostInput({
+            compiledElectron: this.call.compiledElectron,
+            ownerSessionId: this.call.ctx.sessionManager.getSessionId(),
+        });
+        this.hostAffecting =
+            this.call.compiledElectron !== undefined &&
+                ["cleanup", "probe"].includes(this.call.compiledElectron.action);
+        this.workingPageState = this.runtime.sessions.pages.fork();
+        this.priorPages = this.workingPageState.views();
+        this.priorManifest = this.runtime.artifacts.manifest;
+        this.operationId = randomUUID();
+        this.launchId =
+            this.call.compiledElectron && "launchId" in this.call.compiledElectron
+                ? this.call.compiledElectron.launchId
+                : undefined;
+        this.selected =
+            this.launchId !== undefined && this.launchId !== ""
+                ? [this.electronHostLaunchRecords.get(this.launchId)].filter((record) => record !== undefined)
+                : getActiveElectronRecords(this.electronHostLaunchRecords);
+        this.keys = this.selectedKeys();
+        this.begin = this.beginRecord();
+    }
+    selectedKeys() {
+        const keys = new Set(this.selected.flatMap((record) => record.sessionName !== undefined && record.sessionName !== ""
+            ? [getAgentBrowserSessionIdentityKey(record.sessionName, record.namespace)]
+            : []));
+        if (this.call.compiledElectron?.action === "probe" &&
+            !(this.launchId !== undefined && this.launchId !== "") &&
+            this.runtime.managed.active) {
+            keys.add(getAgentBrowserSessionIdentityKey(this.runtime.managed.name, this.runtime.managed.namespace));
+        }
+        return keys;
+    }
+    beginRecord() {
+        return {
+            event: {
+                version: 1,
+                phase: "begin",
+                operationId: this.operationId,
+                toolCallId: this.call.toolCallId,
+                commandIndex: this.call.commandIndex ?? 0,
+                isError: true,
+                state: {},
+                pages: [...this.keys].map((key) => ({
+                    key,
+                    refs: { kind: "unknown" },
+                    unknown: true,
+                })),
+            },
+        };
+    }
+    async admit() {
+        if (this.hostAffecting) {
+            try {
+                if (!(await appendBrowserRecord(this.call.ctx.sessionManager, () => appendBrowserTransition(this.runtime.pi, this.begin), this.begin, this.call.branch)) ||
+                    !this.call.branch.isCurrent()) {
+                    throw new Error("The selected Pi branch changed before host-operation admission.");
+                }
+            }
+            catch (error) {
+                return browserExecutionFailure(new Error("Could not persist Electron/browser-state begin; the host operation was not run.", { cause: error }), this.executionSignal);
+            }
+            this.runtime.sessions.pages.applyBrowserRecord(this.begin);
+        }
+        return undefined;
+    }
+    async dispatch() {
+        this.electronHostResult = await handleElectronHostInput({
+            attachedSessionKeys: this.runtime.sessions.attached,
+            compiledElectron: this.call.compiledElectron,
+            cwd: this.call.ctx.cwd,
+            electronChildProcesses: this.runtime.electron.childProcesses,
+            electronLaunchRecords: this.electronHostLaunchRecords,
+            implicitSessionCloseTimeoutMs: this.runtime.implicitSessionCloseTimeoutMs,
+            managedSessionActive: this.runtime.managed.active,
+            managedSessionName: this.runtime.managed.name,
+            managedSessionNamespace: this.runtime.managed.namespace,
+            managedSessionRestoreState: this.runtime.managed.restore,
+            ownedManagedSessions: this.runtime.managed.owned,
+            redactedCompiledElectron: this.call.redactedCompiledElectron,
+            sessionPageState: this.workingPageState,
+            signal: this.executionSignal,
+        });
+    }
+    cleanupRecords() {
+        const details = this.electronHostResult?.details;
+        if (!isRecord(details) || !isRecord(details.electron) || !isRecord(details.electron.cleanup)) {
+            return [];
+        }
+        const rows = details.electron.cleanup.results;
+        return Array.isArray(rows) ? rows : [];
+    }
+    resetManagedSession() {
+        this.runtime.managed.active = false;
+        this.runtime.managed.compatibilityWorkaround = undefined;
+        this.runtime.managed.headedAutosaveDisabled = false;
+        this.runtime.managed.headedAutosaveInterval = undefined;
+        this.runtime.managed.namespace = undefined;
+        this.runtime.managed.freshOrdinal += 1;
+        this.runtime.managed.name = createFreshSessionName(this.runtime.managed.baseName, this.runtime.ephemeralSessionSeed, this.runtime.managed.freshOrdinal);
+    }
+    retireClosedIdentity(identity) {
+        this.runtime.recordings.retire(identity.sessionName, identity.namespace);
+        const key = getSessionContextKey(identity.sessionName, identity.namespace) ?? identity.sessionName;
+        this.runtime.sessions.clear(key);
+        this.workingPageState.clearSession(key);
+        if (key ===
+            (getSessionContextKey(this.runtime.managed.name, this.runtime.managed.namespace) ??
+                this.runtime.managed.name)) {
+            this.resetManagedSession();
+        }
+    }
+    cleanedLaunchIds(records) {
+        const ids = new Set();
+        for (const row of records) {
+            if (isRecord(row) && isElectronLaunchRecord(row.record)) {
+                ids.add(row.record.launchId);
+            }
+        }
+        return ids;
+    }
+    applyCleanup() {
+        const result = this.electronHostResult;
+        if (!result || this.call.compiledElectron?.action !== "cleanup") {
+            return;
+        }
+        this.runtime.branch.advanceState();
+        const records = this.cleanupRecords();
+        const cleanedLaunchIds = this.cleanedLaunchIds(records);
+        this.runtime.electron.replaceActive(this.electronHostLaunchRecords, cleanedLaunchIds);
+        this.runtime.electron.mergeCleanup(records);
+        const namespace = isRecord(result.details) && typeof result.details.namespace === "string"
+            ? result.details.namespace
+            : undefined;
+        const identities = getCleanupResultsClosedManagedSessionIdentities(records, namespace);
+        syncElectronCleanupManagedSessions(this.runtime.managed.owned, records, namespace);
+        for (const identity of identities) {
+            this.retireClosedIdentity(identity);
+        }
+        if (this.runtime.artifacts.manifest && isRecord(result.details)) {
+            result.details.artifactRetentionSummary = formatSessionArtifactRetentionSummary(this.runtime.artifacts.manifest);
+        }
+    }
+    selectedRecordForKey(key) {
+        return this.selected.find((candidate) => candidate.sessionName !== undefined &&
+            candidate.sessionName !== "" &&
+            getAgentBrowserSessionIdentityKey(candidate.sessionName, candidate.namespace) === key);
+    }
+    snapshotChanged(key) {
+        const snapshot = this.workingPageState.get(key).refSnapshot;
+        return (snapshot !== undefined &&
+            snapshot.snapshotId !== this.priorPages.get(key)?.refSnapshot?.snapshotId);
+    }
+    headedAutosaveInterval(key) {
+        const owner = this.runtime.managed.owned.get(key);
+        return (owner?.headedManagedAutosaveInterval ??
+            (owner?.headedManagedAutosaveDisabled === true ? "0" : undefined));
+    }
+    async bindSnapshotGeneration(key) {
+        if (!this.snapshotChanged(key)) {
+            return;
+        }
+        const record = this.selectedRecordForKey(key);
+        const daemon = await inspectManagedSessionDaemon({
+            cwd: this.call.ctx.cwd,
+            sessionName: record?.sessionName ?? this.runtime.managed.name,
+            namespace: record?.namespace ?? this.runtime.managed.namespace,
+            signal: this.executionSignal,
+            includeGeneration: true,
+            headedManagedAutosaveInterval: this.headedAutosaveInterval(key),
+        });
+        this.workingPageState.bindSnapshotGeneration(key, daemon.status === "active" ? daemon.generation : undefined);
+    }
+    buildFinish(result) {
+        const changes = browserPageChanges(this.workingPageState, this.priorPages, [...this.keys]);
+        return {
+            event: {
+                version: 1,
+                phase: this.hostAffecting ? "finish" : "state",
+                operationId: this.operationId,
+                toolCallId: this.call.toolCallId,
+                commandIndex: this.call.commandIndex ?? 0,
+                isError: result.isError === true,
+                state: browserStateEffects(isRecord(result.details) ? result.details : {}),
+                pages: changes.pages,
+                artifacts: artifactChanges(this.priorManifest, this.runtime.artifacts.manifest),
+            },
+            ...(changes.snapshot ? { snapshot: changes.snapshot } : {}),
+        };
+    }
+    persistenceFailure(result, error) {
+        if (this.call.branch.isCurrent()) {
+            this.runtime.sessions.pages.applyBrowserRecord(this.begin);
+        }
+        return {
+            ...browserExecutionFailure(new Error("The host operation finished, but its state could not be persisted. Inspect before retrying; changes may already have happened.", { cause: error }), this.executionSignal),
+            details: {
+                ...(isRecord(result.details) ? result.details : {}),
+                browserStatePersistence: "finish-unconfirmed",
+                resultCategory: "failure",
+                failureCategory: "upstream-error",
+                nextActions: undefined,
+            },
+        };
+    }
+    async persistFinish() {
+        const result = this.electronHostResult;
+        if (!result || !this.hostAffecting || !this.call.branch.isCurrent()) {
+            return undefined;
+        }
+        for (const key of this.keys) {
+            // Bind each ordered host snapshot to its live daemon before persisting one canonical finish.
+            // oxlint-disable-next-line no-await-in-loop
+            await this.bindSnapshotGeneration(key);
+        }
+        const finish = this.buildFinish(result);
+        try {
+            if (!(await appendBrowserRecord(this.call.ctx.sessionManager, () => appendBrowserTransition(this.runtime.pi, finish), finish, this.call.branch)) ||
+                !this.call.branch.isCurrent()) {
+                throw new Error("The selected Pi branch changed before host-state confirmation.");
+            }
+        }
+        catch (error) {
+            return this.persistenceFailure(result, error);
+        }
+        this.runtime.sessions.pages.applyBrowserRecord(finish);
+        this.runtime.artifacts.manifest = applyArtifactChanges(this.runtime.artifacts.manifest, finish.event.artifacts);
+        if (isRecord(result.details)) {
+            result.details.browserEventVersion = 1;
+            result.details.artifactManifest = invocationArtifactManifest(this.runtime.artifacts.manifest, this.priorManifest, result.details);
+        }
+        return undefined;
+    }
+    complete() {
+        if (this.electronHostResult && this.executionSignal?.aborted === true) {
+            const failure = browserExecutionFailure(this.executionSignal.reason, this.executionSignal);
+            return {
+                ...this.electronHostResult,
+                ...failure,
+                details: {
+                    ...(isRecord(this.electronHostResult.details) ? this.electronHostResult.details : {}),
+                    ...(isRecord(failure.details) ? failure.details : {}),
+                },
+            };
+        }
+        return this.electronHostResult;
+    }
+    async run() {
+        const admissionFailure = await this.admit();
+        if (admissionFailure) {
+            return admissionFailure;
+        }
+        await this.dispatch();
+        this.applyCleanup();
+        const failure = await this.persistFinish();
+        if (failure) {
+            return failure;
+        }
+        return this.complete();
+    }
+}
+export function runElectronHostInput(runtime, call, executionSignal = call.signal) {
+    return new ElectronHostTransaction(runtime, call, executionSignal).run();
+}

package/dist/extensions/agent-browser/lib/orchestration/extension-intent-replay.js

@@ -0,0 +1,41 @@
+import { getBrowserRecord } from "../browser-transcript.js";
+class PendingOwnedBrowserIntents {
+    ownerSessionId;
+    begins = new Map();
+    constructor(ownerSessionId) {
+        this.ownerSessionId = ownerSessionId;
+    }
+    clearPage(key) {
+        for (const [id, begin] of this.begins) {
+            if (begin.pages?.some((page) => page.key === key) === true) {
+                this.begins.delete(id);
+            }
+        }
+    }
+    apply(event) {
+        if (event.phase === "begin" &&
+            event.state.ownerSessionId === this.ownerSessionId &&
+            event.state.wrapperManaged === true) {
+            this.begins.set(event.operationId, event);
+        }
+        else if (event.phase === "finish") {
+            this.begins.delete(event.operationId);
+        }
+        for (const page of event.pages ?? []) {
+            if (page.clear) {
+                this.clearPage(page.key);
+            }
+        }
+    }
+}
+/** Interrupted owned intents retain cleanup scope, never proof of a successful launch. */
+export function collectPendingOwnedBrowserIntents(branch, ownerSessionId) {
+    const pending = new PendingOwnedBrowserIntents(ownerSessionId);
+    for (const entry of branch) {
+        const event = getBrowserRecord(entry)?.event;
+        if (event) {
+            pending.apply(event);
+        }
+    }
+    return [...pending.begins.values()];
+}

package/dist/extensions/agent-browser/lib/orchestration/extension-invocation.js

@@ -0,0 +1,7 @@
+export function createBrowserInvocation(input) {
+    return {
+        ...input,
+        nativeToolCallId: input.nativeToolCallId ?? input.toolCallId,
+        modelVisible: input.modelVisible ?? true,
+    };
+}

package/dist/extensions/agent-browser/lib/orchestration/extension-lifecycle.js

@@ -0,0 +1,102 @@
+import { cleanupSecureTempArtifacts } from "../temp.js";
+import { getActiveElectronRecords } from "./browser-run/session-state.js";
+import { cleanupActiveElectronHostLaunches } from "./electron-host/index.js";
+import { loadAgentBrowserConfigSync } from "../config.js";
+import { closeOwnedManagedSessionsExcept } from "./extension-managed-ownership.js";
+import { getCleanupResultsClosedManagedSessionIdentities, getCleanupResultsPreservedUserDataDirs, getOffBranchOwnedElectronLaunchRecords, syncElectronCleanupManagedSessions, } from "./extension-electron-ownership.js";
+import { shouldIncludeProjectConfig } from "./extension-prompt.js";
+import { notifyRecordingPersistence } from "./extension-recording.js";
+import { recoverScriptSessionLeasesWithinQueue } from "./extension-script-leases.js";
+import { restoreBranchBackedState } from "./extension-branch-restore.js";
+class BrowserLifecycle {
+    runtime;
+    constructor(runtime) {
+        this.runtime = runtime;
+    }
+    async restore(ctx, resetRuntimeOwnership) {
+        const { runtime } = this;
+        const branch = await restoreBranchBackedState(runtime, ctx, { resetRuntimeOwnership });
+        if (resetRuntimeOwnership) {
+            runtime.electron.childProcesses = new Map();
+            runtime.prompt.registerWebSearch(loadAgentBrowserConfigSync({
+                cwd: ctx.cwd,
+                includeProjectConfig: shouldIncludeProjectConfig(ctx),
+            }));
+        }
+        await recoverScriptSessionLeasesWithinQueue(runtime, ctx, branch);
+        runtime.recordings.flush();
+        notifyRecordingPersistence(runtime.recordings.dirty, ctx);
+    }
+    start(ctx) {
+        return this.runtime.managedSessionExecutionQueue.run(() => this.runtime.artifacts.queue.run(() => this.restore(ctx, true)));
+    }
+    async tree(ctx) {
+        this.runtime.branch.invalidateRestore();
+        await this.runtime.code.settle();
+        await this.runtime.managedSessionExecutionQueue.run(() => this.runtime.artifacts.queue.run(() => this.restore(ctx, false)));
+    }
+    async cleanup(ctx, quitting) {
+        const { runtime } = this;
+        const active = getActiveElectronRecords(runtime.electron.records);
+        const preserved = quitting
+            ? active
+                .filter((record) => !runtime.electron.ownedRecords.has(record.launchId))
+                .map((record) => record.userDataDir)
+            : active.map((record) => record.userDataDir);
+        const records = quitting
+            ? runtime.electron.ownedRecords
+            : getOffBranchOwnedElectronLaunchRecords(runtime.electron.ownedRecords, runtime.electron.records);
+        const results = await cleanupActiveElectronHostLaunches({
+            attachedSessionKeys: runtime.sessions.attached,
+            cwd: ctx?.cwd ?? runtime.managed.cwd,
+            electronChildProcesses: runtime.electron.childProcesses,
+            electronLaunchRecords: records,
+            managedSessionRestoreState: runtime.managed.restore,
+            ownedManagedSessions: runtime.managed.owned,
+            sessionPageState: runtime.sessions.pages,
+            timeoutMs: runtime.implicitSessionCloseTimeoutMs,
+        });
+        const preservePaths = [
+            ...new Set([...preserved, ...getCleanupResultsPreservedUserDataDirs(results)]),
+        ];
+        syncElectronCleanupManagedSessions(runtime.managed.owned, results);
+        for (const identity of getCleanupResultsClosedManagedSessionIdentities(results)) {
+            runtime.recordings.retire(identity.sessionName, identity.namespace);
+        }
+        await closeOwnedManagedSessionsExcept(runtime.managed.owned, runtime.sessions, {
+            restore: runtime.managed.restore,
+            timeoutMs: runtime.implicitSessionCloseTimeoutMs,
+        }, {
+            keepSessionName: !quitting && runtime.managed.active ? runtime.managed.name : undefined,
+            keepNamespace: !quitting && runtime.managed.active ? runtime.managed.namespace : undefined,
+            onClosed: (owner) => runtime.recordings.retire(owner.sessionName, owner.namespace),
+        });
+        runtime.recordings.flush();
+        notifyRecordingPersistence(runtime.recordings.dirty, ctx);
+        return preservePaths;
+    }
+    reset() {
+        const { runtime } = this;
+        runtime.managed.reset();
+        runtime.sessions.reset();
+        runtime.artifacts.manifest = undefined;
+        runtime.recordings.resetIfClean();
+        runtime.electron.reset();
+    }
+    async shutdown(ctx, quitting) {
+        await this.runtime.code.settle();
+        this.runtime.branch.invalidate();
+        const preservePaths = await this.runtime.managedSessionExecutionQueue.run(() => this.runtime.artifacts.queue.run(() => this.cleanup(ctx, quitting)));
+        this.reset();
+        await cleanupSecureTempArtifacts({ preservePaths });
+    }
+}
+function isQuitting(event) {
+    return event?.reason === "quit";
+}
+export function registerBrowserLifecycle(runtime) {
+    const lifecycle = new BrowserLifecycle(runtime);
+    runtime.pi.on("session_start", (_event, ctx) => lifecycle.start(ctx));
+    runtime.pi.on("session_tree", (_event, ctx) => lifecycle.tree(ctx));
+    runtime.pi.on("session_shutdown", (event, ctx) => lifecycle.shutdown(ctx, isQuitting(event)));
+}

package/dist/extensions/agent-browser/lib/orchestration/extension-managed-ownership.js

@@ -0,0 +1,133 @@
+import { isRecord } from "../parsing.js";
+import { closeManagedSession } from "./browser-run/managed-session-daemon-policy.js";
+import { getActiveElectronRecords, getSessionContextKey } from "./browser-run/session-state.js";
+function inheritedLaunchSettings(existing, options) {
+    return {
+        compatibilityWorkaround: Object.hasOwn(options, "compatibilityWorkaround")
+            ? options.compatibilityWorkaround
+            : existing?.compatibilityWorkaround,
+        headedManagedAutosaveDisabled: options.headedManagedAutosaveDisabled ?? existing?.headedManagedAutosaveDisabled,
+        headedManagedAutosaveInterval: options.headedManagedAutosaveInterval ?? existing?.headedManagedAutosaveInterval,
+        socketDir: options.socketDir ?? existing?.socketDir,
+    };
+}
+export function trackOwnedManagedSession(sessions, sessionName, cwd, options = {}) {
+    if (sessionName === undefined || sessionName === "") {
+        return;
+    }
+    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,
+        ...inheritedLaunchSettings(existing, options),
+        cwd,
+        namespace: options.namespace,
+        sessionName,
+    });
+}
+export function untrackOwnedManagedSession(sessions, sessionName, namespace) {
+    if (sessionName === undefined || sessionName === "") {
+        return;
+    }
+    sessions.delete(sessionName.includes("\u0000")
+        ? sessionName
+        : (getSessionContextKey(sessionName, namespace) ?? sessionName));
+}
+export function untrackOwnedManagedSessionFromBranchClose(sessions, sessionName, activeBranchRank, closeBranchRank) {
+    if (sessionName === undefined || sessionName === "" || closeBranchRank === undefined) {
+        return;
+    }
+    const owner = sessions.get(sessionName);
+    if (owner?.branchOwned !== true) {
+        return;
+    }
+    if (activeBranchRank !== undefined && closeBranchRank <= activeBranchRank) {
+        return;
+    }
+    sessions.delete(sessionName);
+}
+function getOutcomeLaunchSettings(details) {
+    return {
+        compatibilityWorkaround: getRecognizedCompatibilityWorkaround(details.compatibilityWorkaround),
+        headedManagedAutosaveDisabled: details.managedSessionHeadedAutosaveDisabled === true,
+        headedManagedAutosaveInterval: typeof details.managedSessionHeadedAutosaveInterval === "string"
+            ? details.managedSessionHeadedAutosaveInterval
+            : undefined,
+        namespace: typeof details.namespace === "string" ? details.namespace : undefined,
+        socketDir: typeof details.managedSessionSocketDir === "string"
+            ? details.managedSessionSocketDir
+            : undefined,
+    };
+}
+function outcomeCreatesOwner(outcome) {
+    return (outcome.activeAfter === true &&
+        (outcome.status === "created" ||
+            outcome.status === "replaced" ||
+            outcome.status === "unchanged"));
+}
+function retireOutcomeOwner(sessions, outcome, details, current) {
+    if (outcome.succeeded !== true || outcome.status !== "closed") {
+        return;
+    }
+    const attempted = typeof outcome.attemptedSessionName === "string" ? outcome.attemptedSessionName : undefined;
+    const namespace = typeof details.namespace === "string" ? details.namespace : undefined;
+    untrackOwnedManagedSession(sessions, attempted ?? current, namespace);
+}
+export function syncOwnedManagedSessionsFromResult(sessions, result, cwd) {
+    const details = isRecord(result.details) ? result.details : undefined;
+    if (!details || !isRecord(details.managedSessionOutcome)) {
+        return;
+    }
+    const outcome = details.managedSessionOutcome;
+    const current = typeof outcome.currentSessionName === "string" ? outcome.currentSessionName : undefined;
+    if (outcomeCreatesOwner(outcome)) {
+        trackOwnedManagedSession(sessions, current, cwd, getOutcomeLaunchSettings(details));
+    }
+    retireOutcomeOwner(sessions, outcome, details, current);
+}
+export async function closeOwnedManagedSessionsExcept(sessions, pages, settings, options) {
+    const keepKey = getSessionContextKey(options.keepSessionName, options.keepNamespace);
+    // Snapshot ownership before awaiting: callbacks may add owners during shutdown cleanup.
+    const owners = Array.from(sessions);
+    for (const [key, owner] of owners) {
+        if (key === keepKey) {
+            continue;
+        }
+        // Session close and its durable cleanup callback must finish before the next owner is retired.
+        // oxlint-disable-next-line no-await-in-loop
+        const error = await closeManagedSession({
+            confirmActions: pages.getConfirmActions(key) ?? process.env.AGENT_BROWSER_CONFIRM_ACTIONS,
+            cwd: owner.cwd,
+            headedManagedAutosaveInterval: owner.headedManagedAutosaveInterval,
+            namespace: owner.namespace,
+            preserveAttachedBrowserSession: pages.hasAttachment(key),
+            restoreState: settings.restore,
+            sessionName: owner.sessionName,
+            socketDir: owner.socketDir,
+            timeoutMs: settings.timeoutMs,
+        });
+        if (error === undefined || error === "") {
+            sessions.delete(key);
+            options.onClosed?.(owner);
+        }
+    }
+}
+export function shouldSerializeBrowserCommand(sessions, electronRecords, options) {
+    const session = options.explicitSessionName;
+    if (session === undefined || session === "" || session === options.managedSessionName) {
+        return true;
+    }
+    if (sessions.has(getSessionContextKey(session, options.namespace) ?? session)) {
+        return true;
+    }
+    return getActiveElectronRecords(electronRecords).some((record) => record.sessionName === session);
+}
+export function getRecognizedCompatibilityWorkaround(value) {
+    const workaround = isRecord(value) ? value : undefined;
+    return (workaround?.id === "chatgpt-headless-user-agent" ||
+        workaround?.id === "cloudflare-headless-user-agent") &&
+        typeof workaround.reason === "string"
+        ? { id: workaround.id, reason: workaround.reason }
+        : undefined;
+}