pi-agent-browser-native 0.9.3 → 0.9.5

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

@@ -0,0 +1,303 @@
+import { format } from "node:util";
+import { extractUpstreamCommandTokens, isPlainTextInspectionArgs } from "../runtime.js";
+import { extractExplicitSessionName, resolveAgentBrowserNamespace, scanUpstreamGlobalFlagOccurrences, } from "../argv-grammar.js";
+import { parseArgvDescriptor } from "../argv-descriptor.js";
+import { needsManagedSession } from "../command-policy.js";
+import { isRecord } from "../parsing.js";
+import { getAgentBrowserProcessTimeoutMs } from "../process.js";
+import { getCommandAwareProcessTimeoutMs } from "./browser-run/prepare/wait-timeouts.js";
+import { getAgentBrowserProcessEnvironment } from "../process-environment.js";
+import { withNativeSessionDefaults } from "./native-session-defaults.js";
+import { getBrowserCwdError, resolveExecutionCwd } from "../execution-cwd.js";
+import { resolveOperationPaths } from "./operation-paths.js";
+import { isCloseCommand } from "../command-taxonomy.js";
+import { getSessionContextKey } from "./browser-run/session-state.js";
+import { buildValidationFailureResult, resolveAgentBrowserInput, } from "./input-plan.js";
+import { applyAgentBrowserOutputPath } from "./output-file.js";
+import { loadAgentBrowserConfigSync } from "../config.js";
+import { scopeReadConfirmationArgs } from "../read-confirmation.js";
+import { getArtifactPreflightValidationError, commandClosesAllSessions, } from "./extension-artifact-preflight.js";
+import { browserExecutionFailure } from "./extension-result-state.js";
+import { shouldSerializeBrowserCommand } from "./extension-managed-ownership.js";
+import { shouldSerializeElectronHostInput } from "./extension-electron-ownership.js";
+import { shouldIncludeProjectConfig } from "./extension-prompt.js";
+import { validateUpstreamVersion } from "./extension-version-check.js";
+import { applyUnserializedOutputPath } from "./extension-command-output.js";
+import { runCoordinatedElectronHostInput } from "./extension-host-coordination.js";
+import { runWithinSessionQueue } from "./extension-execution-queue.js";
+function validationFailure(input, validationError) {
+    return buildValidationFailureResult({
+        ...input,
+        attemptedKind: input.kind,
+        kind: "invalid",
+        status: "invalid",
+        validationError,
+    });
+}
+// tool_call hooks can mutate input before the canonical input planner validates it.
+function requestedOutputPath(params) {
+    return isRecord(params) && typeof params.outputPath === "string" ? params.outputPath : undefined;
+}
+function operationTimeout(call, input) {
+    const electronTimeout = input.kind === "electron" && "timeoutMs" in input.compiledElectron
+        ? input.compiledElectron.timeoutMs
+        : undefined;
+    return (electronTimeout ??
+        call.params.timeoutMs ??
+        getCommandAwareProcessTimeoutMs(extractUpstreamCommandTokens(input.toolArgs), input.toolStdin) ??
+        getAgentBrowserProcessTimeoutMs());
+}
+class BrowserAdmission {
+    runtime;
+    invocation;
+    constructor(runtime, invocation) {
+        this.runtime = runtime;
+        this.invocation = invocation;
+    }
+    admit() {
+        const { runtime, invocation } = this;
+        const branch = invocation.selectedBranch ?? runtime.branch.capture(invocation.ctx);
+        let operationCwd;
+        try {
+            operationCwd = invocation.capturedCwd ?? resolveExecutionCwd(runtime.pi, invocation.ctx);
+        }
+        catch (error) {
+            return {
+                failure: buildValidationFailureResult({
+                    kind: "invalid",
+                    status: "invalid",
+                    redactedArgs: [],
+                    toolArgs: [],
+                    validationError: error instanceof Error ? error.message : format("%s", error),
+                }),
+            };
+        }
+        return this.validateInvocation(branch, operationCwd);
+    }
+    validateInvocation(branch, operationCwd) {
+        const { runtime, invocation } = this;
+        const promptPolicy = runtime.prompt.policy(invocation.ctx);
+        const outputPath = requestedOutputPath(invocation.params);
+        const input = resolveAgentBrowserInput({
+            getBatchPreflightValidationError: (args, stdin) => getArtifactPreflightValidationError({ args, cwd: operationCwd, outputPath, stdin }),
+            params: invocation.params,
+        });
+        if (input.status === "invalid") {
+            return { failure: buildValidationFailureResult(input) };
+        }
+        const replayError = this.replayFailure(input);
+        if (replayError) {
+            return { failure: replayError };
+        }
+        const explicitConfig = scanUpstreamGlobalFlagOccurrences(input.toolArgs, "--config").length > 0 ||
+            getAgentBrowserProcessEnvironment().AGENT_BROWSER_CONFIG !== undefined;
+        const session = extractExplicitSessionName(input.toolArgs);
+        const managedAtAdmission = input.kind !== "electron" && (session === undefined || session === "") && !explicitConfig;
+        return {
+            call: {
+                ...invocation,
+                branch,
+                operationCwd,
+                promptPolicy,
+                outputPath,
+                admittedInput: input,
+                explicitConfig,
+                managedAtAdmission,
+            },
+        };
+    }
+    replayFailure(input) {
+        const error = this.runtime.branch.replayError;
+        if (error === undefined || error === "" || isPlainTextInspectionArgs(input.toolArgs)) {
+            return undefined;
+        }
+        return browserExecutionFailure(new Error(error), this.invocation.signal, "validation-error");
+    }
+    selectBrowserCwd(call) {
+        const session = extractExplicitSessionName(call.admittedInput.toolArgs);
+        if (call.explicitConfig) {
+            return call.operationCwd;
+        }
+        if (session !== undefined && session !== "") {
+            const namespace = resolveAgentBrowserNamespace(call.admittedInput.toolArgs, getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE);
+            return (this.runtime.managed.owned.get(getSessionContextKey(session, namespace) ?? session)?.cwd ??
+                call.ctx.cwd);
+        }
+        if (call.params.sessionMode === "fresh") {
+            return call.operationCwd;
+        }
+        return this.runtime.managed.active ? this.runtime.managed.cwd : call.ctx.cwd;
+    }
+    prepare(call) {
+        const browserCwd = this.selectBrowserCwd(call);
+        const input = call.admittedInput;
+        const error = input.kind === "electron" ? undefined : getBrowserCwdError(browserCwd);
+        if (error !== undefined && error !== "") {
+            return { failure: validationFailure(input, error) };
+        }
+        const resolvedInput = this.bindOperationPaths(call, browserCwd);
+        return {
+            call: {
+                ...call,
+                browserCwd,
+                resolvedInput,
+                executionTimeoutMs: operationTimeout(call, resolvedInput),
+            },
+        };
+    }
+    bindOperationPaths(call, browserCwd) {
+        const input = call.admittedInput;
+        if (isPlainTextInspectionArgs(input.toolArgs) ||
+            (call.operationCwd === browserCwd && call.operationCwd === call.ctx.cwd)) {
+            return input;
+        }
+        const bound = resolveOperationPaths(input.toolArgs, input.toolStdin, call.operationCwd);
+        return { ...input, toolArgs: bound.args, toolStdin: bound.stdin };
+    }
+    canSelectNativeRoot(call) {
+        if (this.runtime.managed.active ||
+            this.runtime.managed.freshOrdinal > 0 ||
+            call.params.sessionMode === "fresh") {
+            return false;
+        }
+        return (this.runtime.sessions.pages.findReadConfirmation([...call.resolvedInput.toolArgs], resolveAgentBrowserNamespace(call.resolvedInput.toolArgs, getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE), call.resolvedInput.toolStdin) === undefined);
+    }
+    nativeRoot(call, config) {
+        if (!this.canSelectNativeRoot(call)) {
+            return undefined;
+        }
+        const root = process.env.PI_SUBAGENT_ROOT_SESSION_ID;
+        const id = process.env.PI_SUBAGENT_CHILD === "1" && root !== undefined && root !== ""
+            ? root
+            : call.ctx.sessionManager.getSessionId();
+        const profile = config.trustedBrowserDefaultProfile;
+        return {
+            id,
+            profile: profile?.policy === "always" && !/[\\/~]/.test(profile.name) ? profile.name : undefined,
+            executablePath: config.trustedBrowserExecutablePath,
+        };
+    }
+    async executeAdmitted(admitted) {
+        const prepared = this.prepare(admitted);
+        if ("failure" in prepared) {
+            return prepared.failure;
+        }
+        const { call } = prepared;
+        await this.runtime.beforeExecute?.(call.nativeToolCallId, { ...call.ctx, signal: call.signal });
+        const config = loadAgentBrowserConfigSync({
+            cwd: call.ctx.cwd,
+            includeProjectConfig: shouldIncludeProjectConfig(call.ctx),
+        });
+        return withNativeSessionDefaults(call.resolvedInput, { cwd: call.browserCwd, signal: call.signal, root: this.nativeRoot(call, config) }, (input, defaults) => this.executeNative(call, input, defaults));
+    }
+    prepareNative(call, input, defaults) {
+        const readConfirmation = this.runtime.sessions.pages.findReadConfirmation([...input.toolArgs], resolveAgentBrowserNamespace(input.toolArgs, getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE), input.toolStdin);
+        const resolvedInput = readConfirmation
+            ? { ...input, toolArgs: scopeReadConfirmationArgs(input.toolArgs, readConfirmation) }
+            : input;
+        const qaFailure = this.attachedQaFailure(resolvedInput);
+        if (qaFailure) {
+            return { failure: qaFailure };
+        }
+        return {
+            call: {
+                ...call,
+                resolvedInput,
+                readConfirmation,
+                withLaunchDefaults: defaults,
+                toolArgs: resolvedInput.toolArgs,
+                compiledElectron: resolvedInput.kind === "electron" ? resolvedInput.compiledElectron : undefined,
+                redactedCompiledElectron: resolvedInput.kind === "electron" ? resolvedInput.redactedCompiledElectron : undefined,
+            },
+        };
+    }
+    attachedQaFailure(input) {
+        if (input.kind !== "qa" ||
+            !input.compiledQaPreset.checks.attached ||
+            this.runtime.managed.active) {
+            return undefined;
+        }
+        const session = extractExplicitSessionName(input.toolArgs);
+        if (session !== undefined && session !== "") {
+            return undefined;
+        }
+        return validationFailure(input, "qa.attached requires an active attached session. Run electron.launch or connect to an Electron debug port first, or configure a native shared session.");
+    }
+    needsVersionCheck(call) {
+        if (call.compiledElectron &&
+            ["cleanup", "list", "status"].includes(call.compiledElectron.action)) {
+            return false;
+        }
+        if (call.readConfirmation?.capabilities?.readRequiresConfirmation === true) {
+            return false;
+        }
+        if (!needsManagedSession(parseArgvDescriptor(call.toolArgs), call.resolvedInput.toolStdin)) {
+            return false;
+        }
+        return (!isPlainTextInspectionArgs(call.toolArgs) &&
+            !isCloseCommand(extractUpstreamCommandTokens(call.toolArgs)[0]) &&
+            call.signal?.aborted !== true);
+    }
+    coordinate(call) {
+        const explicitSessionName = extractExplicitSessionName(call.toolArgs);
+        const namespace = explicitSessionName !== undefined && explicitSessionName !== ""
+            ? resolveAgentBrowserNamespace(call.toolArgs, getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE)
+            : undefined;
+        const serializeBrowserCommand = shouldSerializeBrowserCommand(this.runtime.managed.owned, this.runtime.electron.ownedRecords, {
+            namespace,
+            explicitSessionName,
+            managedSessionName: this.runtime.managed.name,
+        });
+        const callerOwnedSessionQueueKey = !serializeBrowserCommand && explicitSessionName !== undefined && explicitSessionName !== ""
+            ? (getSessionContextKey(explicitSessionName, namespace) ?? explicitSessionName)
+            : undefined;
+        return {
+            ...call,
+            explicitSessionName,
+            callerOwnedSessionNamespace: namespace,
+            serializeBrowserCommand,
+            callerOwnedSessionQueueKey,
+            closesAllSessions: commandClosesAllSessions(call.toolArgs, call.resolvedInput.toolStdin),
+        };
+    }
+    async executeNative(prepared, input, defaults) {
+        const admitted = this.prepareNative(prepared, input, defaults);
+        if ("failure" in admitted) {
+            return admitted.failure;
+        }
+        const { call } = admitted;
+        if (this.needsVersionCheck(call)) {
+            const failure = await validateUpstreamVersion(this.runtime.validatedUpstreamPathKeys, call.browserCwd, call.signal);
+            if (failure) {
+                return applyAgentBrowserOutputPath({
+                    cwd: call.operationCwd,
+                    outputPath: call.outputPath,
+                    result: failure,
+                });
+            }
+        }
+        const runHost = () => runCoordinatedElectronHostInput(this.runtime, call);
+        const hostResult = await (shouldSerializeElectronHostInput(call.compiledElectron)
+            ? this.runtime.managedSessionExecutionQueue.run(runHost, call.signal)
+            : runHost());
+        if (hostResult) {
+            return call.compiledElectron?.action === "cleanup"
+                ? hostResult
+                : applyUnserializedOutputPath(this.runtime, call, hostResult);
+        }
+        return runWithinSessionQueue(this.runtime, this.coordinate(call));
+    }
+    async run() {
+        const admitted = this.admit();
+        if ("failure" in admitted) {
+            return admitted.failure;
+        }
+        const { call } = admitted;
+        return call.managedAtAdmission
+            ? this.runtime.managedSessionExecutionQueue.run(() => this.executeAdmitted(call), call.signal)
+            : this.executeAdmitted(call);
+    }
+}
+export function executeBrowserInvocation(runtime, invocation) {
+    return new BrowserAdmission(runtime, invocation).run();
+}

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

