@namzu/sdk 46.0.0 → 48.1.0

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

@@ -7,7 +7,11 @@ import type {
 } 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'
+import {
+	ConnectorHttpOperation,
+	readConnectorResponseBody,
+	validateConnectorTimeoutMs,
+} from '../http-operation.js'
 import { MCPHttpStatusError } from './errors.js'
 import { refuseMcpHttpRedirect } from './http-redirect.js'
 
@@ -21,6 +25,23 @@ const DEFAULT_TIMEOUT_MS = 30_000
  * an unresponsive peer does not accumulate as a dangling request forever.
  */
 const SESSION_DELETE_TIMEOUT_MS = 5_000
+/** SSE streams may live for hours; bound each event and read rather than their lifetime. */
+const MAX_SSE_EVENT_CHARS = 1_048_576
+const MAX_SSE_CHUNK_BYTES = 8_388_608
+/** A single event may contain a JSON-RPC batch; bound its dispatch work too. */
+const MAX_RESPONSE_SSE_MESSAGES_PER_EVENT = 256
+const MAX_SUBSCRIPTION_ERROR_BODY_BYTES = 65_536
+
+/** A successful HTTP status can still carry a JSON-RPC listen refusal. */
+export class MCPSubscriptionResponseError extends Error {
+	readonly bodyText: string
+
+	constructor(bodyText: string) {
+		super('MCP subscriptions/listen returned JSON instead of an SSE response stream')
+		this.name = 'MCPSubscriptionResponseError'
+		this.bodyText = bodyText
+	}
+}
 
 export class StreamableHttpTransport implements MCPTransport {
 	private messageHandlers: Array<(message: MCPJsonRpcMessage) => void> = []
@@ -202,7 +223,7 @@ export class StreamableHttpTransport implements MCPTransport {
 			// POST capable of poisoning every later request on this connection.
 			if (message.method === 'initialize') this.captureSessionId(response)
 
-			await this.dispatchResponseMessages(response, operation, owned.generation)
+			await this.dispatchResponseMessages(response, operation, owned.generation, message.id)
 		} finally {
 			// A streamable HTTP send owns one POST; its rejection is delivered to
 			// that caller. It is not evidence that the logical MCP session died.
@@ -213,6 +234,124 @@ export class StreamableHttpTransport implements MCPTransport {
 		}
 	}
 
+	/**
+	 * Modern MCP subscriptions are long-lived POST response streams. The ordinary
+	 * `send` has a request deadline and stops at its terminal reply; a
+	 * subscription may remain open indefinitely. The client owns the initial
+	 * acknowledgment deadline and this stream's abort signal.
+	 */
+	async sendSubscription(
+		message: MCPJsonRpcMessage,
+		options: MCPTransportSendOptions,
+		onMessage?: (message: MCPJsonRpcMessage) => void,
+	): Promise<void> {
+		if (message.method !== 'subscriptions/listen' || message.id === undefined) {
+			throw new Error('sendSubscription requires a subscriptions/listen request')
+		}
+		if (!this.connected) throw new Error('StreamableHttpTransport: not connected')
+		const owned = this.beginSend(options.signal)
+		try {
+			const response = await this.fetchImpl(this.config.url, {
+				method: 'POST',
+				headers: this.buildHeaders(options.headers),
+				body: JSON.stringify(message),
+				redirect: 'manual',
+				signal: owned.controller.signal,
+			})
+			refuseMcpHttpRedirect(response, message.method)
+			if (!response.ok) {
+				throw new MCPHttpStatusError(
+					'StreamableHttpTransport',
+					response.status,
+					response.statusText,
+					await readSubscriptionErrorBody(response, owned.controller.signal, this.timeoutMs),
+				)
+			}
+			const mediaType = (response.headers.get('content-type') ?? '')
+				.split(';', 1)[0]
+				?.trim()
+				.toLowerCase()
+			if (mediaType !== 'text/event-stream' || !response.body) {
+				// A 200 JSON response can be a valid in-band JSON-RPC refusal.
+				// Read it under the same byte and time bounds as a failed HTTP
+				// response, then release its body before retry classification.
+				if (mediaType === 'application/json' && response.body) {
+					throw new MCPSubscriptionResponseError(
+						await readSubscriptionErrorBody(response, owned.controller.signal, this.timeoutMs),
+					)
+				}
+				// Unknown response media types still own a body. Never leave a
+				// held POST open while the client schedules its next attempt.
+				void response.body?.cancel().catch(() => undefined)
+				throw new Error('MCP subscriptions/listen did not return an SSE response stream')
+			}
+
+			const reader = response.body.getReader()
+			const decoder = new TextDecoder()
+			let buffer = ''
+			let previousChunkEndedWithCr = false
+			const cancelReader = (): void => {
+				void reader.cancel().catch(() => undefined)
+			}
+			owned.controller.signal.addEventListener('abort', cancelReader, { once: true })
+			if (owned.controller.signal.aborted) cancelReader()
+			try {
+				while (this.connected && owned.generation === this.generation) {
+					const { done, value } = await reader.read()
+					if (done) break
+					if (
+						!this.connected ||
+						owned.generation !== this.generation ||
+						owned.controller.signal.aborted
+					)
+						break
+					if (value.byteLength > MAX_SSE_CHUNK_BYTES) {
+						throw new Error('MCP subscription SSE chunk exceeds its size limit')
+					}
+					const oldLength = buffer.length
+					let chunk = decoder.decode(value, { stream: true })
+					// SSE permits LF, CRLF, and bare CR. A CRLF split across chunks
+					// still counts as one line break, not an empty line.
+					if (previousChunkEndedWithCr && chunk.startsWith('\n')) chunk = chunk.slice(1)
+					previousChunkEndedWithCr = chunk.endsWith('\r')
+					buffer += chunk.replace(/\r\n|\r/g, '\n')
+					let searchFrom = Math.max(0, oldLength - 1)
+					while (true) {
+						const boundary = findSseEventBoundary(buffer, searchFrom)
+						if (!boundary) break
+						if (boundary.start > MAX_SSE_EVENT_CHARS) {
+							throw new Error('MCP subscription SSE event exceeds its size limit')
+						}
+						const event = buffer.slice(0, boundary.start)
+						buffer = buffer.slice(boundary.end)
+						searchFrom = 0
+						for (const frame of parseSseMessages(event).messages) {
+							if (
+								!this.connected ||
+								owned.generation !== this.generation ||
+								owned.controller.signal.aborted
+							)
+								return
+							if (onMessage) onMessage(frame)
+							else for (const handler of [...this.messageHandlers]) handler(frame)
+						}
+					}
+					if (buffer.length > MAX_SSE_EVENT_CHARS) {
+						throw new Error('MCP subscription SSE event exceeds its size limit')
+					}
+				}
+				// A dangling partial event is not a notification. It cannot be
+				// forwarded as a complete JSON-RPC frame when the stream closes.
+			} finally {
+				owned.controller.signal.removeEventListener('abort', cancelReader)
+				cancelReader()
+				reader.releaseLock()
+			}
+		} finally {
+			owned.dispose()
+		}
+	}
+
 	onMessage(handler: (message: MCPJsonRpcMessage) => void): void {
 		this.messageHandlers.push(handler)
 	}
@@ -300,22 +439,119 @@ export class StreamableHttpTransport implements MCPTransport {
 		response: Response,
 		operation: ConnectorHttpOperation,
 		generation: number,
+		requestId: string | number | undefined,
 	): Promise<void> {
+		const contentType = response.headers.get('content-type') ?? ''
+		if (contentType.includes('text/event-stream') && response.body) {
+			await this.dispatchSseResponseMessages(response.body, operation, generation, requestId)
+			return
+		}
 		const text = await operation.run(() => response.text())
 		this.assertCurrent(generation, operation)
 		if (text.trim().length === 0) return
 
-		const contentType = response.headers.get('content-type') ?? ''
 		const messages = contentType.includes('text/event-stream')
 			? this.parseSseAndCaptureEventId(text)
 			: parseJsonMessages(text)
 
 		for (const message of messages) {
+			this.dispatchMessage(message, operation, generation)
+		}
+	}
+
+	private dispatchMessage(
+		message: MCPJsonRpcMessage,
+		operation: ConnectorHttpOperation,
+		generation: number,
+	): void {
+		this.assertCurrent(generation, operation)
+		for (const handler of [...this.messageHandlers]) {
 			this.assertCurrent(generation, operation)
-			for (const handler of [...this.messageHandlers]) {
+			handler(message)
+		}
+	}
+
+	/** Dispatch a complete SSE event as it arrives, without waiting for EOF. */
+	private async dispatchSseResponseMessages(
+		body: ReadableStream<Uint8Array>,
+		operation: ConnectorHttpOperation,
+		generation: number,
+		requestId: string | number | undefined,
+	): Promise<void> {
+		const reader = body.getReader()
+		const decoder = new TextDecoder()
+		let buffer = ''
+		let previousChunkEndedWithCr = false
+		const dispatchEvent = (event: string): boolean => {
+			if (event.length > MAX_SSE_EVENT_CHARS) {
+				throw new Error('MCP response SSE event exceeds its size limit')
+			}
+			if (sseBatchExceedsMessageLimit(event, MAX_RESPONSE_SSE_MESSAGES_PER_EVENT)) {
+				throw new Error('MCP response SSE event exceeds its message limit')
+			}
+			const parsed = parseSseMessages(event)
+			if (parsed.lastEventId !== undefined) this.lastEventId = parsed.lastEventId
+			if (parsed.messages.length > MAX_RESPONSE_SSE_MESSAGES_PER_EVENT) {
+				throw new Error('MCP response SSE event exceeds its message limit')
+			}
+			for (const message of parsed.messages) {
+				this.dispatchMessage(message, operation, generation)
+				if (
+					requestId !== undefined &&
+					message.id === requestId &&
+					message.method === undefined &&
+					(Object.hasOwn(message, 'result') || Object.hasOwn(message, 'error'))
+				) {
+					// The request is complete even if the peer keeps its SSE body open.
+					return true
+				}
+			}
+			return false
+		}
+		const appendChunk = (decoded: string): boolean => {
+			if (!decoded) return false
+			let chunk = decoded
+			// A CRLF split across reads is one line break; LF, CRLF and bare
+			// CR all delimit SSE lines.
+			if (previousChunkEndedWithCr && chunk.startsWith('\n')) chunk = chunk.slice(1)
+			previousChunkEndedWithCr = chunk.endsWith('\r')
+			buffer += chunk.replace(/\r\n|\r/g, '\n')
+			while (true) {
+				const boundary = findSseEventBoundary(buffer, 0)
+				if (!boundary) break
+				if (boundary.start > MAX_SSE_EVENT_CHARS) {
+					throw new Error('MCP response SSE event exceeds its size limit')
+				}
+				const event = buffer.slice(0, boundary.start)
+				buffer = buffer.slice(boundary.end)
+				if (dispatchEvent(event)) return true
+			}
+			if (buffer.length > MAX_SSE_EVENT_CHARS) {
+				throw new Error('MCP response SSE event exceeds its size limit')
+			}
+			return false
+		}
+		try {
+			while (true) {
+				const { done, value } = await operation.run(() => reader.read())
 				this.assertCurrent(generation, operation)
-				handler(message)
+				if (done) {
+					if (appendChunk(decoder.decode())) return
+					// Retain the old whole-body reader's acceptance of a final event
+					// without a trailing blank line when the peer actually closes.
+					if (buffer.trim()) dispatchEvent(buffer)
+					return
+				}
+				if (value.byteLength > MAX_SSE_CHUNK_BYTES) {
+					throw new Error('MCP response SSE chunk exceeds its size limit')
+				}
+				if (appendChunk(decoder.decode(value, { stream: true }))) return
 			}
+		} finally {
+			// Cancelling is best effort: a hostile or custom body must not hold
+			// send() open after a terminal reply, timeout, or caller abort.
+			void reader.cancel().catch(() => undefined)
+			reader.releaseLock()
 		}
 	}
 
@@ -334,6 +570,67 @@ export class StreamableHttpTransport implements MCPTransport {
 	}
 }
 
+/** Count only top-level JSON-array separators, skipping nested values and strings. */
+function sseBatchExceedsMessageLimit(event: string, limit: number): boolean {
+	const data = event
+		.split('\n')
+		.filter((line) => line.startsWith('data:'))
+		.map((line) => line.slice('data:'.length).trimStart())
+		.join('\n')
+		.trimStart()
+	if (!data.startsWith('[')) return false
+	let depth = 0
+	let inString = false
+	let escaped = false
+	let separators = 0
+	for (const character of data) {
+		if (inString) {
+			if (escaped) escaped = false
+			else if (character === '\\') escaped = true
+			else if (character === '"') inString = false
+			continue
+		}
+		if (character === '"') inString = true
+		else if (character === '[' || character === '{') depth++
+		else if (character === ']' || character === '}') depth--
+		else if (character === ',' && depth === 1 && ++separators >= limit) return true
+	}
+	return false
+}
+
+/** Find an SSE blank line after line endings have been normalized to LF. */
+function findSseEventBoundary(
+	value: string,
+	from: number,
+): { start: number; end: number } | undefined {
+	const start = value.indexOf('\n\n', from)
+	return start < 0 ? undefined : { start, end: start + 2 }
+}
+
+/** Keep a rejected listen response useful for diagnosis without buffering an unbounded body. */
+async function readSubscriptionErrorBody(
+	response: Response,
+	signal: AbortSignal,
+	timeoutMs: number,
+): Promise<string> {
+	const operation = new ConnectorHttpOperation(signal, timeoutMs, 'MCP subscription error body')
+	try {
+		const body = await readConnectorResponseBody(
+			response,
+			operation,
+			MAX_SUBSCRIPTION_ERROR_BODY_BYTES,
+		)
+		return typeof body === 'string' ? body : (JSON.stringify(body) ?? '')
+	} catch {
+		// The status is still the answer when a peer sends an unreadable,
+		// oversized, or stalled error body.
+		return ''
+	} finally {
+		operation.close()
+		void response.body?.cancel().catch(() => undefined)
+	}
+}
+
 /**
  * The body of a failed response, or an empty string.
  *

package/src/connector/tools/index.ts

@@ -13,5 +13,5 @@ export {
 } from './adapter.js'
 export type { ConnectorRouterInput } from './adapter.js'
 
-export { ConnectorToolRouter } from './router.js'
-export type { ConnectorToolStrategy, ConnectorToolRouterConfig } from './router.js'
+export { connectorTools } from './router.js'
+export type { ConnectorToolStrategy, ConnectorTools } from './router.js'

package/src/connector/tools/router.ts

@@ -1,5 +1,5 @@
 import type { ConnectorManager } from '../../manager/connector/lifecycle.js'
-import type { ToolDefinition, ToolRegistryContract } from '../../types/tool/index.js'
+import type { ToolDefinition } 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'
@@ -7,69 +7,46 @@ import { connectorInstanceToTools, createConnectorRouterTool } from './adapter.j
 
 export type ConnectorToolStrategy = 'per-method' | 'router'
 
-export interface ConnectorToolRouterConfig {
-	manager: ConnectorManager
+export interface ConnectorTools {
 	strategy?: ConnectorToolStrategy
 	log?: Logger
 }
 
-export class ConnectorToolRouter {
-	private manager: ConnectorManager
-	private strategy: ConnectorToolStrategy
-	private log: Logger
-
-	constructor(config: ConnectorToolRouterConfig) {
-		this.manager = config.manager
-		this.strategy = config.strategy ?? 'per-method'
-		this.log = resolveLogger(config.log).child({ [SCOPE_ATTRIBUTE]: 'connector/tools/router' })
-	}
-
-	getTools(): ToolDefinition[] {
-		if (this.strategy === 'router') {
-			const connected = this.manager.listConnectedInstances()
-			if (connected.length === 0) return []
-			return [createConnectorRouterTool(this.manager)]
-		}
-
-		const tools: ToolDefinition[] = []
-		for (const instance of this.manager.listConnectedInstances()) {
-			try {
-				tools.push(...connectorInstanceToTools(instance.id, this.manager))
-			} catch (err) {
-				this.log.error('Failed to create tools for a connector instance', {
-					'namzu.connector.instance_id': instance.id,
-					'exception.message': toErrorMessage(err),
-				})
-			}
-		}
-		return tools
+/**
+ * Every tool a connector manager's connected instances currently offer.
+ *
+ * Plain and stateless — a caller wraps the result in `toolset(source, tools)`
+ * (`toolsets/toolset.ts`) itself, re-calling this whenever a reconnect or a
+ * drift notice (`onMCPToolDrift`-shaped) means the set may have changed. This
+ * replaces `ConnectorToolRouter`, whose `registerTools`/`unregisterTools`/
+ * `refreshTools` mutated a `ToolRegistryContract` directly (plan.md v3 §2)
+ * and had no production caller; a live toolset with its own `onChange` is
+ * where that live-refresh story belongs now, not a router bound to a
+ * specific registry instance.
+ */
+export function connectorTools(
+	manager: ConnectorManager,
+	config: ConnectorTools = {},
+): ToolDefinition[] {
+	const strategy = config.strategy ?? 'per-method'
+	const log = resolveLogger(config.log).child({ [SCOPE_ATTRIBUTE]: 'connector/tools/router' })
+
+	if (strategy === 'router') {
+		const connected = manager.listConnectedInstances()
+		if (connected.length === 0) return []
+		return [createConnectorRouterTool(manager)]
 	}
 
-	registerTools(toolRegistry: ToolRegistryContract): string[] {
-		const tools = this.getTools()
-		const names: string[] = []
-		for (const tool of tools) {
-			toolRegistry.register(tool)
-			names.push(tool.name)
+	const tools: ToolDefinition[] = []
+	for (const instance of manager.listConnectedInstances()) {
+		try {
+			tools.push(...connectorInstanceToTools(instance.id, manager))
+		} catch (err) {
+			log.error('Failed to create tools for a connector instance', {
+				'namzu.connector.instance_id': instance.id,
+				'exception.message': toErrorMessage(err),
+			})
 		}
-		this.log.info('Registered connector tools', {
-			'namzu.connector.tool_count': names.length,
-			'namzu.tool.names': names,
-		})
-		return names
-	}
-
-	unregisterTools(toolRegistry: ToolRegistryContract, toolNames: string[]): void {
-		for (const name of toolNames) {
-			toolRegistry.unregister(name)
-		}
-		this.log.info('Unregistered connector tools', {
-			'namzu.connector.tool_count': toolNames.length,
-		})
-	}
-
-	refreshTools(toolRegistry: ToolRegistryContract, previousNames: string[]): string[] {
-		this.unregisterTools(toolRegistry, previousNames)
-		return this.registerTools(toolRegistry)
 	}
+	return tools
 }

package/src/directory/derive-supervisor.ts

@@ -1,6 +1,7 @@
 import { DEFAULT_TIMEOUT_MS, DEFAULT_TOKEN_BUDGET } from '../agents/runAgent.js'
 import type { AgentIdentity } from '../agents/runAgent.js'
-import { ToolRegistry } from '../registry/tool/execute.js'
+import { toolset } from '../toolsets/toolset.js'
+import type { Toolset } from '../toolsets/types.js'
 import type { SupervisorAgentConfig } from '../types/agent/supervisor.js'
 import type { LLMProvider } from '../types/provider/index.js'
 
@@ -44,14 +45,17 @@ export interface DelegatePlan {
 	readonly manifest: DirectoryManifest
 	/** The delegate's own instructions, tools and model, already assembled. */
 	readonly systemPrompt: string
-	readonly tools: ToolRegistry
+	readonly toolsets: readonly Toolset[]
 	readonly model: string
 }
 
-function toolsOf(manifest: DirectoryManifest): ToolRegistry {
-	const tools = new ToolRegistry()
-	for (const entry of manifest.tools) tools.register(entry.definition)
-	return tools
+function toolsOf(manifest: DirectoryManifest): readonly Toolset[] {
+	return [
+		toolset(
+			'directory',
+			manifest.tools.map((entry) => entry.definition),
+		),
+	]
 }
 
 function delegatePlan(entry: SubAgentEntry, fallbackModel: string): DelegatePlan {
@@ -59,7 +63,7 @@ function delegatePlan(entry: SubAgentEntry, fallbackModel: string): DelegatePlan
 		id: entry.id,
 		manifest: entry.manifest,
 		systemPrompt: entry.manifest.instructions,
-		tools: toolsOf(entry.manifest),
+		toolsets: toolsOf(entry.manifest),
 		// A delegate may name its own model — a cheap one for a narrow job is
 		// the common case — and inherits the supervisor's only when it does
 		// not. Inheriting unconditionally would silently bill every specialist
@@ -114,7 +118,7 @@ export function deriveSupervisorOptions(
 		agentManager: input.agentManager,
 		agentIds: delegates.map((d) => d.id),
 		systemPrompt: manifest.instructions,
-		tools: toolsOf(manifest),
+		toolsets: toolsOf(manifest),
 		// Skills were loaded and then dropped. The manifest reads a whole
 		// `skills/` directory and `SupervisorAgentConfig` takes them, and the
 		// cast that used to close this object meant nobody was told the field

package/src/directory/derive.ts

@@ -1,6 +1,5 @@
 import type { RunAgentOptions } from '../agents/runAgent.js'
-import { ToolRegistry } from '../registry/tool/execute.js'
-
+import { toolset } from '../toolsets/toolset.js'
 import type { DeriveTurnOptionsInput, DirectoryManifest } from './types.js'
 
 /**
@@ -32,14 +31,18 @@ export function deriveTurnOptions(
 		)
 	}
 
-	const tools = new ToolRegistry()
-	for (const entry of manifest.tools) tools.register(entry.definition)
+	const toolsets = [
+		toolset(
+			'directory',
+			manifest.tools.map((entry) => entry.definition),
+		),
+	]
 
 	return {
 		provider: input.provider,
 		prompt: input.prompt,
 		model,
-		tools,
+		toolsets,
 		// The one value the project knows and `runAgent` cannot infer. Left
 		// unset it would default to the host's own cwd, pointing the file
 		// tools' containment at the host's source tree rather than at the

package/src/execution/code-runtime/types.ts

@@ -18,7 +18,7 @@
  *    backend that cannot withhold those is not a backend for this.
  *  - **Everything it can do, it does by asking.** The only channel out is a
  *    call back into the host, which is what makes NZ-EXEC-06's dispatch
- *    through the turn's own `ToolRegistry` possible — the program cannot
+ *    through the turn's own `ToolManager` possible — the program cannot
  *    reach a tool the turn did not grant, because it cannot reach anything.
  *  - **Bounded.** Wall clock and output, both enforced by the backend
  *    rather than requested of the program.
@@ -57,7 +57,7 @@ export interface HostCallContext {
  * What the host will answer.
  *
  * A function rather than a table, so the host decides per call. NZ-EXEC-06
- * makes this the turn's `ToolRegistry` and its permission gate, which is
+ * makes this the turn's `ToolManager` and its permission gate, which is
  * exactly the point: the program's reach is the turn's reach, resolved at
  * the moment of the call rather than frozen when the program started.
  */

package/src/invariants/index.ts

@@ -9,6 +9,7 @@
 // worse home than the one it started in.
 
 import { ManagedRegistry } from '../registry/ManagedRegistry.js'
+import { RegistryCollisionError } from '../registry/collision.js'
 
 /**
  * What a module's check said about its own claim, the moment it was asked.
@@ -50,12 +51,14 @@ export type InvariantCheck<TContext = unknown> = (
  * every reference to the other's `id` kept resolving as if it still existed.
  * Mirrors `ProbeNameCollisionError`.
  */
-export class InvariantNameCollisionError extends Error {
+export class InvariantNameCollisionError extends RegistryCollisionError {
 	readonly moduleName: string
 	readonly invariantName: string
 
 	constructor(moduleName: string, invariantName: string) {
 		super(
+			'InvariantRegistry',
+			`${moduleName}:${invariantName}`,
 			`Invariant "${moduleName}:${invariantName}" is already registered. Two modules picked the same name, or this module registered itself twice — pick a different name, or find the second registration.`,
 		)
 		this.name = 'InvariantNameCollisionError'