@namzu/sdk 30.2.0 → 31.0.0

package/src/connector/mcp/stdio.ts

@@ -3,9 +3,17 @@ import type {
 	MCPJsonRpcMessage,
 	MCPStdioTransportConfig,
 	MCPTransport,
+	MCPTransportSendOptions,
 } from '../../types/connector/index.js'
 import { SCOPE_ATTRIBUTE } from '../../utils/log/types.js'
 import { type Logger, resolveLogger } from '../../utils/logger.js'
+import {
+	WINDOWS_CORE_ENV_KEYS,
+	applyEnvironmentOverrides,
+	pickEnvironmentEntries,
+	readEnvironmentEntry,
+	setEnvironmentEntry,
+} from '../../utils/process-environment.js'
 
 /**
  * How long a child gets to honour SIGTERM before SIGKILL. Two seconds is
@@ -50,45 +58,11 @@ const BASE_ENV_KEYS: readonly string[] = [
 	'TMPDIR',
 	'USER',
 	'LOGNAME',
-	// Windows. `SystemRoot` and `ComSpec` are load-bearing: without them a
-	// child cannot resolve system DLLs or the command interpreter.
-	'PATHEXT',
-	'SystemRoot',
-	'SystemDrive',
-	'ComSpec',
-	'WINDIR',
-	'TEMP',
-	'TMP',
-	'USERPROFILE',
-	'HOMEDRIVE',
-	'HOMEPATH',
-	'APPDATA',
-	'LOCALAPPDATA',
-	'PROGRAMDATA',
-	'PROGRAMFILES',
-	'NUMBER_OF_PROCESSORS',
-	'PROCESSOR_ARCHITECTURE',
+	// Windows. `SystemRoot`, `ComSpec` and `WINDIR` are load-bearing: without
+	// them a child cannot resolve system DLLs or the command interpreter.
+	...WINDOWS_CORE_ENV_KEYS,
 ]
 
-/**
- * Read one variable from the parent, honouring the platform's own casing rules.
- *
- * Node exposes `process.env` on Windows through a case-insensitive proxy, so a
- * direct lookup already works there — but the KEY this returns has to be the
- * one the parent actually uses, or a child comparing key names sees a spelling
- * the host never set.
- */
-function readParentVar(source: NodeJS.ProcessEnv, name: string): [string, string] | undefined {
-	const direct = source[name]
-	if (direct !== undefined) return [name, direct]
-	if (process.platform !== 'win32') return undefined
-	const lowered = name.toLowerCase()
-	for (const [key, value] of Object.entries(source)) {
-		if (key.toLowerCase() === lowered && value !== undefined) return [key, value]
-	}
-	return undefined
-}
-
 /**
  * What the child is handed: plumbing, then the named inheritances, then the
  * literal values.
@@ -103,19 +77,15 @@ export function buildChildEnv(
 	config: Pick<MCPStdioTransportConfig, 'env' | 'inheritEnv'>,
 	source: NodeJS.ProcessEnv = process.env,
 ): Record<string, string> {
-	const env: Record<string, string> = {}
-	for (const name of BASE_ENV_KEYS) {
-		const found = readParentVar(source, name)
-		if (found) env[found[0]] = found[1]
-	}
+	const env = pickEnvironmentEntries(BASE_ENV_KEYS, source)
 	for (const name of config.inheritEnv ?? []) {
-		const found = readParentVar(source, name)
+		const found = readEnvironmentEntry(source, name)
 		// A named variable the parent does not hold is simply absent. Refusing
 		// the spawn would turn an optional credential into a startup failure,
 		// and inventing an empty string would tell the server it has one.
-		if (found) env[found[0]] = found[1]
+		if (found) setEnvironmentEntry(env, found[0], found[1])
 	}
-	for (const [name, value] of Object.entries(config.env ?? {})) env[name] = value
+	applyEnvironmentOverrides(env, config.env)
 	return env
 }
 
@@ -244,10 +214,15 @@ export class StdioTransport implements MCPTransport {
 		this.errorHandlers = []
 	}
 
-	async send(message: MCPJsonRpcMessage): Promise<void> {
+	async send(message: MCPJsonRpcMessage, options?: MCPTransportSendOptions): Promise<void> {
+		options?.signal?.throwIfAborted()
 		if (!this.process?.stdin?.writable) {
 			throw new Error('StdioTransport: not connected or stdin not writable')
 		}
+		// No await lies between the checks and write, so a standard AbortSignal
+		// cannot change in this interval. Once written, MCP protocol
+		// `notifications/cancelled` is the cooperative cancellation mechanism.
+		options?.signal?.throwIfAborted()
 		const data = `${JSON.stringify(message)}\n`
 		this.process.stdin.write(data)
 	}

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

@@ -2,9 +2,11 @@ import type {
 	MCPJsonRpcMessage,
 	MCPStreamableHttpTransportConfig,
 	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
 
@@ -14,17 +16,25 @@ export class StreamableHttpTransport implements MCPTransport {
 	private errorHandlers: Array<(error: Error) => void> = []
 	private connected = false
 	private sessionId: string | null = null
+	private generation = 0
+	private activeSends = new Set<AbortController>()
 	private log: Logger
+	private readonly timeoutMs: number
 
 	constructor(
 		private readonly config: MCPStreamableHttpTransportConfig,
 		log?: Logger,
 	) {
+		this.timeoutMs = validateConnectorTimeoutMs(
+			config.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+			'StreamableHttpTransport timeoutMs',
+		)
 		this.log = resolveLogger(log).child({ [SCOPE_ATTRIBUTE]: 'connector/mcp/streamable-http' })
 	}
 
 	async connect(): Promise<void> {
 		if (this.connected) return
+		this.generation++
 		this.connected = true
 		this.log.info('StreamableHttpTransport connected', { 'namzu.mcp.url': this.config.url })
 	}
@@ -34,9 +44,15 @@ export class StreamableHttpTransport implements MCPTransport {
 			// Never connected, or already closed: nothing will notify, so this is
 			// the only chance to drop what `connect()` registered before it failed.
 			this.clearHandlers()
+			this.sessionId = null
 			return
 		}
 		this.connected = false
+		this.generation++
+		this.sessionId = null
+		const reason = new Error('StreamableHttpTransport closed')
+		for (const controller of this.activeSends) controller.abort(reason)
+		this.activeSends.clear()
 		for (const handler of this.closeHandlers) handler()
 		// After the notification, never before it.
 		this.clearHandlers()
@@ -49,38 +65,45 @@ export class StreamableHttpTransport implements MCPTransport {
 		this.errorHandlers = []
 	}
 
-	async send(message: MCPJsonRpcMessage): Promise<void> {
+	async send(message: MCPJsonRpcMessage, options?: MCPTransportSendOptions): Promise<void> {
 		if (!this.connected) {
 			throw new Error('StreamableHttpTransport: not connected')
 		}
 
-		const controller = new AbortController()
-		const timeout = setTimeout(
-			() => controller.abort(),
-			this.config.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+		const owned = this.beginSend(options?.signal)
+		const operation = new ConnectorHttpOperation(
+			owned.controller.signal,
+			this.timeoutMs,
+			'Streamable HTTP MCP send',
 		)
 
 		try {
-			const response = await fetch(this.config.url, {
-				method: 'POST',
-				headers: this.buildHeaders(),
-				body: JSON.stringify(message),
-				signal: controller.signal,
-			})
-
-			this.captureSessionId(response)
+			const response = await operation.run(() =>
+				fetch(this.config.url, {
+					method: 'POST',
+					headers: this.buildHeaders(),
+					body: JSON.stringify(message),
+					signal: operation.signal,
+				}),
+			)
 
 			if (!response.ok) {
 				throw new Error(`StreamableHttpTransport: HTTP ${response.status}: ${response.statusText}`)
 			}
+			this.assertCurrent(owned.generation, operation)
+			// MCP assigns the session during initialize. Letting an ordinary or
+			// failed per-request response rotate it makes one bad cancellation
+			// POST capable of poisoning every later request on this connection.
+			if (message.method === 'initialize') this.captureSessionId(response)
 
-			await this.dispatchResponseMessages(response)
-		} catch (err) {
-			const error = err instanceof Error ? err : new Error(String(err))
-			for (const handler of this.errorHandlers) handler(error)
-			throw error
+			await this.dispatchResponseMessages(response, operation, owned.generation)
 		} finally {
-			clearTimeout(timeout)
+			// A streamable HTTP send owns one POST; its rejection is delivered to
+			// that caller. It is not evidence that the logical MCP session died.
+			// Raising onError here would let A's failed best-effort cancellation
+			// reject every unrelated pending request B..N on the shared client.
+			operation.close()
+			owned.dispose()
 		}
 	}
 
@@ -122,8 +145,45 @@ export class StreamableHttpTransport implements MCPTransport {
 		}
 	}
 
-	private async dispatchResponseMessages(response: Response): Promise<void> {
-		const text = await response.text()
+	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('Streamable HTTP MCP response belongs to a closed connection generation')
+		}
+	}
+
+	private async dispatchResponseMessages(
+		response: Response,
+		operation: ConnectorHttpOperation,
+		generation: number,
+	): Promise<void> {
+		const text = await operation.run(() => response.text())
+		this.assertCurrent(generation, operation)
 		if (text.trim().length === 0) return
 
 		const contentType = response.headers.get('content-type') ?? ''
@@ -132,7 +192,11 @@ export class StreamableHttpTransport implements MCPTransport {
 			: parseJsonMessages(text)
 
 		for (const message of messages) {
-			for (const handler of this.messageHandlers) handler(message)
+			this.assertCurrent(generation, operation)
+			for (const handler of [...this.messageHandlers]) {
+				this.assertCurrent(generation, operation)
+				handler(message)
+			}
 		}
 	}
 }

package/src/connector/tools/adapter.ts

@@ -1,9 +1,11 @@
 import { z } from 'zod'
 import type { ConnectorManager } from '../../manager/connector/lifecycle.js'
+import { renderToolSchema } from '../../registry/tool/schema.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 { connectorToolError } from './result.js'
 
 export function connectorMethodToTool(
 	connectorId: ConnectorId,
@@ -16,25 +18,30 @@ export function connectorMethodToTool(
 	return {
 		name: toolName,
 		description: `[${connectorId}] ${method.description}`,
-		inputSchema: method.inputSchema,
+		// ConnectorManager owns method parsing. A second Zod parse here would
+		// re-run transforms before the manager sees the value.
+		inputSchema: z.unknown(),
+		modelInputSchema: renderToolSchema(method.inputSchema),
+		...(method.outputSchema ? { outputSchema: renderToolSchema(method.outputSchema) } : {}),
 		category: 'network',
 		permissions: ['network_access'],
 		isReadOnly: () => false,
 		isDestructive: () => false,
 		isConcurrencySafe: () => true,
 
-		async execute(input: unknown, _context: ToolContext): Promise<ToolResult> {
+		async execute(input: unknown, context: ToolContext): Promise<ToolResult> {
 			const result = await manager.execute({
 				instanceId,
 				method: method.name,
 				input,
+				signal: context.abortSignal,
 			})
 
 			return {
 				success: result.success,
 				output: result.success ? JSON.stringify(result.output, null, 2) : '',
 				data: result.output,
-				error: result.error,
+				error: result.success ? undefined : connectorToolError(result),
 			}
 		},
 	}
@@ -49,9 +56,10 @@ export function connectorInstanceToTools(
 		throw new Error(`Connector instance not found: "${instanceId}"`)
 	}
 
-	const definition = manager.getRegistry().getOrThrow(instance.connectorId)
+	const connectorId = manager.getInstanceConnectorId(instanceId)
+	const definition = manager.getInstanceDefinition(instanceId)
 	return definition.methods.map((method) =>
-		connectorMethodToTool(instance.connectorId, instanceId, method, manager),
+		connectorMethodToTool(connectorId, instanceId, method, manager),
 	)
 }
 
@@ -87,7 +95,7 @@ export function createConnectorRouterTool(
 		isDestructive: () => false,
 		isConcurrencySafe: () => true,
 
-		async execute(input: ConnectorRouterInput, _context: ToolContext): Promise<ToolResult> {
+		async execute(input: ConnectorRouterInput, context: ToolContext): Promise<ToolResult> {
 			const instanceId = parseConnectorInstanceId(String(input.instanceId))
 			const instance = manager.getInstance(instanceId)
 			if (!instance) {
@@ -98,11 +106,12 @@ export function createConnectorRouterTool(
 				}
 			}
 
-			if (instance.connectorId !== input.connectorId) {
+			const connectorId = manager.getInstanceConnectorId(instanceId)
+			if (connectorId !== input.connectorId) {
 				return {
 					success: false,
 					output: '',
-					error: `Instance "${input.instanceId}" belongs to connector "${instance.connectorId}", not "${input.connectorId}"`,
+					error: `Instance "${input.instanceId}" belongs to connector "${connectorId}", not "${input.connectorId}"`,
 				}
 			}
 
@@ -110,13 +119,14 @@ export function createConnectorRouterTool(
 				instanceId,
 				method: input.method,
 				input: input.input,
+				signal: context.abortSignal,
 			})
 
 			return {
 				success: result.success,
 				output: result.success ? JSON.stringify(result.output, null, 2) : '',
 				data: result.output,
-				error: result.error,
+				error: result.success ? undefined : connectorToolError(result),
 			}
 		},
 	}
@@ -130,11 +140,10 @@ function buildRouterDescription(manager: ConnectorManager): string {
 
 	const parts = ['Execute a method on a connected connector instance. Available:']
 	for (const inst of instances) {
-		const def = manager.getRegistry().get(inst.connectorId)
-		if (def) {
-			const methods = def.methods.map((m) => m.name).join(', ')
-			parts.push(`- ${inst.connectorId} (${inst.id}): ${methods}`)
-		}
+		const connectorId = manager.getInstanceConnectorId(inst.id)
+		const definition = manager.getInstanceDefinition(inst.id)
+		const methods = definition.methods.map((method) => method.name).join(', ')
+		parts.push(`- ${connectorId} (${inst.id}): ${methods}`)
 	}
 	return parts.join('\n')
 }

package/src/connector/tools/definitions.ts

@@ -3,6 +3,7 @@ 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 { connectorToolError } from './result.js'
 
 export interface ConnectorToolConfig {
 	manager: ConnectorManager
@@ -28,7 +29,7 @@ export function createConnectorExecuteTool(config: ConnectorToolConfig): ToolDef
 		destructive: false,
 		concurrencySafe: true,
 
-		async execute(input) {
+		async execute(input, context) {
 			const instanceId = parseConnectorInstanceId(String(input.instance_id))
 			const instance = config.manager.getInstance(instanceId)
 
@@ -52,13 +53,15 @@ export function createConnectorExecuteTool(config: ConnectorToolConfig): ToolDef
 				instanceId,
 				method: input.method,
 				input: input.input,
+				signal: context.abortSignal,
 			})
 
 			if (!result.success) {
 				return {
 					success: false,
 					output: '',
-					error: result.error ?? 'Connector execution failed',
+					error: connectorToolError(result),
+					data: { output: result.output, metadata: result.metadata },
 				}
 			}
 

package/src/connector/tools/result.ts

@@ -0,0 +1,21 @@
+import type { ConnectorExecuteResult } from '../../types/connector/index.js'
+
+/** Keep remote side-effect uncertainty in the text the model actually sees. */
+export function connectorToolError(result: ConnectorExecuteResult): string {
+	const base = result.error ?? 'Connector execution failed'
+	const normalized = base.toLowerCase()
+	const outcome = result.metadata?.remoteOutcome
+	const retrySafety = result.metadata?.retrySafety
+	if (outcome === 'not_started' && !normalized.includes('no remote request was started')) {
+		return `${base} No remote request was started; retry is safe.`
+	}
+	if (outcome === 'unknown' && !normalized.includes('remote outcome is unknown')) {
+		return retrySafety === 'safe'
+			? `${base} The remote outcome is unknown, but retry is safe for this operation.`
+			: `${base} The remote outcome is unknown; do not automatically retry.`
+	}
+	if (outcome === 'response_received' && !normalized.includes('response')) {
+		return `${base} A remote response was received; use its status before deciding whether to retry.`
+	}
+	return base
+}