@boardwalk-labs/engine 0.1.0

package/dist/mcp/oauth.js

@@ -0,0 +1,337 @@
+// PARENT-side OAuth 2.1 for MCP servers (MCP authorization spec, 2025-06-18): discovery
+// (RFC 9728 protected-resource metadata → RFC 8414 AS metadata), RFC 7591 dynamic client
+// registration, the authorization-code + PKCE (S256) grant with a loopback redirect, RFC 8707
+// resource indicators, and the refresh grant. All of it runs in the ENGINE process: token
+// state never belongs to the run process, and the one interactive step is an explicit public
+// API (`Engine.authorizeMcpServer`) — a headless run that would need a human fails loudly
+// instead of prompting. Every external response is Zod-validated (CODE_QUALITY §2.1).
+import { createHash, randomBytes } from "node:crypto";
+import http from "node:http";
+import { z } from "zod";
+import { EngineError } from "../errors.js";
+import { canonicalServerUrl } from "./token_store.js";
+/** A fresh high-entropy verifier and its S256 challenge. */
+export function createPkcePair() {
+    const verifier = randomBytes(32).toString("base64url");
+    return { verifier, challenge: s256Challenge(verifier) };
+}
+/** The S256 transform, exported so tests can verify the challenge against the verifier. */
+export function s256Challenge(verifier) {
+    return createHash("sha256").update(verifier, "ascii").digest("base64url");
+}
+// ----------------------------------------------------------------------------
+// WWW-Authenticate parsing (RFC 9110 §11.6.1, the Bearer challenge subset we need)
+// ----------------------------------------------------------------------------
+/**
+ * Extract the parameters of a Bearer challenge (`resource_metadata`, `error`, …). Returns an
+ * empty record for non-Bearer or malformed headers — discovery then falls back to the
+ * well-known path, so a sloppy header degrades gracefully instead of failing authorization.
+ */
+export function parseBearerChallenge(header) {
+    const match = /^\s*Bearer\b(.*)$/i.exec(header);
+    if (match === null)
+        return {};
+    const params = {};
+    // key="quoted value" or key=token, comma-separated.
+    const paramRe = /([A-Za-z0-9_-]+)\s*=\s*(?:"((?:[^"\\]|\\.)*)"|([^\s,"]+))/g;
+    for (const param of (match[1] ?? "").matchAll(paramRe)) {
+        const key = param[1];
+        const value = param[2] !== undefined ? param[2].replaceAll('\\"', '"') : param[3];
+        if (key !== undefined && value !== undefined)
+            params[key.toLowerCase()] = value;
+    }
+    return params;
+}
+// ----------------------------------------------------------------------------
+// Discovery: server → protected-resource metadata → authorization-server metadata
+// ----------------------------------------------------------------------------
+const protectedResourceSchema = z.looseObject({
+    resource: z.string().optional(),
+    authorization_servers: z.array(z.string()).optional(),
+});
+const asMetadataSchema = z.looseObject({
+    issuer: z.string().min(1),
+    authorization_endpoint: z.string().min(1),
+    token_endpoint: z.string().min(1),
+    registration_endpoint: z.string().optional(),
+});
+/**
+ * Find the authorization server for an MCP server: probe it unauthenticated, follow the 401's
+ * `resource_metadata` hint (RFC 9728), fall back to the well-known protected-resource path,
+ * and finally — for pre-9728 servers — treat the server's own origin as the issuer (the
+ * 2025-03-26 MCP default). Failing any later step is loud: authorization can't be guessed.
+ */
+export async function discoverAuthorization(serverUrl, io = {}) {
+    const doFetch = io.fetchImpl ?? fetch;
+    const canonical = canonicalServerUrl(serverUrl);
+    const origin = new URL(serverUrl).origin;
+    const metadataUrls = [
+        ...(await resourceMetadataHint(serverUrl, doFetch)),
+        wellKnownUrl(serverUrl, "oauth-protected-resource"),
+        `${origin}/.well-known/oauth-protected-resource`,
+    ];
+    let issuer = origin; // pre-RFC-9728 fallback: the resource server is its own issuer
+    let resource = canonical;
+    for (const url of dedupe(metadataUrls)) {
+        const metadata = await fetchJson(url, doFetch, protectedResourceSchema);
+        if (metadata === null)
+            continue;
+        issuer = metadata.authorization_servers?.[0] ?? issuer;
+        resource = metadata.resource ?? resource;
+        break;
+    }
+    const asMetadata = await fetchJson(wellKnownUrl(issuer, "oauth-authorization-server"), doFetch, asMetadataSchema);
+    if (asMetadata === null) {
+        throw new EngineError("PROVIDER_ERROR", `Could not discover OAuth authorization-server metadata for MCP server ${serverUrl} ` +
+            `(issuer ${issuer}).`, "The server's authorization server must publish RFC 8414 metadata at " +
+            "/.well-known/oauth-authorization-server.");
+    }
+    return {
+        authorizationEndpoint: asMetadata.authorization_endpoint,
+        tokenEndpoint: asMetadata.token_endpoint,
+        registrationEndpoint: asMetadata.registration_endpoint,
+        resource,
+    };
+}
+/** Probe the MCP server unauthenticated and harvest the 401's resource_metadata hint, if any. */
+async function resourceMetadataHint(serverUrl, doFetch) {
+    try {
+        const response = await doFetch(serverUrl, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                accept: "application/json, text/event-stream",
+            },
+            body: JSON.stringify({ jsonrpc: "2.0", id: 0, method: "ping" }),
+        });
+        if (response.status !== 401)
+            return [];
+        const challenge = parseBearerChallenge(response.headers.get("www-authenticate") ?? "");
+        const hint = challenge["resource_metadata"];
+        return hint !== undefined ? [hint] : [];
+    }
+    catch {
+        return []; // unreachable server — the well-known fallbacks will fail loudly below
+    }
+}
+/** RFC 8414 path handling: the well-known segment goes between the origin and the path. */
+function wellKnownUrl(base, suffix) {
+    const url = new URL(base);
+    const path = url.pathname.replace(/\/+$/, "");
+    return `${url.origin}/.well-known/${suffix}${path}`;
+}
+async function fetchJson(url, doFetch, schema) {
+    try {
+        const response = await doFetch(url, { headers: { accept: "application/json" } });
+        if (!response.ok)
+            return null;
+        const parsed = schema.safeParse(await response.json());
+        return parsed.success ? parsed.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+function dedupe(urls) {
+    return [...new Set(urls)];
+}
+// ----------------------------------------------------------------------------
+// Dynamic client registration (RFC 7591)
+// ----------------------------------------------------------------------------
+const registrationResultSchema = z.looseObject({ client_id: z.string().min(1) });
+/** Register a public client (no secret — token_endpoint_auth_method "none", per OAuth 2.1 CLI practice). */
+export async function registerClient(registrationEndpoint, redirectUri, io = {}) {
+    const doFetch = io.fetchImpl ?? fetch;
+    const response = await doFetch(registrationEndpoint, {
+        method: "POST",
+        headers: { "content-type": "application/json", accept: "application/json" },
+        body: JSON.stringify({
+            client_name: "Boardwalk Engine",
+            redirect_uris: [redirectUri],
+            grant_types: ["authorization_code", "refresh_token"],
+            response_types: ["code"],
+            token_endpoint_auth_method: "none",
+        }),
+    });
+    if (!response.ok) {
+        throw new EngineError("PROVIDER_ERROR", `OAuth client registration failed: ${String(response.status)} from ${registrationEndpoint}.`);
+    }
+    const parsed = registrationResultSchema.safeParse(await response.json());
+    if (!parsed.success) {
+        throw new EngineError("PROVIDER_ERROR", `OAuth client registration returned a malformed response (no client_id).`);
+    }
+    return parsed.data.client_id;
+}
+// ----------------------------------------------------------------------------
+// Token grants (authorization_code exchange + refresh_token)
+// ----------------------------------------------------------------------------
+const tokenResponseSchema = z.looseObject({
+    access_token: z.string().min(1),
+    refresh_token: z.string().min(1).optional(),
+    expires_in: z.number().positive().optional(),
+});
+export async function exchangeAuthorizationCode(args, io = {}) {
+    return await tokenGrant(args.tokenEndpoint, {
+        grant_type: "authorization_code",
+        client_id: args.clientId,
+        code: args.code,
+        redirect_uri: args.redirectUri,
+        code_verifier: args.codeVerifier,
+        resource: args.resource,
+    }, io);
+}
+export async function refreshAccessToken(args, io = {}) {
+    return await tokenGrant(args.tokenEndpoint, {
+        grant_type: "refresh_token",
+        client_id: args.clientId,
+        refresh_token: args.refreshToken,
+        ...(args.resource !== undefined ? { resource: args.resource } : {}),
+    }, io);
+}
+async function tokenGrant(tokenEndpoint, params, io) {
+    const doFetch = io.fetchImpl ?? fetch;
+    const response = await doFetch(tokenEndpoint, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+        body: new URLSearchParams(params).toString(),
+    });
+    if (!response.ok) {
+        // Status only — an AS error body can echo grant material; never put it in an error message.
+        throw new EngineError("PROVIDER_ERROR", `OAuth token request (${params["grant_type"] ?? "unknown grant"}) failed: ` +
+            `${String(response.status)} from ${tokenEndpoint}.`);
+    }
+    const parsed = tokenResponseSchema.safeParse(await response.json());
+    if (!parsed.success) {
+        throw new EngineError("PROVIDER_ERROR", "OAuth token response was malformed.");
+    }
+    return {
+        accessToken: parsed.data.access_token,
+        refreshToken: parsed.data.refresh_token,
+        expiresAt: parsed.data.expires_in !== undefined
+            ? Date.now() + Math.floor(parsed.data.expires_in * 1000)
+            : undefined,
+    };
+}
+const DEFAULT_AUTHORIZE_TIMEOUT_MS = 5 * 60_000;
+/**
+ * The one-time interactive step: discovery → dynamic registration → PKCE authorization-code
+ * grant with a loopback redirect → tokens persisted to the store. Resolves when the grant is
+ * stored; rejects on state mismatch, an AS `error` redirect, or timeout. After this, runs use
+ * the server headlessly (silent refresh included) until the grant dies.
+ */
+export async function runAuthorizationFlow(args) {
+    const io = { fetchImpl: args.fetchImpl };
+    const discovery = await discoverAuthorization(args.serverUrl, io);
+    if (discovery.registrationEndpoint === undefined) {
+        throw new EngineError("UNSUPPORTED", `The authorization server for ${args.serverUrl} does not support dynamic client ` +
+            "registration (RFC 7591), which this engine requires.", "Pre-provisioned client credentials are not supported yet; supply a token via the " +
+            "McpServerRef headers instead.");
+    }
+    const state = randomBytes(16).toString("base64url");
+    const pkce = createPkcePair();
+    const loopback = await startLoopbackListener(state, args.timeoutMs ?? DEFAULT_AUTHORIZE_TIMEOUT_MS);
+    try {
+        const clientId = await registerClient(discovery.registrationEndpoint, loopback.redirectUri, io);
+        const authorizeUrl = new URL(discovery.authorizationEndpoint);
+        authorizeUrl.searchParams.set("response_type", "code");
+        authorizeUrl.searchParams.set("client_id", clientId);
+        authorizeUrl.searchParams.set("redirect_uri", loopback.redirectUri);
+        authorizeUrl.searchParams.set("state", state);
+        authorizeUrl.searchParams.set("code_challenge", pkce.challenge);
+        authorizeUrl.searchParams.set("code_challenge_method", "S256");
+        authorizeUrl.searchParams.set("resource", discovery.resource);
+        args.onAuthorizationUrl(authorizeUrl.toString());
+        const code = await loopback.code;
+        const grant = await exchangeAuthorizationCode({
+            tokenEndpoint: discovery.tokenEndpoint,
+            clientId,
+            code,
+            redirectUri: loopback.redirectUri,
+            codeVerifier: pkce.verifier,
+            resource: discovery.resource,
+        }, io);
+        const entry = {
+            clientId,
+            accessToken: grant.accessToken,
+            ...(grant.refreshToken !== undefined ? { refreshToken: grant.refreshToken } : {}),
+            ...(grant.expiresAt !== undefined ? { expiresAt: grant.expiresAt } : {}),
+            tokenEndpoint: discovery.tokenEndpoint,
+            resource: discovery.resource,
+        };
+        args.store.set(args.serverUrl, entry);
+    }
+    finally {
+        loopback.close();
+    }
+}
+/**
+ * The OAuth 2.1 native-app redirect target: an ephemeral HTTP listener on 127.0.0.1 (loopback
+ * redirect URIs are the one http:// form the spec allows). One-shot — first valid hit settles.
+ */
+function startLoopbackListener(state, timeoutMs) {
+    return new Promise((resolveListener, rejectListener) => {
+        let resolveCode = null;
+        let rejectCode = null;
+        const code = new Promise((resolve, reject) => {
+            resolveCode = resolve;
+            rejectCode = reject;
+        });
+        // Why the pre-attached catch: if the flow fails BEFORE awaiting `code` (e.g. registration
+        // throws), close() rejects this promise with nobody listening yet — without a standing
+        // handler that's an unhandled rejection. The real awaiter still receives the rejection.
+        void code.catch(() => undefined);
+        const server = http.createServer((req, res) => {
+            const url = new URL(req.url ?? "/", "http://127.0.0.1");
+            if (url.pathname !== "/callback") {
+                res.writeHead(404).end();
+                return;
+            }
+            const fail = (message) => {
+                res.writeHead(400, { "content-type": "text/plain" }).end(message);
+                rejectCode?.(new EngineError("PROVIDER_ERROR", `MCP authorization failed: ${message}`));
+            };
+            const errorParam = url.searchParams.get("error");
+            if (errorParam !== null) {
+                fail(`the authorization server returned error "${errorParam}".`);
+                return;
+            }
+            if (url.searchParams.get("state") !== state) {
+                fail("state mismatch on the OAuth redirect (possible CSRF) — try authorizing again.");
+                return;
+            }
+            const codeParam = url.searchParams.get("code");
+            if (codeParam === null || codeParam.length === 0) {
+                fail("the redirect carried no authorization code.");
+                return;
+            }
+            res
+                .writeHead(200, { "content-type": "text/html" })
+                .end("<html><body>Authorized — you can close this tab and return to Boardwalk.</body></html>");
+            resolveCode?.(codeParam);
+        });
+        const timer = setTimeout(() => {
+            rejectCode?.(new EngineError("PROVIDER_ERROR", `MCP authorization timed out after ${String(Math.round(timeoutMs / 1000))}s — the ` +
+                "authorization URL was never completed."));
+            server.close();
+        }, timeoutMs);
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            if (address === null || typeof address !== "object") {
+                clearTimeout(timer);
+                server.close();
+                rejectListener(new EngineError("INTERNAL", "Loopback listener failed to bind a port."));
+                return;
+            }
+            resolveListener({
+                redirectUri: `http://127.0.0.1:${String(address.port)}/callback`,
+                code,
+                close: () => {
+                    clearTimeout(timer);
+                    server.close();
+                    // A close before settle (caller bailed early) must not leave the promise pending.
+                    rejectCode?.(new EngineError("CANCELLED", "MCP authorization was abandoned."));
+                },
+            });
+        });
+    });
+}

