@namzu/sdk 30.2.0 → 31.0.0

package/src/connector/mcp/client.ts

@@ -9,6 +9,7 @@ import type {
 	MCPLifecycleEvent,
 	MCPPromptDefinition,
 	MCPPromptMessage,
+	MCPRequestOptions,
 	MCPResource,
 	MCPResourceTemplate,
 	MCPServerCapabilities,
@@ -23,6 +24,7 @@ import { generateMCPClientId } from '../../utils/id.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 { validateConnectorTimeoutMs } from '../http-operation.js'
 import { HttpSseTransport } from './http-sse.js'
 import { StdioTransport } from './stdio.js'
 import { StreamableHttpTransport } from './streamable-http.js'
@@ -39,6 +41,9 @@ import { VERSION } from '../../version.js'
 /** Runaway guard for a server whose cursor never ends. */
 const MAX_LIST_PAGES = 100
 
+/** A cancellation notification must never become the next unbounded wait. */
+const CANCEL_NOTIFICATION_TIMEOUT_MS = 1_000
+
 const NAMZU_CLIENT_INFO = { name: 'namzu-sdk', version: VERSION }
 
 export class MCPClient {
@@ -53,18 +58,26 @@ export class MCPClient {
 		string | number,
 		{
 			resolve: (value: unknown) => void
-			reject: (reason: Error) => void
+			reject: (reason: unknown) => void
+			abort: (reason: unknown) => void
 		}
 	>()
 	private nextRequestId = 1
 	private notificationHandlers: Array<(method: string, params?: Record<string, unknown>) => void> =
 		[]
 	private lifecycleListeners: MCPEventListener[] = []
+	/** Best-effort protocol cancellations still belong to this connection generation. */
+	private cancellationControllers = new Set<AbortController>()
 	private log: Logger
 	private readonly config: MCPClientConfig
+	private readonly requestTimeoutMs: number
 
 	constructor(config: MCPClientConfig) {
 		this.config = config
+		this.requestTimeoutMs = validateConnectorTimeoutMs(
+			config.requestTimeoutMs ?? DEFAULT_MCP_REQUEST_TIMEOUT_MS,
+			'MCPClient requestTimeoutMs',
+		)
 		this.id = config.id ?? generateMCPClientId()
 		// Built BEFORE the transport, not after: `createTransport` threads
 		// `this.log` into whichever transport it constructs (LOG-10), so the
@@ -87,12 +100,14 @@ export class MCPClient {
 			this.transport.onMessage((msg) => this.handleMessage(msg))
 			this.transport.onClose(() => {
 				this.status = 'disconnected'
+				this.abortCancellations(new Error('MCP transport closed'))
 				this.log.info('MCP transport closed')
 				this.emitLifecycle({ type: 'mcp_client_disconnected', clientId: this.id })
 				this.rejectAllPending(`MCP transport to "${this.config.serverName}" closed`)
 			})
 			this.transport.onError((err) => {
 				this.status = 'error'
+				this.abortCancellations(err)
 				this.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 })
@@ -153,6 +168,8 @@ export class MCPClient {
 	}
 
 	async disconnect(): Promise<void> {
+		const reason = new Error('MCPClient disconnecting')
+		this.abortCancellations(reason)
 		if (this.status === 'disconnected') return
 
 		this.rejectAllPending('MCPClient disconnecting')
@@ -180,28 +197,36 @@ export class MCPClient {
 		}
 	}
 
-	async listTools(): Promise<MCPToolDefinition[]> {
+	async listTools(options?: MCPRequestOptions): Promise<MCPToolDefinition[]> {
 		this.requireConnected()
-		return await this.listAllPages('tools/list', 'tools')
+		return await this.listAllPages('tools/list', 'tools', options)
 	}
 
-	async callTool(name: string, args?: Record<string, unknown>): Promise<MCPToolResult> {
+	async callTool(
+		name: string,
+		args?: Record<string, unknown>,
+		options?: MCPRequestOptions,
+	): Promise<MCPToolResult> {
 		this.requireConnected()
-		const result = (await this.request('tools/call', {
-			name,
-			arguments: args ?? {},
-		})) as MCPToolResult
+		const result = (await this.request(
+			'tools/call',
+			{
+				name,
+				arguments: args ?? {},
+			},
+			options,
+		)) as MCPToolResult
 		return result
 	}
 
-	async listResources(): Promise<MCPResource[]> {
+	async listResources(options?: MCPRequestOptions): Promise<MCPResource[]> {
 		this.requireConnected()
-		return await this.listAllPages('resources/list', 'resources')
+		return await this.listAllPages('resources/list', 'resources', options)
 	}
 
-	async readResource(uri: string): Promise<MCPContentBlock[]> {
+	async readResource(uri: string, options?: MCPRequestOptions): Promise<MCPContentBlock[]> {
 		this.requireConnected()
-		const result = (await this.request('resources/read', { uri })) as {
+		const result = (await this.request('resources/read', { uri }, options)) as {
 			contents: MCPContentBlock[]
 		}
 		return result.contents
@@ -220,9 +245,9 @@ export class MCPClient {
 	 * of it being generic: a server that pages its prompts does not get
 	 * silently truncated to page one the way the tool list once was.
 	 */
-	async listPrompts(): Promise<MCPPromptDefinition[]> {
+	async listPrompts(options?: MCPRequestOptions): Promise<MCPPromptDefinition[]> {
 		this.requireConnected()
-		return await this.listAllPages('prompts/list', 'prompts')
+		return await this.listAllPages('prompts/list', 'prompts', options)
 	}
 
 	/**
@@ -237,21 +262,26 @@ export class MCPClient {
 	async getPrompt(
 		name: string,
 		args?: Record<string, string>,
+		options?: MCPRequestOptions,
 	): Promise<{ description?: string; messages: MCPPromptMessage[] }> {
 		this.requireConnected()
-		const result = (await this.request('prompts/get', {
-			name,
-			arguments: args ?? {},
-		})) as { description?: string; messages?: MCPPromptMessage[] }
+		const result = (await this.request(
+			'prompts/get',
+			{
+				name,
+				arguments: args ?? {},
+			},
+			options,
+		)) as { description?: string; messages?: MCPPromptMessage[] }
 		return {
 			...(result.description !== undefined ? { description: result.description } : {}),
 			messages: result.messages ?? [],
 		}
 	}
 
-	async listResourceTemplates(): Promise<MCPResourceTemplate[]> {
+	async listResourceTemplates(options?: MCPRequestOptions): Promise<MCPResourceTemplate[]> {
 		this.requireConnected()
-		return await this.listAllPages('resources/templates/list', 'resourceTemplates')
+		return await this.listAllPages('resources/templates/list', 'resourceTemplates', options)
 	}
 
 	/**
@@ -271,15 +301,20 @@ export class MCPClient {
 	 * until the process dies. Hitting it is loud, because a silently
 	 * truncated catalogue is the failure being fixed here.
 	 */
-	private async listAllPages<T>(method: string, field: string): Promise<T[]> {
+	private async listAllPages<T>(
+		method: string,
+		field: string,
+		options?: MCPRequestOptions,
+	): Promise<T[]> {
 		const items: T[] = []
 		let cursor: string | undefined
 
 		for (let page = 1; ; page++) {
-			const result = (await this.request(method, cursor === undefined ? {} : { cursor })) as Record<
-				string,
-				unknown
-			>
+			const result = (await this.request(
+				method,
+				cursor === undefined ? {} : { cursor },
+				options,
+			)) as Record<string, unknown>
 
 			const batch = result[field]
 			if (Array.isArray(batch)) items.push(...(batch as T[]))
@@ -364,7 +399,13 @@ export class MCPClient {
 	 * server hung the whole run with no error and no `run_failed`: not a
 	 * crash, just a process that stopped.
 	 */
-	private async request(method: string, params: Record<string, unknown>): Promise<unknown> {
+	private request(
+		method: string,
+		params: Record<string, unknown>,
+		options?: MCPRequestOptions,
+	): Promise<unknown> {
+		// Refuse before allocating an id or asking the transport to do work.
+		options?.signal?.throwIfAborted()
 		const id = this.nextRequestId++
 		const message: MCPJsonRpcMessage = {
 			jsonrpc: '2.0',
@@ -372,40 +413,150 @@ export class MCPClient {
 			method,
 			params,
 		}
-		const timeoutMs = this.config.requestTimeoutMs ?? DEFAULT_MCP_REQUEST_TIMEOUT_MS
-
-		return new Promise<unknown>((resolve, reject) => {
-			const timer = setTimeout(() => {
-				this.pendingRequests.delete(id)
-				this.log.warn('MCP request timed out', {
-					'namzu.connector.server': this.config.serverName,
-					'namzu.connector.method': method,
-					'namzu.connector.timeout_ms': timeoutMs,
-				})
-				reject(
-					new Error(
-						`MCP request "${method}" to "${this.config.serverName}" timed out after ${timeoutMs}ms`,
-					),
+		const transportController = new AbortController()
+		let issued = false
+		let settled = false
+		let resolvePublic!: (value: unknown) => void
+		let rejectPublic!: (reason: unknown) => void
+		const result = new Promise<unknown>((resolve, reject) => {
+			resolvePublic = resolve
+			rejectPublic = reject
+		})
+
+		type Terminal = 'response' | 'failure' | 'caller' | 'timeout' | 'transport_closed'
+		const entry = {
+			resolve: (value: unknown) => settle('response', value),
+			reject: (reason: unknown) => settle('failure', reason),
+			abort: (reason: unknown) => settle('transport_closed', reason),
+		}
+		const onCallerAbort = (): void => {
+			settle('caller', options?.signal?.reason)
+		}
+		const cleanup = (): void => {
+			clearTimeout(timer)
+			options?.signal?.removeEventListener('abort', onCallerAbort)
+			if (this.pendingRequests.get(id) === entry) this.pendingRequests.delete(id)
+		}
+		const settle = (terminal: Terminal, value: unknown): boolean => {
+			if (settled) return false
+			settled = true
+			// The terminal winner owns cleanup synchronously. In particular, a
+			// response delivered from inside transport.send removes the abort
+			// listener before that same send call can observe a later abort.
+			cleanup()
+
+			if (terminal === 'response') {
+				resolvePublic(value)
+				return true
+			}
+
+			rejectPublic(value)
+			if (terminal === 'caller' || terminal === 'timeout' || terminal === 'transport_closed') {
+				// Latch public settlement before aborting transport. An abort listener
+				// may synchronously reject send() with a generic AbortError; it no
+				// longer owns this request and cannot replace the first cause.
+				transportController.abort(value)
+			}
+			if (issued && method !== 'initialize' && (terminal === 'caller' || terminal === 'timeout')) {
+				this.sendCancellation(
+					id,
+					terminal === 'caller' ? 'Caller cancelled request' : 'Request deadline expired',
 				)
-			}, timeoutMs)
+			}
+			return true
+		}
+		const settleSendFailure = (reason: unknown): void => {
+			// An HTTP transport may have a deliberately shorter deadline than
+			// the JSON-RPC round-trip deadline. It is still a request timeout:
+			// the peer may be working after this local POST wait ended, so the
+			// correlated protocol cancellation remains required.
+			if (reason instanceof Error && reason.name === 'TimeoutError') {
+				settle('timeout', reason)
+				return
+			}
+			entry.reject(reason)
+		}
 
-			this.pendingRequests.set(id, {
-				resolve: (value) => {
-					clearTimeout(timer)
-					resolve(value)
-				},
-				reject: (err) => {
-					clearTimeout(timer)
-					reject(err)
-				},
+		this.pendingRequests.set(id, entry)
+		const timer = setTimeout(() => {
+			const error = new Error(
+				`MCP request "${method}" to "${this.config.serverName}" timed out after ${this.requestTimeoutMs}ms`,
+			)
+			error.name = 'TimeoutError'
+			this.log.warn('MCP request timed out', {
+				'namzu.connector.server': this.config.serverName,
+				'namzu.connector.method': method,
+				'namzu.connector.timeout_ms': this.requestTimeoutMs,
+			})
+			settle('timeout', error)
+		}, this.requestTimeoutMs)
+		options?.signal?.addEventListener('abort', onCallerAbort, { once: true })
+		// AbortSignal events are not replayed. This closes the listener-install
+		// race before the request is issued.
+		if (options?.signal?.aborted) {
+			onCallerAbort()
+			return result
+		}
+
+		try {
+			issued = true
+			const sending = this.transport.send(message, {
+				signal: transportController.signal,
 			})
+			void sending.catch((err) => {
+				settleSendFailure(err)
+			})
+		} catch (err) {
+			settleSendFailure(err)
+		}
 
-			this.transport.send(message).catch((err) => {
+		return result
+	}
+
+	/** Ask the peer to stop without letting cleanup become another hanging request. */
+	private sendCancellation(id: string | number, reason: string): void {
+		const controller = new AbortController()
+		this.cancellationControllers.add(controller)
+		const timer = setTimeout(() => {
+			const error = new Error('MCP cancellation notification timed out')
+			error.name = 'TimeoutError'
+			controller.abort(error)
+			this.cancellationControllers.delete(controller)
+		}, CANCEL_NOTIFICATION_TIMEOUT_MS)
+		timer.unref?.()
+		let sending: Promise<void>
+		try {
+			sending = this.transport.send(
+				{
+					jsonrpc: '2.0',
+					method: 'notifications/cancelled',
+					params: { requestId: id, reason },
+				},
+				{ signal: controller.signal },
+			)
+		} catch (err) {
+			clearTimeout(timer)
+			this.cancellationControllers.delete(controller)
+			this.log.debug('Failed to send MCP cancellation notification', {
+				'exception.message': toErrorMessage(err),
+			})
+			return
+		}
+		void sending
+			.catch((err) => {
+				this.log.debug('Failed to send MCP cancellation notification', {
+					'exception.message': toErrorMessage(err),
+				})
+			})
+			.finally(() => {
 				clearTimeout(timer)
-				this.pendingRequests.delete(id)
-				reject(err)
+				this.cancellationControllers.delete(controller)
 			})
-		})
+	}
+
+	private abortCancellations(reason: unknown): void {
+		for (const controller of this.cancellationControllers) controller.abort(reason)
+		this.cancellationControllers.clear()
 	}
 
 	/**
@@ -422,10 +573,9 @@ export class MCPClient {
 			'namzu.connector.count': this.pendingRequests.size,
 			'namzu.connector.reason': reason,
 		})
-		for (const [, pending] of this.pendingRequests) {
-			pending.reject(new Error(reason))
+		for (const pending of [...this.pendingRequests.values()]) {
+			pending.abort(new Error(reason))
 		}
-		this.pendingRequests.clear()
 	}
 
 	private async notify(method: string, params: Record<string, unknown>): Promise<void> {
@@ -441,7 +591,6 @@ export class MCPClient {
 		if (message.id !== undefined) {
 			const pending = this.pendingRequests.get(message.id)
 			if (pending) {
-				this.pendingRequests.delete(message.id)
 				if (message.error) {
 					pending.reject(new Error(`MCP error ${message.error.code}: ${message.error.message}`))
 				} else {

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

@@ -2,9 +2,13 @@ import type {
 	MCPHttpSseTransportConfig,
 	MCPJsonRpcMessage,
 	MCPTransport,
+	MCPTransportSendOptions,
 } from '../../types/connector/index.js'
 import { SCOPE_ATTRIBUTE } from '../../utils/log/types.js'
 import { type Logger, resolveLogger } from '../../utils/logger.js'
+import { ConnectorHttpOperation, validateConnectorTimeoutMs } from '../http-operation.js'
+
+const DEFAULT_TIMEOUT_MS = 30_000
 
 /**
  * Trim trailing slashes without a regex.
@@ -27,9 +31,12 @@ export class HttpSseTransport implements MCPTransport {
 	private errorHandlers: Array<(error: Error) => void> = []
 	private connected = false
 	private abortController: AbortController | null = null
+	private generation = 0
+	private activeSends = new Set<AbortController>()
 	private sseUrl: string
 	private postUrl: string
 	private log: Logger
+	private readonly timeoutMs: number
 
 	constructor(
 		private readonly config: MCPHttpSseTransportConfig,
@@ -38,6 +45,10 @@ export class HttpSseTransport implements MCPTransport {
 		const base = stripTrailingSlashes(config.url)
 		this.sseUrl = `${base}/sse`
 		this.postUrl = `${base}/message`
+		this.timeoutMs = validateConnectorTimeoutMs(
+			config.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+			'HttpSseTransport timeoutMs',
+		)
 		this.log = resolveLogger(log).child({ [SCOPE_ATTRIBUTE]: 'connector/mcp/http-sse' })
 	}
 
@@ -45,13 +56,18 @@ export class HttpSseTransport implements MCPTransport {
 		if (this.connected) return
 
 		this.abortController = new AbortController()
-		await this.startSSE()
+		const generation = ++this.generation
 		this.connected = true
+		await this.startSSE(generation, this.abortController.signal)
 		this.log.info('HttpSseTransport connected', { 'namzu.mcp.url': this.config.url })
 	}
 
 	async close(): Promise<void> {
 		this.connected = false
+		this.generation++
+		const reason = new Error('HttpSseTransport closed')
+		for (const controller of this.activeSends) controller.abort(reason)
+		this.activeSends.clear()
 		this.abortController?.abort()
 		this.abortController = null
 		for (const handler of this.closeHandlers) handler()
@@ -74,24 +90,30 @@ export class HttpSseTransport implements MCPTransport {
 		this.errorHandlers = []
 	}
 
-	async send(message: MCPJsonRpcMessage): Promise<void> {
+	async send(message: MCPJsonRpcMessage, options?: MCPTransportSendOptions): Promise<void> {
 		if (!this.connected) {
 			throw new Error('HttpSseTransport: not connected')
 		}
 
-		const controller = new AbortController()
-		const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs ?? 30_000)
+		const owned = this.beginSend(options?.signal)
+		const operation = new ConnectorHttpOperation(
+			owned.controller.signal,
+			this.timeoutMs,
+			'HTTP-SSE MCP send',
+		)
 
 		try {
-			const response = await fetch(this.postUrl, {
-				method: 'POST',
-				headers: {
-					'Content-Type': 'application/json',
-					...this.config.headers,
-				},
-				body: JSON.stringify(message),
-				signal: controller.signal,
-			})
+			const response = await operation.run(() =>
+				fetch(this.postUrl, {
+					method: 'POST',
+					headers: {
+						'Content-Type': 'application/json',
+						...this.config.headers,
+					},
+					body: JSON.stringify(message),
+					signal: operation.signal,
+				}),
+			)
 
 			if (!response.ok) {
 				throw new Error(`HTTP ${response.status}: ${response.statusText}`)
@@ -99,11 +121,16 @@ export class HttpSseTransport implements MCPTransport {
 
 			const contentType = response.headers.get('content-type') ?? ''
 			if (contentType.includes('application/json')) {
-				const body = (await response.json()) as MCPJsonRpcMessage
-				for (const handler of this.messageHandlers) handler(body)
+				const body = (await operation.run(() => response.json())) as MCPJsonRpcMessage
+				this.assertCurrent(owned.generation, operation)
+				for (const handler of [...this.messageHandlers]) {
+					this.assertCurrent(owned.generation, operation)
+					handler(body)
+				}
 			}
 		} finally {
-			clearTimeout(timeout)
+			operation.close()
+			owned.dispose()
 		}
 	}
 
@@ -123,9 +150,45 @@ export class HttpSseTransport implements MCPTransport {
 		return this.connected
 	}
 
-	private async startSSE(): Promise<void> {
-		this.listenSSE().catch((err) => {
-			if (this.connected) {
+	private beginSend(signal: AbortSignal | undefined): {
+		readonly controller: AbortController
+		readonly generation: number
+		dispose(): void
+	} {
+		signal?.throwIfAborted()
+		const controller = new AbortController()
+		const onAbort = (): void => controller.abort(signal?.reason)
+		signal?.addEventListener('abort', onAbort, { once: true })
+		if (signal?.aborted) onAbort()
+		if (controller.signal.aborted) {
+			signal?.removeEventListener('abort', onAbort)
+			controller.signal.throwIfAborted()
+		}
+		this.activeSends.add(controller)
+		return {
+			controller,
+			generation: this.generation,
+			dispose: () => {
+				signal?.removeEventListener('abort', onAbort)
+				this.activeSends.delete(controller)
+			},
+		}
+	}
+
+	private assertCurrent(generation: number, operation: ConnectorHttpOperation): void {
+		operation.throwIfStopped()
+		if (!this.connected || generation !== this.generation) {
+			throw new Error('HTTP-SSE MCP response belongs to a closed connection generation')
+		}
+	}
+
+	private isCurrent(generation: number): boolean {
+		return this.connected && generation === this.generation
+	}
+
+	private async startSSE(generation: number, signal: AbortSignal): Promise<void> {
+		this.listenSSE(generation, signal).catch((err) => {
+			if (this.connected && generation === this.generation) {
 				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)))
@@ -133,13 +196,13 @@ export class HttpSseTransport implements MCPTransport {
 		})
 	}
 
-	private async listenSSE(): Promise<void> {
+	private async listenSSE(generation: number, signal: AbortSignal): Promise<void> {
 		const response = await fetch(this.sseUrl, {
 			headers: {
 				Accept: 'text/event-stream',
 				...this.config.headers,
 			},
-			signal: this.abortController?.signal,
+			signal,
 		})
 
 		if (!response.ok || !response.body) {
@@ -150,21 +213,26 @@ export class HttpSseTransport implements MCPTransport {
 		const decoder = new TextDecoder()
 		let buffer = ''
 
-		while (this.connected) {
+		while (this.isCurrent(generation)) {
 			const { done, value } = await reader.read()
 			if (done) break
+			if (!this.isCurrent(generation)) break
 
 			buffer += decoder.decode(value, { stream: true })
 			const events = buffer.split('\n\n')
 			buffer = events.pop() ?? ''
 
 			for (const event of events) {
+				if (!this.isCurrent(generation)) return
 				const dataLine = event.split('\n').find((line) => line.startsWith('data: '))
 				if (!dataLine) continue
 				const data = dataLine.slice(6)
 				try {
 					const message = JSON.parse(data) as MCPJsonRpcMessage
-					for (const handler of this.messageHandlers) handler(message)
+					for (const handler of [...this.messageHandlers]) {
+						if (!this.isCurrent(generation)) return
+						handler(message)
+					}
 				} catch {
 					this.log.warn('HttpSseTransport: invalid SSE data', {
 						'namzu.mcp.data_head': data.slice(0, 100),

package/src/connector/mcp/prompt-adapter.ts

@@ -123,10 +123,12 @@ export function mcpPromptToToolDefinition(
 		isDestructive: () => false,
 		isConcurrencySafe: () => true,
 
-		async execute(input: unknown, _context: ToolContext): Promise<ToolResult> {
+		async execute(input: unknown, context: ToolContext): Promise<ToolResult> {
 			const args = (input ?? {}) as Record<string, string>
 			try {
-				const result = await client.getPrompt(prompt.name, args)
+				const result = await client.getPrompt(prompt.name, args, {
+					signal: context.abortSignal,
+				})
 				return {
 					success: true,
 					output: renderPromptMessages(
@@ -137,6 +139,10 @@ export function mcpPromptToToolDefinition(
 					),
 				}
 			} catch (err) {
+				// Cancellation belongs to the run, not to the remote prompt. Turning
+				// it into an ordinary failed tool result would let the executor treat
+				// a withdrawn operation as one the model may route around.
+				if (context.abortSignal?.aborted) throw context.abortSignal.reason
 				// Returned to the MODEL rather than thrown. A prompt that
 				// cannot be fetched — a server that went away, an argument it
 				// rejected — is something the agent can work around, and