@@ -0,0 +1,36 @@
+import { buildValidationFailureResult } from "./input-plan.js";
+import { applyAgentBrowserOutputPath, canWriteAgentBrowserOutput } from "./output-file.js";
+import { getArtifactPreflightValidationError } from "./extension-artifact-preflight.js";
+import { warnRecordingPersistence, } from "./extension-recording.js";
+export async function applyUnserializedOutputPath(resources, call, result, preserveTextContent = false) {
+    if (!(call.outputPath !== undefined && call.outputPath !== "") ||
+        !canWriteAgentBrowserOutput(result)) {
+        return warnRecordingPersistence(resources.recordings.dirty, result);
+    }
+    return resources.artifacts.queue.run(async () => {
+        resources.recordings.flush();
+        const reservationError = getArtifactPreflightValidationError({
+            activeRecordingReservations: [...resources.recordings.active.values()],
+            args: [],
+            cwd: call.operationCwd,
+            outputPath: call.outputPath,
+        });
+        if (reservationError !== undefined && reservationError !== "") {
+            return warnRecordingPersistence(resources.recordings.dirty, buildValidationFailureResult({
+                attemptedKind: call.resolvedInput.kind,
+                kind: "invalid",
+                redactedArgs: call.resolvedInput.redactedArgs,
+                status: "invalid",
+                toolArgs: call.resolvedInput.toolArgs,
+                toolStdin: call.resolvedInput.toolStdin,
+                validationError: reservationError,
+            }));
+        }
+        return applyAgentBrowserOutputPath({
+            cwd: call.operationCwd,
+            outputPath: call.outputPath,
+            preserveTextContent,
+            result: warnRecordingPersistence(resources.recordings.dirty, result),
+        });
+    });
+}

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

