@fitchmultz/pi-mcp-adapter 8.0.0 → 8.0.2

package/dist/mcp-auth-flow.js

@@ -6,12 +6,14 @@
 import { auth as runSdkAuth, extractWWWAuthenticateParams, UnauthorizedError, Client, StreamableHTTPClientTransport, validateAuthorizationResponseIssuer, InsufficientScopeError, SdkHttpError, computeScopeUnion, isStrictScopeSuperset, } from "@modelcontextprotocol/client";
 import open from "open";
 import { McpOAuthProvider, issuersMatch, loopbackRedirectsMatch, validateOAuthClientMetadataUrl, validateOAuthPrivateKeyJwt, validateOAuthCrossAppAccess } from "./mcp-oauth-provider.js";
-import { ensureCallbackServer, waitForCallback, cancelPendingCallback, stopCallbackServer, releaseCallbackServer, takeCallbackResult, } from "./mcp-callback-server.js";
+import { ensureCallbackServer, waitForCallback, cancelPendingCallback, releaseCallbackServer, takeCallbackResult, } from "./mcp-callback-server.js";
 import { getAuthForUrl, clearAllCredentials, clearClientInfo, clearTokens, clearCodeVerifier, getOAuthState, clearOAuthState, getAuthBaseDir, } from "./mcp-auth.js";
 import { isServerDisabled, isNonInteractiveOAuth, validateServerProtocolConfig } from "./types.js";
 import { ADAPTER_VERSION, formatTerminalError, interpolateEnvRecord, interpolateEnvVars, normalizeRequestTimeoutMs } from "./utils.js";
 import { abortable, throwIfAborted } from "./abort.js";
 import { combineAbortSignals, isAbortError } from "./runtime-owner.js";
