@vibesdotdev/mcp 0.0.0-stage → 1.0.0-rc.1

package/dist/adapters/mcp/mcp-http-session.js

@@ -0,0 +1,797 @@
+import { rpcMessage, jsonRpcError, jsonRpcRequestId } from "./json-rpc.js";
+export { jsonRpcError, jsonRpcRequestId } from "./json-rpc.js";
+/**
+ * Shared MCP streamable HTTP session handler (Bun.serve and serverless isolate hosts).
+ */
+import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
+import { CaughtFailureSchema, isCapabilityError, settle, settleNow, valueFreeFailure } from '@vibesdotdev/kernel';
+import { JsonObjectSchema, JsonValueSchema } from '@vibesdotdev/kernel/schemas/json';
+import * as z from 'zod/v4';
+import { resolveSessionIdFromWebHeaders } from "../session-id.js";
+import { wrapTransportWithSchemaTightening } from "../zod-mcp.js";
+import { MCP_WORKSPACE_HEADER, parseMcpRequestScope, runWithMcpRequestScope } from "./request-context.js";
+import { connectionIdentityFromMeta, RELAY_ATTESTATION_SOURCE } from "./connection-identity.js";
+import { agentForClientName } from "./serve-identity.js";
+const InitializeParamsSchema = z.object({
+    clientInfo: z.object({
+        name: z.string(),
+        version: z.string().optional().catch(undefined)
+    }).loose(),
+    _meta: JsonObjectSchema.optional().catch(undefined)
+}).loose();
+const InitializeMessageSchema = z.object({
+    method: z.literal('initialize'),
+    params: InitializeParamsSchema
+}).loose();
+/** The first JSON-RPC message: a batch's first element, or the body itself. */
+function jsonString(value) {
+    const parsed = z.string().safeParse(value);
+    return parsed.success ? parsed.data : undefined;
+}
+function initializeParams(body) {
+    const parsed = InitializeMessageSchema.safeParse(rpcMessage(body));
+    if (!parsed.success)
+        return undefined;
+    return { clientInfo: parsed.data.params.clientInfo, _meta: parsed.data.params._meta };
+}
+/**
+ * The connection an `initialize` opens. `attested` is whether it presented the
+ * host's relay secret. An attested relay declares its launch identity in
+ * `_meta` (and a harness clientInfo name implies its agent); that identity is
+ * verified. Any other loopback client's `_meta` identity stays a declaration,
+ * which admission refuses, and its clientInfo name implies nothing: only
+ * verified identity reaches the connection's clientInfo, which session binding
+ * reads.
+ */
+function initializeConnection(body, attested, source) {
+    const params = initializeParams(body);
+    if (!params)
+        return {};
+    const declared = connectionIdentityFromMeta(params._meta);
+    const impliedAgent = attested && !declared?.agentId ? agentForClientName(source, params.clientInfo.name) : undefined;
+    const identity = impliedAgent
+        ? Object.freeze({ ...declared, agentId: impliedAgent })
+        : declared;
+    const verified = attested && identity ? Object.freeze({ source: RELAY_ATTESTATION_SOURCE, caller: identity }) : undefined;
+    return {
+        identity: identity || undefined,
+        verified: verified || undefined,
+        clientInfo: {
+            name: params.clientInfo.name,
+            version: params.clientInfo.version,
+            agentId: verified?.caller.agentId || undefined,
+            harnessSessionId: verified?.caller.harnessSessionId || undefined
+        }
+    };
+}
+/**
+ * SESSION POOL SIZING — why these numbers, and what the old ones cost.
+ *
+ * This host serves two client shapes at once. Short-lived ones (the external
+ * hooks runner) handshake, call one tool, and `DELETE` — verified: a DELETE
+ * does terminate the session and the count drops. Long-lived ones (an agent's
+ * interactive MCP client) attach for hours and are IDLE most of that time,
+ * because an agent spends its time thinking, not calling tools.
+ *
+ * A 50-session cap with LRU eviction is exactly wrong for that mix: "least
+ * recently active" selects the interactive clients — the hook sessions are
+ * always the freshest thing in the pool. Measured on this machine over 53 h of
+ * uptime: 7,291 sessions opened, 483 cap evictions. Each one silently killed a
+ * live agent's session; every later request on it then failed, permanently,
+ * with no recovery path. That is a coordination outage, and AGENT-CONSTITUTION
+ * names a failing coordination surface the highest-priority defect there is.
+ *
+ * So: the cap becomes a backstop rather than a routine event (256), idle TTL
+ * does the reclaiming (halved to 2 h, swept every minute instead of every
+ * five), and a session that was active in the last minute is never sacrificed
+ * to admit a new one — the host refuses the new session instead, which is a
+ * loud, recoverable failure on a client that is still connected and retrying,
+ * not a silent one on a client that has merely gone quiet.
+ */
+const DEFAULT_MAX_SESSIONS = 256;
+const DEFAULT_SESSION_TTL_MS = 2 * 60 * 60 * 1000;
+const DEFAULT_MIN_EVICTION_IDLE_MS = 60 * 1000;
+const SESSION_SWEEP_INTERVAL_MS = 60 * 1000;
+const DEFAULT_DURABLE_RESTORE_DEADLINE_MS = 15 * 1000;
+/**
+ * A session's SSE streams write a keep-alive comment this often. The Bun
+ * listener closes a quiet connection on Bun.serve's default 10 s idleTimeout,
+ * checked on a coarse timer, so a cut can land from about 8 s. The SDK's
+ * default interval is 15 s, so a relay's quiet notification stream was cut
+ * before its first frame and every relay lost its host about every 10 s.
+ */
+const SSE_KEEP_ALIVE_MS = 5 * 1000;
+const InitializeRequestSchema = z.object({
+    jsonrpc: z.literal('2.0'),
+    method: z.literal('initialize')
+}).loose();
+function isInitializeRequest(body) {
+    return InitializeRequestSchema.safeParse(body).success;
+}
+/**
+ * Session lifecycle binds cross SQLite-backed participant/session authority.
+ * Serialize both the current receipt replay and the legacy authored-init replay
+ * used by already-running relays from before the durable receipt cutover. An
+ * exact status join is also a bind, even when an older relay lacks receiptOnly.
+ * Ordinary tools and ambient status reads never enter this lane.
+ */
+const SessionArgumentsSchema = z.object({
+    action: z.string().optional(),
+    sessionId: JsonValueSchema.optional(),
+    participantId: JsonValueSchema.optional(),
+    receiptOnly: JsonValueSchema.optional(),
+    newSession: JsonValueSchema.optional()
+}).loose();
+const SessionCallSchema = z.object({
+    method: z.string(),
+    params: z.object({
+        name: z.string(),
+        arguments: SessionArgumentsSchema.optional()
+    }).loose()
+}).loose();
+function sessionCall(body) {
+    const parsed = SessionCallSchema.safeParse(rpcMessage(body));
+    return parsed.success ? parsed.data : undefined;
+}
+function isDurableSessionRestoreRequest(body) {
+    const candidate = sessionCall(body);
+    const args = candidate?.params.arguments;
+    return (candidate?.method === 'tools/call' &&
+        candidate.params.name === 'session' &&
+        (args?.action === 'init' ||
+            (args?.action === 'status' &&
+                jsonString(args.sessionId) !== undefined &&
+                jsonString(args.participantId) !== undefined)));
+}
+function durableRestoreIdentity(body) {
+    const candidate = sessionCall(body);
+    if (candidate?.method !== 'tools/call' || candidate.params.name !== 'session')
+        return null;
+    const args = candidate.params.arguments;
+    const sessionId = jsonString(args?.sessionId);
+    const participantId = jsonString(args?.participantId);
+    if (args?.action === 'status' && args.receiptOnly === true && sessionId !== undefined && participantId !== undefined) {
+        return {
+            key: `status:${participantId}:${sessionId}`,
+            readOnly: true
+        };
+    }
+    if (args?.action === 'init' && args.newSession !== true && participantId !== undefined) {
+        return {
+            key: `init:${participantId}:${sessionId ?? 'active'}`,
+            readOnly: false
+        };
+    }
+    return null;
+}
+function durableRestoreRequest(body) {
+    const candidate = sessionCall(body);
+    const args = candidate?.params.arguments;
+    if (candidate?.method !== 'tools/call' ||
+        candidate.params.name !== 'session' ||
+        (args?.action !== 'init' && args?.action !== 'status')) {
+        return null;
+    }
+    return {
+        action: args.action,
+        sessionId: jsonString(args.sessionId),
+        participantId: jsonString(args.participantId),
+        receiptOnly: args.receiptOnly === true,
+        newSession: args.newSession === true
+    };
+}
+function asCanonicalReceiptRestore(body, receipt) {
+    const rewrite = (candidate) => {
+        const record = JsonObjectSchema.safeParse(candidate);
+        if (!record.success)
+            return candidate;
+        const params = JsonObjectSchema.safeParse(record.data.params);
+        if (!params.success)
+            return candidate;
+        return {
+            ...record.data,
+            params: {
+                ...params.data,
+                name: 'session',
+                arguments: {
+                    action: 'status',
+                    sessionId: receipt.sessionId,
+                    participantId: receipt.participantId,
+                    receiptOnly: true
+                }
+            }
+        };
+    };
+    if (body === undefined)
+        return undefined;
+    return Array.isArray(body) ? body.map(rewrite) : rewrite(body);
+}
+function responseReceipt(body, log) {
+    const dataLines = body
+        .split('\n')
+        .filter((line) => line.startsWith('data:'))
+        .map((line) => line.slice(5).trim());
+    const payloads = dataLines.length > 0 ? dataLines : [body];
+    for (const payload of payloads) {
+        const read = settleNow(() => JsonValueSchema.parse(JSON.parse(payload)));
+        if (!read.ok) {
+            log.debug('restore response payload is not JSON; skipping', { error: valueFreeFailure(read.cause) });
+            continue;
+        }
+        const parsed = z.object({
+            result: z.object({
+                structuredContent: z.object({
+                    sessionId: JsonValueSchema.optional(),
+                    session: z.object({ id: JsonValueSchema.optional() }).loose().optional(),
+                    participant: z.object({ id: JsonValueSchema.optional() }).loose().optional()
+                }).loose().optional()
+            }).loose().optional()
+        }).loose().safeParse(read.value);
+        if (!parsed.success)
+            continue;
+        const content = parsed.data.result?.structuredContent;
+        const sessionId = jsonString(content?.sessionId ?? content?.session?.id);
+        const participantId = jsonString(content?.participant?.id);
+        if (sessionId !== undefined && participantId !== undefined)
+            return { sessionId, participantId };
+    }
+    return undefined;
+}
+function replayBufferedResponse(buffered, requestId, log) {
+    const rewrite = (payload) => {
+        const read = settleNow(() => JsonObjectSchema.parse(JSON.parse(payload)));
+        if (!read.ok) {
+            log.debug('SSE payload is not JSON; forwarded unrewritten', { error: valueFreeFailure(read.cause) });
+            return payload;
+        }
+        const parsed = read.value;
+        if ('id' in parsed)
+            return JSON.stringify({ ...parsed, id: requestId });
+        return JSON.stringify(parsed);
+    };
+    const contentType = new Headers(buffered.headers).get('content-type') ?? '';
+    const body = contentType.includes('text/event-stream')
+        ? buffered.body
+            .split('\n')
+            .map((line) => (line.startsWith('data:') ? `data: ${rewrite(line.slice(5).trim())}` : line))
+            .join('\n')
+        : rewrite(buffered.body);
+    return new Response(body, {
+        status: buffered.status,
+        statusText: buffered.statusText,
+        headers: buffered.headers
+    });
+}
+function withSessionHeader(req, sessionId) {
+    if (req.headers.get('mcp-session-id') === sessionId)
+        return req;
+    const headers = new Headers(req.headers);
+    headers.set('mcp-session-id', sessionId);
+    return new Request(req, { headers });
+}
+export function createMcpHttpSessionHandler(options) {
+    /** A request naming a workspace this host cannot serve is refused, never run without it. */
+    const refuseUnservedWorkspace = (scope, body) => scope.workspacePath && !options.runInRequestWorkspace
+        ? jsonRpcError(400, -32602, `This MCP host serves no per-request workspace; drop the ${MCP_WORKSPACE_HEADER} header.`, { id: jsonRpcRequestId(body) })
+        : null;
+    const sessions = new Map();
+    const startedAt = Date.now();
+    const maxSessions = options.maxSessions ?? DEFAULT_MAX_SESSIONS;
+    const sessionTtlMs = options.sessionTtlMs ?? DEFAULT_SESSION_TTL_MS;
+    const minEvictionIdleMs = options.minEvictionIdleMs ?? DEFAULT_MIN_EVICTION_IDLE_MS;
+    const durableRestoreDeadlineMs = options.durableRestoreDeadlineMs ?? DEFAULT_DURABLE_RESTORE_DEADLINE_MS;
+    const maxParallelReceiptRestores = options.maxParallelReceiptRestores ?? 64;
+    const now = options.now ?? Date.now;
+    const log = options.logger.child('http-session');
+    /**
+     * Sessions this host terminated, and why. A client whose session was reaped
+     * cannot tell that from "wrong id" unless the host remembers, and "your
+     * session expired, re-initialize" is the difference between a reconnect and
+     * an agent concluding the tool is broken.
+     */
+    const terminatedSessions = new Map();
+    const TERMINATED_MEMORY = 512;
+    let restoreQueueDepth = 0;
+    let restoreTail = Promise.resolve();
+    const activeRestoreStartedAt = new Map();
+    let activeReceiptRestores = 0;
+    let receiptRestoreExecutions = 0;
+    let mutationRestoreExecutions = 0;
+    let legacyRestoreAttempts = 0;
+    let legacyRestoreResolved = 0;
+    let legacyRestoreUnresolved = 0;
+    const receiptRestoreWaiters = [];
+    const restoreCache = new Map();
+    const RESTORE_CACHE_TTL_MS = 60_000;
+    async function acquireReceiptRestoreSlot() {
+        if (activeReceiptRestores < maxParallelReceiptRestores) {
+            activeReceiptRestores += 1;
+            return;
+        }
+        await new Promise((resolve) => receiptRestoreWaiters.push(resolve));
+        activeReceiptRestores += 1;
+    }
+    function releaseReceiptRestoreSlot() {
+        activeReceiptRestores -= 1;
+        receiptRestoreWaiters.shift()?.();
+    }
+    /**
+     * Exact receipt restores are read-only Session authority checks followed by
+     * a transport-local memory bind. Run those in a bounded parallel lane so a
+     * real fleet of distinct relays does not spend minutes behind one global
+     * queue. Legacy init/status requests can still mutate authority and therefore
+     * retain the single-writer lane.
+     */
+    async function admitDurableRestore(identity, transportSessionId, requestId, operation) {
+        // A cached receipt is safe only when this host can revalidate Session
+        // authority and publish the replacement transport's memory-only binding.
+        const cacheIdentity = options.bindCachedDurableRestore ? identity : null;
+        const cached = cacheIdentity ? restoreCache.get(cacheIdentity.key) : undefined;
+        if (cached &&
+            (cached.completedAt === undefined || now() - cached.completedAt < RESTORE_CACHE_TTL_MS)) {
+            const buffered = await cached.promise;
+            if (buffered.receipt) {
+                await options.bindCachedDurableRestore?.({
+                    transportSessionId,
+                    ...buffered.receipt
+                });
+            }
+            return replayBufferedResponse(buffered, requestId, log);
+        }
+        if (cacheIdentity && cached)
+            restoreCache.delete(cacheIdentity.key);
+        const run = (async () => {
+            restoreQueueDepth += 1;
+            let release;
+            if (identity?.readOnly) {
+                receiptRestoreExecutions += 1;
+                await acquireReceiptRestoreSlot();
+                release = releaseReceiptRestoreSlot;
+            }
+            else {
+                mutationRestoreExecutions += 1;
+                const preceding = restoreTail;
+                let releaseWriter;
+                restoreTail = new Promise((resolve) => {
+                    releaseWriter = resolve;
+                });
+                await preceding;
+                release = releaseWriter;
+            }
+            const restoreToken = Symbol('durable-restore');
+            activeRestoreStartedAt.set(restoreToken, now());
+            try {
+                const response = await operation();
+                // Streamable HTTP returns the Response shell before its tool handler has
+                // settled. Buffer this one tiny status receipt inside admission; otherwise
+                // the lane appears free while the storage-heavy restore is still running.
+                const body = await response.text();
+                return {
+                    status: response.status,
+                    statusText: response.statusText,
+                    headers: [...response.headers.entries()],
+                    body,
+                    receipt: responseReceipt(body, log)
+                };
+            }
+            finally {
+                activeRestoreStartedAt.delete(restoreToken);
+                restoreQueueDepth -= 1;
+                try {
+                    if (!identity?.readOnly) {
+                        // Promise-only handoff keeps draining microtasks and can still starve
+                        // node:http. One runtime-owned timer turn admits /health before the
+                        // next writer; disposal cancels it, and the lane is released either way.
+                        await options.lifecycle.delay(0);
+                    }
+                }
+                finally {
+                    release();
+                }
+            }
+        })();
+        if (cacheIdentity) {
+            const entry = { promise: run };
+            restoreCache.set(cacheIdentity.key, entry);
+            run.then((buffered) => {
+                if (buffered.receipt)
+                    entry.completedAt = now();
+                else if (restoreCache.get(cacheIdentity.key) === entry) {
+                    restoreCache.delete(cacheIdentity.key);
+                }
+            }, (cause) => {
+                log.debug('durable restore failed; dropping the cached receipt', {
+                    error: valueFreeFailure(CaughtFailureSchema.parse(cause))
+                });
+                if (restoreCache.get(cacheIdentity.key) === entry)
+                    restoreCache.delete(cacheIdentity.key);
+                return cause;
+            });
+            while (restoreCache.size > maxSessions * 2) {
+                const oldest = restoreCache.entries().next();
+                if (oldest.done || oldest.value[1].completedAt === undefined)
+                    break;
+                restoreCache.delete(oldest.value[0]);
+            }
+        }
+        const buffered = await run;
+        return replayBufferedResponse(buffered, requestId, log);
+    }
+    function rememberTerminated(sessionId, reason) {
+        terminatedSessions.set(sessionId, { at: Date.now(), reason });
+        while (terminatedSessions.size > TERMINATED_MEMORY) {
+            const oldest = terminatedSessions.keys().next();
+            if (oldest.done)
+                break;
+            terminatedSessions.delete(oldest.value);
+        }
+    }
+    /** Close a server; a failed close is reported, never dropped. */
+    function closeServer(server, sessionId, reason) {
+        void settle(() => server.close()).then((closed) => {
+            if (closed.ok)
+                return;
+            log.warn('MCP server close failed', {
+                sessionId,
+                reason,
+                error: valueFreeFailure(closed.cause)
+            });
+        });
+    }
+    function dropSession(sessionId, reason) {
+        const session = sessions.get(sessionId);
+        if (!session)
+            return;
+        session.releaseMembership?.();
+        sessions.delete(sessionId);
+        rememberTerminated(sessionId, reason);
+        closeServer(session.server, sessionId, reason);
+    }
+    /** Drop every session idle past the TTL. */
+    let lastSweepAt = Date.now();
+    function expireIdleSessions() {
+        const current = Date.now();
+        lastSweepAt = current;
+        for (const [sid, session] of sessions) {
+            if (current - session.lastActivityAt > sessionTtlMs) {
+                log.info('Evicting expired MCP session', {
+                    sessionId: sid,
+                    idleMs: current - session.lastActivityAt
+                });
+                dropSession(sid, 'idle-ttl');
+            }
+        }
+    }
+    /**
+     * Per-request expiry, on every host: the first request after each sweep
+     * interval sweeps, and a session named by a request is expired before use.
+     * A stateless handler keeps no sessions and sweeps nothing.
+     */
+    function expireForRequest(sessionId) {
+        if (Date.now() - lastSweepAt >= SESSION_SWEEP_INTERVAL_MS)
+            expireIdleSessions();
+        const named = sessionId ? sessions.get(sessionId) : undefined;
+        if (sessionId && named && Date.now() - named.lastActivityAt > sessionTtlMs)
+            dropSession(sessionId, 'idle-ttl');
+    }
+    /**
+     * A persistent host also sweeps in the background on its runtime-owned
+     * interval, so an idle host releases its sessions without traffic. A finite
+     * host refuses the interval (confirmed absence of background work) and
+     * relies on per-request expiry alone.
+     */
+    let stopSweep = null;
+    if (!options.stateless) {
+        const started = settleNow(() => options.lifecycle.interval(expireIdleSessions, SESSION_SWEEP_INTERVAL_MS));
+        if (started.ok)
+            stopSweep = started.value;
+        else if (valueFreeFailure(started.cause).reason !== 'lifecycle-interval-finite')
+            throw started.cause;
+    }
+    async function handleMcpHttpRequest(req) {
+        const url = new URL(req.url);
+        if (url.pathname === '/health' || url.pathname === '/mcp/health') {
+            const oldestRestoreStartedAt = activeRestoreStartedAt.size === 0
+                ? null
+                : Math.min(...activeRestoreStartedAt.values());
+            const activeRestoreAgeMs = oldestRestoreStartedAt === null ? null : Math.max(0, now() - oldestRestoreStartedAt);
+            const restoreHealthy = activeRestoreAgeMs === null || activeRestoreAgeMs < durableRestoreDeadlineMs;
+            return new Response(JSON.stringify({
+                ...options.healthExtras,
+                ok: restoreHealthy,
+                sessions: sessions.size,
+                maxSessions,
+                restoreQueueDepth,
+                activeReceiptRestores,
+                restoreExecutions: {
+                    readOnly: receiptRestoreExecutions,
+                    mutation: mutationRestoreExecutions
+                },
+                legacyRestoreClassifications: {
+                    attempted: legacyRestoreAttempts,
+                    resolved: legacyRestoreResolved,
+                    unresolved: legacyRestoreUnresolved
+                },
+                activeRestoreAgeMs,
+                restoreDeadlineMs: durableRestoreDeadlineMs,
+                reason: restoreHealthy ? undefined : 'durable-restore-overdue',
+                uptime: Math.floor((Date.now() - startedAt) / 1000),
+            }), {
+                status: restoreHealthy ? 200 : 503,
+                headers: { 'content-type': 'application/json' }
+            });
+        }
+        const isMcpEndpoint = (options.endpointPaths ?? ['/mcp', '/']).includes(url.pathname);
+        if (!isMcpEndpoint) {
+            return new Response('Not Found', { status: 404 });
+        }
+        const authenticate = options.authenticate;
+        if (authenticate) {
+            const fakeReq = {
+                headers: Object.fromEntries(req.headers.entries())
+            };
+            // An authenticator that throws answers a JSON-RPC error, never a
+            // rejection into the host: a typed UNAVAILABLE refusal is 503,
+            // anything else 500. Fixed text on the wire; the cause is logged once.
+            const authed = await settle(() => authenticate(fakeReq));
+            if (!authed.ok) {
+                const failure = valueFreeFailure(authed.cause);
+                if (isCapabilityError(authed.cause) && authed.cause.code === 'UNAVAILABLE') {
+                    log.warn('MCP authentication unavailable; answering 503', { failure, reason: authed.cause.reason });
+                    return jsonRpcError(503, -32001, 'Service unavailable: authentication is temporarily unreachable');
+                }
+                log.error('MCP authenticator failed; answering 500', { failure });
+                return jsonRpcError(500, -32603, 'Internal error: authentication failed');
+            }
+            if (!authed.value) {
+                return jsonRpcError(401, -32001, 'Unauthorized: Valid API key with mcp scope required');
+            }
+        }
+        // Stateless edge mode: build an ephemeral server+transport per request.
+        // No session Map, no cross-request continuity required — each JSON-RPC
+        // message (initialize / tools/list / tools/call) is self-contained, which
+        // is the only model that works across serverless isolates.
+        if (options.stateless) {
+            const served = await settle(async () => {
+                let parsedBody;
+                if (req.method === 'POST') {
+                    const text = await req.text();
+                    if (text.trim().length > 0) {
+                        const parsed = settleNow(() => JsonValueSchema.parse(JSON.parse(text)));
+                        if (!parsed.ok)
+                            return jsonRpcError(400, -32700, 'Parse error: invalid JSON payload');
+                        parsedBody = parsed.value;
+                    }
+                }
+                const requestScope = parseMcpRequestScope(req.headers);
+                const refusal = refuseUnservedWorkspace(requestScope, parsedBody);
+                if (refusal)
+                    return refusal;
+                const server = options.buildServer();
+                const transport = new WebStandardStreamableHTTPServerTransport({
+                    sessionIdGenerator: undefined,
+                    // Await the complete response before disposing this request's server.
+                    enableJsonResponse: true
+                });
+                // Same tools/list tightening (pattern strip + union dedup) the stdio
+                // transport gets in server.consumer.ts.
+                wrapTransportWithSchemaTightening(transport, { omitOutputSchema: options.omitOutputSchema });
+                await server.connect(transport);
+                try {
+                    return await runWithMcpRequestScope(requestScope, () => transport.handleRequest(req, { parsedBody }), options.runInRequestWorkspace);
+                }
+                finally {
+                    // Tear down the ephemeral server so it doesn't leak.
+                    closeServer(server, null, 'stateless-request-complete');
+                }
+            });
+            if (!served.ok) {
+                log.error('Error handling stateless MCP request', { error: valueFreeFailure(served.cause) });
+                return jsonRpcError(500, -32603, 'Internal error');
+            }
+            return served.value;
+        }
+        const sessionId = resolveSessionIdFromWebHeaders(req.headers);
+        const served = await settle(async () => {
+            let parsedBody;
+            if (req.method === 'POST') {
+                const text = await req.text();
+                if (text.trim().length > 0) {
+                    const parsed = settleNow(() => JsonValueSchema.parse(JSON.parse(text)));
+                    if (!parsed.ok)
+                        return jsonRpcError(400, -32700, 'Parse error: invalid JSON payload');
+                    parsedBody = parsed.value;
+                }
+            }
+            expireForRequest(sessionId ?? undefined);
+            const session = sessionId ? sessions.get(sessionId) : undefined;
+            const requestScope = parseMcpRequestScope(req.headers);
+            const refusal = refuseUnservedWorkspace(requestScope, parsedBody);
+            if (refusal)
+                return refusal;
+            if (sessionId && session) {
+                session.lastActivityAt = Date.now();
+                let restoreBody = parsedBody;
+                let restoreIdentity = durableRestoreIdentity(restoreBody);
+                const restoreRequest = durableRestoreRequest(restoreBody);
+                if (restoreRequest &&
+                    !restoreRequest.receiptOnly &&
+                    !restoreRequest.newSession &&
+                    options.resolveReadOnlyDurableRestore) {
+                    legacyRestoreAttempts += 1;
+                    const clientVersion = session.server.server.getClientVersion?.();
+                    const clientInfo = session.connection.clientInfo ??
+                        (clientVersion?.name
+                            ? {
+                                name: clientVersion.name,
+                                version: clientVersion.version || undefined
+                            }
+                            : undefined);
+                    const receipt = await options.resolveReadOnlyDurableRestore({
+                        ...restoreRequest,
+                        transportSessionId: sessionId,
+                        clientInfo: clientInfo || undefined
+                    });
+                    if (receipt) {
+                        legacyRestoreResolved += 1;
+                        restoreBody = asCanonicalReceiptRestore(restoreBody, receipt);
+                        restoreIdentity = durableRestoreIdentity(restoreBody);
+                    }
+                    else {
+                        legacyRestoreUnresolved += 1;
+                        // Refuse only the BARE init: with no session named the tool
+                        // would mint, and an identity-less caller gives the host no
+                        // durable seat to attach it to. An init that NAMES a session
+                        // is a fresh bind, not a restore — there is no prior binding
+                        // to resurrect, and the tool never mints for a named id: it
+                        // binds or rejects (foreign/archived/ambiguous) with proper
+                        // tool errors. Gating it here broke the documented bind flow
+                        // (docs/session-binding.md) for every harness that declares
+                        // no stable identity.
+                        if (restoreRequest.action === 'init' &&
+                            !restoreRequest.sessionId &&
+                            !restoreRequest.participantId &&
+                            !clientInfo?.harnessSessionId) {
+                            return jsonRpcError(409, -32004, 'Legacy session restore requires a stable participant or harness session identity', { id: jsonRpcRequestId(restoreBody) });
+                        }
+                    }
+                }
+                const execute = () => runWithMcpRequestScope(requestScope, () => session.transport.handleRequest(withSessionHeader(req, sessionId), {
+                    parsedBody: restoreBody
+                }), options.runInRequestWorkspace);
+                return isDurableSessionRestoreRequest(restoreBody)
+                    ? admitDurableRestore(restoreIdentity, sessionId, jsonRpcRequestId(restoreBody), execute)
+                    : execute();
+            }
+            if (isInitializeRequest(parsedBody) && !session) {
+                if (sessions.size >= maxSessions) {
+                    // Only a session quiet for `minEvictionIdleMs` may be sacrificed. Plain
+                    // LRU picked the interactive agents every time: they are idle while their
+                    // agent thinks, and the short-lived hook sessions churning past them are
+                    // always fresher.
+                    const now = Date.now();
+                    let oldestSid = null;
+                    let oldestTime = Infinity;
+                    for (const [sid, candidate] of sessions) {
+                        if (now - candidate.lastActivityAt < minEvictionIdleMs)
+                            continue;
+                        if (candidate.lastActivityAt < oldestTime) {
+                            oldestTime = candidate.lastActivityAt;
+                            oldestSid = sid;
+                        }
+                    }
+                    if (!oldestSid) {
+                        // Every live session is in active use. Refusing the NEW connection is
+                        // recoverable: that client is here, sees the error, and can retry.
+                        // Killing an established one is not — that client is elsewhere and
+                        // finds out only when its next tool call fails.
+                        log.error('Session cap reached with no idle session to reclaim', {
+                            totalSessions: sessions.size,
+                            maxSessions,
+                            minEvictionIdleMs
+                        });
+                        return jsonRpcError(503, -32000, `MCP host is at its session cap (${maxSessions}) and every session is in ` +
+                            `active use. Retry shortly; this is not a missing tool.`, { id: jsonRpcRequestId(parsedBody), headers: { 'retry-after': '5' } });
+                    }
+                    log.warn('Session cap reached, evicting the most idle session', {
+                        evictedSession: oldestSid,
+                        idleMs: now - oldestTime,
+                        totalSessions: sessions.size,
+                        maxSessions
+                    });
+                    dropSession(oldestSid, 'session-cap');
+                }
+                const connectionContext = initializeConnection(parsedBody, options.relayAttestation?.verify(req.headers.get('authorization')) === true, options.runtime);
+                const server = options.buildServer(connectionContext);
+                let releaseMembership;
+                const transport = new WebStandardStreamableHTTPServerTransport({
+                    sessionIdGenerator: options.sessionIdGenerator ?? (() => crypto.randomUUID()),
+                    keepAliveMs: SSE_KEEP_ALIVE_MS,
+                    onsessioninitialized: (sid) => {
+                        releaseMembership = options.bindMembershipOwner?.(sid);
+                        connectionContext.transportSessionId = sid;
+                        sessions.set(sid, {
+                            transport,
+                            server,
+                            lastActivityAt: Date.now(),
+                            connection: connectionContext,
+                            releaseMembership
+                        });
+                    }
+                });
+                transport.onclose = () => {
+                    releaseMembership?.();
+                    releaseMembership = undefined;
+                    const sid = transport.sessionId;
+                    if (sid) {
+                        sessions.delete(sid);
+                        // A client DELETE, a transport error, and our own eviction all land
+                        // here. Recording it means a later request on that id is told the
+                        // session was terminated rather than that it is unknown.
+                        if (!terminatedSessions.has(sid))
+                            rememberTerminated(sid, 'closed');
+                    }
+                    log.debug('MCP HTTP session closed', { sessionId: sid });
+                };
+                transport.onerror = (err) => {
+                    log.error('HTTP transport error', {
+                        error: valueFreeFailure(CaughtFailureSchema.parse(err)),
+                        sessionId: transport.sessionId
+                    });
+                    return err;
+                };
+                // Same tools/list tightening (pattern strip + union dedup) the stdio
+                // transport gets in server.consumer.ts.
+                wrapTransportWithSchemaTightening(transport, { omitOutputSchema: options.omitOutputSchema });
+                await server.connect(transport);
+                server.server.onerror = (err) => {
+                    log.error('MCP protocol error (HTTP)', {
+                        error: valueFreeFailure(CaughtFailureSchema.parse(err)),
+                        sessionId: transport.sessionId
+                    });
+                    return err;
+                };
+                return runWithMcpRequestScope(requestScope, () => transport.handleRequest(req, { parsedBody }), options.runInRequestWorkspace);
+            }
+            if (sessionId) {
+                // MCP streamable HTTP: a request carrying a session id the host does not
+                // hold MUST answer 404, which is a client's instruction to start a new
+                // session with a fresh InitializeRequest. Answering 400 (as this did)
+                // reads as "malformed request" and leaves the client permanently broken
+                // against a host that would happily serve it again.
+                const terminated = terminatedSessions.get(sessionId);
+                log.info('Request for a session this host no longer holds', {
+                    sessionId,
+                    reason: terminated?.reason ?? 'unknown'
+                });
+                return jsonRpcError(404, -32001, terminated
+                    ? `MCP session ${sessionId} was terminated by the host (${terminated.reason}). ` +
+                        `Start a new session with a fresh initialize request.`
+                    : `MCP session ${sessionId} is not known to this host. ` +
+                        `Start a new session with a fresh initialize request.`, { id: jsonRpcRequestId(parsedBody) });
+            }
+            return jsonRpcError(400, -32000, 'Bad Request: No valid session ID provided', {
+                id: jsonRpcRequestId(parsedBody)
+            });
+        });
+        if (!served.ok) {
+            log.error('Error handling MCP request', { error: valueFreeFailure(served.cause) });
+            return jsonRpcError(500, -32603, 'Internal error');
+        }
+        return served.value;
+    }
+    return {
+        handleRequest: handleMcpHttpRequest,
+        dispose: () => {
+            stopSweep?.();
+            stopSweep = null;
+            for (const [sid, session] of sessions) {
+                session.releaseMembership?.();
+                rememberTerminated(sid, 'host-shutdown');
+                closeServer(session.server, sid, 'host-shutdown');
+            }
+            sessions.clear();
+        }
+    };
+}
+//# sourceMappingURL=mcp-http-session.js.map