@@ -0,0 +1,335 @@
+import { getSuccessfulBatchCloseLifecycle } from "../batch-lifecycle.js";
+import { appendBrowserTransition, applyArtifactChanges, artifactChanges, browserStateEffects, } from "../browser-transcript.js";
+import { appendBrowserRecord, hasPublishedBrowserJournal } from "../browser-journal.js";
+import { extractUpstreamCommandTokens } from "../runtime.js";
+import { isBooleanFlagEnabled, deleteIdentityKeysInNamespace, extractExplicitSessionName, getAgentBrowserSessionIdentityKey, isAgentBrowserSessionIdentityKeyInNamespace, } from "../argv-grammar.js";
+import { isRecord } from "../parsing.js";
+import { mergeBrowserRunArtifactManifest } from "./browser-run/artifact-merge.js";
+import { isCloseCommand } from "../command-taxonomy.js";
+import { getSessionContextKey } from "./browser-run/session-state.js";
+import { applyAgentBrowserOutputPath } from "./output-file.js";
+import { formatSessionArtifactRetentionSummary } from "../results/artifact-manifest.js";
+import { isSuccessfulNativeConfirmedClose } from "../read-confirmation.js";
+import { getArtifactCommandSteps } from "./extension-artifact-preflight.js";
+import { browserExecutionFailure, invocationArtifactManifest, browserPageChanges, } from "./extension-result-state.js";
+import { untrackOwnedManagedSession, syncOwnedManagedSessionsFromResult, } from "./extension-managed-ownership.js";
+import { getTouchedElectronLaunchIds } from "./extension-electron-ownership.js";
+import { warnRecordingPersistence, appendActiveRecordingCleanupAction, } from "./extension-recording.js";
+export class BrowserCommandResult {
+    runtime;
+    call;
+    prepared;
+    dispatch;
+    result;
+    branchRestoreStillCurrent;
+    resultDetails;
+    resultSessionName;
+    resultNamespace;
+    constructor(runtime, call, prepared, dispatch) {
+        this.runtime = runtime;
+        this.call = call;
+        this.prepared = prepared;
+        this.dispatch = dispatch;
+        this.result = dispatch.result;
+        this.branchRestoreStillCurrent = call.branch.isCurrent();
+        this.resultDetails = isRecord(this.result.details) ? this.result.details : undefined;
+        this.resultSessionName =
+            typeof this.resultDetails?.sessionName === "string"
+                ? this.resultDetails.sessionName
+                : extractExplicitSessionName(call.toolArgs);
+        this.resultNamespace =
+            typeof this.resultDetails?.namespace === "string"
+                ? this.resultDetails.namespace
+                : prepared.selectedPlan.namespace;
+    }
+    reconcileNativeIdentity() {
+        const { prepared } = this;
+        if (prepared.browserRunState.confirmationPolicyMayBeEstablished === false) {
+            prepared.workingPageState.setConfirmActions(prepared.selectedKey, prepared.priorPages.get(prepared.selectedKey)?.confirmActions);
+        }
+        this.annotateManagedIdentity();
+    }
+    resultMatchesManagedIdentity() {
+        const details = this.resultDetails;
+        if (!details ||
+            typeof details.sessionName !== "string" ||
+            !this.prepared.browserRunState.managedSessionActive) {
+            return false;
+        }
+        return (getAgentBrowserSessionIdentityKey(details.sessionName, typeof details.namespace === "string" ? details.namespace : undefined) ===
+            getAgentBrowserSessionIdentityKey(this.prepared.browserRunState.managedSessionName, this.prepared.browserRunState.managedSessionNamespace));
+    }
+    annotateManagedIdentity() {
+        if (this.resultDetails && this.prepared.begin.event.state.wrapperManaged === true) {
+            this.resultDetails.managedSessionSocketDir =
+                this.prepared.begin.event.state.managedSessionSocketDir;
+        }
+        if (this.resultDetails && this.resultMatchesManagedIdentity()) {
+            this.resultDetails.managedSessionCwd = this.prepared.browserRunState.managedSessionCwd;
+        }
+    }
+    attachmentRemainsActive() {
+        const outcome = isRecord(this.resultDetails?.managedSessionOutcome)
+            ? this.resultDetails.managedSessionOutcome
+            : undefined;
+        return (this.result.isError !== true ||
+            ((this.dispatch.attachedSessionRequested || this.dispatch.attachedSessionKnown) &&
+                outcome?.activeAfter === true));
+    }
+    closesAttachment() {
+        const tokens = extractUpstreamCommandTokens(this.call.toolArgs);
+        return ((this.result.isError !== true &&
+            (isCloseCommand(tokens[0]) ||
+                isSuccessfulNativeConfirmedClose(tokens, this.resultDetails?.data))) ||
+            getSuccessfulBatchCloseLifecycle(this.resultDetails?.batchSteps)?.endsClosed === true);
+    }
+    retainAttachment(key) {
+        this.runtime.sessions.attached.add(key);
+        this.result = {
+            ...this.result,
+            details: { ...this.resultDetails, attachedBrowserSession: true },
+        };
+    }
+    shouldRetainAttachment() {
+        return (this.attachmentRemainsActive() &&
+            (this.dispatch.attachedSessionRequested || this.dispatch.attachedSessionKnown));
+    }
+    retainAfterCloseAll(key) {
+        if (this.shouldRetainAttachment() &&
+            getSuccessfulBatchCloseLifecycle(this.resultDetails?.batchSteps)?.endsClosed === false) {
+            this.retainAttachment(key);
+        }
+    }
+    reconcileAttachments() {
+        if (!this.branchRestoreStillCurrent) {
+            return;
+        }
+        const closeAll = this.resultDetails?.closeAllApplied === true;
+        if (closeAll) {
+            deleteIdentityKeysInNamespace(this.runtime.sessions.attached, this.resultNamespace);
+        }
+        const key = getSessionContextKey(this.resultSessionName, this.resultNamespace) ?? this.resultSessionName;
+        if (key === undefined || key === "") {
+            return;
+        }
+        if (closeAll) {
+            this.retainAfterCloseAll(key);
+            return;
+        }
+        if (this.closesAttachment()) {
+            this.runtime.sessions.attached.delete(key);
+        }
+        else if (this.shouldRetainAttachment()) {
+            this.retainAttachment(key);
+        }
+    }
+    mergeRoutes() {
+        const updated = this.prepared.browserRunState.networkRoutesBySession;
+        const initial = this.dispatch.initialNetworkRoutesBySession;
+        if (updated === initial) {
+            return;
+        }
+        const merged = new Map(this.runtime.sessions.routes);
+        for (const [key, value] of updated) {
+            if (!initial.has(key) || initial.get(key) !== value) {
+                merged.set(key, value);
+            }
+        }
+        for (const key of initial.keys()) {
+            if (!updated.has(key)) {
+                merged.delete(key);
+            }
+        }
+        this.runtime.sessions.routes = merged;
+    }
+    retireClosedRecordings() {
+        const handled = this.runtime.recordings.syncResult(this.result);
+        if (this.resultDetails?.closeAllApplied === true) {
+            // Snapshot reservations because retiring an identity deletes from the live index.
+            for (const [key, reservation] of Array.from(this.runtime.recordings.active)) {
+                if (isAgentBrowserSessionIdentityKeyInNamespace(key, this.resultNamespace)) {
+                    this.runtime.recordings.retire(reservation.sessionName, reservation.namespace);
+                }
+            }
+        }
+        for (const key of this.prepared.browserRunState.closedManagedSessionNames) {
+            if (handled.has(key)) {
+                continue;
+            }
+            const reservation = this.runtime.recordings.active.get(key);
+            if (reservation) {
+                this.runtime.recordings.retire(reservation.sessionName, reservation.namespace);
+            }
+        }
+    }
+    appendRecordingCleanup() {
+        if (this.resultSessionName === undefined || this.resultSessionName === "") {
+            return;
+        }
+        const reservation = this.runtime.recordings.active.get(getAgentBrowserSessionIdentityKey(this.resultSessionName, this.resultNamespace));
+        if (reservation) {
+            this.result = appendActiveRecordingCleanupAction(this.result, reservation);
+        }
+    }
+    mergeResultArtifacts() {
+        if (!this.branchRestoreStillCurrent) {
+            return;
+        }
+        this.mergeRoutes();
+        this.runtime.artifacts.manifest = mergeBrowserRunArtifactManifest(this.runtime.artifacts.manifest, this.dispatch.initialArtifactManifest, this.prepared.browserRunState.artifactManifest);
+        this.retireClosedRecordings();
+        this.appendRecordingCleanup();
+        if (this.runtime.artifacts.manifest && isRecord(this.result.details)) {
+            this.result.details.artifactRetentionSummary = formatSessionArtifactRetentionSummary(this.runtime.artifacts.manifest);
+        }
+    }
+    adoptRuntime() {
+        const branchStateStillCurrent = this.prepared.generationAtStart === this.runtime.branch.stateGeneration &&
+            this.call.branch.isCurrent();
+        if (this.call.serializeBrowserCommand || branchStateStillCurrent) {
+            this.runtime.managed.freshOrdinal = Math.max(this.runtime.managed.freshOrdinal, this.prepared.browserRunState.freshSessionOrdinal);
+            this.runtime.managed.active = this.prepared.browserRunState.managedSessionActive;
+            this.runtime.managed.compatibilityWorkaround =
+                this.prepared.browserRunState.managedSessionCompatibilityWorkaround;
+            this.runtime.managed.headedAutosaveDisabled =
+                this.prepared.browserRunState.managedSessionHeadedAutosaveDisabled === true;
+            this.runtime.managed.headedAutosaveInterval =
+                this.prepared.browserRunState.managedSessionHeadedAutosaveInterval;
+            this.runtime.managed.cwd = this.prepared.browserRunState.managedSessionCwd;
+            this.runtime.managed.name = this.prepared.browserRunState.managedSessionName;
+            this.runtime.managed.namespace = this.prepared.browserRunState.managedSessionNamespace;
+            for (const closedSessionName of this.prepared.browserRunState.closedManagedSessionNames) {
+                untrackOwnedManagedSession(this.runtime.managed.owned, closedSessionName);
+            }
+            syncOwnedManagedSessionsFromResult(this.runtime.managed.owned, this.result, this.prepared.browserRunState.managedSessionCwd);
+            this.runtime.electron.mergeActive(this.runtime.electron.records, {
+                ownerSessionId: this.call.ctx.sessionManager.getSessionId(),
+                touchedLaunchIds: !(this.result.isError === true)
+                    ? getTouchedElectronLaunchIds(this.call.explicitSessionName ?? this.prepared.browserRunState.managedSessionName, this.runtime.electron.records, this.resultNamespace)
+                    : undefined,
+            });
+            if (this.call.serializeBrowserCommand) {
+                this.runtime.branch.advanceState();
+            }
+        }
+    }
+    finishState() {
+        return {
+            ...browserStateEffects(isRecord(this.result.details) ? this.result.details : {}),
+            ...this.prepared.browserRunState.observedBrowserEffects,
+            ownerSessionId: this.call.ctx.sessionManager.getSessionId(),
+            ...(this.prepared.begin.event.state.wrapperManaged === true
+                ? {
+                    managedSessionDaemon: this.runtime.managed.restore.getDaemonReceipt(this.resultSessionName, this.resultNamespace),
+                }
+                : {}),
+        };
+    }
+    needsFinish(pagesChanged, artifactsChanged) {
+        return (this.prepared.browserAffecting ||
+            pagesChanged ||
+            (artifactsChanged && hasPublishedBrowserJournal(this.call.ctx.sessionManager)) ||
+            this.resultDetails?.readConfirmation !== undefined ||
+            this.prepared.browserRunState.observedBrowserEffects?.readConfirmation !== undefined);
+    }
+    buildFinish() {
+        if (this.prepared.selectedPlan.plainTextInspection || !this.branchRestoreStillCurrent) {
+            return undefined;
+        }
+        const changes = browserPageChanges(this.prepared.workingPageState, this.prepared.priorPages, [
+            ...this.prepared.browserRunState.closedManagedSessionNames,
+            ...(this.prepared.browserAffecting ? [this.prepared.selectedKey] : []),
+        ]);
+        const artifacts = artifactChanges(this.dispatch.initialArtifactManifest, this.runtime.artifacts.manifest);
+        const requiresFinish = this.needsFinish(changes.pages.length > 0, artifacts !== undefined);
+        if (!requiresFinish) {
+            return undefined;
+        }
+        return {
+            event: {
+                version: 1,
+                phase: this.prepared.browserAffecting ? "finish" : "state",
+                operationId: this.prepared.operationId,
+                toolCallId: this.call.toolCallId,
+                commandIndex: this.call.commandIndex ?? 0,
+                isError: this.result.isError === true,
+                state: this.finishState(),
+                pages: changes.pages,
+                artifacts,
+            },
+            ...(changes.snapshot ? { snapshot: changes.snapshot } : {}),
+        };
+    }
+    persistenceFailure(error) {
+        return {
+            ...this.result,
+            ...browserExecutionFailure(new Error("The browser command finished, but its state could not be persisted. Changes may already have happened; inspect the current page before retrying.", { cause: error }), this.prepared.executionSignal),
+            details: {
+                ...(isRecord(this.result.details) ? this.result.details : {}),
+                resultCategory: "failure",
+                failureCategory: "upstream-error",
+                browserStatePersistence: "finish-unconfirmed",
+                nextActions: [
+                    {
+                        id: "inspect-after-browser-state-persistence-failure",
+                        tool: "agent_browser",
+                        params: {
+                            args: [
+                                "--session",
+                                this.prepared.selectedPlan.sessionName ?? "default",
+                                "--namespace",
+                                this.prepared.selectedPlan.namespace ?? "",
+                                "batch",
+                                "--bail",
+                            ],
+                            stdin: JSON.stringify([
+                                ["get", "url"],
+                                ["snapshot", "-i"],
+                            ]),
+                        },
+                        reason: "The effect may already have happened. Verify the current URL and inspect before deciding whether to retry.",
+                        safety: "Read-only inspection; no mutation is replayed.",
+                    },
+                ],
+            },
+        };
+    }
+    async persistFinish() {
+        const finish = this.buildFinish();
+        if (!finish) {
+            return undefined;
+        }
+        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 browser-state confirmation.");
+            }
+        }
+        catch (error) {
+            return this.persistenceFailure(error);
+        }
+        this.runtime.sessions.pages.applyBrowserRecord(finish);
+        this.runtime.artifacts.manifest = applyArtifactChanges(this.runtime.artifacts.manifest, finish.event.artifacts);
+        return undefined;
+    }
+    async complete() {
+        if (isRecord(this.result.details)) {
+            this.result.details.browserEventVersion = 1;
+            if (!(this.call.compiledElectron?.action === "launch" &&
+                this.call.compiledElectron.handoff === "snapshot") &&
+                !getArtifactCommandSteps(this.call.toolArgs, this.call.resolvedInput.toolStdin).steps.some((step) => step[0] === "snapshot")) {
+                delete this.result.details.refSnapshot;
+            }
+            this.result.details.artifactManifest = invocationArtifactManifest(this.call.branch.isCurrent()
+                ? this.runtime.artifacts.manifest
+                : this.prepared.browserRunState.artifactManifest, this.dispatch.initialArtifactManifest, this.result.details);
+        }
+        return applyAgentBrowserOutputPath({
+            cwd: this.call.operationCwd,
+            outputPath: this.call.outputPath,
+            preserveTextContent: Array.isArray(this.call.params.args) &&
+                isBooleanFlagEnabled(this.call.params.args, "--json"),
+            result: warnRecordingPersistence(this.runtime.recordings.dirty, this.result),
+        });
+    }
+}