+import { clearPendingAuth, getPendingAuthKey, getRuntime, getRuntimeState, legacyRuntime, } from "./mcp-oauth-runtime.js";
+export { createOAuthRuntime, hasPendingAuth, initializeOAuth, shutdownOAuth, supportsOAuth, } from "./mcp-oauth-runtime.js";
 function applyConfiguredScope(discovery, config) {
     return {
         ...discovery,
@@ -34,45 +36,6 @@ function validateCallbackIssuer(serverName, context, response) {
         throw new Error(`The OAuth authorization response issuer does not match the discovered issuer for ${serverName}.`);
     }
 }
-const runtimeStates = new WeakMap();
-const activeRuntimes = new Set();
-export function createOAuthRuntime(signal) {
-    const controller = new AbortController();
-    const runtime = { signal: combineAbortSignals(signal, controller.signal) };
-    runtimeStates.set(runtime, {
-        controller,
-        generation: 0,
-        pendingAuths: new Map(),
-        pendingAuthStates: new Map(),
-        pendingAuthCleanupTimers: new Map(),
-        pendingAuthentications: new Map(),
-        requests: new Map(),
-    });
-    activeRuntimes.add(runtime);
-    return runtime;
-}
-let legacyRuntime = createOAuthRuntime();
-activeRuntimes.delete(legacyRuntime);
-function getRuntime(options) {
-    if (options?.runtime) {
-        options.runtime.signal.throwIfAborted();
-        activeRuntimes.add(options.runtime);
-        return options.runtime;
-    }
-    if (legacyRuntime.signal.aborted)
-        legacyRuntime = createOAuthRuntime();
-    activeRuntimes.add(legacyRuntime);
-    return legacyRuntime;
-}
-function getRuntimeState(runtime) {
-    const state = runtimeStates.get(runtime);
-    if (!state)
-        throw new Error("Unknown OAuth runtime");
-    return state;
-}
-function getPendingAuthKey(serverName, options) {
-    return JSON.stringify([serverName, getAuthBaseDir(options)]);
-}
 export function isOAuthChallenge(error) {
     return error instanceof InsufficientScopeError || error instanceof UnauthorizedError
         || (error instanceof SdkHttpError && error.status === 401);
@@ -105,13 +68,6 @@ export function bindOAuthRequestIssuer(serverName, serverUrl, storageBase, issue
     }
     request.issuer = issuer;
 }
-export function hasPendingAuth(serverName, options, runtime) {
-    const state = getRuntimeState(runtime ?? legacyRuntime);
-    if (options) {
-        return state.pendingAuths.has(getPendingAuthKey(serverName, options));
-    }
-    return Array.from(state.pendingAuths.values()).some(pendingAuth => pendingAuth.serverName === serverName);
-}
 /** Timeout for manual auth completion (5 minutes) */
 const MANUAL_AUTH_TIMEOUT_MS = 5 * 60 * 1000;
 /**
@@ -446,31 +402,6 @@ async function setPendingAuth(runtime, serverName, pendingAuth, oauthState, sign
     cleanupTimer.unref?.();
     state.pendingAuthCleanupTimers.set(key, cleanupTimer);
 }
-async function clearPendingAuth(runtime, serverName, oauthState, fallbackStorageOptions = {}) {
-    const state = getRuntimeState(runtime);
-    const key = getPendingAuthKey(serverName, fallbackStorageOptions);
-    const pendingAuth = state.pendingAuths.get(key);
-    const authStorageOptions = pendingAuth?.authStorageOptions ?? fallbackStorageOptions;
-    const pendingState = state.pendingAuthStates.get(key);
-    if (oauthState && pendingState && pendingState !== oauthState)
-        return;
-    const timer = state.pendingAuthCleanupTimers.get(key);
-    if (timer) {
-        clearTimeout(timer);
-        state.pendingAuthCleanupTimers.delete(key);
-    }
-    pendingAuth?.authProvider.deactivate();
-    state.pendingAuths.delete(key);
-    state.pendingAuthStates.delete(key);
-    const stateToRelease = pendingState ?? oauthState;
-    if (stateToRelease) {
-        cancelPendingCallback(stateToRelease);
-        const storedState = await getOAuthState(serverName, authStorageOptions);
-        if (storedState === stateToRelease) {
-            await clearOAuthState(serverName, authStorageOptions);
-        }
-    }
-}
 function getSearchParamsFromInput(input) {
     try {
         const url = new URL(input);
@@ -727,69 +658,3 @@ export async function removeAuth(serverName, options = {}) {
     throwIfAborted(signal);
     console.log(`MCP Auth: Removed credentials for ${serverName}`);
 }
-/**
- * Check if OAuth is supported for a server configuration.
- * OAuth is supported for HTTP servers unless explicitly disabled.
- *
- * @param definition - The server definition
- * @returns True if OAuth is supported
- */
-export function supportsOAuth(definition) {
-    // OAuth requires a URL
-    if (!definition.url)
-        return false;
-    // Explicitly disabled via auth: false or oauth: false
-    if (definition.auth === false)
-        return false;
-    if (definition.oauth === false)
-        return false;
-    if (definition.auth === "oauth")
-        return true;
-    // Configured custom headers take precedence over implicit OAuth auto-detection.
-    if (definition.headers && Object.keys(definition.headers).length > 0)
-        return false;
-    // OAuth is enabled when auth is not specified (auto-detect)
-    return definition.auth === undefined;
-}
-/**
- * Initialize the OAuth system on startup.
- * OAuth callback binding is lazy and starts from startAuth() only.
- */
-export async function initializeOAuth(runtimeOrSignal) {
-    if (runtimeOrSignal && "signal" in runtimeOrSignal) {
-        runtimeOrSignal.signal.throwIfAborted();
-        activeRuntimes.add(runtimeOrSignal);
-        return runtimeOrSignal;
-    }
-    await shutdownOAuth(legacyRuntime);
-    legacyRuntime = createOAuthRuntime(runtimeOrSignal);
-    return legacyRuntime;
-}
-/**
- * Shutdown one OAuth runtime. The callback server remains process-shared while
- * another runtime has pending/reserved callback state or is still active.
- */
-export async function shutdownOAuth(runtime = legacyRuntime) {
-    const state = getRuntimeState(runtime);
-    if (state.controller.signal.aborted)
-        return;
-    state.generation += 1;
-    state.controller.abort(new Error("OAuth runtime stopped"));
-    for (const callbackState of Array.from(state.pendingAuthStates.values()))
-        cancelPendingCallback(callbackState);
-    const results = await Promise.allSettled(Array.from(state.pendingAuths.values(), pendingAuth => clearPendingAuth(runtime, pendingAuth.serverName, undefined, pendingAuth.authStorageOptions)));
-    const failures = results.flatMap(result => result.status === "rejected" ? [result.reason] : []);
-    state.pendingAuthentications.clear();
-    state.requests.clear();
-    activeRuntimes.delete(runtime);
-    if (activeRuntimes.size === 0) {
-        try {
-            await stopCallbackServer();
-        }
-        catch (error) {
-            failures.push(error);
-        }
-    }
-    if (failures.length)
-        throw new AggregateError(failures, "MCP OAuth cleanup failed");
-}

package/dist/mcp-callback-server.js

@@ -5,7 +5,7 @@
  * Uses Node.js http module for compatibility.
  */
 import { createServer } from "http";
-import { DEFAULT_OAUTH_CALLBACK_PATH, getConfiguredOAuthCallbackPort, getOAuthCallbackPath, getOAuthCallbackPort, setOAuthCallbackPath, setOAuthCallbackPort, } from "./mcp-oauth-provider.js";
+import { DEFAULT_OAUTH_CALLBACK_PATH, getConfiguredOAuthCallbackPort, getOAuthCallbackPath, getOAuthCallbackPort, setOAuthCallbackPath, setOAuthCallbackPort, } from "./mcp-oauth-callback-config.js";
 // HTML templates for callback responses
 const HTML_SUCCESS = `<!DOCTYPE html>
 <html>

package/dist/mcp-code.d.ts

@@ -1,7 +1,6 @@
 import type { ToolInfo } from "@earendil-works/pi-coding-agent";
 import type { McpExtensionState } from "./state.ts";
 import { type ContentBlock, type McpOperationContext } from "./types.ts";
-export declare const DEFAULT_MCP_SCRIPT_TIMEOUT_MS = 30000;
 export declare const runMcpScript: typeof runMcpScriptOperation;
 declare function runMcpScriptOperation(state: McpExtensionState, code: string, timeoutMs?: number | null, getPiTools?: () => ToolInfo[], signal?: AbortSignal, toolCallId?: string, beforeDispatch?: (signal: AbortSignal | undefined, operation: McpOperationContext) => Promise<void>): Promise<{
     content: ContentBlock[];

package/dist/mcp-code.js

@@ -1,13 +1,16 @@
 import { formatWithOptions } from "node:util";
 import { Worker } from "node:worker_threads";
-import { guardMcpOutput, guardedMcpDetails, resolveMcpOutputGuardOptions, readMcpResult, formatMcpResultReference, formatMcpPayloadFile } from "./mcp-output-guard.js";
+import { guardedMcpDetails, resolveMcpOutputGuardOptions, readMcpResult, formatMcpResultReference, formatMcpPayloadFile } from "./mcp-output-guard.js";
+import { createMcpOutputSpool } from "./mcp-output-preview.js";
 import { executeCall, executeConnect } from "./proxy-modes.js";
 import { executeResourceList, executeResourceRead } from "./resource-tools.js";
 import { combineAbortSignals } from "./runtime-owner.js";
 import { paginate, rankSuggestions, rankToolMatches } from "./search-ranking.js";
 import { catalogCoverage, toToolDescriptor } from "./tool-metadata.js";
 import { isServerDisabled } from "./types.js";
-export const DEFAULT_MCP_SCRIPT_TIMEOUT_MS = 30_000;
+import { DEFAULT_MCP_SCRIPT_TIMEOUT_MS } from "./utils.js";
+/** UTF-16 units of emitted output, plus 256 per emit, the worker may queue before it waits for the host. */
+const SCRIPT_OUTPUT_WINDOW = 4 * 1024 * 1024;
 class McpScriptTimeoutError extends Error {
     constructor(timeoutMs) {
         super(`mcp_script timed out after ${timeoutMs}ms`);
@@ -71,8 +74,9 @@ function parseWorkerMessage(value) {
     if (typeof value !== "object" || value === null)
         return null;
     const message = value;
+    // An older worker file, such as one restored by a rollback under a running Pi, neither charges the window nor sends a size.
     if (message.type === "emit" && "block" in message)
-        return { type: "emit", block: message.block };
+        return { type: "emit", block: message.block, size: typeof message.size === "number" ? message.size : 0 };
     if (message.type === "call" && typeof message.id === "number" && typeof message.path === "string") {
         return { type: "call", id: message.id, path: message.path, ...(message.args !== undefined ? { args: message.args } : {}), ...(typeof message.server === "string" ? { server: message.server } : {}) };
     }
@@ -110,7 +114,7 @@ async function runMcpScriptOperation(state, code, timeoutMs = DEFAULT_MCP_SCRIPT
     const resolvedTimeoutMs = timeoutMs === null ? null : Number.isFinite(timeoutMs) && timeoutMs > 0
         ? Math.floor(timeoutMs)
         : DEFAULT_MCP_SCRIPT_TIMEOUT_MS;
-    const output = [];
+    const output = createMcpOutputSpool(resolveMcpOutputGuardOptions(state.config.settings, state.outputDirectory));
     const externalSignal = combineAbortSignals(state.owner?.signal, signal);
     const timeoutController = new AbortController();
     const callSignal = combineAbortSignals(externalSignal, timeoutController.signal);
@@ -273,8 +277,9 @@ async function runMcpScriptOperation(state, code, timeoutMs = DEFAULT_MCP_SCRIPT
         if (externalSignal?.aborted) {
             throw abortReasonError(externalSignal.reason);
         }
+        const outputFlow = new Int32Array(new SharedArrayBuffer(4));
         worker = new Worker(new URL("./mcp-script-worker.mjs", import.meta.url), {
-            workerData: { code },
+            workerData: { code, outputFlow, outputWindow: SCRIPT_OUTPUT_WINDOW },
             env: {},
         });
         const activeWorker = worker;
@@ -286,6 +291,9 @@ async function runMcpScriptOperation(state, code, timeoutMs = DEFAULT_MCP_SCRIPT
                     return;
                 if (message.type === "emit") {
                     output.push(toContentBlock(message.block));
+                    const queued = Atomics.sub(outputFlow, 0, message.size) - message.size;
+                    if (queued <= SCRIPT_OUTPUT_WINDOW / 2)
+                        Atomics.notify(outputFlow, 0);
                     return;
                 }
                 if (message.type === "done") {
@@ -395,8 +403,13 @@ async function runMcpScriptOperation(state, code, timeoutMs = DEFAULT_MCP_SCRIPT
         await worker?.terminate();
     }
     const callsSnapshot = snapshotCalls();
-    // Snapshot before the asynchronous output guard; the terminated worker can no longer emit.
-    const guarded = await guardMcpOutput([...(output.length > 0 ? output : [{ type: "text", text: "(no output)" }]), ...[...payloadNotices].map(text => ({ type: "text", text })), ...[...resultRefs].map(ref => ({ type: "text", text: formatMcpResultReference(ref) }))], resolveMcpOutputGuardOptions(state.config.settings, state.outputDirectory));
+    if (output.empty)
+        output.push({ type: "text", text: "(no output)" });
+    for (const text of payloadNotices)
+        output.push({ type: "text", text });
+    for (const ref of resultRefs)
+        output.push({ type: "text", text: formatMcpResultReference(ref) });
+    const guarded = output.finish();
     return {
         content: guarded.content,
         details: {

package/dist/mcp-oauth-callback-config.d.ts

@@ -0,0 +1,8 @@
+/** SDK-free process-shared OAuth callback endpoint configuration. */
+export declare const DEFAULT_OAUTH_CALLBACK_PORT = 19876;
+export declare const DEFAULT_OAUTH_CALLBACK_PATH = "/callback";
+export declare function getConfiguredOAuthCallbackPort(): number;
+export declare function getOAuthCallbackPort(): number;
+export declare function setOAuthCallbackPort(port: number): void;
+export declare function getOAuthCallbackPath(): string;
+export declare function setOAuthCallbackPath(path: string): void;

package/dist/mcp-oauth-callback-config.js

@@ -0,0 +1,28 @@
+/** SDK-free process-shared OAuth callback endpoint configuration. */
+// Callback server configuration
+export const DEFAULT_OAUTH_CALLBACK_PORT = 19876;
+export const DEFAULT_OAUTH_CALLBACK_PATH = "/callback";
+let configuredOAuthCallbackPort = DEFAULT_OAUTH_CALLBACK_PORT;
+if (process.env.MCP_OAUTH_CALLBACK_PORT) {
+    const parsedPort = Number.parseInt(process.env.MCP_OAUTH_CALLBACK_PORT, 10);
+    if (Number.isInteger(parsedPort) && parsedPort > 0 && parsedPort <= 65535) {
+        configuredOAuthCallbackPort = parsedPort;
+    }
+}
+let oauthCallbackPort = configuredOAuthCallbackPort;
+let oauthCallbackPath = DEFAULT_OAUTH_CALLBACK_PATH;
+export function getConfiguredOAuthCallbackPort() {
+    return configuredOAuthCallbackPort;
+}
+export function getOAuthCallbackPort() {
+    return oauthCallbackPort;
+}
+export function setOAuthCallbackPort(port) {
+    oauthCallbackPort = port;
+}
+export function getOAuthCallbackPath() {
+    return oauthCallbackPath;
+}
+export function setOAuthCallbackPath(path) {
+    oauthCallbackPath = path.startsWith("/") ? path : `/${path}`;
+}

package/dist/mcp-oauth-provider.d.ts

@@ -13,13 +13,6 @@ export declare function validateOAuthClientMetadataUrl(value: string | false | u
 /** Only the port may differ; keep raw host, path and query spelling exact. */
 export declare function loopbackRedirectsMatch(first: string, second: unknown): boolean;
 export declare function issuersMatch(first: string, second: string): boolean;
-declare const DEFAULT_OAUTH_CALLBACK_PORT = 19876;
-declare const DEFAULT_OAUTH_CALLBACK_PATH = "/callback";
-export declare function getConfiguredOAuthCallbackPort(): number;
-export declare function getOAuthCallbackPort(): number;
-export declare function setOAuthCallbackPort(port: number): void;
-export declare function getOAuthCallbackPath(): string;
-export declare function setOAuthCallbackPath(path: string): void;
 /** Configuration options for OAuth */
 export interface McpOAuthConfig {
     skipIssuerMetadataValidation?: boolean;
@@ -151,4 +144,4 @@ export declare class McpOAuthProvider implements OAuthClientProvider {
     private prepareCrossAppRequest;
     prepareTokenRequest(scope?: string): URLSearchParams | Promise<URLSearchParams> | undefined;
 }
-export { DEFAULT_OAUTH_CALLBACK_PORT, DEFAULT_OAUTH_CALLBACK_PATH };
+export { DEFAULT_OAUTH_CALLBACK_PORT, DEFAULT_OAUTH_CALLBACK_PATH, getConfiguredOAuthCallbackPort, getOAuthCallbackPath, getOAuthCallbackPort, setOAuthCallbackPath, setOAuthCallbackPort, } from "./mcp-oauth-callback-config.ts";

package/dist/mcp-oauth-provider.js

@@ -10,6 +10,7 @@ import { getAuthForUrl, updateTokens, updateClientInfo, clearAllCredentials, cle
 import { resolveCommandSecret } from "./utils.js";
 import { isNonInteractiveOAuth } from "./types.js";
 import { combineAbortSignals } from "./runtime-owner.js";
+import { getOAuthCallbackPath, getOAuthCallbackPort } from "./mcp-oauth-callback-config.js";
 import sharedClientMetadata from "./docs/client-metadata.json" with { type: "json" };
 /** Validate explicit document URLs without echoing possible credentials in errors. */
 export function validateOAuthClientMetadataUrl(value) {
@@ -50,33 +51,6 @@ export function issuersMatch(first, second) {
         || (first.endsWith("/") && first.slice(0, -1) === second)
         || (second.endsWith("/") && second.slice(0, -1) === first);
 }
-// Callback server configuration
-const DEFAULT_OAUTH_CALLBACK_PORT = 19876;
-const DEFAULT_OAUTH_CALLBACK_PATH = "/callback";
-let configuredOAuthCallbackPort = DEFAULT_OAUTH_CALLBACK_PORT;
-if (process.env.MCP_OAUTH_CALLBACK_PORT) {
-    const parsedPort = Number.parseInt(process.env.MCP_OAUTH_CALLBACK_PORT, 10);
-    if (Number.isInteger(parsedPort) && parsedPort > 0 && parsedPort <= 65535) {
-        configuredOAuthCallbackPort = parsedPort;
-    }
-}
-let oauthCallbackPort = configuredOAuthCallbackPort;
-let oauthCallbackPath = DEFAULT_OAUTH_CALLBACK_PATH;
-export function getConfiguredOAuthCallbackPort() {
-    return configuredOAuthCallbackPort;
-}
-export function getOAuthCallbackPort() {
-    return oauthCallbackPort;
-}
-export function setOAuthCallbackPort(port) {
-    oauthCallbackPort = port;
-}
-export function getOAuthCallbackPath() {
-    return oauthCallbackPath;
-}
-export function setOAuthCallbackPath(path) {
-    oauthCallbackPath = path.startsWith("/") ? path : `/${path}`;
-}
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -669,4 +643,4 @@ export class McpOAuthProvider {
         return params;
     }
 }
-export { DEFAULT_OAUTH_CALLBACK_PORT, DEFAULT_OAUTH_CALLBACK_PATH };
+export { DEFAULT_OAUTH_CALLBACK_PORT, DEFAULT_OAUTH_CALLBACK_PATH, getConfiguredOAuthCallbackPort, getOAuthCallbackPath, getOAuthCallbackPort, setOAuthCallbackPath, setOAuthCallbackPort, } from "./mcp-oauth-callback-config.js";

package/dist/mcp-oauth-runtime.d.ts

@@ -0,0 +1,83 @@
+/**
+ * SDK-free OAuth runtime ownership and pending-flow cleanup.
+ * Native auth/protocol implementation stays in mcp-auth-flow.ts and is loaded
+ * only by operations that need it; all callers share the state owned here.
+ */
+import type { McpOAuthProvider } from "./mcp-oauth-provider.ts";
+import { type AuthStorageOptions } from "./mcp-auth.ts";
+import type { ServerEntry } from "./types.ts";
+/** Auth status for a server */
+export type AuthStatus = "authenticated" | "expired" | "not_authenticated";
+export interface McpOAuthRuntime {
+    readonly signal: AbortSignal;
+}
+export interface AuthenticateOptions {
+    onAuthorizationUrl?: (authorizationUrl: string) => void | Promise<void>;
+    authStorageOptions?: AuthStorageOptions;
+    signal?: AbortSignal;
+    runtime?: McpOAuthRuntime;
+}
+export type AuthDiscovery = {
+    resourceMetadataUrl?: URL;
+    scope?: string;
+    skipIssuerMetadataValidation?: boolean;
+};
+export type CallbackIssuer = {
+    expectedIssuer?: string | undefined;
+    fallbackIssuer?: string;
+    issParameterSupported?: boolean;
+};
+export type PendingAuth = {
+    serverName: string;
+    authProvider: McpOAuthProvider;
+    serverUrl: string;
+    authorizationUrl: string;
+    discovery: AuthDiscovery;
+    callbackIssuer: CallbackIssuer;
+    request?: OAuthRequest;
+    authStorageOptions: AuthStorageOptions;
+};
+export type RuntimeState = {
+    controller: AbortController;
+    generation: number;
+    pendingAuths: Map<string, PendingAuth>;
+    pendingAuthStates: Map<string, string>;
+    pendingAuthCleanupTimers: Map<string, ReturnType<typeof setTimeout>>;
+    pendingAuthentications: Map<string, Promise<AuthStatus>>;
+    requests: Map<string, OAuthRequest>;
+};
+export declare function createOAuthRuntime(signal?: AbortSignal): McpOAuthRuntime;
+export declare let legacyRuntime: McpOAuthRuntime;
+export declare function getRuntime(options?: AuthenticateOptions): McpOAuthRuntime;
+export declare function getRuntimeState(runtime: McpOAuthRuntime): RuntimeState;
+export declare function getPendingAuthKey(serverName: string, options: AuthStorageOptions): string;
+export type OAuthRequest = {
+    serverName: string;
+    serverUrl: string;
+    requestedScope?: string;
+    challenge?: {
+        requiredScope?: string;
+        resourceMetadataUrl?: URL;
+    };
+    issuer?: string;
+};
+export declare function hasPendingAuth(serverName: string, options?: AuthStorageOptions, runtime?: McpOAuthRuntime): boolean;
+export declare function clearPendingAuth(runtime: McpOAuthRuntime, serverName: string, oauthState?: string, fallbackStorageOptions?: AuthStorageOptions): Promise<void>;
+/**
+ * Check if OAuth is supported for a server configuration.
+ * OAuth is supported for HTTP servers unless explicitly disabled.
+ *
+ * @param definition - The server definition
+ * @returns True if OAuth is supported
+ */
+export declare function supportsOAuth(definition: ServerEntry): boolean;
+/**
+ * Initialize the OAuth system on startup.
+ * OAuth callback binding is lazy and starts from startAuth() only.
+ */
+export declare function initializeOAuth(runtimeOrSignal?: McpOAuthRuntime | AbortSignal): Promise<McpOAuthRuntime>;
+/**
+ * Shutdown one OAuth runtime. The callback server remains process-shared while
+ * another runtime has pending/reserved callback state or is still active.
+ */
+export declare function shutdownOAuth(runtime?: McpOAuthRuntime): Promise<void>;

package/dist/mcp-oauth-runtime.js

@@ -0,0 +1,145 @@
+/**
+ * SDK-free OAuth runtime ownership and pending-flow cleanup.
+ * Native auth/protocol implementation stays in mcp-auth-flow.ts and is loaded
+ * only by operations that need it; all callers share the state owned here.
+ */
+import { cancelPendingCallback, stopCallbackServer } from "./mcp-callback-server.js";
+import { getAuthBaseDir, getOAuthState, clearOAuthState } from "./mcp-auth.js";
+import { combineAbortSignals } from "./runtime-owner.js";
+const runtimeStates = new WeakMap();
+const activeRuntimes = new Set();
+export function createOAuthRuntime(signal) {
+    const controller = new AbortController();
+    const runtime = { signal: combineAbortSignals(signal, controller.signal) };
+    runtimeStates.set(runtime, {
+        controller,
+        generation: 0,
+        pendingAuths: new Map(),
+        pendingAuthStates: new Map(),
+        pendingAuthCleanupTimers: new Map(),
+        pendingAuthentications: new Map(),
+        requests: new Map(),
+    });
+    activeRuntimes.add(runtime);
+    return runtime;
+}
+export let legacyRuntime = createOAuthRuntime();
+activeRuntimes.delete(legacyRuntime);
+export function getRuntime(options) {
+    if (options?.runtime) {
+        options.runtime.signal.throwIfAborted();
+        activeRuntimes.add(options.runtime);
+        return options.runtime;
+    }
+    if (legacyRuntime.signal.aborted)
+        legacyRuntime = createOAuthRuntime();
+    activeRuntimes.add(legacyRuntime);
+    return legacyRuntime;
+}
+export function getRuntimeState(runtime) {
+    const state = runtimeStates.get(runtime);
+    if (!state)
+        throw new Error("Unknown OAuth runtime");
+    return state;
+}
+export function getPendingAuthKey(serverName, options) {
+    return JSON.stringify([serverName, getAuthBaseDir(options)]);
+}
+export function hasPendingAuth(serverName, options, runtime) {
+    const state = getRuntimeState(runtime ?? legacyRuntime);
+    if (options) {
+        return state.pendingAuths.has(getPendingAuthKey(serverName, options));
+    }
+    return Array.from(state.pendingAuths.values()).some(pendingAuth => pendingAuth.serverName === serverName);
+}
+export async function clearPendingAuth(runtime, serverName, oauthState, fallbackStorageOptions = {}) {
+    const state = getRuntimeState(runtime);
+    const key = getPendingAuthKey(serverName, fallbackStorageOptions);
+    const pendingAuth = state.pendingAuths.get(key);
+    const authStorageOptions = pendingAuth?.authStorageOptions ?? fallbackStorageOptions;
+    const pendingState = state.pendingAuthStates.get(key);
+    if (oauthState && pendingState && pendingState !== oauthState)
+        return;
+    const timer = state.pendingAuthCleanupTimers.get(key);
+    if (timer) {
+        clearTimeout(timer);
+        state.pendingAuthCleanupTimers.delete(key);
+    }
+    pendingAuth?.authProvider.deactivate();
+    state.pendingAuths.delete(key);
+    state.pendingAuthStates.delete(key);
+    const stateToRelease = pendingState ?? oauthState;
+    if (stateToRelease) {
+        cancelPendingCallback(stateToRelease);
+        const storedState = await getOAuthState(serverName, authStorageOptions);
+        if (storedState === stateToRelease) {
+            await clearOAuthState(serverName, authStorageOptions);
+        }
+    }
+}
+/**
+ * Check if OAuth is supported for a server configuration.
+ * OAuth is supported for HTTP servers unless explicitly disabled.
+ *
+ * @param definition - The server definition
+ * @returns True if OAuth is supported
+ */
+export function supportsOAuth(definition) {
+    // OAuth requires a URL
+    if (!definition.url)
+        return false;
+    // Explicitly disabled via auth: false or oauth: false
+    if (definition.auth === false)
+        return false;
+    if (definition.oauth === false)
+        return false;
+    if (definition.auth === "oauth")
+        return true;
+    // Configured custom headers take precedence over implicit OAuth auto-detection.
+    if (definition.headers && Object.keys(definition.headers).length > 0)
+        return false;
+    // OAuth is enabled when auth is not specified (auto-detect)
+    return definition.auth === undefined;
+}
+/**
+ * Initialize the OAuth system on startup.
+ * OAuth callback binding is lazy and starts from startAuth() only.
+ */
+export async function initializeOAuth(runtimeOrSignal) {
+    if (runtimeOrSignal && "signal" in runtimeOrSignal) {
+        runtimeOrSignal.signal.throwIfAborted();
+        activeRuntimes.add(runtimeOrSignal);
+        return runtimeOrSignal;
+    }
+    await shutdownOAuth(legacyRuntime);
+    legacyRuntime = createOAuthRuntime(runtimeOrSignal);
+    return legacyRuntime;
+}
+/**
+ * Shutdown one OAuth runtime. The callback server remains process-shared while
+ * another runtime has pending/reserved callback state or is still active.
+ */
+export async function shutdownOAuth(runtime = legacyRuntime) {
+    const state = getRuntimeState(runtime);
+    if (state.controller.signal.aborted)
+        return;
+    state.generation += 1;
+    state.controller.abort(new Error("OAuth runtime stopped"));
+    for (const callbackState of Array.from(state.pendingAuthStates.values()))
+        cancelPendingCallback(callbackState);
+    const results = await Promise.allSettled(Array.from(state.pendingAuths.values(), pendingAuth => clearPendingAuth(runtime, pendingAuth.serverName, undefined, pendingAuth.authStorageOptions)));
+    const failures = results.flatMap(result => result.status === "rejected" ? [result.reason] : []);
+    state.pendingAuthentications.clear();
+    state.requests.clear();
+    activeRuntimes.delete(runtime);
+    if (activeRuntimes.size === 0) {
+        try {
+            await stopCallbackServer();
+        }
+        catch (error) {
+            failures.push(error);
+        }
+    }
+    if (failures.length)
+        throw new AggregateError(failures, "MCP OAuth cleanup failed");
+}

package/dist/mcp-output-guard.d.ts

@@ -61,7 +61,7 @@ export interface McpPayloadFile {
     error?: string;
 }
 export type RetainedMcpResult = Pick<GuardedMcpOutput, "mcpResult" | "resultRef" | "resultWriteError" | "payloadFiles">;
-export declare function resolveMcpOutputGuardOptions(settings?: McpSettings, outputDirectory?: string): Pick<McpOutputGuardOptions, "enabled" | "maxBytes" | "maxLines" | "detailsMaxBytes" | "outputDirectory">;
+export declare function resolveMcpOutputGuardOptions(settings?: McpSettings, outputDirectory?: string): Pick<McpOutputGuardOptions, "enabled" | "detailsMaxBytes" | "outputDirectory"> & Required<Pick<McpOutputGuardOptions, "maxBytes" | "maxLines">>;
 /** Spread helper for tool-result details: includes mcpResult/outputGuard only when present. */
 export declare function guardedMcpDetails(guarded: GuardedMcpOutput): Record<string, unknown>;
 /**