package/dist/mcp/token_store.d.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+/** Where the store lives under the engine data dir (engine + supervisor must agree). */
+export declare const MCP_TOKENS_FILENAME = "mcp_tokens.json";
+declare const entrySchema: z.ZodObject<{
+    clientId: z.ZodString;
+    accessToken: z.ZodString;
+    refreshToken: z.ZodOptional<z.ZodString>;
+    expiresAt: z.ZodOptional<z.ZodNumber>;
+    tokenEndpoint: z.ZodOptional<z.ZodString>;
+    resource: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type McpTokenEntry = z.infer<typeof entrySchema>;
+/**
+ * Canonicalize an MCP server URL for keying token state: the same server written with a
+ * default port, trailing slash, or different case must hit the same entry — otherwise an
+ * authorize under one spelling is invisible to a run using another.
+ */
+export declare function canonicalServerUrl(serverUrl: string): string;
+export declare class McpTokenStore {
+    private readonly path;
+    constructor(path: string);
+    /** The stored entry for a server, or null. `serverUrl` may be any spelling of the URL. */
+    get(serverUrl: string): McpTokenEntry | null;
+    set(serverUrl: string, entry: McpTokenEntry): void;
+    delete(serverUrl: string): void;
+    private readAll;
+    private writeAll;
+    private corruptError;
+}
+export {};

package/dist/mcp/token_store.js

@@ -0,0 +1,101 @@
+// PARENT-side MCP OAuth token persistence. Tokens live with the engine — never in the run
+// process beyond the single brokered value a request needs — in one JSON file under the data
+// dir, mode 0600 (they are credentials; CODE_QUALITY §7.4 treats them like secrets: values
+// never logged). Zod-validated on every read because a disk file is a trust boundary even
+// when we wrote it.
+import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { z } from "zod";
+import { EngineError } from "../errors.js";
+/** Where the store lives under the engine data dir (engine + supervisor must agree). */
+export const MCP_TOKENS_FILENAME = "mcp_tokens.json";
+const entrySchema = z.strictObject({
+    /** The dynamically-registered OAuth client id this server's grants belong to. */
+    clientId: z.string().min(1),
+    accessToken: z.string().min(1),
+    refreshToken: z.string().min(1).optional(),
+    /** Epoch ms. Absent ⇒ the AS declared no expiry; the token is used until rejected. */
+    expiresAt: z.number().int().positive().optional(),
+    // Why these two travel with the tokens: silent refresh runs headless in the supervisor; it
+    // must not depend on re-running discovery (a transient discovery failure would break runs
+    // that hold a perfectly good refresh token).
+    tokenEndpoint: z.string().min(1).optional(),
+    /** The RFC 8707 resource indicator the grant was issued for. */
+    resource: z.string().min(1).optional(),
+});
+const fileSchema = z.record(z.string(), entrySchema);
+/**
+ * Canonicalize an MCP server URL for keying token state: the same server written with a
+ * default port, trailing slash, or different case must hit the same entry — otherwise an
+ * authorize under one spelling is invisible to a run using another.
+ */
+export function canonicalServerUrl(serverUrl) {
+    let url;
+    try {
+        url = new URL(serverUrl);
+    }
+    catch {
+        throw new EngineError("VALIDATION", `"${serverUrl}" is not a valid MCP server URL.`);
+    }
+    const path = url.pathname.replace(/\/+$/, "");
+    // URL already lowercases the host and drops default ports from `host`.
+    return `${url.protocol}//${url.host}${path}`;
+}
+export class McpTokenStore {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    /** The stored entry for a server, or null. `serverUrl` may be any spelling of the URL. */
+    get(serverUrl) {
+        return this.readAll()[canonicalServerUrl(serverUrl)] ?? null;
+    }
+    set(serverUrl, entry) {
+        const all = this.readAll();
+        all[canonicalServerUrl(serverUrl)] = entry;
+        this.writeAll(all);
+    }
+    delete(serverUrl) {
+        const all = this.readAll();
+        const key = canonicalServerUrl(serverUrl);
+        if (key in all) {
+            delete all[key];
+            this.writeAll(all);
+        }
+    }
+    readAll() {
+        let raw;
+        try {
+            raw = readFileSync(this.path, "utf8");
+        }
+        catch {
+            return {}; // no file yet — nothing authorized
+        }
+        let json;
+        try {
+            json = JSON.parse(raw);
+        }
+        catch {
+            throw this.corruptError();
+        }
+        const parsed = fileSchema.safeParse(json);
+        if (!parsed.success)
+            throw this.corruptError();
+        return parsed.data;
+    }
+    writeAll(all) {
+        mkdirSync(dirname(this.path), { recursive: true });
+        // Write-tmp-then-rename so a crash mid-write can't corrupt the token file (which would
+        // force re-authorizing every MCP server). rename is atomic within a filesystem; the tmp
+        // sibling shares the data dir so it's never a cross-device move.
+        const tmp = `${this.path}.${String(process.pid)}.tmp`;
+        writeFileSync(tmp, `${JSON.stringify(all, null, 2)}\n`, { mode: 0o600 });
+        // writeFileSync only applies `mode` on create — re-assert so an existing tmp from a prior
+        // crash ends up locked down before it becomes the real file.
+        chmodSync(tmp, 0o600);
+        renameSync(tmp, this.path);
+    }
+    corruptError() {
+        return new EngineError("INTERNAL", `The MCP token store at ${this.path} is corrupt.`, "Delete the file and re-authorize the affected servers with engine.authorizeMcpServer.");
+    }
+}

package/dist/mcp/transport_http.d.ts

@@ -0,0 +1,38 @@
+import type { JsonRpcOutbound, McpTransport } from "./jsonrpc.js";
+export interface HttpTransportOptions {
+    /** The MCP server's name from the agent() call — names the endpoint in every error. */
+    serverName: string;
+    url: string;
+    /** Program-supplied headers (the program is the trusted layer; credentials go here). */
+    headers?: Record<string, string> | undefined;
+    /**
+     * The OAuth hook: called when the server answers 401. `failedToken` is the bearer token the
+     * rejected request carried (null when none was sent). Returns a token to retry with; throws
+     * to fail the call (e.g. when the engine holds no token and a human must authorize).
+     * Omitted ⇒ a 401 is a plain provider error.
+     */
+    acquireToken?: ((failedToken: string | null) => Promise<string>) | undefined;
+    fetchImpl?: typeof fetch | undefined;
+}
+export declare class HttpTransport implements McpTransport {
+    private readonly serverName;
+    private readonly url;
+    private readonly baseHeaders;
+    private readonly acquireToken;
+    private readonly fetchImpl;
+    private messageCb;
+    private sessionId;
+    private protocolVersion;
+    private bearerToken;
+    constructor(opts: HttpTransportOptions);
+    send(message: JsonRpcOutbound): Promise<void>;
+    onMessage(cb: (message: unknown) => void): void;
+    onClose(_cb: (err: Error) => void): void;
+    /** The MCP client calls this after the initialize handshake settles the version. */
+    setProtocolVersion(version: string): void;
+    /** Best-effort session teardown (spec: clients SHOULD DELETE the session when done). */
+    close(): Promise<void>;
+    private requestHeaders;
+    private consumeResponse;
+    private deliverJson;
+}

package/dist/mcp/transport_http.js

@@ -0,0 +1,143 @@
+// MCP streamable-HTTP transport (spec rev 2025-06-18 §Transports): every client message is a
+// POST to the server URL; the response is either a single JSON body or an SSE stream of
+// JSON-RPC messages (one shared parser with the provider adapters — src/agent/sse.ts). The
+// transport also owns the session header (`Mcp-Session-Id`, captured at initialize and
+// replayed on every later request) and the OAuth retry dance: program-supplied headers are
+// always applied first; a bearer token is only fetched — through the `acquireToken` hook the
+// connection layer provides — after the server answers 401.
+import { EngineError } from "../errors.js";
+import { sseDataLines } from "../agent/sse.js";
+/** 401-retry budget per message: original try + one retried token + one invalidate-and-retry. */
+const MAX_AUTH_ATTEMPTS = 3;
+export class HttpTransport {
+    serverName;
+    url;
+    baseHeaders;
+    acquireToken;
+    fetchImpl;
+    messageCb = null;
+    sessionId = null;
+    protocolVersion = null;
+    bearerToken = null;
+    constructor(opts) {
+        this.serverName = opts.serverName;
+        this.url = opts.url;
+        this.baseHeaders = { ...opts.headers };
+        this.acquireToken = opts.acquireToken;
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+    }
+    async send(message) {
+        const body = JSON.stringify(message);
+        let response = null;
+        for (let attempt = 1; attempt <= MAX_AUTH_ATTEMPTS; attempt++) {
+            const sentToken = this.bearerToken;
+            try {
+                response = await this.fetchImpl(this.url, {
+                    method: "POST",
+                    headers: this.requestHeaders(sentToken),
+                    body,
+                });
+            }
+            catch (err) {
+                // fetch network failures are bare TypeErrors ("fetch failed") — name the server.
+                throw new EngineError("PROVIDER_ERROR", `MCP server "${this.serverName}" (${this.url}) is unreachable: ` +
+                    `${err instanceof Error ? err.message : String(err)}.`, "Check the URL and that the server is up — the agent() call named this server, so " +
+                    "the run fails rather than silently dropping its tools.");
+            }
+            if (response.status !== 401)
+                break;
+            if (this.acquireToken === undefined || attempt === MAX_AUTH_ATTEMPTS) {
+                throw new EngineError("PROVIDER_ERROR", `MCP server "${this.serverName}" (${this.url}) rejected the request: 401 Unauthorized.`, this.acquireToken === undefined
+                    ? "The server demands credentials; supply them in the McpServerRef headers, or use " +
+                        "an engine-authorized OAuth token."
+                    : "A freshly issued token was still rejected — re-authorize the server with " +
+                        "engine.authorizeMcpServer.");
+            }
+            // The hook decides between cached/refreshed/none; passing the failed token tells the
+            // engine to invalidate it rather than hand the same one back.
+            this.bearerToken = await this.acquireToken(sentToken);
+        }
+        if (response === null)
+            return; // unreachable: the loop always assigns — satisfies narrowing
+        await this.consumeResponse(response);
+    }
+    onMessage(cb) {
+        this.messageCb = cb;
+    }
+    onClose(_cb) {
+        // HTTP has no long-lived pipe to lose; per-request failures reject the send instead.
+    }
+    /** The MCP client calls this after the initialize handshake settles the version. */
+    setProtocolVersion(version) {
+        this.protocolVersion = version;
+    }
+    /** Best-effort session teardown (spec: clients SHOULD DELETE the session when done). */
+    async close() {
+        if (this.sessionId === null)
+            return;
+        try {
+            await this.fetchImpl(this.url, {
+                method: "DELETE",
+                headers: this.requestHeaders(this.bearerToken),
+            });
+        }
+        catch {
+            // The session will expire server-side; teardown must never fail a finished run.
+        }
+        this.sessionId = null;
+    }
+    requestHeaders(token) {
+        return {
+            "content-type": "application/json",
+            accept: "application/json, text/event-stream",
+            ...this.baseHeaders,
+            ...(this.sessionId !== null ? { "mcp-session-id": this.sessionId } : {}),
+            ...(this.protocolVersion !== null ? { "mcp-protocol-version": this.protocolVersion } : {}),
+            // After base headers: OAuth only engages when the program's own headers got a 401, so
+            // overriding a program-supplied Authorization here is the correct escalation.
+            ...(token !== null ? { authorization: `Bearer ${token}` } : {}),
+        };
+    }
+    async consumeResponse(response) {
+        const session = response.headers.get("mcp-session-id");
+        if (session !== null && session.length > 0)
+            this.sessionId = session;
+        if (response.status === 202 || response.status === 204)
+            return; // accepted notification
+        if (!response.ok) {
+            const detail = (await response.text()).slice(0, 300);
+            throw new EngineError("PROVIDER_ERROR", `MCP server "${this.serverName}" (${this.url}) returned ${String(response.status)}: ${detail}`);
+        }
+        const contentType = response.headers.get("content-type") ?? "";
+        if (contentType.includes("text/event-stream")) {
+            // The server chose to stream: each SSE data line is one JSON-RPC message; the response
+            // to our request arrives through the same onMessage path the correlator already watches.
+            for await (const data of sseDataLines(response)) {
+                this.deliverJson(data);
+            }
+            return;
+        }
+        if (contentType.includes("application/json")) {
+            this.deliverJson(await response.text());
+        }
+        // Any other content type carries no JSON-RPC messages — nothing to deliver.
+    }
+    deliverJson(text) {
+        let message;
+        try {
+            message = JSON.parse(text);
+        }
+        catch {
+            return; // malformed server frame — the request will time out with a clear error
+        }
+        // 2025-03-26-era servers may still answer with a JSON-RPC batch array.
+        if (Array.isArray(message)) {
+            // Why the annotation: Array.isArray narrows unknown to any[]; widen back to unknown[].
+            const items = message;
+            for (const item of items)
+                this.messageCb?.(item);
+            return;
+        }
+        this.messageCb?.(message);
+    }
+}

package/dist/mcp/transport_stdio.d.ts

@@ -0,0 +1,27 @@
+import type { JsonRpcOutbound, McpTransport } from "./jsonrpc.js";
+export interface StdioTransportOptions {
+    /** The MCP server's name from the agent() call — names the process in every error. */
+    serverName: string;
+    command: string;
+    args?: readonly string[] | undefined;
+    /** Layered over process.env (the program supplies credentials here directly). */
+    env?: Record<string, string> | undefined;
+}
+export declare class StdioTransport implements McpTransport {
+    private readonly serverName;
+    private readonly child;
+    private messageCb;
+    private closeCb;
+    /** Set once the transport failed or was closed — later sends must fail fast, not hang. */
+    private dead;
+    private closedDeliberately;
+    private stdoutBuffer;
+    constructor(opts: StdioTransportOptions);
+    send(message: JsonRpcOutbound): Promise<void>;
+    onMessage(cb: (message: unknown) => void): void;
+    onClose(cb: (err: Error) => void): void;
+    /** Kill the server process. Deliberate teardown — no error is surfaced for the exit. */
+    close(): Promise<void>;
+    private deliverLine;
+    private die;
+}