@namzu/sdk 27.0.0 → 28.0.0

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'

package/src/connector/mcp/{server-stdio.ts → server/server-stdio.ts}

@@ -1,7 +1,8 @@
 import type { Readable, Writable } from 'node:stream'
+import { SCOPE_ATTRIBUTE } from '../../../utils/log/types.js'
 
-import type { MCPJsonRpcMessage, MCPTransport } from '../../types/connector/mcp.js'
-import { type Logger, getRootLogger } from '../../utils/logger.js'
+import type { MCPJsonRpcMessage, MCPTransport } from '../../../types/connector/mcp.js'
+import { type Logger, resolveLogger } from '../../../utils/logger.js'
 
 /**
  * The server half of stdio, so `MCPServer` has something to run on.
@@ -48,10 +49,10 @@ export class ServerStdioTransport implements MCPTransport {
 	 * that replaced `process.stdin` would break every other test sharing
 	 * the runner.
 	 */
-	constructor(streams?: { input?: Readable; output?: Writable }) {
+	constructor(streams?: { input?: Readable; output?: Writable }, log?: Logger) {
 		this.input = streams?.input ?? process.stdin
 		this.output = streams?.output ?? process.stdout
-		this.log = getRootLogger().child({ component: 'ServerStdioTransport' })
+		this.log = resolveLogger(log).child({ [SCOPE_ATTRIBUTE]: 'connector/mcp/server/stdio' })
 	}
 
 	async connect(): Promise<void> {

package/src/connector/mcp/{server.ts → server/server.ts}

@@ -1,4 +1,5 @@
-import { JSON_RPC_METHOD_NOT_FOUND } from '../../constants/mcp/index.js'
+import { JSON_RPC_METHOD_NOT_FOUND } from '../../../constants/mcp/index.js'
+import { NAMZU } from '../../../constants/telemetry/index.js'
 import type {
 	MCPContentBlock,
 	MCPJsonRpcMessage,
@@ -9,12 +10,13 @@ import type {
 	MCPToolDefinition,
 	MCPToolResult,
 	MCPTransport,
-} from '../../types/connector/index.js'
-import type { MCPPromptDefinition, MCPPromptMessage } from '../../types/connector/index.js'
-import type { MCPServerId } from '../../types/ids/index.js'
-import { toErrorMessage } from '../../utils/error.js'
-import { generateMCPServerId } from '../../utils/id.js'
-import { type Logger, getRootLogger } from '../../utils/logger.js'
+} from '../../../types/connector/index.js'
+import type { MCPPromptDefinition, MCPPromptMessage } from '../../../types/connector/index.js'
+import type { MCPServerId } from '../../../types/ids/index.js'
+import { toErrorMessage } from '../../../utils/error.js'
+import { generateMCPServerId } from '../../../utils/id.js'
+import { SCOPE_ATTRIBUTE } from '../../../utils/log/types.js'
+import { type Logger, resolveLogger } from '../../../utils/logger.js'
 
 /**
  * A method this server does not implement.
@@ -73,13 +75,17 @@ export class MCPServer {
 		toolProvider: MCPServerToolProvider,
 		resourceProvider?: MCPServerResourceProvider,
 		promptProvider?: MCPServerPromptProvider,
+		log?: Logger,
 	) {
 		this.id = config.id ?? generateMCPServerId()
 		this.config = config
 		this.toolProvider = toolProvider
 		this.resourceProvider = resourceProvider
 		this.promptProvider = promptProvider
-		this.log = getRootLogger().child({ component: 'MCPServer', serverId: this.id })
+		this.log = resolveLogger(log).child({
+			[SCOPE_ATTRIBUTE]: 'connector/mcp/server',
+			[NAMZU.MCP_SERVER_ID]: this.id,
+		})
 	}
 
 	async start(transport: MCPTransport): Promise<void> {
@@ -95,13 +101,13 @@ export class MCPServer {
 			this.log.info('MCP client disconnected')
 		})
 		transport.onError((err) => {
-			this.log.error('MCP server transport error', { error: err.message })
+			this.log.error('MCP server transport error', { 'exception.message': err.message })
 		})
 
 		await transport.connect()
 		this.running = true
 		this.startedAt = Date.now()
-		this.log.info(`MCPServer "${this.config.name}" started`)
+		this.log.info('MCPServer started', { 'namzu.mcp.server_name': this.config.name })
 	}
 
 	async stop(): Promise<void> {
@@ -111,7 +117,7 @@ export class MCPServer {
 			await this.transport.close()
 			this.transport = null
 		}
-		this.log.info(`MCPServer "${this.config.name}" stopped`)
+		this.log.info('MCPServer stopped', { 'namzu.mcp.server_name': this.config.name })
 	}
 
 	isRunning(): boolean {

package/src/connector/mcp/stdio.ts

@@ -4,7 +4,8 @@ import type {
 	MCPStdioTransportConfig,
 	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'
 
 /**
  * How long a child gets to honour SIGTERM before SIGKILL. Two seconds is
@@ -129,8 +130,11 @@ export class StdioTransport implements MCPTransport {
 	private buffer = ''
 	private log: Logger
 
-	constructor(private readonly config: MCPStdioTransportConfig) {
-		this.log = getRootLogger().child({ component: 'StdioTransport' })
+	constructor(
+		private readonly config: MCPStdioTransportConfig,
+		log?: Logger,
+	) {
+		this.log = resolveLogger(log).child({ [SCOPE_ATTRIBUTE]: 'connector/mcp/stdio' })
 	}
 
 	async connect(): Promise<void> {
@@ -148,12 +152,14 @@ export class StdioTransport implements MCPTransport {
 		})
 
 		this.process.stderr?.on('data', (chunk: Buffer) => {
-			this.log.warn(`MCP server stderr: ${chunk.toString('utf-8').trim()}`)
+			this.log.warn('MCP server stderr', {
+				'namzu.mcp.stderr': chunk.toString('utf-8').trim(),
+			})
 		})
 
 		this.process.on('close', (code) => {
 			this.connected = false
-			this.log.info(`MCP server process exited with code ${code}`)
+			this.log.info('MCP server process exited', { 'namzu.mcp.exit_code': code })
 			for (const handler of this.closeHandlers) handler()
 			// After the notification, not before it: this event is what tells
 			// `MCPClient` the session ended.
@@ -167,9 +173,10 @@ export class StdioTransport implements MCPTransport {
 		})
 
 		this.connected = true
-		this.log.info(
-			`StdioTransport connected: ${this.config.command} ${(this.config.args ?? []).join(' ')}`,
-		)
+		this.log.info('StdioTransport connected', {
+			'namzu.mcp.command': this.config.command,
+			'namzu.mcp.args': (this.config.args ?? []).join(' '),
+		})
 	}
 
 	async close(): Promise<void> {
@@ -272,7 +279,9 @@ export class StdioTransport implements MCPTransport {
 				const message = JSON.parse(trimmed) as MCPJsonRpcMessage
 				for (const handler of this.messageHandlers) handler(message)
 			} catch {
-				this.log.warn(`StdioTransport: invalid JSON-RPC message: ${trimmed.slice(0, 100)}`)
+				this.log.warn('StdioTransport: invalid JSON-RPC message', {
+					'namzu.mcp.message_head': trimmed.slice(0, 100),
+				})
 			}
 		}
 	}

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

@@ -3,7 +3,8 @@ import type {
 	MCPStreamableHttpTransportConfig,
 	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'
 
 const DEFAULT_TIMEOUT_MS = 30_000
 
@@ -15,14 +16,17 @@ export class StreamableHttpTransport implements MCPTransport {
 	private sessionId: string | null = null
 	private log: Logger
 
-	constructor(private readonly config: MCPStreamableHttpTransportConfig) {
-		this.log = getRootLogger().child({ component: 'StreamableHttpTransport' })
+	constructor(
+		private readonly config: MCPStreamableHttpTransportConfig,
+		log?: Logger,
+	) {
+		this.log = resolveLogger(log).child({ [SCOPE_ATTRIBUTE]: 'connector/mcp/streamable-http' })
 	}
 
 	async connect(): Promise<void> {
 		if (this.connected) return
 		this.connected = true
-		this.log.info(`StreamableHttpTransport connected to ${this.config.url}`)
+		this.log.info('StreamableHttpTransport connected', { 'namzu.mcp.url': this.config.url })
 	}
 
 	async close(): Promise<void> {

package/src/{bridge/tools/connector → connector/tools}/adapter.ts

@@ -1,9 +1,9 @@
 import { z } from 'zod'
-import type { ConnectorManager } from '../../../manager/connector/lifecycle.js'
-import type { ConnectorMethod } from '../../../types/connector/index.js'
-import type { ConnectorId, ConnectorInstanceId } from '../../../types/ids/index.js'
-import type { ToolContext, ToolDefinition, ToolResult } from '../../../types/tool/index.js'
-import { parseConnectorInstanceId } from '../../../utils/id.js'
+import type { ConnectorManager } from '../../manager/connector/lifecycle.js'
+import type { ConnectorMethod } from '../../types/connector/index.js'
+import type { ConnectorId, ConnectorInstanceId } from '../../types/ids/index.js'
+import type { ToolContext, ToolDefinition, ToolResult } from '../../types/tool/index.js'
+import { parseConnectorInstanceId } from '../../utils/id.js'
 
 export function connectorMethodToTool(
 	connectorId: ConnectorId,

package/src/{bridge/tools/connector → connector/tools}/definitions.ts

@@ -1,8 +1,8 @@
 import { z } from 'zod'
-import type { ConnectorManager } from '../../../manager/connector/lifecycle.js'
-import { defineTool } from '../../../tools/defineTool.js'
-import type { ToolDefinition } from '../../../types/tool/index.js'
-import { parseConnectorInstanceId } from '../../../utils/id.js'
+import type { ConnectorManager } from '../../manager/connector/lifecycle.js'
+import { defineTool } from '../../tools/defineTool.js'
+import type { ToolDefinition } from '../../types/tool/index.js'
+import { parseConnectorInstanceId } from '../../utils/id.js'
 
 export interface ConnectorToolConfig {
 	manager: ConnectorManager

package/src/{bridge/tools/connector → connector/tools}/router.ts

@@ -1,7 +1,8 @@
-import type { ConnectorManager } from '../../../manager/connector/lifecycle.js'
-import type { ToolDefinition, ToolRegistryContract } from '../../../types/tool/index.js'
-import { toErrorMessage } from '../../../utils/error.js'
-import { type Logger, getRootLogger } from '../../../utils/logger.js'
+import type { ConnectorManager } from '../../manager/connector/lifecycle.js'
+import type { ToolDefinition, ToolRegistryContract } from '../../types/tool/index.js'
+import { toErrorMessage } from '../../utils/error.js'
+import { SCOPE_ATTRIBUTE } from '../../utils/log/types.js'
+import { type Logger, resolveLogger } from '../../utils/logger.js'
 import { connectorInstanceToTools, createConnectorRouterTool } from './adapter.js'
 
 export type ConnectorToolStrategy = 'per-method' | 'router'
@@ -9,6 +10,7 @@ export type ConnectorToolStrategy = 'per-method' | 'router'
 export interface ConnectorToolRouterConfig {
 	manager: ConnectorManager
 	strategy?: ConnectorToolStrategy
+	log?: Logger
 }
 
 export class ConnectorToolRouter {
@@ -19,7 +21,7 @@ export class ConnectorToolRouter {
 	constructor(config: ConnectorToolRouterConfig) {
 		this.manager = config.manager
 		this.strategy = config.strategy ?? 'per-method'
-		this.log = getRootLogger().child({ component: 'ConnectorToolRouter' })
+		this.log = resolveLogger(config.log).child({ [SCOPE_ATTRIBUTE]: 'connector/tools/router' })
 	}
 
 	getTools(): ToolDefinition[] {
@@ -34,8 +36,9 @@ export class ConnectorToolRouter {
 			try {
 				tools.push(...connectorInstanceToTools(instance.id, this.manager))
 			} catch (err) {
-				this.log.error(`Failed to create tools for instance ${instance.id}`, {
-					error: toErrorMessage(err),
+				this.log.error('Failed to create tools for a connector instance', {
+					'namzu.connector.instance_id': instance.id,
+					'exception.message': toErrorMessage(err),
 				})
 			}
 		}
@@ -49,7 +52,10 @@ export class ConnectorToolRouter {
 			toolRegistry.register(tool)
 			names.push(tool.name)
 		}
-		this.log.info(`Registered ${names.length} connector tools`, { tools: names })
+		this.log.info('Registered connector tools', {
+			'namzu.connector.tool_count': names.length,
+			'namzu.tool.names': names,
+		})
 		return names
 	}
 
@@ -57,7 +63,9 @@ export class ConnectorToolRouter {
 		for (const name of toolNames) {
 			toolRegistry.unregister(name)
 		}
-		this.log.info(`Unregistered ${toolNames.length} connector tools`)
+		this.log.info('Unregistered connector tools', {
+			'namzu.connector.tool_count': toolNames.length,
+		})
 	}
 
 	refreshTools(toolRegistry: ToolRegistryContract, previousNames: string[]): string[] {