@namzu/sdk 27.1.0 → 28.0.0

package/src/connector/index.ts

@@ -18,43 +18,59 @@ export type {
 export { HttpConnector } from './builtins/http.js'
 export { WebhookConnector } from './builtins/webhook.js'
 
-export { BaseExecutionContext } from '../execution/base.js'
-export { LocalExecutionContext } from '../execution/local.js'
-export type { LocalExecutionContextOptions } from '../execution/local.js'
-
+// All five backends live in `execution/`. This block reached into two
+// directories to reassemble one group, which is what let the concept sit in
+// two places — a connector is one CALLER of an execution context, not the
+// thing that defines one.
 export {
-	RemoteExecutionContext,
-	HybridExecutionContext,
+	BaseExecutionContext,
 	ExecutionContextFactory,
-} from './execution/index.js'
+	HybridExecutionContext,
+	LocalExecutionContext,
+	RemoteExecutionContext,
+} from '../execution/index.js'
 export type {
-	RemoteExecutionContextOptions,
 	HybridExecutionContextOptions,
-} from './execution/index.js'
-
-export { StdioTransport } from './mcp/stdio.js'
-export { HttpSseTransport } from './mcp/http-sse.js'
-export { StreamableHttpTransport } from './mcp/streamable-http.js'
-
-export { MCPClient } from './mcp/client.js'
+	LocalExecutionContextOptions,
+	RemoteExecutionContextOptions,
+} from '../execution/index.js'
 
+// One seam, not two. This block used to hand-list names from the mcp LEAF
+// modules while `mcp/index.ts` listed its own set, and the two diverged:
+// `ServerStdioTransport` reached that barrel and stopped here, so
+// `MCPServer` was public with no public way to serve it — a consumer could
+// construct the thing and not run it. Sourcing from the barrel means a name
+// added there cannot be silently dropped on the way out.
 export {
-	mcpToolToToolDefinition,
-	toolDefinitionToMCPTool,
+	applyNamePolicy,
+	applyToolPolicy,
+	diffTools,
+	hasDrift,
+	HttpSseTransport,
+	MCPClient,
+	MCPConnectorBridge,
+	MCPMethodNotFound,
+	MCPServer,
+	MCPToolDiscovery,
 	mcpJsonSchemaToZod,
-	zodToMCPJsonSchema,
+	mcpPromptToToolDefinition,
 	mcpToolResultToToolResult,
+	mcpToolToToolDefinition,
+	renderPromptMessages,
+	ServerStdioTransport,
+	StdioTransport,
+	StreamableHttpTransport,
+	toolDefinitionToMCPTool,
 	toolResultToMCPToolResult,
-} from './mcp/adapter.js'
-
-export { MCPToolDiscovery } from './mcp/discovery.js'
-export { mcpPromptToToolDefinition, renderPromptMessages } from './mcp/prompt-adapter.js'
-
-export { MCPConnectorBridge } from '../bridge/mcp/connector/adapter.js'
-
-export { MCPServer, MCPMethodNotFound } from './mcp/server.js'
+	toolsHash,
+	zodToMCPJsonSchema,
+} from './mcp/index.js'
 export type {
-	MCPServerToolProvider,
-	MCPServerResourceProvider,
 	MCPServerPromptProvider,
-} from './mcp/server.js'
+	MCPServerResourceProvider,
+	MCPServerToolProvider,
+	MCPToolDiscoveryOptions,
+	MCPToolDrift,
+	MCPToolPolicy,
+	MCPToolPolicyDecision,
+} from './mcp/index.js'

package/src/connector/mcp/client.ts

