open-managed-agents 0.1.0

package/dist/src/control-plane/sessions/pi/runner.js

@@ -0,0 +1,1104 @@
+import { AuthStorage, createAgentSession, createSyntheticSourceInfo, DefaultResourceLoader, ModelRegistry, SessionManager, } from "@earendil-works/pi-coding-agent";
+import { RuntimeUnsupportedSessionFileResourcesError } from "../../events/types.js";
+import { PiCustomToolBridge, } from "./custom-tools.js";
+import { PiToolPermissionBridge, } from "./tool-permissions.js";
+import { McpConnection } from "./mcp/client.js";
+import { createGuardedMcpFetch } from "./mcp/fetch.js";
+import { createMcpToolDefinitions, } from "./mcp/bridge.js";
+import { resolveSandboxProviderFactory, } from "./sandbox/selection.js";
+const DEFAULT_IDLE_TTL_MS = 15 * 60 * 1000;
+const ALREADY_PROCESSING_MESSAGE = "Agent is already processing";
+// Builds the resource loader that advertises snapshotted skills to the model at
+// their in-container mount paths. Exported so the real-SDK contract test can
+// exercise the exact same construction the runner uses. The loader must be
+// reload()ed before use (see createResourceLoader): a caller-provided loader is
+// used as-is by createAgentSession, and skillsOverride only runs inside reload().
+export function buildSessionSkillsResourceLoader(skills, systemPrompt) {
+    return new DefaultResourceLoader({
+        cwd: "/",
+        agentDir: "/nonexistent-oma-pi-agent",
+        noExtensions: true,
+        noSkills: true,
+        noPromptTemplates: true,
+        noThemes: true,
+        noContextFiles: true,
+        ...(systemPrompt === undefined ? {} : { systemPrompt }),
+        skillsOverride: () => ({
+            diagnostics: [],
+            skills: skills.map((skill) => {
+                const baseDir = `/workspace/skills/${skill.name}`;
+                const filePath = `${baseDir}/SKILL.md`;
+                return { name: skill.name, description: skill.description, filePath, baseDir, disableModelInvocation: false, sourceInfo: createSyntheticSourceInfo(filePath, { source: "oma-session-snapshot", scope: "temporary", origin: "top-level", baseDir }) };
+            }),
+        }),
+    });
+}
+const DEFAULT_MCP_MAX_CONSECUTIVE_FAILURES = 5;
+const MCP_UNAUTHENTICATED_FINGERPRINT = "none";
+function createPrivatePiModelCatalog(provider = "anthropic", modelId = "claude-haiku-4-5") {
+    const authStorage = AuthStorage.create();
+    const modelRegistry = ModelRegistry.create(authStorage);
+    const allowedProviders = new Set([provider]);
+    return {
+        defaultModel: { provider, id: modelId },
+        allowedProviders,
+        authStorage,
+        modelRegistry,
+        securityReport: { warnings: [] },
+        // Standalone runners are an internal/test seam without deployment
+        // admission policy. Production always receives the shared allowlisted
+        // catalog from the composition root.
+        resolve: (ref) => modelRegistry.find(ref.provider, ref.id),
+        list: (options = {}) => (options.availableOnly ? modelRegistry.getAvailable() : modelRegistry.getAll())
+            .filter((model) => allowedProviders.has(model.provider) &&
+            (options.provider === undefined || model.provider === options.provider)),
+        // Standalone runners do not participate in production admission. Tests
+        // and internal callers may supply their own session factory without
+        // configuring operator credentials.
+        hasConfiguredAuth: () => true,
+        providerAuthMetadata: (providerName) => {
+            const status = modelRegistry.getProviderAuthStatus(providerName);
+            return {
+                ...(status.source === undefined ? {} : { source: status.source }),
+                ...(status.label === undefined ? {} : { label: status.label }),
+            };
+        },
+    };
+}
+export class PiSessionRunner {
+    opts;
+    authStorage;
+    modelRegistry;
+    modelCatalog;
+    sessions = new Map();
+    pendingSessions = new Map();
+    pendingInterrupts = new Map();
+    closedSessionIds = new Set();
+    customToolBridge;
+    toolPermissionBridge;
+    preparingSessionAgents = new Map();
+    preparingSessionSkills = new Map();
+    idleTtlMs;
+    now;
+    sessionFactory;
+    mcpFetch;
+    /**
+     * Consecutive connect failures per (session, server). Runner-level so the
+     * count SURVIVES handle recreation — fresh-handle retry is the mechanism
+     * (plan 0122 §4.6). Cleared on closeSession.
+     */
+    mcpFailureCounts = new Map();
+    closed = false;
+    constructor(opts = {}) {
+        this.opts = opts;
+        const catalog = opts.modelCatalog ?? createPrivatePiModelCatalog(opts.provider, opts.model);
+        this.modelCatalog = catalog;
+        this.authStorage = catalog.authStorage;
+        this.modelRegistry = catalog.modelRegistry;
+        this.resolveSandboxProviderFactory();
+        this.idleTtlMs = opts.idleTtlMs ?? DEFAULT_IDLE_TTL_MS;
+        this.now = opts.now ?? Date.now;
+        this.sessionFactory = opts.sessionFactory;
+        this.mcpFetch = opts.mcp?.fetch ?? createGuardedMcpFetch();
+        this.customToolBridge = new PiCustomToolBridge({
+            customTools: opts.customTools,
+            timeoutMs: opts.customToolTimeoutMs,
+        });
+        this.toolPermissionBridge = new PiToolPermissionBridge({
+            access: (workspaceId, sessionId, toolName) => opts.builtinToolAccess?.(workspaceId, sessionId, toolName, {
+                agentId: this.preparingSessionAgents.get(sessionId)?.workspaceId === workspaceId
+                    ? this.preparingSessionAgents.get(sessionId)?.agentId
+                    : undefined,
+                agentVersion: this.preparingSessionAgents.get(sessionId)?.workspaceId === workspaceId
+                    ? this.preparingSessionAgents.get(sessionId)?.agentVersion
+                    : undefined,
+            }) ?? { enabled: true, permission: "allow" },
+            timeoutMs: opts.toolConfirmationTimeoutMs,
+        });
+    }
+    runUserMessage(workspaceId, sessionId, text, opts = {}) {
+        return this.runOnSession(workspaceId, sessionId, text, opts.signal);
+    }
+    async prepareSession(workspaceId, sessionId, opts = {}) {
+        if (opts.agent) {
+            this.preparingSessionAgents.set(sessionId, {
+                workspaceId,
+                agentId: opts.agent.id,
+                agentVersion: opts.agent.version,
+            });
+        }
+        if (opts.skills)
+            this.preparingSessionSkills.set(sessionId, opts.skills);
+        try {
+            const sandboxContext = opts.environmentId === undefined
+                ? undefined
+                : { environmentId: opts.environmentId };
+            const handle = await this.getOrCreateHandle(workspaceId, sessionId, opts.fileMounts, sandboxContext, opts.vaultIds === undefined ? undefined : { vaultIds: opts.vaultIds });
+            this.touch(sessionId, handle);
+        }
+        finally {
+            if (opts.agent)
+                this.preparingSessionAgents.delete(sessionId);
+            if (opts.skills)
+                this.preparingSessionSkills.delete(sessionId);
+        }
+    }
+    claimCustomToolResult(workspaceId, sessionId, event) {
+        return this.customToolBridge.claimResult(workspaceId, sessionId, event);
+    }
+    claimToolConfirmation(workspaceId, sessionId, event) {
+        return this.toolPermissionBridge.claimConfirmation(workspaceId, sessionId, event);
+    }
+    async interruptSession(_workspaceId, sessionId) {
+        const pending = this.pendingInterrupts.get(sessionId);
+        if (pending)
+            return pending;
+        const interrupt = this.interruptSessionInternal(sessionId);
+        this.pendingInterrupts.set(sessionId, interrupt);
+        try {
+            await interrupt;
+        }
+        finally {
+            if (this.pendingInterrupts.get(sessionId) === interrupt) {
+                this.pendingInterrupts.delete(sessionId);
+            }
+        }
+    }
+    async interruptSessionInternal(sessionId) {
+        const existing = this.sessions.get(sessionId);
+        if (existing) {
+            await this.interruptHandle(sessionId, existing);
+            return;
+        }
+        const pending = this.pendingSessions.get(sessionId);
+        if (!pending)
+            return;
+        try {
+            const handle = await pending;
+            await this.interruptHandle(sessionId, handle);
+        }
+        catch {
+            // Interrupting a failed/closed pending session is a no-op for callers.
+        }
+    }
+    customToolNames(workspaceId, sessionId) {
+        const handle = this.sessions.get(sessionId);
+        if (handle)
+            return handle.customToolNames;
+        return this.customToolBridge.customToolNames(workspaceId, sessionId, this.preparingSessionAgentContext(workspaceId, sessionId));
+    }
+    publicToolUseIdForPiToolCallId(_workspaceId, sessionId, piToolCallId) {
+        return this.toolPermissionBridge.publicToolUseIdForPiToolCallId(sessionId, piToolCallId);
+    }
+    suppressPiToolUse(_workspaceId, sessionId, piToolCallId) {
+        return this.toolPermissionBridge.suppressPiToolUse(sessionId, piToolCallId);
+    }
+    async collectSessionOutputs(_workspaceId, sessionId) {
+        const handle = this.sessions.get(sessionId);
+        if (!handle?.sandbox) {
+            return { kind: "unsupported", reason: "no_live_sandbox" };
+        }
+        if (typeof handle.sandbox.collectOutputFiles !== "function") {
+            return { kind: "unsupported", reason: "provider_unsupported" };
+        }
+        return {
+            kind: "collected",
+            files: await handle.sandbox.collectOutputFiles(),
+        };
+    }
+    close() {
+        this.closed = true;
+        for (const [sessionId, handle] of this.sessions) {
+            if (handle.running) {
+                handle.closeWhenIdle = true;
+                this.scheduleEviction(sessionId, handle);
+            }
+            else {
+                this.evict(sessionId, handle);
+            }
+        }
+    }
+    async closeSession(workspaceId, sessionId) {
+        this.closedSessionIds.add(sessionId);
+        this.mcpFailureCounts.delete(sessionId);
+        try {
+            const existing = this.sessions.get(sessionId);
+            if (existing) {
+                await this.closeHandle(sessionId, existing);
+                return;
+            }
+            const pending = this.pendingSessions.get(sessionId);
+            if (!pending)
+                return;
+            try {
+                const handle = await pending;
+                await this.closeHandle(sessionId, handle);
+            }
+            catch {
+                // A close-requested pending session disposes itself during materialization.
+            }
+        }
+        finally {
+            this.closedSessionIds.delete(sessionId);
+        }
+    }
+    async *runOnSession(workspaceId, sessionId, text, signal) {
+        // Cross-request interrupt/message ordering: a message that arrives while
+        // abort is settling waits and then starts a fresh post-interrupt turn.
+        await this.waitForPendingInterrupt(sessionId);
+        const handle = await this.getOrCreateHandle(workspaceId, sessionId);
+        if (this.closed) {
+            this.evict(sessionId, handle);
+            throw new Error("PiSessionRunner is closed");
+        }
+        this.touch(sessionId, handle);
+        if (handle.running && !handle.needsFreshPromptAfterInterrupt) {
+            try {
+                await handle.session.followUp(text);
+                this.touch(sessionId, handle);
+            }
+            catch (error) {
+                this.evict(sessionId, handle);
+                throw error;
+            }
+            return;
+        }
+        handle.needsFreshPromptAfterInterrupt = false;
+        const queue = [];
+        const gatedEvents = [];
+        const activeSandboxedToolCalls = new Map();
+        let done = false;
+        let failure;
+        let becameFollowUp = false;
+        let wake;
+        const stop = handle.session.subscribe((event) => {
+            updateRunning(handle, event);
+            queue.push(event);
+            wake?.();
+        });
+        const previousInternal = handle.emitInternal;
+        const installedInternalEmitter = previousInternal === undefined;
+        if (installedInternalEmitter) {
+            handle.emitInternal = (event) => {
+                if (event.type === "oma.tool_permission_use") {
+                    const match = takeMessageEndForToolCall(handle.sandbox, [gatedEvents, queue], event.piToolCallId);
+                    if (match !== undefined) {
+                        queue.push({
+                            type: "oma.tool_permission_with_model_end",
+                            messageEnd: match.event,
+                            permissionUse: event,
+                            suppressedPiToolCallIds: match.suppressedPiToolCallIds,
+                        });
+                        wake?.();
+                        return;
+                    }
+                }
+                if (event.type === "oma.mcp_tool_use") {
+                    // Opportunistic coalescing, mirroring the permission path: when
+                    // the message_end carrying this toolCall is still queued, persist
+                    // it atomically with the use event; otherwise the use event stands
+                    // alone (both orders produce correct wire output — plan 0122 §4.4).
+                    const match = takeMessageEndForMcpToolCall(handle.mcpToolNames, [gatedEvents, queue], event.piToolCallId);
+                    if (match !== undefined) {
+                        queue.push({
+                            type: "oma.mcp_tool_with_model_end",
+                            messageEnd: match.event,
+                            mcpToolUse: event,
+                            suppressedPiToolCallIds: match.suppressedPiToolCallIds,
+                        });
+                        wake?.();
+                        return;
+                    }
+                }
+                queue.push(event);
+                wake?.();
+            };
+            // Connect failures queued at session build flush now — the first
+            // moment an event consumer exists (plan 0122 §4.2).
+            for (const failure of handle.pendingMcpFailures.splice(0)) {
+                queue.push(failure);
+            }
+        }
+        const onAbort = () => {
+            void handle.session.abort();
+            wake?.();
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+        const run = handle.session
+            .prompt(text)
+            .catch(async (error) => {
+            if (isAlreadyProcessing(error)) {
+                await handle.session.followUp(text);
+                // Best effort for the losing prompt race: once Pi confirms this turn
+                // is a follow-up, discard overlap events captured by this temporary
+                // subscriber. A pre-rejection event can still escape; in practice that
+                // should be limited to early status frames, while the winning prompt
+                // subscriber owns the full turn and follow-up output.
+                becameFollowUp = true;
+                queue.length = 0;
+                return;
+            }
+            failure = error;
+        })
+            .finally(() => {
+            done = true;
+            wake?.();
+        });
+        try {
+            while (!done || queue.length > 0) {
+                if (becameFollowUp)
+                    break;
+                if (queue.length === 0) {
+                    await new Promise((resolve) => {
+                        wake = resolve;
+                        if (done || becameFollowUp || queue.length > 0) {
+                            wake = undefined;
+                            resolve();
+                        }
+                    });
+                    wake = undefined;
+                    continue;
+                }
+                const event = queue.shift();
+                if (isInternalRuntimeEvent(event)) {
+                    yield event;
+                    continue;
+                }
+                const sandboxedToolCalls = sandboxedToolCallsInMessage(handle.sandbox, event);
+                if (sandboxedToolCalls.length > 0) {
+                    for (const call of sandboxedToolCalls) {
+                        activeSandboxedToolCalls.set(call.toolCallId, call.toolName);
+                    }
+                    gatedEvents.push(event);
+                    continue;
+                }
+                const sandboxedStart = sandboxedToolEvent(handle.sandbox, event, "tool_execution_start");
+                if (sandboxedStart) {
+                    activeSandboxedToolCalls.set(sandboxedStart.toolCallId, sandboxedStart.toolName);
+                    gatedEvents.push(event);
+                    continue;
+                }
+                const sandboxedEnd = sandboxedToolEvent(handle.sandbox, event, "tool_execution_end");
+                if (activeSandboxedToolCalls.size > 0) {
+                    gatedEvents.push(event);
+                    if (sandboxedEnd) {
+                        assertSandboxProviderHandledToolCall({
+                            sandbox: handle.sandbox,
+                            toolPermissionBridge: this.toolPermissionBridge,
+                            sessionId,
+                            toolName: sandboxedEnd.toolName,
+                            toolCallId: sandboxedEnd.toolCallId,
+                            isError: sandboxedEnd.isError,
+                        });
+                        assertSandboxProviderHealthy(handle.sandbox);
+                        activeSandboxedToolCalls.delete(sandboxedEnd.toolCallId);
+                        if (activeSandboxedToolCalls.size === 0) {
+                            const releasableEvents = gatedEvents.splice(0);
+                            for (const releasableEvent of releasableEvents) {
+                                yield releasableEvent;
+                            }
+                        }
+                    }
+                    continue;
+                }
+                if (sandboxedEnd) {
+                    assertSandboxProviderHandledToolCall({
+                        sandbox: handle.sandbox,
+                        toolPermissionBridge: this.toolPermissionBridge,
+                        sessionId,
+                        toolName: sandboxedEnd.toolName,
+                        toolCallId: sandboxedEnd.toolCallId,
+                        isError: sandboxedEnd.isError,
+                    });
+                    assertSandboxProviderHealthy(handle.sandbox);
+                    yield event;
+                    continue;
+                }
+                yield event;
+            }
+            await run;
+            if (failure)
+                throw failure;
+            if (activeSandboxedToolCalls.size > 0 || gatedEvents.length > 0) {
+                throw new Error("Sandboxed builtin tool execution ended without validation");
+            }
+            if (handle.closeWhenIdle) {
+                this.evict(sessionId, handle);
+            }
+            else {
+                this.touch(sessionId, handle);
+            }
+        }
+        catch (error) {
+            this.evict(sessionId, handle);
+            throw error;
+        }
+        finally {
+            if (installedInternalEmitter) {
+                handle.emitInternal = previousInternal;
+            }
+            stop();
+            signal?.removeEventListener("abort", onAbort);
+        }
+    }
+    async getOrCreateHandle(workspaceId, sessionId, fileMounts, context, credentialContext) {
+        if (this.closed)
+            throw new Error("PiSessionRunner is closed");
+        if (this.closedSessionIds.has(sessionId)) {
+            throw new Error(`Runtime session ${sessionId} is closed`);
+        }
+        const existing = this.sessions.get(sessionId);
+        if (existing) {
+            if (existing.closeWhenIdle && !existing.running) {
+                this.evict(sessionId, existing);
+            }
+            else {
+                return existing;
+            }
+        }
+        const pending = this.pendingSessions.get(sessionId);
+        if (pending)
+            return pending;
+        const created = (async () => {
+            const customToolContext = this.preparingSessionAgentContext(workspaceId, sessionId);
+            const agentRevision = this.opts.agentRevision?.(workspaceId, sessionId, customToolContext);
+            const revisionModel = agentRevision === undefined
+                ? undefined
+                : this.modelCatalog.resolve(agentRevision.model);
+            if (agentRevision !== undefined && revisionModel === undefined) {
+                throw new Error(`Pi model not available: ${agentRevision.model.provider}/${agentRevision.model.id}`);
+            }
+            if (agentRevision !== undefined &&
+                revisionModel !== undefined &&
+                !this.modelCatalog.hasConfiguredAuth(revisionModel)) {
+                throw new Error(`Credentials for model provider ${agentRevision.model.provider} are not configured on this deployment`);
+            }
+            const customToolNames = new Set((this.opts.customTools?.(workspaceId, sessionId, customToolContext) ?? []).map((tool) => tool.name));
+            const sandboxProviderFactory = this.resolveSandboxProviderFactory();
+            let sandbox;
+            let session;
+            let mcp = EMPTY_MCP;
+            try {
+                try {
+                    sandbox = await sandboxProviderFactory?.(workspaceId, sessionId, context);
+                }
+                catch (providerError) {
+                    this.opts.onSandboxEvent?.("error");
+                    throw providerError;
+                }
+                if (sandbox !== undefined)
+                    this.opts.onSandboxEvent?.("created");
+                const mounts = fileMounts ??
+                    (await this.opts.fileMountResolver?.(workspaceId, sessionId)) ??
+                    [];
+                if (mounts.length > 0) {
+                    if (typeof sandbox?.materializeFileResources !== "function") {
+                        throw new RuntimeUnsupportedSessionFileResourcesError();
+                    }
+                    await sandbox.materializeFileResources(mounts);
+                }
+                // MCP wiring is skipped entirely under a sessionFactory — the
+                // factory bypasses createPiSession, so tools could never reach Pi
+                // and a green test on this path would test nothing (plan 0122 §5).
+                if (this.sessionFactory === undefined) {
+                    mcp = await this.prepareMcp(workspaceId, sessionId, {
+                        ...customToolContext,
+                        ...(credentialContext === undefined ? {} : credentialContext),
+                    });
+                    for (const name of mcp.toolNames) {
+                        if (customToolNames.has(name)) {
+                            throw new Error(`MCP tool name collides with a custom tool: ${name}`);
+                        }
+                        customToolNames.add(name);
+                    }
+                }
+                assertNoSandboxCustomToolNameCollision(sandbox, customToolNames);
+                session =
+                    this.sessionFactory === undefined
+                        ? await this.createPiSession(workspaceId, sessionId, sandbox, customToolContext, agentRevision, revisionModel, mcp.toolDefinitions)
+                        : await this.sessionFactory(workspaceId, sessionId);
+                assertActiveToolSurface(session, this.enabledSandboxToolNames(workspaceId, sessionId, sandbox), customToolNames);
+            }
+            catch (error) {
+                this.disposeSandbox(sandbox);
+                this.disposeMcpConnections(mcp.connections);
+                session?.dispose();
+                throw error;
+            }
+            if (!session)
+                throw new Error("Pi session was not created");
+            const handle = {
+                session,
+                sandbox,
+                running: false,
+                needsFreshPromptAfterInterrupt: false,
+                // Retrying MCP failures use fresh-handle mechanics: dispose at
+                // idle so the NEXT turn re-runs connect/discovery (plan 0122 §4.6).
+                // Exhausted failures also close: unchanged fingerprints skip dialing
+                // on rebuild, while rotated credentials can reset the budget.
+                closeWhenIdle: mcp.pendingFailures.length > 0 || mcp.skippedExhausted,
+                lastUsedAt: this.now(),
+                timer: undefined,
+                customToolNames,
+                mcpToolNames: mcp.toolNames,
+                mcpConnections: mcp.connections,
+                pendingMcpFailures: [...mcp.pendingFailures],
+                mcpFailureEmittedServers: new Set(),
+                emitInternal: undefined,
+            };
+            if (this.closed || this.closedSessionIds.has(sessionId)) {
+                this.disposeSandbox(sandbox);
+                this.disposeMcpConnections(mcp.connections);
+                session.dispose();
+                this.pendingSessions.delete(sessionId);
+                throw new Error(this.closed
+                    ? "PiSessionRunner is closed"
+                    : `Runtime session ${sessionId} is closed`);
+            }
+            this.sessions.set(sessionId, handle);
+            this.pendingSessions.delete(sessionId);
+            this.scheduleEviction(sessionId, handle);
+            return handle;
+        })()
+            .catch((error) => {
+            this.pendingSessions.delete(sessionId);
+            throw error;
+        });
+        this.pendingSessions.set(sessionId, created);
+        return created;
+    }
+    /**
+     * Connect + discover the agent's declared MCP servers (plan 0122 §4.2).
+     * Failures are captured, never propagated: they queue on the handle and
+     * flush as session.error events at turn start (emitInternal does not exist
+     * yet at build time). Exhausted servers (count >= max, or MCP disabled by
+     * deployment) are skipped without dialing and without re-emitting.
+     */
+    async prepareMcp(workspaceId, sessionId, context) {
+        const mcpOpts = this.opts.mcp;
+        if (!mcpOpts)
+            return EMPTY_MCP;
+        const servers = mcpOpts.servers?.(workspaceId, sessionId, context) ?? [];
+        if (servers.length === 0)
+            return EMPTY_MCP;
+        const maxFailures = mcpOpts.maxConsecutiveFailures ?? DEFAULT_MCP_MAX_CONSECUTIVE_FAILURES;
+        let counts = this.mcpFailureCounts.get(sessionId);
+        if (!counts) {
+            counts = new Map();
+            this.mcpFailureCounts.set(sessionId, counts);
+        }
+        const connections = [];
+        const toolDefinitions = [];
+        const toolNames = new Set();
+        const pendingFailures = [];
+        let skippedExhausted = false;
+        // Dial concurrently (review 0122-M1: a serial loop let N slow servers
+        // stall the turn for N×timeout while pinning the sandbox); outcomes are
+        // processed in declaration order so failure events stay deterministic.
+        const dialable = [];
+        for (const server of servers) {
+            if (!mcpOpts.enabled) {
+                counts.set(server.name, {
+                    count: maxFailures,
+                    fingerprint: MCP_UNAUTHENTICATED_FINGERPRINT,
+                }); // emit once
+                pendingFailures.push({
+                    type: "oma.mcp_connection_failed",
+                    mcpServerName: server.name,
+                    message: "MCP is disabled by deployment configuration",
+                    retryStatus: "exhausted",
+                });
+                continue;
+            }
+            dialable.push(server);
+        }
+        const dialed = await Promise.all(dialable.map(async (server) => {
+            let credential;
+            try {
+                credential = await mcpOpts.credentials?.(workspaceId, sessionId, server.url, context);
+                const fingerprint = credential?.fingerprint ?? MCP_UNAUTHENTICATED_FINGERPRINT;
+                const count = currentMcpFailureCount(counts, server.name, fingerprint);
+                if (count >= maxFailures) {
+                    return { server, credential, fingerprint, count, skipped: true };
+                }
+                const connection = await McpConnection.connect(server, {
+                    fetch: this.mcpFetch,
+                    ...(credential === undefined
+                        ? {}
+                        : { credential }),
+                    ...(mcpOpts.operationTimeoutMs === undefined
+                        ? {}
+                        : { operationTimeoutMs: mcpOpts.operationTimeoutMs }),
+                });
+                return {
+                    server,
+                    credential,
+                    fingerprint: connection.credential?.fingerprint ?? MCP_UNAUTHENTICATED_FINGERPRINT,
+                    count,
+                    connection,
+                };
+            }
+            catch (error) {
+                const finalFingerprint = credential?.fingerprint ?? MCP_UNAUTHENTICATED_FINGERPRINT;
+                return {
+                    server,
+                    fingerprint: finalFingerprint,
+                    count: currentMcpFailureCount(counts, server.name, finalFingerprint),
+                    failure: error instanceof Error ? error.message : String(error),
+                    errorType: mcpConnectErrorType(error),
+                };
+            }
+        }));
+        for (const outcome of dialed) {
+            const { server, count } = outcome;
+            if ("skipped" in outcome && outcome.skipped) {
+                skippedExhausted = true;
+                continue;
+            }
+            if (!("connection" in outcome) || outcome.connection === undefined) {
+                const failures = count + 1;
+                counts.set(server.name, { count: failures, fingerprint: outcome.fingerprint });
+                const errorType = "errorType" in outcome ? outcome.errorType : undefined;
+                mcpOpts.onConnection?.(errorType === "mcp_authentication_failed_error"
+                    ? "auth_failed"
+                    : "connect_failed");
+                pendingFailures.push({
+                    type: "oma.mcp_connection_failed",
+                    errorType,
+                    mcpServerName: server.name,
+                    message: mcpFailureMessage(errorType),
+                    retryStatus: failures >= maxFailures ? "exhausted" : "retrying",
+                });
+                continue;
+            }
+            const connection = outcome.connection;
+            counts.set(server.name, { count: 0, fingerprint: outcome.fingerprint });
+            mcpOpts.onConnection?.("connected");
+            connections.push(connection);
+            const definitions = createMcpToolDefinitions({
+                workspaceId,
+                sessionId,
+                connection,
+                permissionBridge: this.toolPermissionBridge,
+                getEmitter: () => this.sessions.get(sessionId)?.emitInternal,
+                ...(mcpOpts.access === undefined ? {} : { access: mcpOpts.access }),
+                ...(context === undefined ? {} : { agentContext: context }),
+                ...(mcpOpts.outputCapBytes === undefined
+                    ? {}
+                    : { outputCapBytes: mcpOpts.outputCapBytes }),
+                ...(mcpOpts.onToolCall === undefined
+                    ? {}
+                    : { onToolCall: mcpOpts.onToolCall }),
+                // Mid-call transport failure is connection-class (review 0122-M1,
+                // Codex-adv): count it against the retry budget, surface the
+                // structured mcp_connection_failed_error (once per server per
+                // handle), and reconnect next turn via fresh-handle mechanics.
+                onTransportFailure: (failedServerName, error) => {
+                    const fingerprint = connection.credential?.fingerprint ?? MCP_UNAUTHENTICATED_FINGERPRINT;
+                    const failures = currentMcpFailureCount(counts, failedServerName, fingerprint) + 1;
+                    counts.set(failedServerName, { count: failures, fingerprint });
+                    const handle = this.sessions.get(sessionId);
+                    if (!handle)
+                        return;
+                    handle.closeWhenIdle = true;
+                    if (handle.mcpFailureEmittedServers.has(failedServerName))
+                        return;
+                    handle.mcpFailureEmittedServers.add(failedServerName);
+                    handle.emitInternal?.({
+                        type: "oma.mcp_connection_failed",
+                        errorType: mcpConnectErrorType(error),
+                        mcpServerName: failedServerName,
+                        message: mcpFailureMessage(mcpConnectErrorType(error)),
+                        retryStatus: failures >= maxFailures ? "exhausted" : "retrying",
+                    });
+                },
+            });
+            for (const definition of definitions) {
+                if (toolNames.has(definition.name)) {
+                    throw new Error(`MCP tool name collision across servers: ${definition.name}`);
+                }
+                toolNames.add(definition.name);
+                toolDefinitions.push(definition);
+            }
+        }
+        return {
+            connections,
+            toolDefinitions,
+            toolNames,
+            pendingFailures,
+            skippedExhausted,
+        };
+    }
+    disposeMcpConnections(connections) {
+        for (const connection of connections) {
+            void connection.close();
+        }
+    }
+    async createPiSession(workspaceId, sessionId, sandbox, context, revision, revisionModel, mcpTools = []) {
+        const provider = revision?.model.provider ?? this.modelCatalog.defaultModel.provider;
+        const modelId = revision?.model.id ?? this.modelCatalog.defaultModel.id;
+        const model = revisionModel ?? this.modelCatalog.resolve({ provider, id: modelId });
+        if (!model) {
+            throw new Error(`Pi model not available: ${provider}/${modelId}`);
+        }
+        const customToolNames = (this.opts.customTools?.(workspaceId, sessionId, context) ?? []).map((tool) => tool.name);
+        const sandboxTools = this.enabledSandboxTools(workspaceId, sessionId, sandbox);
+        const customTools = [
+            ...sandboxTools,
+            ...this.customToolBridge.createTools(workspaceId, sessionId, () => this.sessions.get(sessionId)?.emitInternal, context),
+            ...mcpTools,
+        ];
+        const mcpToolNames = mcpTools.map((tool) => tool.name);
+        const { session } = await createAgentSession({
+            model,
+            thinkingLevel: this.opts.thinkingLevel ?? "off",
+            noTools: "builtin",
+            tools: sandbox
+                ? [
+                    ...sandboxTools.map((tool) => tool.name),
+                    ...customToolNames,
+                    ...mcpToolNames,
+                ]
+                : [...customToolNames, ...mcpToolNames],
+            customTools,
+            authStorage: this.authStorage,
+            modelRegistry: this.modelRegistry,
+            sessionManager: SessionManager.inMemory(),
+            resourceLoader: await this.createResourceLoader(workspaceId, sessionId, revision?.system ?? undefined),
+        });
+        return session;
+    }
+    async createResourceLoader(workspaceId, sessionId, systemPrompt) {
+        const skills = this.preparingSessionSkills.get(sessionId) ?? this.opts.skills?.(workspaceId, sessionId) ?? [];
+        const loader = buildSessionSkillsResourceLoader(skills, systemPrompt);
+        // createAgentSession only reload()s a loader it constructs itself; a
+        // caller-provided one is used as-is. skillsOverride runs inside reload(),
+        // so without this the model never sees <available_skills> even though the
+        // skill files are mounted in the sandbox.
+        await loader.reload();
+        return loader;
+    }
+    preparingSessionAgentContext(workspaceId, sessionId) {
+        const preparing = this.preparingSessionAgents.get(sessionId);
+        if (preparing?.workspaceId !== workspaceId)
+            return undefined;
+        return {
+            agentId: preparing.agentId,
+            agentVersion: preparing.agentVersion,
+        };
+    }
+    resolveSandboxProviderFactory() {
+        // Direct factories are trusted internal wiring for tests and already-built
+        // providers. Never derive this option from public request, agent, or prompt
+        // input; untrusted provider choice must go through sandboxProviderSelection.
+        if (this.opts.sandboxProviderFactory)
+            return this.opts.sandboxProviderFactory;
+        return resolveSandboxProviderFactory(this.opts.sandboxProviderSelection, this.opts.sandboxProviderSelectionOptions);
+    }
+    touch(sessionId, handle) {
+        handle.lastUsedAt = this.now();
+        this.scheduleEviction(sessionId, handle);
+    }
+    enabledSandboxTools(workspaceId, sessionId, sandbox) {
+        if (!sandbox)
+            return [];
+        const toolsByName = new Map(sandbox.tools.map((tool) => [tool.name, tool]));
+        const out = [];
+        for (const toolName of sandbox.toolNames) {
+            const access = this.toolPermissionBridge.access(workspaceId, sessionId, toolName);
+            if (!access.enabled)
+                continue;
+            const tool = toolsByName.get(toolName);
+            if (!tool)
+                continue;
+            out.push(this.toolPermissionBridge.wrapTool(workspaceId, sessionId, toolName, tool, () => this.sessions.get(sessionId)?.emitInternal));
+        }
+        return out;
+    }
+    enabledSandboxToolNames(workspaceId, sessionId, sandbox) {
+        if (!sandbox)
+            return new Set();
+        const out = new Set();
+        for (const toolName of sandbox.toolNames) {
+            const access = this.toolPermissionBridge.access(workspaceId, sessionId, toolName);
+            if (access.enabled)
+                out.add(toolName);
+        }
+        return out;
+    }
+    scheduleEviction(sessionId, handle) {
+        if (handle.timer)
+            clearTimeout(handle.timer);
+        if (this.idleTtlMs <= 0)
+            return;
+        handle.timer = setTimeout(() => {
+            if (handle.running) {
+                this.scheduleEviction(sessionId, handle);
+                return;
+            }
+            if (handle.closeWhenIdle) {
+                this.evict(sessionId, handle);
+                return;
+            }
+            if (this.now() - handle.lastUsedAt < this.idleTtlMs) {
+                this.scheduleEviction(sessionId, handle);
+                return;
+            }
+            this.evict(sessionId, handle);
+        }, this.idleTtlMs);
+    }
+    async closeHandle(sessionId, handle) {
+        if (handle.running) {
+            handle.closeWhenIdle = true;
+        }
+        try {
+            await handle.session.abort();
+        }
+        catch {
+            // Disposal below is the authoritative cleanup path.
+        }
+        this.evict(sessionId, handle);
+    }
+    async interruptHandle(sessionId, handle) {
+        handle.session.clearQueue?.();
+        await handle.session.abort();
+        handle.session.clearQueue?.();
+        handle.running = false;
+        handle.needsFreshPromptAfterInterrupt = true;
+        this.touch(sessionId, handle);
+    }
+    async waitForPendingInterrupt(sessionId) {
+        const interrupt = this.pendingInterrupts.get(sessionId);
+        if (!interrupt)
+            return;
+        try {
+            await interrupt;
+        }
+        catch {
+            // interruptSession callers observe abort errors; message delivery waits only
+            // for the abort window to close before deciding prompt vs follow-up.
+        }
+    }
+    evict(sessionId, handle) {
+        if (handle.timer)
+            clearTimeout(handle.timer);
+        if (this.sessions.get(sessionId) === handle) {
+            this.sessions.delete(sessionId);
+        }
+        this.customToolBridge.rejectSession(sessionId, new Error("Runtime session evicted"));
+        this.toolPermissionBridge.rejectSession(sessionId, new Error("Runtime session evicted"));
+        this.disposeSandbox(handle.sandbox);
+        this.disposeMcpConnections(handle.mcpConnections);
+        handle.session.dispose();
+    }
+    disposeSandbox(sandbox) {
+        if (sandbox === undefined)
+            return;
+        sandbox.dispose();
+        this.opts.onSandboxEvent?.("disposed");
+    }
+}
+function assertActiveToolSurface(session, sandboxToolNames, customToolNames) {
+    if (typeof session.getActiveToolNames !== "function") {
+        throw new Error("Pi runtime session does not expose active tool names");
+    }
+    const activeToolNames = session.getActiveToolNames();
+    const expectedToolNames = new Set(customToolNames);
+    for (const name of sandboxToolNames)
+        expectedToolNames.add(name);
+    for (const name of activeToolNames) {
+        if (expectedToolNames.has(name))
+            continue;
+        throw new Error(`Unexpected active Pi tool after sandbox setup: ${name}`);
+    }
+}
+function assertNoSandboxCustomToolNameCollision(sandbox, customToolNames) {
+    if (!sandbox)
+        return;
+    for (const name of customToolNames) {
+        if (!sandbox.toolNames.has(name))
+            continue;
+        throw new Error(`Custom tool name conflicts with sandbox builtin: ${name}`);
+    }
+}
+function updateRunning(handle, event) {
+    if (typeof event !== "object" || event === null)
+        return;
+    const type = event.type;
+    if (type === "agent_start")
+        handle.running = true;
+    if (type === "agent_end")
+        handle.running = false;
+}
+function isAlreadyProcessing(error) {
+    return (error instanceof Error &&
+        error.message.includes(ALREADY_PROCESSING_MESSAGE));
+}
+function isInternalRuntimeEvent(event) {
+    if (typeof event !== "object" || event === null)
+        return false;
+    const type = event.type;
+    return (type === "oma.custom_tool_use" ||
+        type === "oma.tool_permission_use" ||
+        type === "oma.tool_permission_with_model_end" ||
+        type === "oma.mcp_tool_use" ||
+        type === "oma.mcp_tool_with_model_end" ||
+        type === "oma.mcp_tool_result" ||
+        type === "oma.mcp_connection_failed");
+}
+function currentMcpFailureCount(counts, serverName, fingerprint) {
+    const existing = counts.get(serverName);
+    if (!existing || existing.fingerprint !== fingerprint) {
+        counts.set(serverName, { count: 0, fingerprint });
+        return 0;
+    }
+    return existing.count;
+}
+function mcpConnectErrorType(error) {
+    const code = error.code;
+    return code === 401 || code === 403
+        ? "mcp_authentication_failed_error"
+        : "mcp_connection_failed_error";
+}
+function mcpFailureMessage(errorType) {
+    return errorType === "mcp_authentication_failed_error"
+        ? "MCP authentication failed"
+        : "MCP connection failed";
+}
+const EMPTY_MCP = {
+    connections: [],
+    toolDefinitions: [],
+    toolNames: new Set(),
+    pendingFailures: [],
+    skippedExhausted: false,
+};
+/** message_end toolCall blocks whose pi-name is an MCP tool of this handle. Exported for direct contract tests (review 0122-M1, Sonnet 1). */
+export function mcpToolCallsInMessage(mcpToolNames, event) {
+    if (mcpToolNames.size === 0)
+        return [];
+    if (typeof event !== "object" || event === null)
+        return [];
+    const typed = event;
+    if (typed.type !== "message_end")
+        return [];
+    if (typeof typed.message !== "object" || typed.message === null)
+        return [];
+    const message = typed.message;
+    if (message.role !== "assistant" || !Array.isArray(message.content))
+        return [];
+    const out = [];
+    for (const block of message.content) {
+        if (typeof block !== "object" || block === null)
+            continue;
+        const toolCall = block;
+        if (toolCall.type !== "toolCall")
+            continue;
+        if (typeof toolCall.id !== "string" || typeof toolCall.name !== "string") {
+            continue;
+        }
+        if (!mcpToolNames.has(toolCall.name))
+            continue;
+        out.push({ toolCallId: toolCall.id });
+    }
+    return out;
+}
+/** MCP-aware variant of takeMessageEndForToolCall (plan 0122 §4.4 step 2). Exported for direct contract tests. */
+export function takeMessageEndForMcpToolCall(mcpToolNames, eventQueues, piToolCallId) {
+    for (const events of eventQueues) {
+        let suppressedPiToolCallIds = [];
+        const index = events.findIndex((event) => {
+            const calls = mcpToolCallsInMessage(mcpToolNames, event);
+            if (!calls.some((call) => call.toolCallId === piToolCallId))
+                return false;
+            suppressedPiToolCallIds = calls.map((call) => call.toolCallId);
+            return true;
+        });
+        if (index === -1)
+            continue;
+        const [event] = events.splice(index, 1);
+        return { event, suppressedPiToolCallIds };
+    }
+    return undefined;
+}
+function sandboxedToolEvent(sandbox, event, eventType) {
+    if (!sandbox || typeof event !== "object" || event === null)
+        return undefined;
+    const typed = event;
+    if (typed.type !== eventType)
+        return undefined;
+    if (typeof typed.toolName !== "string")
+        return undefined;
+    if (typeof typed.toolCallId !== "string")
+        return undefined;
+    if (!sandbox.toolNames.has(typed.toolName))
+        return undefined;
+    return {
+        toolName: typed.toolName,
+        toolCallId: typed.toolCallId,
+        isError: typed.isError === true,
+    };
+}
+function sandboxedToolCallsInMessage(sandbox, event) {
+    if (!sandbox || typeof event !== "object" || event === null)
+        return [];
+    const typed = event;
+    if (typed.type !== "message_end")
+        return [];
+    if (typeof typed.message !== "object" || typed.message === null)
+        return [];
+    const message = typed.message;
+    if (message.role !== "assistant" || !Array.isArray(message.content))
+        return [];
+    const out = [];
+    for (const block of message.content) {
+        if (typeof block !== "object" || block === null)
+            continue;
+        const toolCall = block;
+        if (toolCall.type !== "toolCall")
+            continue;
+        if (typeof toolCall.id !== "string" || typeof toolCall.name !== "string") {
+            continue;
+        }
+        if (!sandbox.toolNames.has(toolCall.name))
+            continue;
+        out.push({
+            toolName: toolCall.name,
+            toolCallId: toolCall.id,
+        });
+    }
+    return out;
+}
+function takeMessageEndForToolCall(sandbox, eventQueues, piToolCallId) {
+    for (const events of eventQueues) {
+        let suppressedPiToolCallIds = [];
+        const index = events.findIndex((event) => {
+            const calls = sandboxedToolCallsInMessage(sandbox, event);
+            if (!calls.some((call) => call.toolCallId === piToolCallId))
+                return false;
+            suppressedPiToolCallIds = calls.map((call) => call.toolCallId);
+            return true;
+        });
+        if (index === -1)
+            continue;
+        const [event] = events.splice(index, 1);
+        return { event, suppressedPiToolCallIds };
+    }
+    return undefined;
+}
+function assertSandboxProviderHandledToolCall(opts) {
+    if (!opts.sandbox)
+        return;
+    if (opts.sandbox.invocations.toolCallIds[opts.toolName].has(opts.toolCallId)) {
+        return;
+    }
+    if (opts.isError &&
+        opts.toolPermissionBridge.permissionDenied(opts.sessionId, opts.toolCallId)) {
+        return;
+    }
+    throw new Error(`Sandboxed builtin tool ${opts.toolName} executed without invoking the sandbox provider`);
+}
+function assertSandboxProviderHealthy(sandbox) {
+    if (sandbox?.isPoisoned?.() !== true)
+        return;
+    throw new Error("Sandbox provider was poisoned during tool execution");
+}