@namzu/sdk 48.3.1 → 50.0.0

package/src/bridge/acp/update.ts

@@ -34,13 +34,21 @@ const STOP_REASONS: Readonly<Record<string, AcpStopReason>> = {
 	stop_condition: 'end_turn',
 	max_iterations: 'max_turns',
 	max_tokens: 'max_turns',
+	token_budget: 'max_turns',
+	cost_limit: 'max_turns',
+	cost_unmeasurable: 'error',
+	timeout: 'error',
 	cancelled: 'cancelled',
 	canceled: 'cancelled',
 	aborted: 'cancelled',
 	paused: 'cancelled',
 	guardrail_blocked: 'refused',
+	input_guardrail: 'refused',
+	output_guardrail: 'refused',
+	step_refused: 'refused',
 	plan_rejected: 'refused',
 	answer_rejected: 'refused',
+	structured_output_failed: 'error',
 	error: 'error',
 	provider_error: 'error',
 }
@@ -50,6 +58,28 @@ export function toAcpStopReason(reason: StopReason | string | undefined): AcpSto
 	return STOP_REASONS[reason] ?? 'error'
 }
 
+function messageIdentity(event: { messageId?: string; turnId?: string; iteration?: number }) {
+	return {
+		...(event.messageId === undefined ? {} : { messageId: event.messageId }),
+		...(event.turnId === undefined ? {} : { turnId: event.turnId }),
+		...(event.iteration === undefined ? {} : { iteration: event.iteration }),
+	}
+}
+
+function thoughtIdentity(event: {
+	messageId?: string
+	turnId?: string
+	iteration?: number
+	blockIndex?: number
+}) {
+	return {
+		...messageIdentity(event),
+		...(event.messageId === undefined || event.blockIndex === undefined
+			? {}
+			: { blockId: `${event.messageId}:${event.blockIndex}` }),
+	}
+}
+
 /**
  * One session event as a session update, or `null`.
  *
@@ -62,10 +92,48 @@ export function toAcpSessionUpdate(
 ): AcpSessionUpdate | null {
 	switch (event.type) {
 		case 'text_delta':
-			return { kind: 'agent_message_chunk', text: event.text }
+			return {
+				kind: 'agent_message_chunk',
+				text: event.text,
+				...messageIdentity(event),
+				...(event.textPart
+					? {
+							textPart: {
+								id: event.textPart.id,
+								...(event.textPart.phase === undefined ? {} : { phase: event.textPart.phase }),
+							},
+							...(event.textPart.phase === undefined ? {} : { phase: event.textPart.phase }),
+						}
+					: {}),
+			}
+
+		case 'message_completed':
+			return {
+				kind: 'agent_message',
+				status: 'completed',
+				...messageIdentity(event),
+				stopReason: event.stopReason,
+				...(event.content === undefined ? {} : { content: event.content }),
+				...(event.textParts
+					? {
+							textParts: event.textParts.map((part) => ({
+								id: part.id,
+								text: part.text,
+								...(part.phase === undefined ? {} : { phase: part.phase }),
+							})),
+						}
+					: {}),
+			}
+
+		case 'reasoning_started':
+			return { kind: 'agent_thought', status: 'pending', ...thoughtIdentity(event) }
 
 		case 'reasoning_delta':
-			return { kind: 'agent_thought_chunk', text: event.text }
+			return { kind: 'agent_thought_chunk', text: event.text, ...thoughtIdentity(event) }
+
+		case 'reasoning_completed':
+			// Readable text arrived as deltas. Never copy signed or opaque replay material.
+			return { kind: 'agent_thought', status: 'completed', ...thoughtIdentity(event) }
 
 		case 'tool_executing':
 			return {
@@ -76,28 +144,114 @@ export function toAcpSessionUpdate(
 				view: presenter.presentCall(event.toolName, event.input),
 			}
 
+		case 'tool_progress':
+			return {
+				kind: 'tool_call',
+				toolCallId: event.toolUseId,
+				title: event.toolName,
+				status: 'pending',
+				view: { kind: 'generic', label: event.toolName },
+				progress: {
+					message: event.message,
+					...(event.fraction === undefined ? {} : { fraction: event.fraction }),
+				},
+			}
+
 		case 'tool_completed':
 			return {
 				kind: 'tool_call',
 				toolCallId: event.toolUseId,
 				title: event.toolName,
-				// `isError`, the field the event actually carries. The INPUT is
-				// not on this event — only the result is — so the presenter is
-				// asked with `undefined`, and a tool whose `presentResult` needs
-				// its input falls back to the generic view rather than being
-				// handed a guess at what it was called with.
+				// The runtime already presented the result with its real input and
+				// data. Older producers may only carry text; keep that fallback.
 				status: event.isError === true ? 'failed' : 'completed',
-				view: presenter.presentResult(event.toolName, undefined, {
-					success: event.isError !== true,
-					output: typeof event.result === 'string' ? event.result : String(event.result ?? ''),
-				}),
+				...(event.durationMs === undefined ? {} : { durationMs: event.durationMs }),
+				...(event.facts === undefined ? {} : { facts: event.facts }),
+				view:
+					event.presentation ??
+					presenter.presentResult(event.toolName, undefined, {
+						success: event.isError !== true,
+						output: typeof event.result === 'string' ? event.result : String(event.result ?? ''),
+					}),
+			}
+
+		case 'hosted_tool': {
+			// This is provider-executed activity, not a local tool request. Reuse
+			// the peer's existing display-only tool row without exposing a raw
+			// provider item or asking the host to execute or approve anything.
+			const page = Boolean(event.tool.url && !event.tool.query)
+			const title = page ? 'Web fetch' : 'Web search'
+			const target = (page ? event.tool.url : event.tool.query)?.replace(/\s+/g, ' ').trim()
+			const label =
+				event.tool.status === 'running'
+					? ''
+					: `${title}${target ? `: ${target.slice(0, 200)}` : ''}${
+							event.tool.status === 'failed'
+								? ' failed'
+								: !page &&
+										Number.isSafeInteger(event.tool.results) &&
+										(event.tool.results ?? -1) >= 0
+									? ` · ${event.tool.results} ${event.tool.results === 1 ? 'source' : 'sources'}`
+									: ''
+						}`
+			return {
+				kind: 'tool_call',
+				toolCallId: `provider-hosted-web-search:${event.iteration}:${event.tool.id}`,
+				title,
+				status:
+					event.tool.status === 'running'
+						? 'pending'
+						: event.tool.status === 'completed'
+							? 'completed'
+							: 'failed',
+				view: { kind: 'generic', label, presentation: 'activity' },
+			}
+		}
+
+		case 'provider_retry':
+			return {
+				kind: 'provider_retry',
+				attempt: event.attempt,
+				maxRetries: event.maxRetries,
+				delayMs: event.delayMs,
+				...(event.status === undefined ? {} : { status: event.status }),
+				serverDirected: event.serverDirected,
+				...(event.turnId === undefined ? {} : { turnId: event.turnId }),
 			}
 
 		case 'turn_completed':
-			return { kind: 'turn_ended', stopReason: toAcpStopReason(event.stopReason) }
+			return {
+				kind: 'turn_ended',
+				stopReason: toAcpStopReason(event.stopReason),
+				...(event.turnId === undefined ? {} : { turnId: event.turnId }),
+				...(event.settlement?.resultMessageId === undefined
+					? {}
+					: { messageId: event.settlement.resultMessageId }),
+				...(event.stopReason === undefined ? {} : { reason: event.stopReason }),
+				...(event.result === undefined ? {} : { result: event.result }),
+			}
+
+		case 'turn_paused':
+			return {
+				kind: 'turn_ended',
+				stopReason: 'cancelled',
+				reason: 'paused',
+				// A checkpointed provider fault is still a failure the operator
+				// needs to see. Ordinary review/handoff pauses remain non-errors.
+				...(event.failure || event.providerError
+					? { error: event.failure?.message || event.reason }
+					: {}),
+				...(event.turnId === undefined ? {} : { turnId: event.turnId }),
+			}
 
 		case 'turn_failed':
-			return { kind: 'turn_ended', stopReason: 'error' }
+			return {
+				kind: 'turn_ended',
+				stopReason: 'error',
+				reason: 'error',
+				error: event.error,
+				...(event.turnId === undefined ? {} : { turnId: event.turnId }),
+			}
 
 		default:
 			// Everything else: iteration boundaries, token accounting, plan and

package/src/config/registry.ts

@@ -48,6 +48,8 @@ export interface ConfigScope<T> {
 	update(patch: Partial<T> | Record<string, unknown>): T
 	/** Called after a successful update. Returns an unsubscribe. */
 	watch(listener: (next: T, previous: T) => void): () => void