@@ -20,7 +20,9 @@ import type {
 import type { MCPClientId } from '../../types/ids/index.js'
 import { toErrorMessage } from '../../utils/error.js'
 import { generateMCPClientId } from '../../utils/id.js'
-import { type Logger, getRootLogger } from '../../utils/logger.js'
+import type { LogAttributes } from '../../utils/log/index.js'
+import { SCOPE_ATTRIBUTE } from '../../utils/log/types.js'
+import { type Logger, resolveLogger } from '../../utils/logger.js'
 import { HttpSseTransport } from './http-sse.js'
 import { StdioTransport } from './stdio.js'
 import { StreamableHttpTransport } from './streamable-http.js'
@@ -31,6 +33,7 @@ import {
 	MCP_PROTOCOL_VERSION,
 	MCP_SUPPORTED_PROTOCOL_VERSIONS,
 } from '../../constants/mcp/index.js'
+import { NAMZU } from '../../constants/telemetry/index.js'
 import { VERSION } from '../../version.js'
 
 /** Runaway guard for a server whose cursor never ends. */
@@ -63,8 +66,14 @@ export class MCPClient {
 	constructor(config: MCPClientConfig) {
 		this.config = config
 		this.id = config.id ?? generateMCPClientId()
+		// Built BEFORE the transport, not after: `createTransport` threads
+		// `this.log` into whichever transport it constructs (LOG-10), so the
+		// transport's own logger has to exist by the time that call runs.
+		this.log = resolveLogger(config.logger).child({
+			[SCOPE_ATTRIBUTE]: 'connector/mcp',
+			[NAMZU.SERVER_ID]: config.serverName,
+		})
 		this.transport = this.createTransport(config.transport)
-		this.log = getRootLogger().child({ component: 'MCPClient', serverId: config.serverName })
 	}
 
 	async connect(): Promise<MCPInitializeResult> {
@@ -85,7 +94,7 @@ export class MCPClient {
 			this.transport.onError((err) => {
 				this.status = 'error'
 				this.error = err.message
-				this.log.error('MCP transport error', { error: err.message })
+				this.log.error('MCP transport error', { 'exception.message': err.message })
 				this.emitLifecycle({ type: 'mcp_client_error', clientId: this.id, error: err.message })
 				this.rejectAllPending(`MCP transport to "${this.config.serverName}" failed: ${err.message}`)
 			})
@@ -111,8 +120,8 @@ export class MCPClient {
 			}
 			if (negotiated && negotiated !== MCP_PROTOCOL_VERSION) {
 				this.log.info('MCP server negotiated a different protocol version', {
-					requested: MCP_PROTOCOL_VERSION,
-					negotiated,
+					'namzu.connector.requested': MCP_PROTOCOL_VERSION,
+					'namzu.connector.negotiated': negotiated,
 				})
 			}
 
@@ -128,13 +137,16 @@ export class MCPClient {
 				clientId: this.id,
 				serverName: this.config.serverName,
 			})
-			this.log.info(`Connected to MCP server: ${result.serverInfo.name}`)
+			const connectedAttributes: LogAttributes = {
+				[NAMZU.SERVER_NAME]: result.serverInfo.name,
+			}
+			this.log.info('Connected to MCP server', connectedAttributes)
 
 			return result
 		} catch (err) {
 			this.status = 'error'
 			this.error = toErrorMessage(err)
-			this.log.error('MCP connection failed', { error: this.error })
+			this.log.error('MCP connection failed', { 'exception.message': this.error })
 			this.emitLifecycle({ type: 'mcp_client_error', clientId: this.id, error: this.error })
 			throw err
 		}
@@ -321,7 +333,7 @@ export class MCPClient {
 			try {
 				listener(event)
 			} catch (err) {
-				this.log.warn('MCP lifecycle listener threw', { error: toErrorMessage(err) })
+				this.log.warn('MCP lifecycle listener threw', { 'exception.message': toErrorMessage(err) })
 			}
 		}
 	}
@@ -329,12 +341,12 @@ export class MCPClient {
 	private createTransport(config: MCPTransportUnion): MCPTransport {
 		switch (config.type) {
 			case 'stdio':
-				return new StdioTransport(config)
+				return new StdioTransport(config, this.log)
 			case 'http-sse':
-				return new HttpSseTransport(config)
+				return new HttpSseTransport(config, this.log)
 			case 'streamable_http':
 			case 'streamable-http':
-				return new StreamableHttpTransport(config)
+				return new StreamableHttpTransport(config, this.log)
 			default:
 				throw new Error(`Unsupported MCP transport type: ${(config as MCPTransportUnion).type}`)
 		}
@@ -366,9 +378,9 @@ export class MCPClient {
 			const timer = setTimeout(() => {
 				this.pendingRequests.delete(id)
 				this.log.warn('MCP request timed out', {
-					server: this.config.serverName,
-					method,
-					timeoutMs,
+					'namzu.connector.server': this.config.serverName,
+					'namzu.connector.method': method,
+					'namzu.connector.timeout_ms': timeoutMs,
 				})
 				reject(
 					new Error(
@@ -406,9 +418,9 @@ export class MCPClient {
 	private rejectAllPending(reason: string): void {
 		if (this.pendingRequests.size === 0) return
 		this.log.warn('Failing in-flight MCP requests', {
-			server: this.config.serverName,
-			count: this.pendingRequests.size,
-			reason,
+			'namzu.connector.server': this.config.serverName,
+			'namzu.connector.count': this.pendingRequests.size,
+			'namzu.connector.reason': reason,
 		})
 		for (const [, pending] of this.pendingRequests) {
 			pending.reject(new Error(reason))
@@ -454,8 +466,8 @@ export class MCPClient {
 		// Answer honestly: we do not implement these yet.
 		if (message.method && message.id !== undefined) {
 			this.log.warn('Declining unsupported server-initiated MCP request', {
-				server: this.config.serverName,
-				method: message.method,
+				'namzu.connector.server': this.config.serverName,
+				'namzu.connector.method': message.method,
 			})
 			void this.transport
 				.send({
@@ -468,7 +480,7 @@ export class MCPClient {
 				})
 				.catch((err) => {
 					this.log.debug('Failed to send method-not-found reply', {
-						error: toErrorMessage(err),
+						'exception.message': toErrorMessage(err),
 					})
 				})
 		}

package/src/connector/mcp/discovery.ts

@@ -1,3 +1,4 @@
+import { NAMZU } from '../../constants/telemetry/index.js'
 import type {
 	MCPDiscoveredTool,
 	MCPPromptDefinition,
@@ -5,7 +6,8 @@ import type {
 } from '../../types/connector/index.js'
 import type { ToolDefinition } from '../../types/tool/index.js'
 import { toErrorMessage } from '../../utils/error.js'
-import { type Logger, getRootLogger } from '../../utils/logger.js'
+import { SCOPE_ATTRIBUTE } from '../../utils/log/types.js'
+import { type Logger, resolveLogger } from '../../utils/logger.js'
 import { mcpToolToToolDefinition } from './adapter.js'
 import type { MCPClient } from './client.js'
 import {
@@ -60,7 +62,12 @@ export class MCPToolDiscovery {
 	constructor(clients: MCPClient[], options: MCPToolDiscoveryOptions = {}) {
 		this.clients = clients
 		this.options = options
-		this.log = options.logger ?? getRootLogger().child({ component: 'MCPToolDiscovery' })
+		// Was `options.logger ?? getRootLogger().child(...)`: `??` binds looser
+		// than the method call, so when `options.logger` WAS supplied the
+		// `.child({component: ...})` binding never applied at all — a caller
+		// that injected a logger got NO scope stamp, silently. `resolveLogger`
+		// collapses the fallback so `.child()` always runs, for both paths.
+		this.log = resolveLogger(options.logger).child({ [SCOPE_ATTRIBUTE]: 'connector/mcp/discovery' })
 	}
 
 	addClient(client: MCPClient): void {
@@ -81,7 +88,7 @@ export class MCPToolDiscovery {
 
 		for (const client of this.clients) {
 			if (!client.isConnected()) {
-				this.log.warn(`Skipping disconnected MCP client: ${client.id}`)
+				this.log.warn('Skipping disconnected MCP client', { 'namzu.mcp.client_id': client.id })
 				continue
 			}
 
@@ -89,13 +96,17 @@ export class MCPToolDiscovery {
 				const tools = await this.discoverFrom(client)
 				results.push(...tools)
 			} catch (err) {
-				this.log.error(`Failed to discover tools from ${client.id}`, {
-					error: toErrorMessage(err),
+				this.log.error('Failed to discover tools from an MCP client', {
+					'namzu.mcp.client_id': client.id,
+					'exception.message': toErrorMessage(err),
 				})
 			}
 		}
 
-		this.log.info(`Discovered ${results.length} MCP tools from ${this.clients.length} clients`)
+		this.log.info('Discovered MCP tools', {
+			'namzu.mcp.tool_count': results.length,
+			'namzu.mcp.client_count': this.clients.length,
+		})
 		return results
 	}
 
@@ -112,9 +123,9 @@ export class MCPToolDiscovery {
 
 		if (refused.length > 0) {
 			this.log.warn('MCP tools refused by policy', {
-				serverName: state.serverName,
-				clientId: client.id,
-				refused: refused.map((r) => `${r.name} (${r.reason})`),
+				[NAMZU.SERVER_NAME]: state.serverName,
+				'namzu.mcp.client_id': client.id,
+				'namzu.connector.refused': refused.map((r) => `${r.name} (${r.reason})`),
 			})
 		}
 
@@ -148,9 +159,9 @@ export class MCPToolDiscovery {
 			advertised = await client.listPrompts()
 		} catch (err) {
 			this.log.debug('MCP server published no prompts', {
-				serverName: state.serverName,
-				clientId: client.id,
-				reason: toErrorMessage(err),
+				[NAMZU.SERVER_NAME]: state.serverName,
+				'namzu.mcp.client_id': client.id,
+				'namzu.connector.reason': toErrorMessage(err),
 			})
 			return []
 		}
@@ -160,9 +171,9 @@ export class MCPToolDiscovery {
 
 		if (refused.length > 0) {
 			this.log.warn('MCP prompts refused by policy', {
-				serverName: state.serverName,
-				clientId: client.id,
-				refused: refused.map((r) => `${r.name} (${r.reason})`),
+				[NAMZU.SERVER_NAME]: state.serverName,
+				'namzu.mcp.client_id': client.id,
+				'namzu.connector.refused': refused.map((r) => `${r.name} (${r.reason})`),
 			})
 		}
 
@@ -189,11 +200,11 @@ export class MCPToolDiscovery {
 		if (!hasDrift(drift)) return
 
 		this.log.warn('MCP server tool set changed since the last discovery', {
-			serverName,
-			clientId,
-			added: drift.added,
-			removed: drift.removed,
-			changed: drift.changed,
+			[NAMZU.SERVER_NAME]: serverName,
+			'namzu.mcp.client_id': clientId,
+			'namzu.connector.added': drift.added,
+			'namzu.connector.removed': drift.removed,
+			'namzu.connector.changed': drift.changed,
 		})
 		this.options.onDrift?.({ serverName, clientId, drift })
 	}

package/src/connector/mcp/http-sse.ts

@@ -3,7 +3,8 @@ import type {
 	MCPJsonRpcMessage,
 	MCPTransport,
 } from '../../types/connector/index.js'
-import { type Logger, getRootLogger } from '../../utils/logger.js'
+import { SCOPE_ATTRIBUTE } from '../../utils/log/types.js'
+import { type Logger, resolveLogger } from '../../utils/logger.js'
 
 /**
  * Trim trailing slashes without a regex.
@@ -30,11 +31,14 @@ export class HttpSseTransport implements MCPTransport {
 	private postUrl: string
 	private log: Logger
 
-	constructor(private readonly config: MCPHttpSseTransportConfig) {
+	constructor(
+		private readonly config: MCPHttpSseTransportConfig,
+		log?: Logger,
+	) {
 		const base = stripTrailingSlashes(config.url)
 		this.sseUrl = `${base}/sse`
 		this.postUrl = `${base}/message`
-		this.log = getRootLogger().child({ component: 'HttpSseTransport' })
+		this.log = resolveLogger(log).child({ [SCOPE_ATTRIBUTE]: 'connector/mcp/http-sse' })
 	}
 
 	async connect(): Promise<void> {
@@ -43,7 +47,7 @@ export class HttpSseTransport implements MCPTransport {
 		this.abortController = new AbortController()
 		await this.startSSE()
 		this.connected = true
-		this.log.info(`HttpSseTransport connected to ${this.config.url}`)
+		this.log.info('HttpSseTransport connected', { 'namzu.mcp.url': this.config.url })
 	}
 
 	async close(): Promise<void> {
@@ -122,7 +126,7 @@ export class HttpSseTransport implements MCPTransport {
 	private async startSSE(): Promise<void> {
 		this.listenSSE().catch((err) => {
 			if (this.connected) {
-				this.log.error('SSE stream error', { error: String(err) })
+				this.log.error('SSE stream error', { 'exception.message': String(err) })
 				for (const handler of this.errorHandlers)
 					handler(err instanceof Error ? err : new Error(String(err)))
 			}
@@ -162,7 +166,9 @@ export class HttpSseTransport implements MCPTransport {
 					const message = JSON.parse(data) as MCPJsonRpcMessage
 					for (const handler of this.messageHandlers) handler(message)
 				} catch {
-					this.log.warn(`HttpSseTransport: invalid SSE data: ${data.slice(0, 100)}`)
+					this.log.warn('HttpSseTransport: invalid SSE data', {
+						'namzu.mcp.data_head': data.slice(0, 100),
+					})
 				}
 			}
 		}

package/src/connector/mcp/index.ts

@@ -1,9 +1,6 @@
 export { StdioTransport } from './stdio.js'
 export { HttpSseTransport } from './http-sse.js'
 export { StreamableHttpTransport } from './streamable-http.js'
-// The server half. The three above connect this process to somebody
-// else's MCP server; this one lets somebody else's client drive ours.
-export { ServerStdioTransport } from './server-stdio.js'
 
 export { MCPClient } from './client.js'
 
@@ -21,12 +18,16 @@ export { mcpPromptToToolDefinition, renderPromptMessages } from './prompt-adapte
 
 export { MCPConnectorBridge } from '../../bridge/mcp/connector/adapter.js'
 
-export { MCPServer, MCPMethodNotFound } from './server.js'
+// The direction reverses in `server/`: everything else in this barrel is
+// this process calling somebody else's MCP server, and that subdirectory
+// is somebody else's client calling ours. Re-exported from here so no
+// consumer's import path changes.
+export { MCPMethodNotFound, MCPServer, ServerStdioTransport } from './server/index.js'
 export type {
-	MCPServerToolProvider,
-	MCPServerResourceProvider,
 	MCPServerPromptProvider,
-} from './server.js'
+	MCPServerResourceProvider,
+	MCPServerToolProvider,
+} from './server/index.js'
 
 export type { MCPToolDiscoveryOptions } from './discovery.js'
 export { applyNamePolicy, applyToolPolicy, diffTools, hasDrift, toolsHash } from './policy.js'

package/src/connector/mcp/reconnect.ts

@@ -0,0 +1,194 @@
+import { z } from 'zod'
+
+import type { MCPClient } from './client.js'
+
+/**
+ * Keeps an MCP connection alive across a transport that drops.
+ *
+ * `MCPClient.connect()` is called exactly once, by whoever built the client.
+ * `transport.onClose` sets `status = 'disconnected'`, emits the lifecycle
+ * event and rejects everything pending — and nothing in the module schedules
+ * another attempt. So one blip, one server restart, one laptop sleep, and the
+ * plugin's tools are gone for the rest of the process while the plugin itself
+ * still reports as enabled: the failure is silent at the layer a host looks at.
+ *
+ * This is a supervisor rather than a retry inside `connect()` on purpose. A
+ * caller awaiting `connect()` wants to know whether the first attempt worked;
+ * burying an unbounded retry in it would turn a fast, actionable failure at
+ * startup into a hang. Recovery after a connection that once succeeded is a
+ * different question, and it belongs to a different object.
+ */
+
+/** How the supervisor backs off. Every field has a default. */
+export interface MCPReconnectOptions {
+	/** Defaults to true. `false` makes this object inert rather than absent. */
+	readonly enabled?: boolean
+	/** First wait, in ms. Defaults to 500. */
+	readonly initialDelayMs?: number
+	/** Ceiling for the exponential wait, in ms. Defaults to 30_000. */
+	readonly maxDelayMs?: number
+	/** Attempts before giving up. Defaults to 6. */
+	readonly maxAttempts?: number
+	/**
+	 * Called after a reconnect succeeds.
+	 *
+	 * A reconnected client is not the same as one that never dropped: its
+	 * server may have restarted with a different tool list, and every
+	 * subscription the host made through `onNotification` was made against a
+	 * transport that no longer exists. The supervisor cannot know what a host
+	 * needs to redo, so it says when rather than guessing what.
+	 */
+	readonly onReconnected?: () => void | Promise<void>
+	/** Called when the attempts are exhausted. */
+	readonly onGaveUp?: (attempts: number) => void
+}
+
+const DEFAULTS = {
+	enabled: true,
+	initialDelayMs: 500,
+	maxDelayMs: 30_000,
+	maxAttempts: 6,
+} as const
+
+/**
+ * Watches one client and reconnects it when its transport drops.
+ *
+ * ## Stop it before you disconnect deliberately
+ *
+ * `MCPClient.disconnect()` emits the same `mcp_client_disconnected` event the
+ * transport does when it dies, and the event carries nothing that tells the
+ * two apart. So a supervisor that is still attached when a host tears its
+ * client down will read the teardown as a fault and reconnect the thing the
+ * host just closed.
+ *
+ * `stop()` is therefore part of the teardown sequence, not an optimisation:
+ * call it BEFORE `disconnect()`. The ordering is the contract because the
+ * event cannot be, and widening the event to carry a cause would change a
+ * published union for every consumer.
+ */
+/**
+ * Where the policy comes from, read fresh.
+ *
+ * A function rather than a value, and that is the difference between a
+ * configuration seam that is live and one that merely exists: an operator
+ * raising `maxAttempts` during an outage wants the retry that is happening
+ * NOW to take it, not the next process. `ConfigRegistry` supplies
+ * `() => scope.get()`; a caller with a fixed policy supplies a constant.
+ */
+export type MCPReconnectPolicySource = () => MCPReconnectOptions
+
+export class MCPReconnectSupervisor {
+	private readonly readPolicy: MCPReconnectPolicySource
+	private unsubscribe?: () => void
+	private stopped = false
+	private inFlight = false
+	private timer?: ReturnType<typeof setTimeout>
+
+	constructor(
+		private readonly client: MCPClient,
+		options: MCPReconnectOptions | MCPReconnectPolicySource = {},
+	) {
+		this.readPolicy = typeof options === 'function' ? options : () => options
+	}
+
+	/**
+	 * The policy as of right now.
+	 *
+	 * Called at each decision point rather than cached in a field. Caching it
+	 * in the constructor is what made this a declaration nothing drove: the
+	 * registry could be updated and the supervisor would go on using the
+	 * numbers it read at start-up.
+	 */
+	private policy(): Required<Omit<MCPReconnectOptions, 'onReconnected' | 'onGaveUp'>> &
+		Pick<MCPReconnectOptions, 'onReconnected' | 'onGaveUp'> {
+		return { ...DEFAULTS, ...this.readPolicy() }
+	}
+
+	/** Begin watching. Idempotent. */
+	start(): void {
+		if (!this.policy().enabled || this.unsubscribe || this.stopped) return
+		this.unsubscribe = this.client.onLifecycle((event) => {
+			if (event.type !== 'mcp_client_disconnected' && event.type !== 'mcp_client_error') return
+			void this.recover()
+		})
+	}
+
+	/**
+	 * Stop watching and cancel any pending attempt.
+	 *
+	 * Safe to call more than once, and safe to call from inside a reconnect —
+	 * the loop checks `stopped` between waits, so a teardown during a backoff
+	 * does not have to wait it out.
+	 */
+	stop(): void {
+		this.stopped = true
+		this.unsubscribe?.()
+		this.unsubscribe = undefined
+		if (this.timer) clearTimeout(this.timer)
+		this.timer = undefined
+	}
+
+	private async recover(): Promise<void> {
+		// One recovery at a time. A transport can emit `error` and then
+		// `close` for the same failure, and two overlapping loops would both
+		// call `connect()` — the second landing on the "already connected"
+		// throw of the first one's success.
+		if (this.inFlight || this.stopped) return
+		this.inFlight = true
+
+		try {
+			let delay = this.policy().initialDelayMs
+			// The bound is re-read on EVERY iteration, not captured once. An
+			// operator raising `maxAttempts` mid-outage is doing it because the
+			// attempts in flight are about to run out, and a loop that had
+			// already fixed its ceiling would give up anyway.
+			for (let attempt = 1; attempt <= this.policy().maxAttempts; attempt++) {
+				if (this.stopped) return
+				await this.wait(delay)
+				if (this.stopped) return
+				// Something else may have reconnected it while this waited —
+				// a host retrying by hand, or a previous loop that had not yet
+				// been observed. `connect()` throws when already connected, so
+				// this asks rather than finding out by exception.
+				if (this.client.isConnected()) return
+
+				try {
+					await this.client.connect()
+					await this.policy().onReconnected?.()
+					return
+				} catch {
+					// Deliberately swallowed: a failed attempt is the normal
+					// case here and the client has already logged and emitted
+					// its own error. Re-raising would surface a routine retry
+					// as an unhandled rejection from a timer.
+					delay = Math.min(delay * 2, this.policy().maxDelayMs)
+				}
+			}
+			this.policy().onGaveUp?.(this.policy().maxAttempts)
+		} finally {
+			this.inFlight = false
+		}
+	}
+
+	private wait(ms: number): Promise<void> {
+		return new Promise((resolve) => {
+			this.timer = setTimeout(resolve, ms)
+		})
+	}
+}
+
+/**
+ * The policy as a schema, so a `ConfigRegistry` can validate an operator's
+ * patch against it.
+ *
+ * The callbacks are absent from it on purpose: `onReconnected` and
+ * `onGaveUp` are functions a host wires up in code, and neither survives
+ * JSON or belongs in a file an operator edits. What is here is exactly the
+ * part that is a NUMBER somebody wants to change during an outage.
+ */
+export const MCPReconnectOptionsSchema = z.object({
+	enabled: z.boolean().default(true),
+	initialDelayMs: z.number().int().positive().default(DEFAULTS.initialDelayMs),
+	maxDelayMs: z.number().int().positive().default(DEFAULTS.maxDelayMs),
+	maxAttempts: z.number().int().positive().default(DEFAULTS.maxAttempts),
+})

package/src/connector/mcp/server/index.ts

@@ -0,0 +1,32 @@
+/**
+ * The direction reverses here.
+ *
+ * Everything else under `connector/mcp/` is **this process calling
+ * somebody else's server**: `client.ts` opens the connection, `stdio.ts`
+ * / `http-sse.ts` / `streamable-http.ts` carry it, `discovery.ts` asks
+ * what is on the other end, `adapter.ts` turns what came back into tools.
+ * A reader can assume that of any file in the directory and be right.
+ *
+ * This subdirectory is the opposite: **somebody else's client calling
+ * ours.** `MCPServer` receives requests and answers them, and
+ * `ServerStdioTransport` is the pipe it is spoken to over — the mirror of
+ * `stdio.ts`, not a variant of it.
+ *
+ * They were siblings, distinguished only by the word `server` in two
+ * filenames out of twelve, in a directory where every other name is also
+ * about a server — the one being called. `MCPServerToolProvider` is a
+ * thing a HOST implements to expose its tools to a caller, while
+ * `MCPServerId` two files over identifies a remote server this process
+ * connects to. Same prefix, opposite ends of the wire.
+ *
+ * A directory is the cheapest place to say that, and the only one a
+ * reader consults before opening a file.
+ */
+
+export { MCPMethodNotFound, MCPServer } from './server.js'
+export type {
+	MCPServerPromptProvider,
+	MCPServerResourceProvider,
+	MCPServerToolProvider,
+} from './server.js'
+export { ServerStdioTransport } from './server-stdio.js'