pi-agent-browser-native 0.9.2 → 0.9.4

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

@@ -0,0 +1,269 @@
+import { isAbsolute } from "node:path";
+import { batchHasSuccessfulCloseAll, getSuccessfulBatchCloseLifecycle, } from "../batch-lifecycle.js";
+import { getBrowserResultMessage } from "../browser-transcript.js";
+import { canUseHeadlessCompatibilityUserAgent, extractUpstreamCommandTokens } from "../runtime.js";
+import { extractExplicitSessionName, isAgentBrowserSessionIdentityKeyInNamespace, isUpstreamEnvFlagEnabled, } from "../argv-grammar.js";
+import { isRecord } from "../parsing.js";
+import { getAgentBrowserProcessEnvironment } from "../process-environment.js";
+import { isCloseAllCommand, isCloseCommand } from "../command-taxonomy.js";
+import { hasLaunchScopedFlagToken } from "../launch-scoped-flags.js";
+import { getActiveElectronRecords, getSessionContextKey } from "./browser-run/session-state.js";
+import { isSuccessfulNativeConfirmedClose } from "../read-confirmation.js";
+import { getRecognizedCompatibilityWorkaround } from "./extension-managed-ownership.js";
+import { getCleanupResultClosedManagedSessionIdentities, isElectronLaunchRecord, } from "./extension-electron-ownership.js";
+function stringValue(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function stringArgs(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const args = value;
+    return args.every((arg) => typeof arg === "string") ? args : undefined;
+}
+function parseOutcomeFacts(outcome) {
+    return {
+        outcomeSucceeded: outcome?.succeeded === true,
+        outcomeStatus: stringValue(outcome?.status),
+        outcomeCurrentSessionName: stringValue(outcome?.currentSessionName),
+        outcomeAttemptedSessionName: stringValue(outcome?.attemptedSessionName),
+    };
+}
+function parseResourceRow(entry) {
+    const message = getBrowserResultMessage(entry);
+    const details = isRecord(message?.details) ? message.details : undefined;
+    if (!message || !details) {
+        return undefined;
+    }
+    const args = stringArgs(details.args) ?? [];
+    const command = stringValue(details.command) ?? extractUpstreamCommandTokens(args)[0];
+    const succeeded = getSuccessfulToolResult(details, message);
+    const outcome = getManagedSessionOutcome(details);
+    return {
+        details,
+        succeeded,
+        args,
+        command,
+        sessionName: stringValue(details.sessionName),
+        namespace: stringValue(details.namespace),
+        sessionMode: details.sessionMode === "fresh" || details.sessionMode === "auto"
+            ? details.sessionMode
+            : undefined,
+        usedImplicitSession: details.usedImplicitSession === true,
+        explicitSessionName: extractExplicitSessionName(args),
+        batchCloseLifecycle: getSuccessfulBatchCloseLifecycle(details.batchSteps),
+        closeAllApplied: detailsReportCloseAllApplied(details, succeeded),
+        outcome,
+        ...parseOutcomeFacts(outcome),
+        closesSession: isCloseCommand(command) ||
+            isSuccessfulNativeConfirmedClose(extractUpstreamCommandTokens(getToolResultArgs(details)), details.data),
+    };
+}
+class BranchResourceReplay {
+    events = {
+        electronLaunchActiveRanks: new Map(),
+        electronLaunchCleanupRanks: new Map(),
+        managedSessionActiveIdentities: new Map(),
+        managedSessionActiveRanks: new Map(),
+        managedSessionCloseRanks: new Map(),
+        managedSessionLaunchState: new Map(),
+    };
+    eventRank = 0;
+    retainedLaunchAfterFailure(key, row) {
+        const outcome = row.outcome;
+        return (outcome?.activeAfter === true &&
+            typeof outcome.currentSessionName === "string" &&
+            getSessionContextKey(outcome.currentSessionName, stringValue(outcome.currentSessionNamespace)) === key);
+    }
+    restoreLaunchCompatibility(launch, key, row) {
+        const workaround = getRecognizedCompatibilityWorkaround(row.details.compatibilityWorkaround);
+        const status = row.outcome?.status;
+        const retained = workaround !== undefined &&
+            this.retainedLaunchAfterFailure(key, row) &&
+            typeof status === "string" &&
+            ["created", "replaced", "unchanged"].includes(status);
+        if (!row.succeeded && !retained) {
+            return launch;
+        }
+        if (workaround) {
+            return { ...launch, compatibilityWorkaround: workaround };
+        }
+        if (!canUseHeadlessCompatibilityUserAgent(getToolResultArgs(row.details))) {
+            return { ...launch, compatibilityWorkaround: undefined };
+        }
+        return launch;
+    }
+    restoreLaunchAutosave(prior, key, row) {
+        if (!row.succeeded && !this.retainedLaunchAfterFailure(key, row)) {
+            return prior;
+        }
+        const launch = { ...prior };
+        const details = row.details;
+        if (typeof details.managedSessionHeadedAutosaveDisabled === "boolean") {
+            launch.headedManagedAutosaveDisabled = details.managedSessionHeadedAutosaveDisabled;
+        }
+        if (typeof details.managedSessionHeadedAutosaveInterval === "string") {
+            launch.headedManagedAutosaveInterval = details.managedSessionHeadedAutosaveInterval;
+        }
+        else if (details.managedSessionHeadedAutosaveDisabled === true) {
+            launch.headedManagedAutosaveInterval = "0";
+        }
+        return launch;
+    }
+    restoreLaunch(row) {
+        const { sessionName, namespace, details } = row;
+        if (sessionName === undefined || sessionName === "") {
+            return;
+        }
+        const key = getSessionContextKey(sessionName, namespace) ?? sessionName;
+        const launch = this.events.managedSessionLaunchState.get(key) ?? {
+            compatibilityWorkaround: undefined,
+            headedManagedAutosaveDisabled: false,
+        };
+        if (typeof details.managedSessionCwd === "string" && isAbsolute(details.managedSessionCwd)) {
+            launch.cwd = details.managedSessionCwd;
+        }
+        if (typeof details.managedSessionSocketDir === "string") {
+            launch.socketDir = details.managedSessionSocketDir;
+        }
+        const compatible = this.restoreLaunchCompatibility(launch, key, row);
+        this.events.managedSessionLaunchState.set(key, this.restoreLaunchAutosave(compatible, key, row));
+    }
+    restoreOutcomes(row) {
+        if (row.outcome?.activeAfter === true &&
+            ["created", "replaced", "unchanged"].includes(row.outcomeStatus ?? "")) {
+            this.markActive(row.outcomeCurrentSessionName, row.namespace);
+        }
+        if (row.outcomeSucceeded && row.outcomeStatus === "closed") {
+            this.markClosed(getSessionContextKey(row.outcomeAttemptedSessionName ?? row.outcomeCurrentSessionName ?? row.sessionName, row.namespace));
+        }
+        this.restoreReplacementClose(row);
+    }
+    restoreReplacementClose(row) {
+        const { outcome, outcomeStatus, namespace } = row;
+        if (!outcome || outcomeStatus !== "replaced" || outcome.replacedSessionClosed === false) {
+            return;
+        }
+        this.markClosed(getSessionContextKey(stringValue(outcome.replacedSessionName), stringValue(outcome.replacedSessionNamespace) ?? namespace));
+    }
+    isImplicitManagedLaunch(row) {
+        return (((row.explicitSessionName === undefined || row.explicitSessionName === "") &&
+            (row.usedImplicitSession || row.sessionMode === "fresh")) ||
+            row.details.managedSessionHeadedAutosaveDisabled === true ||
+            typeof row.details.managedSessionHeadedAutosaveInterval === "string");
+    }
+    restoreCommandActivity(row) {
+        if (!row.succeeded) {
+            return;
+        }
+        if (row.closesSession) {
+            this.markClosed(getSessionContextKey(row.explicitSessionName ??
+                row.sessionName ??
+                row.outcomeAttemptedSessionName ??
+                row.outcomeCurrentSessionName, row.namespace));
+        }
+        else if (this.isImplicitManagedLaunch(row)) {
+            this.markActive(row.sessionName, row.namespace);
+        }
+    }
+    restoreNamespaceCloseAll(row) {
+        if (!row.closeAllApplied) {
+            return;
+        }
+        const retained = row.batchCloseLifecycle?.endsClosed === false
+            ? getSessionContextKey(row.sessionName, row.namespace)
+            : undefined;
+        for (const key of this.events.managedSessionActiveIdentities.keys()) {
+            if (key !== retained && isAgentBrowserSessionIdentityKeyInNamespace(key, row.namespace)) {
+                this.events.managedSessionCloseRanks.set(key, this.eventRank);
+            }
+        }
+    }
+    restoreElectronCleanupResult(result, row) {
+        if (isRecord(result) && isElectronLaunchRecord(result.record)) {
+            this.events.electronLaunchCleanupRanks.set(result.record.launchId, this.eventRank);
+        }
+        for (const identity of getCleanupResultClosedManagedSessionIdentities(result, row.namespace)) {
+            this.markClosed(getSessionContextKey(identity.sessionName, identity.namespace) ?? identity.sessionName);
+        }
+    }
+    restoreElectronLaunch(value) {
+        if (isElectronLaunchRecord(value) &&
+            getActiveElectronRecords(new Map([[value.launchId, value]])).length > 0) {
+            this.events.electronLaunchActiveRanks.set(value.launchId, this.eventRank);
+        }
+    }
+    restoreElectron(row) {
+        const electron = isRecord(row.details.electron) ? row.details.electron : undefined;
+        this.restoreElectronLaunch(electron?.launch);
+        const cleanup = isRecord(electron?.cleanup) ? electron.cleanup : undefined;
+        this.restoreElectronCleanupRecords(cleanup?.records);
+        for (const result of Array.isArray(cleanup?.results) ? cleanup.results : []) {
+            this.restoreElectronCleanupResult(result, row);
+        }
+    }
+    restoreElectronCleanupRecords(records) {
+        if (!Array.isArray(records)) {
+            return;
+        }
+        for (const record of records) {
+            if (isElectronLaunchRecord(record)) {
+                this.events.electronLaunchCleanupRanks.set(record.launchId, this.eventRank);
+            }
+        }
+    }
+    markActive(sessionName, namespace) {
+        if (sessionName === undefined || sessionName === "") {
+            return;
+        }
+        const key = getSessionContextKey(sessionName, namespace) ?? sessionName;
+        this.events.managedSessionActiveIdentities.set(key, { namespace, sessionName });
+        this.events.managedSessionActiveRanks.set(key, this.eventRank);
+    }
+    markClosed(key) {
+        if (key !== undefined && key !== "") {
+            this.events.managedSessionCloseRanks.set(key, this.eventRank);
+        }
+    }
+    apply(row) {
+        this.eventRank += 1;
+        this.restoreLaunch(row);
+        this.restoreOutcomes(row);
+        this.restoreCommandActivity(row);
+        this.restoreNamespaceCloseAll(row);
+        this.restoreElectron(row);
+    }
+}
+export function collectBranchManagedResourceEvents(branch) {
+    const replay = new BranchResourceReplay();
+    for (const entry of branch) {
+        const row = parseResourceRow(entry);
+        if (row) {
+            replay.apply(row);
+        }
+    }
+    return replay.events;
+}
+export function getToolResultArgs(details) {
+    return stringArgs(details.args) ?? stringArgs(details.effectiveArgs) ?? [];
+}
+export function detailsReportCloseAllApplied(details, succeeded) {
+    return (details.closeAllApplied === true ||
+        (succeeded && isCloseAllCommand(extractUpstreamCommandTokens(getToolResultArgs(details)))) ||
+        batchHasSuccessfulCloseAll(details.batchSteps));
+}
+export function isAttachedBrowserInvocation(args, env = getAgentBrowserProcessEnvironment()) {
+    return (extractUpstreamCommandTokens([...args])[0] === "connect" ||
+        hasLaunchScopedFlagToken([...args], "--cdp") ||
+        hasLaunchScopedFlagToken([...args], "--auto-connect") ||
+        env.AGENT_BROWSER_CDP !== undefined ||
+        isUpstreamEnvFlagEnabled(env.AGENT_BROWSER_AUTO_CONNECT));
+}
+export function getManagedSessionOutcome(details) {
+    return isRecord(details.managedSessionOutcome) ? details.managedSessionOutcome : undefined;
+}
+export function getSuccessfulToolResult(details, message) {
+    const messageIsError = typeof message.isError === "boolean" ? message.isError : undefined;
+    const exitCode = typeof details.exitCode === "number" ? details.exitCode : undefined;
+    return messageIsError === undefined ? exitCode === undefined || exitCode === 0 : !messageIsError;
+}

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

@@ -0,0 +1,113 @@
+import { format } from "node:util";
+import { applyArtifactChanges, artifactChanges, getBrowserRecord, pageChange, snapshotDefinition, } from "../browser-transcript.js";
+import { redactSensitiveText, redactSensitiveValue } from "../runtime.js";
+import { isRecord } from "../parsing.js";
+import { getSessionArtifactManifestEntryKey, isSessionArtifactManifest, } from "../results/artifact-manifest.js";
+export function browserExecutionFailure(error, signal, fallbackCategory = "upstream-error") {
+    const timeout = error instanceof Error && error.name === "TimeoutError";
+    const summary = redactSensitiveText(error instanceof Error ? error.message : format("%s", error));
+    let failureCategory = fallbackCategory;
+    if (signal?.aborted === true) {
+        failureCategory = "aborted";
+    }
+    if (timeout) {
+        failureCategory = "timeout";
+    }
+    return {
+        content: [{ type: "text", text: summary }],
+        details: { error: summary, summary, resultCategory: "failure", failureCategory },
+        isError: true,
+    };
+}
+export function isResultFileArtifact(artifact) {
+    return (isRecord(artifact) &&
+        typeof artifact.absolutePath === "string" &&
+        typeof artifact.kind === "string" &&
+        typeof artifact.path === "string");
+}
+export function getResultFileArtifacts(result) {
+    const details = isRecord(result.details) ? result.details : undefined;
+    return Array.isArray(details?.artifacts) ? details.artifacts.filter(isResultFileArtifact) : [];
+}
+function rowArtifactPaths(row) {
+    const paths = [];
+    if (typeof row.fullOutputPath === "string") {
+        paths.push(row.fullOutputPath);
+    }
+    for (const path of Array.isArray(row.fullOutputPaths) ? row.fullOutputPaths : []) {
+        if (typeof path === "string") {
+            paths.push(path);
+        }
+    }
+    for (const artifact of Array.isArray(row.artifacts) ? row.artifacts.filter(isRecord) : []) {
+        if (typeof artifact.absolutePath === "string") {
+            paths.push(artifact.absolutePath);
+        }
+        if (typeof artifact.path === "string") {
+            paths.push(artifact.path);
+        }
+    }
+    return paths;
+}
+export function invocationArtifactManifest(current, previous, details, retainedReceipts) {
+    if (!current) {
+        return undefined;
+    }
+    const rows = [
+        details,
+        ...(Array.isArray(details.batchSteps) ? details.batchSteps.filter(isRecord) : []),
+    ];
+    const paths = new Set(rows.flatMap(rowArtifactPaths));
+    const changed = new Set((artifactChanges(previous, current)?.upserts ?? []).map(getSessionArtifactManifestEntryKey));
+    for (const row of retainedReceipts?.entries ?? []) {
+        changed.add(getSessionArtifactManifestEntryKey(row));
+    }
+    const entries = current.entries.filter((row) => changed.has(getSessionArtifactManifestEntryKey(row)) ||
+        paths.has(row.path) ||
+        (row.absolutePath !== undefined && paths.has(row.absolutePath)));
+    if (entries.length === 0) {
+        return undefined;
+    }
+    const projected = redactSensitiveValue({
+        ...current,
+        entries,
+        liveCount: entries.filter((row) => row.retentionState === "live").length,
+        evictedCount: entries.filter((row) => row.retentionState === "evicted").length,
+    });
+    return isSessionArtifactManifest(projected) ? projected : undefined;
+}
+export function restoreArtifactManifestFromBranch(branch) {
+    let restoredManifest;
+    for (const entry of branch) {
+        restoredManifest = applyArtifactChanges(restoredManifest, getBrowserRecord(entry)?.event.artifacts);
+    }
+    return restoredManifest;
+}
+function pageViewChanged(key, page, before) {
+    return (JSON.stringify(pageChange(key, page, before?.refSnapshot?.snapshotId)) !==
+        JSON.stringify(pageChange(key, before ?? {}, before?.refSnapshot?.snapshotId)));
+}
+export function browserPageChanges(working, prior, touched) {
+    const pages = working.views();
+    const keys = new Set(touched);
+    for (const [key, page] of pages) {
+        const before = prior.get(key);
+        if (pageViewChanged(key, page, before)) {
+            keys.add(key);
+        }
+    }
+    for (const key of prior.keys()) {
+        if (!pages.has(key)) {
+            keys.add(key);
+        }
+    }
+    const changes = [...keys].map((key) => {
+        const page = pages.get(key);
+        return page
+            ? pageChange(key, page, prior.get(key)?.refSnapshot?.snapshotId)
+            : { key, refs: { kind: "invalidate" }, clear: true };
+    });
+    const capture = changes.find((page) => page.refs.kind === "replace");
+    const snapshot = capture ? pages.get(capture.key)?.refSnapshot : undefined;
+    return { pages: changes, ...(snapshot ? { snapshot: snapshotDefinition(snapshot) } : {}) };
+}

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

@@ -0,0 +1,146 @@
+import { SessionPageState } from "../session-page-state.js";
+import { getAgentBrowserSessionIdentityKey } from "../argv-grammar.js";
+import { captureBrowserBranch } from "../browser-journal.js";
+import { createEphemeralSessionSeed, createImplicitSessionName, getImplicitSessionCloseTimeoutMs, getImplicitSessionIdleTimeoutMs, } from "../runtime.js";
+import { ManagedSessionRestoreState } from "../managed-session-restore.js";
+import { AsyncExecutionQueue, KeyedAsyncExecutionQueue } from "./execution-queue.js";
+import { BrowserPrompt } from "./extension-prompt.js";
+import { BrowserArtifacts } from "./extension-artifacts.js";
+import { BrowserElectronResources } from "./extension-electron-ownership.js";
+import { BrowserRecordingRegistry } from "./extension-recording.js";
+/** Launch and cleanup ownership for the extension's managed browser identities. */
+export class BrowserManagedSessions {
+    active = false;
+    baseName;
+    compatibilityWorkaround;
+    headedAutosaveDisabled = false;
+    headedAutosaveInterval;
+    name;
+    cwd = process.cwd();
+    namespace;
+    freshOrdinal = 0;
+    restore = new ManagedSessionRestoreState();
+    owned = new Map();
+    constructor(seed) {
+        this.baseName = createImplicitSessionName(undefined, process.cwd(), seed);
+        this.name = this.baseName;
+    }
+    initializeBase(sessionId, cwd, seed) {
+        this.baseName = createImplicitSessionName(sessionId, cwd, seed);
+    }
+    reset() {
+        this.active = false;
+        this.compatibilityWorkaround = undefined;
+        this.headedAutosaveDisabled = false;
+        this.headedAutosaveInterval = undefined;
+        this.namespace = undefined;
+        this.owned.clear();
+    }
+}
+/** Live page-scoped state; clear and reset preserve the existing replacement semantics. */
+export class BrowserSessionResources {
+    pages = new SessionPageState();
+    traces = new Map();
+    attached = new Set();
+    routes = new Map();
+    getConfirmActions(key) {
+        return this.pages.get(key).confirmActions;
+    }
+    hasAttachment(key) {
+        return this.attached.has(key);
+    }
+    clear(sessionName, namespace) {
+        const key = getAgentBrowserSessionIdentityKey(sessionName, namespace);
+        this.attached.delete(key);
+        const routes = new Map(this.routes);
+        routes.delete(key);
+        this.routes = routes;
+        this.traces.delete(key);
+        this.pages.clearSession(key);
+    }
+    reset() {
+        this.pages.reset();
+        this.traces = new Map();
+        this.attached = new Set();
+        this.routes = new Map();
+    }
+}
+/** Branch-current generation and shared empty-root admission, independent of browser resources. */
+export class BrowserBranchState {
+    empty;
+    ownerSessionId = "";
+    replayError;
+    restoreGeneration = 0;
+    stateRevision = 0;
+    get stateGeneration() {
+        return this.stateRevision;
+    }
+    invalidateRestore() {
+        this.restoreGeneration += 1;
+    }
+    advanceState() {
+        this.stateRevision += 1;
+    }
+    invalidate() {
+        this.invalidateRestore();
+        this.advanceState();
+    }
+    beginRestore(ownerSessionId) {
+        this.invalidate();
+        this.ownerSessionId = ownerSessionId;
+    }
+    setReplayError(error) {
+        this.replayError = error;
+    }
+    capture(ctx) {
+        const generation = this.restoreGeneration;
+        const empty = ctx.sessionManager.getLeafId() === null;
+        if (empty &&
+            this.empty?.anchorId === null &&
+            this.empty.sessionId === ctx.sessionManager.getSessionId() &&
+            this.empty.isCurrent()) {
+            return this.empty;
+        }
+        const branch = captureBrowserBranch(ctx.sessionManager, () => generation === this.restoreGeneration);
+        this.empty = empty ? branch : undefined;
+        return branch;
+    }
+}
+/** In-flight code cells are aborted and settled before branch restoration or shutdown. */
+export class BrowserCodeActivity {
+    controllers = new Set();
+    executions = new Set();
+    async settle() {
+        for (const controller of this.controllers) {
+            controller.abort();
+        }
+        await Promise.allSettled(this.executions);
+    }
+}
+/** Readonly root composition. Mutable resources have focused lifetime owners. */
+export class BrowserRuntime {
+    prompt;
+    artifacts;
+    recordings;
+    electron = new BrowserElectronResources();
+    managed;
+    sessions = new BrowserSessionResources();
+    branch = new BrowserBranchState();
+    code = new BrowserCodeActivity();
+    pi;
+    beforeExecute;
+    ephemeralSessionSeed = createEphemeralSessionSeed();
+    implicitSessionIdleTimeoutMs = String(getImplicitSessionIdleTimeoutMs());
+    implicitSessionCloseTimeoutMs = getImplicitSessionCloseTimeoutMs();
+    managedSessionExecutionQueue = new AsyncExecutionQueue();
+    callerOwnedSessionExecutionQueues = new KeyedAsyncExecutionQueue();
+    validatedUpstreamPathKeys = new Set();
+    constructor(pi, beforeExecute) {
+        this.pi = pi;
+        this.managed = new BrowserManagedSessions(this.ephemeralSessionSeed);
+        this.prompt = new BrowserPrompt(pi);
+        this.artifacts = new BrowserArtifacts(pi);
+        this.recordings = new BrowserRecordingRegistry(pi, this.artifacts, () => this.managed.cwd);
+        this.beforeExecute = beforeExecute;
+    }
+}

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

@@ -0,0 +1,58 @@
+import { redactSensitiveText } from "../runtime.js";
+import { getAgentBrowserSessionIdentityKey } from "../argv-grammar.js";
+import { withIsolatedAgentBrowserEnvironment } from "../process-environment.js";
+import { closeManagedSession } from "./browser-run/managed-session-daemon-policy.js";
+import { AGENT_BROWSER_SCRIPT_NAMESPACE, isAgentBrowserScriptSessionName, } from "../input-modes/script.js";
+import { appendScriptSessionLease, getScriptSessionLeasesFromBranch } from "./script-mode.js";
+import { trackOwnedManagedSession, untrackOwnedManagedSession, } from "./extension-managed-ownership.js";
+export async function closeScriptSessionLeaseWithinQueue(resources, sessionName, cwd) {
+    const closeError = await withIsolatedAgentBrowserEnvironment(() => closeManagedSession({
+        confirmActions: resources.sessions.getConfirmActions(getAgentBrowserSessionIdentityKey(sessionName, AGENT_BROWSER_SCRIPT_NAMESPACE)),
+        cwd,
+        namespace: AGENT_BROWSER_SCRIPT_NAMESPACE,
+        restoreState: resources.managed.restore,
+        sessionName,
+        timeoutMs: resources.implicitSessionCloseTimeoutMs,
+    }));
+    if (closeError !== undefined && closeError !== "") {
+        try {
+            appendScriptSessionLease(resources.pi, sessionName, "failed", resources.branch.ownerSessionId);
+        }
+        catch {
+            // Retain the prior outstanding lease so the next startup retries cleanup.
+        }
+        return redactSensitiveText(closeError);
+    }
+    try {
+        appendScriptSessionLease(resources.pi, sessionName, "closed", resources.branch.ownerSessionId);
+    }
+    catch {
+        resources.managed.restore.disable(sessionName);
+        return "The isolated session closed, but its durable cleanup record could not be saved.";
+    }
+    untrackOwnedManagedSession(resources.managed.owned, sessionName, AGENT_BROWSER_SCRIPT_NAMESPACE);
+    resources.managed.restore.clear(sessionName, AGENT_BROWSER_SCRIPT_NAMESPACE);
+    resources.recordings.retire(sessionName, AGENT_BROWSER_SCRIPT_NAMESPACE);
+    resources.sessions.clear(sessionName, AGENT_BROWSER_SCRIPT_NAMESPACE);
+    return undefined;
+}
+export async function recoverScriptSessionLeasesWithinQueue(resources, ctx, branch) {
+    const pendingSessionNames = new Set([...resources.managed.owned.values()]
+        .map((session) => session.sessionName)
+        .filter(isAgentBrowserScriptSessionName));
+    for (const lease of getScriptSessionLeasesFromBranch(branch, ctx.sessionManager.getSessionId()).values()) {
+        if (lease.cleanup !== "closed") {
+            pendingSessionNames.add(lease.sessionName);
+        }
+    }
+    for (const sessionName of pendingSessionNames) {
+        trackOwnedManagedSession(resources.managed.owned, sessionName, ctx.cwd, {
+            branchOwned: true,
+            namespace: AGENT_BROWSER_SCRIPT_NAMESPACE,
+        });
+        resources.managed.restore.disable(sessionName, AGENT_BROWSER_SCRIPT_NAMESPACE);
+        // Each isolated lease must close and persist its terminal record before the next cleanup.
+        // oxlint-disable-next-line no-await-in-loop
+        await closeScriptSessionLeaseWithinQueue(resources, sessionName, ctx.cwd);
+    }
+}

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

@@ -0,0 +1,62 @@
+import { Text } from "@earendil-works/pi-tui";
+import { registerAgentBrowserToolSurface } from "../tool-surface.js";
+import { AgentBrowserResultComponent, formatAgentBrowserRenderCall } from "../pi-tool-rendering.js";
+import { browserExecutionFailure } from "./extension-result-state.js";
+import { finalizeObservation } from "./extension-observation.js";
+import { executeCode } from "./extension-code.js";
+import { executeBrowserInvocation } from "./extension-command-admission.js";
+import { createBrowserInvocation } from "./extension-invocation.js";
+export function registerBrowserTools(runtime) {
+    const renderResult = (result, options, theme, context) => {
+        const component = context.lastComponent instanceof AgentBrowserResultComponent
+            ? context.lastComponent
+            : new AgentBrowserResultComponent();
+        component.setResult(result, options, theme, context.isError);
+        return component;
+    };
+    const renderers = {
+        renderCall: (args, theme, context) => {
+            const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+            text.setText(formatAgentBrowserRenderCall(args, theme, context.expanded));
+            return text;
+        },
+        renderResult,
+    };
+    registerAgentBrowserToolSurface(runtime.pi, {
+        async execute(id, params, signal, onUpdate, ctx) {
+            const branch = runtime.branch.capture(ctx);
+            let result;
+            try {
+                result = await executeBrowserInvocation(runtime, createBrowserInvocation({
+                    toolCallId: id,
+                    params,
+                    signal,
+                    onUpdate,
+                    ctx,
+                    selectedBranch: branch,
+                }));
+            }
+            catch (error) {
+                result = browserExecutionFailure(error, signal);
+            }
+            return finalizeObservation(runtime.artifacts, result, params, { ctx, branch });
+        },
+        async executeCode(id, params, signal, _onUpdate, ctx) {
+            const branch = runtime.branch.capture(ctx);
+            const completion = Promise.withResolvers();
+            const { promise: execution, resolve: finish } = completion;
+            runtime.code.executions.add(execution);
+            try {
+                const result = await executeCode(runtime, { toolCallId: id, params, signal, ctx, branch });
+                return await finalizeObservation(runtime.artifacts, result, params, { ctx, branch });
+            }
+            finally {
+                runtime.code.executions.delete(execution);
+                finish();
+            }
+        },
+        executionMode: runtime.beforeExecute ? "sequential" : undefined,
+        renderCall: renderers.renderCall,
+        renderResult: renderers.renderResult,
+    });
+}