@namzu/sdk 2.0.0 → 3.1.0

package/src/connector/mcp/client.ts

@@ -21,9 +21,17 @@ import { HttpSseTransport } from './http-sse.js'
 import { StdioTransport } from './stdio.js'
 import { StreamableHttpTransport } from './streamable-http.js'
 
-import { MCP_PROTOCOL_VERSION } from '../../constants/mcp/index.js'
+import {
+	DEFAULT_MCP_REQUEST_TIMEOUT_MS,
+	JSON_RPC_METHOD_NOT_FOUND,
+	MCP_PROTOCOL_VERSION,
+	MCP_SUPPORTED_PROTOCOL_VERSIONS,
+} from '../../constants/mcp/index.js'
 import { VERSION } from '../../version.js'
 
+/** Runaway guard for a server whose cursor never ends. */
+const MAX_LIST_PAGES = 100
+
 const NAMZU_CLIENT_INFO = { name: 'namzu-sdk', version: VERSION }
 
 export class MCPClient {
@@ -66,11 +74,13 @@ export class MCPClient {
 			this.transport.onClose(() => {
 				this.status = 'disconnected'
 				this.log.info('MCP transport closed')
+				this.rejectAllPending(`MCP transport to "${this.config.serverName}" closed`)
 			})
 			this.transport.onError((err) => {
 				this.status = 'error'
 				this.error = err.message
 				this.log.error('MCP transport error', { error: err.message })
+				this.rejectAllPending(`MCP transport to "${this.config.serverName}" failed: ${err.message}`)
 			})
 
 			await this.transport.connect()
@@ -81,6 +91,24 @@ export class MCPClient {
 				clientInfo: this.config.clientInfo ?? NAMZU_CLIENT_INFO,
 			})) as MCPInitializeResult
 
+			// The server answers with the version IT will speak, which need
+			// not be the one we asked for. Ignoring that answer — as this did
+			// — makes an unspeakable version look like a healthy connection
+			// until something downstream breaks in a confusing way.
+			const negotiated = result.protocolVersion
+			if (negotiated && !MCP_SUPPORTED_PROTOCOL_VERSIONS.includes(negotiated)) {
+				throw new Error(
+					`MCP server "${this.config.serverName}" negotiated protocol version "${negotiated}", ` +
+						`which this client cannot speak (supported: ${MCP_SUPPORTED_PROTOCOL_VERSIONS.join(', ')}).`,
+				)
+			}
+			if (negotiated && negotiated !== MCP_PROTOCOL_VERSION) {
+				this.log.info('MCP server negotiated a different protocol version', {
+					requested: MCP_PROTOCOL_VERSION,
+					negotiated,
+				})
+			}
+
 			this.serverInfo = result.serverInfo
 			this.serverCapabilities = result.capabilities
 