+	/** Release this registration, including its watchers, while retaining saved overrides. */
+	dispose(): void
 }
 
 export class ConfigNamespaceCollisionError extends RegistryCollisionError {
@@ -149,14 +151,31 @@ export class ConfigRegistry {
 			watchers: new Set(),
 		}
 		this.entries.set(namespace, entry as Entry<unknown>)
+		const assertOwned = (): void => {
+			if (this.entries.get(namespace) !== (entry as Entry<unknown>)) {
+				throw new Error(`Configuration namespace "${namespace}" is no longer registered.`)
+			}
+		}
 
 		return {
-			get: () => entry.resolved,
-			update: (patch) => this.applyUpdate(namespace, entry, patch),
+			get: () => {
+				assertOwned()
+				return entry.resolved
+			},
+			update: (patch) => {
+				assertOwned()
+				return this.applyUpdate(namespace, entry, patch)
+			},
 			watch: (listener) => {
+				assertOwned()
 				entry.watchers.add(listener)
 				return () => entry.watchers.delete(listener)
 			},
+			dispose: () => {
+				if (this.entries.get(namespace) !== (entry as Entry<unknown>)) return
+				this.entries.delete(namespace)
+				entry.watchers.clear()
+			},
 		}
 	}
 
@@ -178,9 +197,11 @@ export class ConfigRegistry {
 		const next = entry.schema.parse({ ...entry.base, ...candidateOverride })
 
 		const previous = entry.resolved
+		const storeKey = this.storeKey(namespace)
+		this.store.save(storeKey, candidateOverride)
+		this.persisted[storeKey] = candidateOverride
 		entry.override = candidateOverride
 		entry.resolved = next
-		this.store.save(this.storeKey(namespace), candidateOverride)
 
 		for (const watcher of entry.watchers) {
 			try {

package/src/connector/mcp/adapter.ts

@@ -81,7 +81,7 @@ function objectToZod(rawSchema: Record<string, unknown>, depth: number): z.ZodTy
 
 	const properties = schema.properties as Record<string, unknown> | undefined
 	if (!properties || Object.keys(properties).length === 0) {
-		return closeOrOpen(z.object({}), schema)
+		return closeOrOpen(z.object({}), schema, depth)
 	}
 	if (depth >= MAX_CONVERSION_DEPTH) return z.record(z.unknown())
 
@@ -93,7 +93,7 @@ function objectToZod(rawSchema: Record<string, unknown>, depth: number): z.ZodTy
 		shape[key] = required.has(key) ? field : field.optional()
 	}
 
-	return closeOrOpen(z.object(shape), schema)
+	return closeOrOpen(z.object(shape), schema, depth)
 }
 
 /**
@@ -105,9 +105,21 @@ function objectToZod(rawSchema: Record<string, unknown>, depth: number): z.ZodTy
  * silently drops undeclared keys rather than rejecting them, so the
  * contract shown to the model tightens without turning a server's
  * incomplete schema into a hard validation failure.
+ * A schema-valued additionalProperties explicitly declares a dictionary:
+ * preserve those keys and validate each value through the same converter.
  */
-function closeOrOpen(obj: z.ZodObject<z.ZodRawShape>, schema: Record<string, unknown>): z.ZodType {
-	return schema.additionalProperties === true ? obj.passthrough() : obj
+function closeOrOpen(
+	obj: z.ZodObject<z.ZodRawShape>,
+	schema: Record<string, unknown>,
+	depth: number,
+): z.ZodType {
+	const additional = schema.additionalProperties
+	if (additional === true) return obj.passthrough()
+	if (additional !== null && typeof additional === 'object' && !Array.isArray(additional))
+		return obj.catchall(
+			depth >= MAX_CONVERSION_DEPTH ? z.unknown() : jsonSchemaPropertyToZod(additional, depth + 1),
+		)
+	return obj
 }
 
 function jsonSchemaPropertyToZod(prop: unknown, depth = 0): z.ZodType {

package/src/connector/mcp/client.ts

@@ -38,6 +38,7 @@ import {
 	type McpEraProbeAnswer,
 	type McpEraResolution,
 	classifyModernHttpFailure,
+	createMcpEraCache,
 	defaultMcpEraCache,
 	mcpEraCacheKey,
 	resolveMcpEra,
@@ -275,7 +276,8 @@ export class MCPClient {
 			),
 			this.requestTimeoutMs,
 		)
-		this.eraCache = config.eraCache ?? defaultMcpEraCache
+		this.eraCache =
+			config.eraCache ?? (config.transportFactory ? createMcpEraCache() : defaultMcpEraCache)
 		this.eraCacheKey = mcpEraCacheKey(config.transport)
 		this.id = config.id ?? generateMCPClientId()
 		// Built BEFORE the transport, not after: `createTransport` threads
@@ -285,7 +287,9 @@ export class MCPClient {
 			[SCOPE_ATTRIBUTE]: 'connector/mcp',
 			[NAMZU.SERVER_ID]: config.serverName,
 		})
-		this.transport = this.createTransport(config.transport)
+		this.transport = config.transportFactory
+			? config.transportFactory()
+			: this.createTransport(config.transport)
 	}
 
 	async connect(): Promise<MCPInitializeResult> {

package/src/connector/mcp/discovery.ts

@@ -55,10 +55,10 @@ export class MCPToolDiscovery {
 	private log: Logger
 	private options: MCPToolDiscoveryOptions
 	/**
-	 * Last admitted tool set per SERVER, for drift detection.
+	 * Last admitted tool set per owner identity, for drift detection.
 	 *
-	 * Keyed by server name rather than client id, and the difference is the
-	 * whole point. A client id is minted per connection, so on the path a
+	 * Plain discovery uses the server name; plugin discovery supplies its
+	 * qualified source id. A client id is minted per connection, so on the path a
 	 * real MCP server actually takes — a plugin enabling, connecting, and
 	 * being disabled again — every discovery was the first one that id had
 	 * ever seen, and drift could not fire however many times the server
@@ -119,9 +119,15 @@ export class MCPToolDiscovery {
 		return results
 	}
 
-	async discoverFrom(client: MCPClient): Promise<MCPDiscoveredTool[]> {
+	async discoverFrom(
+		client: MCPClient,
+		options?: { readonly isCurrent?: () => boolean },
+	): Promise<MCPDiscoveredTool[]> {
 		const state = client.getState()
 		const advertised = await client.listTools()
+		// A newer listing can finish before this one. Do not let the older
+		// generation replace the baseline or emit a drift event after that.
+		if (options?.isCurrent?.() === false) return []
 
 		// The boundary. Without it the REMOTE side decides what enters the
 		// agent's registry, which inverts least privilege: a server could
@@ -144,7 +150,7 @@ export class MCPToolDiscovery {
 			})
 		}
 
-		this.detectDrift(client.id, state.serverName, admitted)
+		this.detectDrift(state.serverName, client.id, state.serverName, admitted)
 
 		return admitted.map((tool) => ({
 			tool,
@@ -153,6 +159,16 @@ export class MCPToolDiscovery {
 		}))
 	}
 
+	/** Record the exact already-admitted snapshot another owner mounted. */
+	recordAdmittedTools(
+		identity: string,
+		clientId: string,
+		serverName: string,
+		admitted: readonly MCPToolDefinition[],
+	): void {
+		this.detectDrift(identity, clientId, serverName, [...admitted])
+	}
+
 	/**
 	 * The prompts a server publishes, through the same admission gate its
 	 * tools go through.
@@ -251,9 +267,14 @@ export class MCPToolDiscovery {
 		})
 	}
 
-	private detectDrift(clientId: string, serverName: string, admitted: MCPToolDefinition[]): void {
-		const previous = this.lastSeen.get(serverName)
-		this.lastSeen.set(serverName, admitted)
+	private detectDrift(
+		identity: string,
+		clientId: string,
+		serverName: string,
+		admitted: MCPToolDefinition[],
+	): void {
+		const previous = this.lastSeen.get(identity)
+		this.lastSeen.set(identity, admitted)
 		if (!previous) return
 
 		const drift = diffTools(previous, admitted)

package/src/connector/mcp/mcp-toolset.ts

@@ -5,7 +5,11 @@ import { NAMZU } from '../../constants/telemetry/index.js'
 import { ToolsetConflictError } from '../../toolsets/combine.js'
 import type { Toolset, ToolsetAvailability } from '../../toolsets/types.js'
 import { deferred } from '../../toolsets/wrappers.js'
-import type { MCPResource, MCPServerCapabilities } from '../../types/connector/index.js'
+import type {
+	MCPResource,
+	MCPServerCapabilities,
+	MCPToolDefinition,
+} from '../../types/connector/index.js'
 import type { ToolContext, ToolDefinition, ToolResult } from '../../types/tool/index.js'
 import type { ToolSource } from '../../types/toolset/index.js'
 import { toErrorMessage } from '../../utils/error.js'
@@ -103,6 +107,8 @@ export interface MCPToolsetOptions {
 	 * added and removed names apply at the next refresh boundary.
 	 */
 	readonly onDrift?: (event: { serverName: string; clientId: string; drift: MCPToolDrift }) => void
+	/** The exact admitted server listing processed at construction and each committed refresh. */
+	readonly onToolsAdmitted?: (tools: readonly MCPToolDefinition[]) => void
 	/** Current tool, prompt and resource names refused by this server's policy. */
 	readonly onRefused?: (event: {
 		serverName: string
@@ -320,14 +326,20 @@ export async function mcpToolset(
 	let promptDefs: ToolDefinition[] = []
 	let mainTools: ToolDefinition[] = []
 	let closed = false
+	let toolRefreshGeneration = 0
+	let admittedToolSnapshot: readonly MCPToolDefinition[] = []
 	const listeners = new Set<() => void>()
 
 	function rebuildMain(): void {
 		mainTools = [...toolDefs, ...promptDefs]
 	}
 
-	async function refreshTools(): Promise<void> {
-		const discovered = await discovery.discoverFrom(client)
+	async function refreshTools(): Promise<boolean> {
+		const generation = ++toolRefreshGeneration
+		const discovered = await discovery.discoverFrom(client, {
+			isCurrent: () => !closed && generation === toolRefreshGeneration,
+		})
+		if (closed || generation !== toolRefreshGeneration) return false
 		const previous = new Map(toolDefs.map((definition) => [definition.name, definition]))
 		toolDefs = discovered.map((d) => {
 			const name = mcpToolsetName(serverName, d.tool.name)
@@ -346,6 +358,8 @@ export async function mcpToolset(
 			if (!discovered.some((entry) => entry.tool.name === name)) heldToolNames.delete(name)
 		}
 		rebuildMain()
+		admittedToolSnapshot = discovered.map((entry) => entry.tool)
+		return true
 	}
 
 	async function refreshPrompts(): Promise<void> {
@@ -414,9 +428,12 @@ export async function mcpToolset(
 		}
 	}
 	assertUnique()
+	options.onToolsAdmitted?.(admittedToolSnapshot)
 
 	const notify = (): void => {
+		if (closed) return
 		assertUnique()
+		options.onToolsAdmitted?.(admittedToolSnapshot)
 		for (const listener of listeners) listener()
 	}
 	const onChange = (listener: () => void): (() => void) => {
@@ -449,7 +466,11 @@ export async function mcpToolset(
 		if (closed) return
 		if (method === 'notifications/tools/list_changed') {
 			if (!currentCapabilities()?.tools?.listChanged) return
-			void refreshTools().then(notify).catch(onRefreshFailure('tools'))
+			void refreshTools()
+				.then((updated) => {
+					if (updated) notify()
+				})
+				.catch(onRefreshFailure('tools'))
 		} else if (method === 'notifications/prompts/list_changed') {
 			if (!currentCapabilities()?.prompts?.listChanged) return
 			void refreshPrompts().then(notify).catch(onRefreshFailure('prompts'))

package/src/connector/mcp/reconnect.ts

@@ -83,6 +83,7 @@ export class MCPReconnectSupervisor {
 	private stopped = false
 	private inFlight = false
 	private timer?: ReturnType<typeof setTimeout>
+	private finishWait?: () => void
 
 	constructor(
 		private readonly client: MCPClient,
@@ -106,7 +107,7 @@ export class MCPReconnectSupervisor {
 
 	/** Begin watching. Idempotent. */
 	start(): void {
-		if (!this.policy().enabled || this.unsubscribe || this.stopped) return
+		if (this.stopped || this.unsubscribe || !this.policy().enabled) return
 		this.unsubscribe = this.client.onLifecycle((event) => {
 			if (event.type !== 'mcp_client_disconnected' && event.type !== 'mcp_client_error') return
 			void this.recover()
@@ -124,8 +125,9 @@ export class MCPReconnectSupervisor {
 		this.stopped = true
 		this.unsubscribe?.()
 		this.unsubscribe = undefined
-		if (this.timer) clearTimeout(this.timer)
-		this.timer = undefined
+		// Clearing the timer alone strands recover() inside an unresolved
+		// promise. Settle it so the stopped check can retire the loop.
+		this.finishWait?.()
 	}
 
 	private async recover(): Promise<void> {
@@ -154,9 +156,22 @@ export class MCPReconnectSupervisor {
 
 				try {
 					await this.client.connect()
+					// A host may stop the supervisor and dispose its live policy
+					// while connect() is still settling. Do not read that policy or
+					// publish a reconnect callback after teardown. A successful
+					// late connect also needs a second close: the host may have
+					// finished its own disconnect before this connect settled.
+					if (this.stopped) {
+						this.closeLateConnection()
+						return
+					}
 					await this.policy().onReconnected?.()
 					return
 				} catch {
+					if (this.stopped) {
+						this.closeLateConnection()
+						return
+					}
 					// 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
@@ -164,15 +179,30 @@ export class MCPReconnectSupervisor {
 					delay = Math.min(delay * 2, this.policy().maxDelayMs)
 				}
 			}
+			if (this.stopped) return
 			this.policy().onGaveUp?.(this.policy().maxAttempts)
 		} finally {
 			this.inFlight = false
 		}
 	}
 
+	private closeLateConnection(): void {
+		// A failed handshake can leave an opened transport, too. Stop is
+		// synchronous and the host's disable path has its own bounded close;
+		// keep this late cleanup best-effort without delaying recovery exit.
+		void this.client.disconnect().catch(() => {})
+	}
+
 	private wait(ms: number): Promise<void> {
 		return new Promise((resolve) => {
-			this.timer = setTimeout(resolve, ms)
+			const finish = () => {
+				if (this.timer) clearTimeout(this.timer)
+				this.timer = undefined
+				if (this.finishWait === finish) this.finishWait = undefined
+				resolve()
+			}
+			this.finishWait = finish
+			this.timer = setTimeout(finish, ms)
 		})
 	}
 }

package/src/constants/acp/index.ts

@@ -49,6 +49,7 @@ export type AcpMethod = (typeof ACP_METHODS)[keyof typeof ACP_METHODS]
  */
 export const ACP_CLIENT_NOTIFICATIONS = {
 	SESSION_UPDATE: 'session/update',
+	TASK_UPDATE: 'namzu/tasks/update',
 } as const
 
 /**
@@ -102,3 +103,6 @@ export const ACP_PERMISSION_CAPABILITY = 'permission'
  * nobody is looking at.
  */
 export const ACP_FILESYSTEM_CAPABILITY = 'fs'
+
+/** Optional Namzu planning notifications, negotiated separately from core ACP. */
+export const ACP_TASK_CAPABILITY = 'namzu/tasks'