@@ -102,10 +130,7 @@ export class MCPClient {
 	async disconnect(): Promise<void> {
 		if (this.status === 'disconnected') return
 
-		for (const [, pending] of this.pendingRequests) {
-			pending.reject(new Error('MCPClient disconnecting'))
-		}
-		this.pendingRequests.clear()
+		this.rejectAllPending('MCPClient disconnecting')
 
 		await this.transport.close()
 		this.status = 'disconnected'
@@ -131,8 +156,7 @@ export class MCPClient {
 
 	async listTools(): Promise<MCPToolDefinition[]> {
 		this.requireConnected()
-		const result = (await this.request('tools/list', {})) as { tools: MCPToolDefinition[] }
-		return result.tools
+		return await this.listAllPages('tools/list', 'tools')
 	}
 
 	async callTool(name: string, args?: Record<string, unknown>): Promise<MCPToolResult> {
@@ -146,8 +170,7 @@ export class MCPClient {
 
 	async listResources(): Promise<MCPResource[]> {
 		this.requireConnected()
-		const result = (await this.request('resources/list', {})) as { resources: MCPResource[] }
-		return result.resources
+		return await this.listAllPages('resources/list', 'resources')
 	}
 
 	async readResource(uri: string): Promise<MCPContentBlock[]> {
@@ -160,10 +183,48 @@ export class MCPClient {
 
 	async listResourceTemplates(): Promise<MCPResourceTemplate[]> {
 		this.requireConnected()
-		const result = (await this.request('resources/templates/list', {})) as {
-			resourceTemplates: MCPResourceTemplate[]
+		return await this.listAllPages('resources/templates/list', 'resourceTemplates')
+	}
+
+	/**
+	 * Read a paged list to the end.
+	 *
+	 * The three list calls each sent an empty params object and returned
+	 * the first page, never sending a cursor and never reading the one
+	 * that came back. A server that pages its catalogue therefore
+	 * contributed only its first page: the rest were never registered,
+	 * never namespaced, never advertised — with no error, no warning and
+	 * no drift signal, because drift compares page one against page one.
+	 * The symptom is a model that does not use a tool it was told about,
+	 * which reads as model incompetence rather than a client bug.
+	 *
+	 * The page cap is a runaway guard, not a limit anyone should reach: a
+	 * server that keeps returning a cursor forever would otherwise loop
+	 * 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[]> {
+		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 batch = result[field]
+			if (Array.isArray(batch)) items.push(...(batch as T[]))
+
+			const next = result.nextCursor
+			if (typeof next !== 'string' || next.length === 0) return items
+			if (page >= MAX_LIST_PAGES) {
+				throw new Error(
+					`${method} did not stop paging after ${MAX_LIST_PAGES} pages (${items.length} items so far). Refusing to keep going rather than returning a catalogue that is silently missing the rest.`,
+				)
+			}
+			cursor = next
 		}
-		return result.resourceTemplates
 	}
 
 	onNotification(handler: (method: string, params?: Record<string, unknown>) => void): void {
@@ -184,6 +245,18 @@ export class MCPClient {
 		}
 	}
 
+	/**
+	 * Send a JSON-RPC request and wait for its reply, bounded by a timer.
+	 *
+	 * There was no timer at all. On `streamable_http` the pending promise
+	 * happened to be bounded because `send()` awaits the fetch inside an
+	 * aborted scope, but on **stdio** — the default for local servers —
+	 * and on `http_sse` (whose reply arrives on a separate channel) a
+	 * server that wedged left the promise pending forever. Combined with
+	 * an executor that awaited tools unbounded, one unresponsive MCP
+	 * 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> {
 		const id = this.nextRequestId++
 		const message: MCPJsonRpcMessage = {
@@ -192,16 +265,62 @@ export class MCPClient {
 			method,
 			params,
 		}
+		const timeoutMs = this.config.requestTimeoutMs ?? DEFAULT_MCP_REQUEST_TIMEOUT_MS
 
 		return new Promise<unknown>((resolve, reject) => {
-			this.pendingRequests.set(id, { resolve, reject })
+			const timer = setTimeout(() => {
+				this.pendingRequests.delete(id)
+				this.log.warn('MCP request timed out', {
+					server: this.config.serverName,
+					method,
+					timeoutMs,
+				})
+				reject(
+					new Error(
+						`MCP request "${method}" to "${this.config.serverName}" timed out after ${timeoutMs}ms`,
+					),
+				)
+			}, timeoutMs)
+
+			this.pendingRequests.set(id, {
+				resolve: (value) => {
+					clearTimeout(timer)
+					resolve(value)
+				},
+				reject: (err) => {
+					clearTimeout(timer)
+					reject(err)
+				},
+			})
+
 			this.transport.send(message).catch((err) => {
+				clearTimeout(timer)
 				this.pendingRequests.delete(id)
 				reject(err)
 			})
 		})
 	}
 
+	/**
+	 * Fail every in-flight request with the same reason.
+	 *
+	 * Previously only `disconnect()` did this, so a transport that dropped
+	 * on its own — process exit, socket reset, server crash — left callers
+	 * waiting on promises that could never settle.
+	 */
+	private rejectAllPending(reason: string): void {
+		if (this.pendingRequests.size === 0) return
+		this.log.warn('Failing in-flight MCP requests', {
+			server: this.config.serverName,
+			count: this.pendingRequests.size,
+			reason,
+		})
+		for (const [, pending] of this.pendingRequests) {
+			pending.reject(new Error(reason))
+		}
+		this.pendingRequests.clear()
+	}
+
 	private async notify(method: string, params: Record<string, unknown>): Promise<void> {
 		const message: MCPJsonRpcMessage = {
 			jsonrpc: '2.0',
@@ -229,6 +348,34 @@ export class MCPClient {
 			for (const handler of this.notificationHandlers) {
 				handler(message.method, message.params)
 			}
+			return
+		}
+
+		// A frame carrying BOTH an id and a method is a server-initiated
+		// REQUEST — `sampling/createMessage`, `elicitation/create`,
+		// `roots/list`, `ping`. It matched neither branch above and was
+		// dropped on the floor, so a spec-current server sat waiting for a
+		// reply that would never come, which looks exactly like a hang.
+		// Answer honestly: we do not implement these yet.
+		if (message.method && message.id !== undefined) {
+			this.log.warn('Declining unsupported server-initiated MCP request', {
+				server: this.config.serverName,
+				method: message.method,
+			})
+			void this.transport
+				.send({
+					jsonrpc: '2.0',
+					id: message.id,
+					error: {
+						code: JSON_RPC_METHOD_NOT_FOUND,
+						message: `Method not found: ${message.method}`,
+					},
+				})
+				.catch((err) => {
+					this.log.debug('Failed to send method-not-found reply', {
+						error: toErrorMessage(err),
+					})
+				})
 		}
 	}
 

package/src/connector/mcp/discovery.ts

@@ -1,17 +1,50 @@
-import type { MCPDiscoveredTool } from '../../types/connector/index.js'
+import type { MCPDiscoveredTool, MCPToolDefinition } from '../../types/connector/index.js'
 import type { ToolDefinition } from '../../types/tool/index.js'
 import { toErrorMessage } from '../../utils/error.js'
 import { type Logger, getRootLogger } from '../../utils/logger.js'
 import { mcpToolToToolDefinition } from './adapter.js'
 import type { MCPClient } from './client.js'
+import {
+	type MCPToolDrift,
+	type MCPToolPolicy,
+	applyToolPolicy,
+	diffTools,
+	hasDrift,
+} from './policy.js'
+
+export interface MCPToolDiscoveryOptions {
+	/**
+	 * What each server is allowed to contribute, keyed by server name.
+	 * `'*'` applies to every server not named explicitly.
+	 *
+	 * Absent ⇒ everything is admitted, which is the pre-existing behavior
+	 * and the reason this option exists.
+	 */
+	readonly policies?: Readonly<Record<string, MCPToolPolicy>>
+	/**
+	 * Called when a server's tool set differs from the previous discovery.
+	 *
+	 * Drift is reported rather than blocked because the right response is a
+	 * host decision: a dev server legitimately changes between runs, while
+	 * a production one changing mid-session is the "rug pull" — advertise
+	 * something benign at approval time, swap it afterwards. Only the host
+	 * knows which it is looking at.
+	 */
+	readonly onDrift?: (event: { serverName: string; clientId: string; drift: MCPToolDrift }) => void
+	readonly logger?: Logger
+}
 
 export class MCPToolDiscovery {
 	private clients: MCPClient[]
 	private log: Logger
+	private options: MCPToolDiscoveryOptions
+	/** Last admitted tool set per client, for drift detection. */
+	private lastSeen = new Map<string, MCPToolDefinition[]>()
 
-	constructor(clients: MCPClient[]) {
+	constructor(clients: MCPClient[], options: MCPToolDiscoveryOptions = {}) {
 		this.clients = clients
-		this.log = getRootLogger().child({ component: 'MCPToolDiscovery' })
+		this.options = options
+		this.log = options.logger ?? getRootLogger().child({ component: 'MCPToolDiscovery' })
 	}
 
 	addClient(client: MCPClient): void {
@@ -20,6 +53,7 @@ export class MCPToolDiscovery {
 
 	removeClient(clientId: string): void {
 		this.clients = this.clients.filter((c) => c.id !== clientId)
+		this.lastSeen.delete(clientId)
 	}
 
 	async discoverAll(): Promise<MCPDiscoveredTool[]> {
@@ -47,9 +81,26 @@ export class MCPToolDiscovery {
 
 	async discoverFrom(client: MCPClient): Promise<MCPDiscoveredTool[]> {
 		const state = client.getState()
-		const tools = await client.listTools()
+		const advertised = await client.listTools()
+
+		// The boundary. Without it the REMOTE side decides what enters the
+		// agent's registry, which inverts least privilege: a server could
+		// add a tool between two runs and it became callable with nobody
+		// having agreed to it.
+		const policy = this.options.policies?.[state.serverName] ?? this.options.policies?.['*']
+		const { admitted, refused } = applyToolPolicy(advertised, policy)
+
+		if (refused.length > 0) {
+			this.log.warn('MCP tools refused by policy', {
+				serverName: state.serverName,
+				clientId: client.id,
+				refused: refused.map((r) => `${r.name} (${r.reason})`),
+			})
+		}
+
+		this.detectDrift(client.id, state.serverName, admitted)
 
-		return tools.map((tool) => ({
+		return admitted.map((tool) => ({
 			tool,
 			clientId: client.id,
 			serverName: state.serverName,
@@ -66,4 +117,22 @@ export class MCPToolDiscovery {
 			return mcpToolToToolDefinition(d.tool, client, d.serverName)
 		})
 	}
+
+	private detectDrift(clientId: string, serverName: string, admitted: MCPToolDefinition[]): void {
+		const previous = this.lastSeen.get(clientId)
+		this.lastSeen.set(clientId, admitted)
+		if (!previous) return
+
+		const drift = diffTools(previous, admitted)
+		if (!hasDrift(drift)) return
+
+		this.log.warn('MCP server tool set changed since the last discovery', {
+			serverName,
+			clientId,
+			added: drift.added,
+			removed: drift.removed,
+			changed: drift.changed,
+		})
+		this.options.onDrift?.({ serverName, clientId, drift })
+	}
 }

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

@@ -5,6 +5,21 @@ import type {
 } from '../../types/connector/index.js'
 import { type Logger, getRootLogger } from '../../utils/logger.js'
 
+/**
+ * Trim trailing slashes without a regex.
+ *
+ * `/\/+$/` backtracks quadratically on a long run of slashes, and this
+ * value crosses a trust boundary — a host-supplied endpoint on a shared
+ * event loop. The scan is linear and says the same thing.
+ */
+function stripTrailingSlashes(value: string): string {
+	let end = value.length
+	while (end > 0 && value[end - 1] === '/') {
+		end--
+	}
+	return value.slice(0, end)
+}
+
 export class HttpSseTransport implements MCPTransport {
 	private messageHandlers: Array<(message: MCPJsonRpcMessage) => void> = []
 	private closeHandlers: Array<() => void> = []
@@ -16,7 +31,7 @@ export class HttpSseTransport implements MCPTransport {
 	private log: Logger
 
 	constructor(private readonly config: MCPHttpSseTransportConfig) {
-		const base = config.url.replace(/\/+$/, '')
+		const base = stripTrailingSlashes(config.url)
 		this.sseUrl = `${base}/sse`
 		this.postUrl = `${base}/message`
 		this.log = getRootLogger().child({ component: 'HttpSseTransport' })

package/src/connector/mcp/index.ts

@@ -19,3 +19,7 @@ export { MCPConnectorBridge } from '../../bridge/mcp/connector/adapter.js'
 
 export { MCPServer } from './server.js'
 export type { MCPServerToolProvider, MCPServerResourceProvider } from './server.js'
+
+export type { MCPToolDiscoveryOptions } from './discovery.js'
+export { applyToolPolicy, diffTools, hasDrift, toolsHash } from './policy.js'
+export type { MCPToolDrift, MCPToolPolicy, MCPToolPolicyDecision } from './policy.js'

package/src/connector/mcp/policy.ts

@@ -0,0 +1,134 @@
+import { createHash } from 'node:crypto'
+import type { MCPToolDefinition } from '../../types/connector/index.js'
+
+/**
+ * What a host will accept from an MCP server.
+ *
+ * Discovery used to take whatever the server offered, which puts the
+ * REMOTE side in charge of what enters the agent's tool registry — the
+ * exact inversion of least privilege. A server could add a tool between
+ * two runs and it became callable with no one having agreed to it.
+ */
+export interface MCPToolPolicy {
+	/**
+	 * Names (as the SERVER reports them, before the `mcp_<server>_` prefix)
+	 * that may be admitted. When set, nothing else is, and a tool that
+	 * appears later is refused by default rather than admitted by default.
+	 */
+	readonly allow?: readonly string[]
+	/** Names that are never admitted, even if `allow` lists them. */
+	readonly deny?: readonly string[]
+}
+
+export interface MCPToolPolicyDecision {
+	readonly admitted: MCPToolDefinition[]
+	/** Refused tools, with the reason, so a host can log or surface them. */
+	readonly refused: ReadonlyArray<{ name: string; reason: 'not_allowed' | 'denied' }>
+}
+
+/**
+ * Apply a policy to one server's advertised tools.
+ *
+ * Deny beats allow. A name on both lists is refused — the restrictive
+ * reading is the only safe one when a config contradicts itself.
+ */
+export function applyToolPolicy(
+	tools: readonly MCPToolDefinition[],
+	policy: MCPToolPolicy | undefined,
+): MCPToolPolicyDecision {
+	if (!policy || (!policy.allow && !policy.deny)) {
+		return { admitted: [...tools], refused: [] }
+	}
+
+	const allow = policy.allow ? new Set(policy.allow) : null
+	const deny = new Set(policy.deny ?? [])
+
+	const admitted: MCPToolDefinition[] = []
+	const refused: Array<{ name: string; reason: 'not_allowed' | 'denied' }> = []
+
+	for (const tool of tools) {
+		if (deny.has(tool.name)) {
+			refused.push({ name: tool.name, reason: 'denied' })
+			continue
+		}
+		if (allow && !allow.has(tool.name)) {
+			refused.push({ name: tool.name, reason: 'not_allowed' })
+			continue
+		}
+		admitted.push(tool)
+	}
+
+	return { admitted, refused }
+}
+
+/**
+ * A stable fingerprint of what a server is offering.
+ *
+ * Covers each tool's name, description and input schema — everything the
+ * model is shown and everything that determines what a call does. A server
+ * can advertise a benign tool at approval time and swap its description or
+ * schema afterwards; nothing about the tool NAME changes, so a name-only
+ * check would miss it entirely.
+ *
+ * Sorted by name and serialized with sorted keys so the hash reflects
+ * meaning rather than transport ordering.
+ */
+export function toolsHash(tools: readonly MCPToolDefinition[]): string {
+	const canonical = [...tools]
+		.sort((a, b) => a.name.localeCompare(b.name))
+		.map((tool) => ({
+			name: tool.name,
+			description: tool.description ?? '',
+			inputSchema: stableStringify(tool.inputSchema),
+			// `annotations` carries `readOnlyHint` and `destructiveHint`, and
+			// those are what `mcpToolToToolDefinition` turns into `isReadOnly`
+			// / `isDestructive` — the flags the HITL review keys on. Omitting
+			// them meant a server could flip a tool from destructive to
+			// read-only, silently removing it from human review, and the
+			// fingerprint built to catch exactly that rug-pull saw nothing.
+			annotations: stableStringify(tool.annotations),
+		}))
+
+	return createHash('sha256').update(JSON.stringify(canonical)).digest('hex')
+}
+
+/** What changed between two discoveries of the same server. */
+export interface MCPToolDrift {
+	readonly added: string[]
+	readonly removed: string[]
+	/** Same name, different description or schema — the rug-pull shape. */
+	readonly changed: string[]
+}
+
+export function diffTools(
+	before: readonly MCPToolDefinition[],
+	after: readonly MCPToolDefinition[],
+): MCPToolDrift {
+	const beforeByName = new Map(before.map((t) => [t.name, t]))
+	const afterByName = new Map(after.map((t) => [t.name, t]))
+
+	const added = [...afterByName.keys()].filter((name) => !beforeByName.has(name))
+	const removed = [...beforeByName.keys()].filter((name) => !afterByName.has(name))
+	const changed = [...afterByName.keys()].filter((name) => {
+		const prev = beforeByName.get(name)
+		if (!prev) return false
+		const next = afterByName.get(name) as MCPToolDefinition
+		return toolsHash([prev]) !== toolsHash([next])
+	})
+
+	return { added, removed, changed }
+}
+
+export function hasDrift(drift: MCPToolDrift): boolean {
+	return drift.added.length > 0 || drift.removed.length > 0 || drift.changed.length > 0
+}
+
+/** JSON with object keys sorted at every depth, so key order cannot move a hash. */
+function stableStringify(value: unknown): string {
+	if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null'
+	if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`
+	const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) =>
+		a.localeCompare(b),
+	)
+	return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(',')}}`
+}

package/src/connector/mcp/schema-refs.ts

@@ -0,0 +1,126 @@
+/**
+ * Resolve `$ref` pointers in a remote tool's input schema before it is
+ * converted.
+ *
+ * A `$ref` reached the converter's `default:` branch and became "anything":
+ * no type, no shape, nothing for the model to work from. And because the
+ * resulting node is inherently optional, a `$ref`'d field the server listed
+ * as required stopped being enforced too — an empty payload validated
+ * clean and was forwarded to the server instead of being rejected with the
+ * "Required: <field>" hint the executor already knows how to build.
+ *
+ * That is not an exotic shape. `$defs` + `$ref` is what several widely used
+ * schema generators emit by default for a nested object, so a server that
+ * did everything right presented its main argument to the model as `{}`.
+ */
+
+/** How deep to follow a schema before giving up. */
+export const MAX_SCHEMA_DEPTH = 64
+
+type JsonObject = Record<string, unknown>
+
+function isObject(value: unknown): value is JsonObject {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** Decode one JSON Pointer token (RFC 6901): `~1` is `/`, `~0` is `~`. */
+function decodeToken(token: string): string {
+	return token.replace(/~1/g, '/').replace(/~0/g, '~')
+}
+
+/**
+ * Follow a local pointer (`#/$defs/Thing`) from the document root.
+ *
+ * Only same-document pointers are resolvable. A `$ref` to another file or
+ * a URL would need a fetch, which is not something a schema conversion may
+ * do — those are left alone and fall through to the permissive branch, the
+ * same as before.
+ */
+function resolvePointer(root: JsonObject, ref: string): unknown {
+	if (ref === '#') return root
+	if (!ref.startsWith('#/')) return undefined
+
+	let current: unknown = root
+	for (const raw of ref.slice(2).split('/')) {
+		const token = decodeToken(raw)
+		if (Array.isArray(current)) {
+			const index = Number(token)
+			if (!Number.isInteger(index)) return undefined
+			current = current[index]
+			continue
+		}
+		if (!isObject(current)) return undefined
+		current = current[token]
+	}
+	return current
+}
+
+interface InlineState {
+	readonly root: JsonObject
+	/** Pointers currently being expanded on THIS path — a cycle guard. */
+	readonly active: Set<string>
+	readonly depth: number
+}
+
+function walk(node: unknown, state: InlineState): unknown {
+	if (Array.isArray(node)) {
+		return node.map((item) => walk(item, state))
+	}
+	if (!isObject(node)) return node
+	if (state.depth >= MAX_SCHEMA_DEPTH) return node
+
+	const ref = node.$ref
+	if (typeof ref === 'string') {
+		return expandRef(node, ref, state)
+	}
+
+	const out: JsonObject = {}
+	for (const [key, value] of Object.entries(node)) {
+		// `$defs` / `definitions` are a dictionary of targets, not part of
+		// the shape. Once every pointer is inlined they describe nothing, and
+		// leaving them in would re-render as dead weight in the schema the
+		// model is shown.
+		if (key === '$defs' || key === 'definitions') continue
+		out[key] = walk(value, { ...state, depth: state.depth + 1 })
+	}
+	return out
+}
+
+function expandRef(node: JsonObject, ref: string, state: InlineState): unknown {
+	const { $ref: _ref, ...siblings } = node
+
+	if (state.active.has(ref)) {
+		// A self-referential schema (a tree node whose children are the same
+		// node) cannot be expanded into a finite tree. Stopping here yields
+		// the permissive node the whole conversion used to produce — but for
+		// one branch of one recursive type, not for every `$ref` in the
+		// document.
+		return { ...siblings }
+	}
+
+	const target = resolvePointer(state.root, ref)
+	if (!isObject(target)) {
+		// A dangling or non-local pointer. The server's schema is wrong or
+		// unreachable; that is its problem to report, and guessing a shape
+		// here would be worse than admitting we do not know one.
+		return { ...siblings }
+	}
+
+	state.active.add(ref)
+	const expanded = walk(target, { ...state, depth: state.depth + 1 })
+	state.active.delete(ref)
+
+	// Sibling keywords alongside `$ref` are legal since draft 2019-09 and are
+	// commonly a `description` on the reference site. They win: they are the
+	// more specific statement about this position.
+	return isObject(expanded) ? { ...expanded, ...siblings } : expanded
+}
+
+/**
+ * Return the schema with every resolvable local `$ref` replaced by its
+ * target. Non-local and dangling pointers, and the second visit to a
+ * recursive one, degrade to whatever sibling keywords were present.
+ */
+export function inlineSchemaRefs(schema: JsonObject): JsonObject {
+	return walk(schema, { root: schema, active: new Set(), depth: 0 }) as JsonObject
+}

package/src/constants/agent/index.ts

@@ -7,6 +7,9 @@ export const AGENT_MANAGER_DEFAULTS: Readonly<AgentManagerConfig> = {
 	maxDepth: 3,
 	evictionMs: 30_000,
 	maxBudgetFraction: 0.5,
+	// Five minutes. Generous for a delegated sub-task, bounded enough that a
+	// wedged child cannot hold its parent open indefinitely.
+	childTimeoutMs: 300_000,
 }
 
 export const DEFAULT_CAPABILITIES: AgentCapabilities = {

package/src/constants/compaction/index.ts

@@ -1,6 +1,6 @@
 // Tool-name buckets used by the compaction extractor to classify
 // captured tool results. Lowercase to match the canonical builtin
-// tool names (Anthropic Claude emits `tool_use.name` lowercase, see
+// tool names (a tool-use block reports its name lowercase, see
 // ses_008-tool-name-case-fix). `edit` is grouped with `write`
 // because both mutate file content.
 export const READ_TOOLS = new Set(['read'])