@namzu/sdk 3.1.0 → 3.2.0

package/src/connector/mcp/client.ts

@@ -3,8 +3,12 @@ import type {
 	MCPClientState,
 	MCPConnectionStatus,
 	MCPContentBlock,
+	MCPEventListener,
 	MCPInitializeResult,
 	MCPJsonRpcMessage,
+	MCPLifecycleEvent,
+	MCPPromptDefinition,
+	MCPPromptMessage,
 	MCPResource,
 	MCPResourceTemplate,
 	MCPServerCapabilities,
@@ -52,6 +56,7 @@ export class MCPClient {
 	private nextRequestId = 1
 	private notificationHandlers: Array<(method: string, params?: Record<string, unknown>) => void> =
 		[]
+	private lifecycleListeners: MCPEventListener[] = []
 	private log: Logger
 	private readonly config: MCPClientConfig
 
@@ -74,12 +79,14 @@ export class MCPClient {
 			this.transport.onClose(() => {
 				this.status = 'disconnected'
 				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.error = err.message
 				this.log.error('MCP transport error', { error: err.message })
+				this.emitLifecycle({ type: 'mcp_client_error', clientId: this.id, error: err.message })
 				this.rejectAllPending(`MCP transport to "${this.config.serverName}" failed: ${err.message}`)
 			})
 
@@ -116,6 +123,11 @@ export class MCPClient {
 
 			this.status = 'connected'
 			this.connectedAt = Date.now()
+			this.emitLifecycle({
+				type: 'mcp_client_connected',
+				clientId: this.id,
+				serverName: this.config.serverName,
+			})
 			this.log.info(`Connected to MCP server: ${result.serverInfo.name}`)
 
 			return result
@@ -123,6 +135,7 @@ export class MCPClient {
 			this.status = 'error'
 			this.error = toErrorMessage(err)
 			this.log.error('MCP connection failed', { error: this.error })
+			this.emitLifecycle({ type: 'mcp_client_error', clientId: this.id, error: this.error })
 			throw err
 		}
 	}
@@ -136,6 +149,7 @@ export class MCPClient {
 		this.status = 'disconnected'
 		this.connectedAt = undefined
 		this.log.info('MCP client disconnected')
+		this.emitLifecycle({ type: 'mcp_client_disconnected', clientId: this.id })
 	}
 
 	isConnected(): boolean {
@@ -181,6 +195,48 @@ export class MCPClient {
 		return result.contents
 	}
 
+	/**
+	 * The prompts a server publishes.
+	 *
+	 * A prompt is the server's own wording for a task it knows how to set
+	 * up — the half of MCP that is not tools. `MCPPromptDefinition` and
+	 * `MCPPromptArgument` were declared when the types were written and no
+	 * method ever asked for one, so a server offering prompts had them
+	 * silently ignored.
+	 *
+	 * Paged through the same reader as every other list, which is the point
+	 * 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[]> {
+		this.requireConnected()
+		return await this.listAllPages('prompts/list', 'prompts')
+	}
+
+	/**
+	 * Fetch one prompt, with its arguments filled in.
+	 *
+	 * Returns the messages the SERVER composed. They are data to be shown to
+	 * a model, never instructions to this client: a prompt arriving from a
+	 * remote server is exactly the untrusted-content case, and treating its
+	 * text as direction would let a server steer the agent by publishing a
+	 * prompt nobody asked to run.
+	 */
+	async getPrompt(
+		name: string,
+		args?: Record<string, string>,
+	): Promise<{ description?: string; messages: MCPPromptMessage[] }> {
+		this.requireConnected()
+		const result = (await this.request('prompts/get', {
+			name,
+			arguments: args ?? {},
+		})) as { description?: string; messages?: MCPPromptMessage[] }
+		return {
+			...(result.description !== undefined ? { description: result.description } : {}),
+			messages: result.messages ?? [],
+		}
+	}
+
 	async listResourceTemplates(): Promise<MCPResourceTemplate[]> {
 		this.requireConnected()
 		return await this.listAllPages('resources/templates/list', 'resourceTemplates')
@@ -231,6 +287,45 @@ export class MCPClient {
 		this.notificationHandlers.push(handler)
 	}
 
+	/**
+	 * Watch this client come up, go down, or fail.
+	 *
+	 * `MCPLifecycleEvent` and `MCPEventListener` were declared with the rest
+	 * of the MCP types and nothing ever emitted one, so a host could observe
+	 * a server dying only by noticing that calls had started failing. The
+	 * four transitions below already existed and already mutated `status`;
+	 * this adds no state, it just says out loud what the client already
+	 * knew.
+	 *
+	 * Returns an unsubscribe. `onNotification` above does not, which is the
+	 * bug this avoids repeating: a listener that cannot be removed keeps a
+	 * disposed host object alive for as long as the client lives.
+	 */
+	onLifecycle(listener: MCPEventListener): () => void {
+		this.lifecycleListeners.push(listener)
+		return () => {
+			const index = this.lifecycleListeners.indexOf(listener)
+			if (index >= 0) this.lifecycleListeners.splice(index, 1)
+		}
+	}
+
+	/**
+	 * A listener that throws must not take the transport down with it.
+	 *
+	 * These fire from inside transport callbacks and from the failure path
+	 * of `connect`, so an exception here would surface as a connection
+	 * error — blaming the server for a bug in the host's own observer.
+	 */
+	private emitLifecycle(event: MCPLifecycleEvent): void {
+		for (const listener of this.lifecycleListeners) {
+			try {
+				listener(event)
+			} catch (err) {
+				this.log.warn('MCP lifecycle listener threw', { error: toErrorMessage(err) })
+			}
+		}
+	}
+
 	private createTransport(config: MCPTransportUnion): MCPTransport {
 		switch (config.type) {
 			case 'stdio':

package/src/connector/mcp/discovery.ts

@@ -38,7 +38,18 @@ export class MCPToolDiscovery {
 	private clients: MCPClient[]
 	private log: Logger
 	private options: MCPToolDiscoveryOptions
-	/** Last admitted tool set per client, for drift detection. */
+	/**
+	 * Last admitted tool set per SERVER, 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
+	 * 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
+	 * changed underneath. The threat is a server that advertises something
+	 * benign when a host approves it and something else afterwards, which is
+	 * a property of the SERVER across connections.
+	 */
 	private lastSeen = new Map<string, MCPToolDefinition[]>()
 
 	constructor(clients: MCPClient[], options: MCPToolDiscoveryOptions = {}) {
@@ -53,7 +64,11 @@ export class MCPToolDiscovery {
 
 	removeClient(clientId: string): void {
 		this.clients = this.clients.filter((c) => c.id !== clientId)
-		this.lastSeen.delete(clientId)
+		// The remembered tool set is deliberately NOT forgotten. Dropping it on
+		// disconnect is what made the rug pull invisible: disable, swap the
+		// server's tools, enable again, and the next discovery had nothing to
+		// compare against. What is remembered is a name and a list of tool
+		// shapes, so keeping it costs almost nothing.
 	}
 
 	async discoverAll(): Promise<MCPDiscoveredTool[]> {
@@ -119,8 +134,8 @@ export class MCPToolDiscovery {
 	}
 
 	private detectDrift(clientId: string, serverName: string, admitted: MCPToolDefinition[]): void {
-		const previous = this.lastSeen.get(clientId)
-		this.lastSeen.set(clientId, admitted)
+		const previous = this.lastSeen.get(serverName)
+		this.lastSeen.set(serverName, admitted)
 		if (!previous) return
 
 		const drift = diffTools(previous, admitted)

package/src/connector/mcp/index.ts

@@ -17,8 +17,12 @@ export { MCPToolDiscovery } from './discovery.js'
 
 export { MCPConnectorBridge } from '../../bridge/mcp/connector/adapter.js'
 
-export { MCPServer } from './server.js'
-export type { MCPServerToolProvider, MCPServerResourceProvider } from './server.js'
+export { MCPServer, MCPMethodNotFound } from './server.js'
+export type {
+	MCPServerToolProvider,
+	MCPServerResourceProvider,
+	MCPServerPromptProvider,
+} from './server.js'
 
 export type { MCPToolDiscoveryOptions } from './discovery.js'
 export { applyToolPolicy, diffTools, hasDrift, toolsHash } from './policy.js'

package/src/connector/mcp/server.ts

@@ -1,3 +1,4 @@
+import { JSON_RPC_METHOD_NOT_FOUND } from '../../constants/mcp/index.js'
 import type {
 	MCPContentBlock,
 	MCPJsonRpcMessage,
@@ -9,11 +10,27 @@ import type {
 	MCPToolResult,
 	MCPTransport,
 } from '../../types/connector/index.js'
+import type { MCPPromptDefinition, MCPPromptMessage } from '../../types/connector/index.js'
 import type { MCPServerId } from '../../types/ids/index.js'
 import { toErrorMessage } from '../../utils/error.js'
 import { generateMCPServerId } from '../../utils/id.js'
 import { type Logger, getRootLogger } from '../../utils/logger.js'
 
+/**
+ * A method this server does not implement.
+ *
+ * Carried as its own error so the dispatcher can answer with the protocol's
+ * own code instead of a generic internal error. `-32603` tells a client the
+ * server broke; `-32601` tells it the server does not do this — and only the
+ * second lets a client stop asking rather than retry.
+ */
+export class MCPMethodNotFound extends Error {
+	constructor(readonly method: string) {
+		super(`Method not found: ${method}`)
+		this.name = 'MCPMethodNotFound'
+	}
+}
+
 export interface MCPServerToolProvider {
 	listTools(): MCPToolDefinition[]
 	callTool(name: string, args?: Record<string, unknown>): Promise<MCPToolResult>
@@ -24,11 +41,27 @@ export interface MCPServerResourceProvider {
 	readResource(uri: string): Promise<MCPContentBlock[]>
 }
 
+/**
+ * Prompts this server publishes.
+ *
+ * Injected as an interface like the other two, so the server owns dispatch
+ * and the host owns content. `MCPPromptDefinition` existed in the types
+ * from the start with no way to serve one.
+ */
+export interface MCPServerPromptProvider {
+	listPrompts(): MCPPromptDefinition[]
+	getPrompt(
+		name: string,
+		args?: Record<string, string>,
+	): Promise<{ description?: string; messages: MCPPromptMessage[] }>
+}
+
 export class MCPServer {
 	readonly id: MCPServerId
 	private config: MCPServerConfig
 	private toolProvider: MCPServerToolProvider
 	private resourceProvider?: MCPServerResourceProvider
+	private promptProvider?: MCPServerPromptProvider
 	private transport: MCPTransport | null = null
 	private running = false
 	private connectedClients = 0
@@ -39,11 +72,13 @@ export class MCPServer {
 		config: MCPServerConfig,
 		toolProvider: MCPServerToolProvider,
 		resourceProvider?: MCPServerResourceProvider,
+		promptProvider?: MCPServerPromptProvider,
 	) {
 		this.id = config.id ?? generateMCPServerId()
 		this.config = config
 		this.toolProvider = toolProvider
 		this.resourceProvider = resourceProvider
+		this.promptProvider = promptProvider
 		this.log = getRootLogger().child({ component: 'MCPServer', serverId: this.id })
 	}
 
@@ -100,7 +135,8 @@ export class MCPServer {
 			const result = await this.dispatch(message.method, message.params ?? {})
 			await this.respond(message.id, result)
 		} catch (err) {
-			await this.respondError(message.id, -32603, toErrorMessage(err))
+			const code = err instanceof MCPMethodNotFound ? JSON_RPC_METHOD_NOT_FOUND : -32603
+			await this.respondError(message.id, code, toErrorMessage(err))
 		}
 	}
 
@@ -116,10 +152,14 @@ export class MCPServer {
 				return this.handleResourcesList()
 			case 'resources/read':
 				return this.handleResourcesRead(params)
+			case 'prompts/list':
+				return this.handlePromptsList()
+			case 'prompts/get':
+				return this.handlePromptsGet(params)
 			case 'ping':
 				return {}
 			default:
-				throw new Error(`Unknown method: ${method}`)
+				throw new MCPMethodNotFound(method)
 		}
 	}
 
@@ -138,6 +178,13 @@ export class MCPServer {
 			capabilities.resources = { subscribe: false, listChanged: false }
 		}
 
+		// Declared only when there is something behind it, matching resources
+		// above. A capability advertised without a provider is a promise the
+		// next call breaks.
+		if (this.promptProvider) {
+			capabilities.prompts = { listChanged: false }
+		}
+
 		return {
 			protocolVersion: '2024-11-05',
 			capabilities,
@@ -166,13 +213,64 @@ export class MCPServer {
 		return this.toolProvider.callTool(name, args)
 	}
 
+	/**
+	 * An empty list is what a server with NO resources returns. A server
+	 * that cannot serve resources at all has to say so differently.
+	 *
+	 * This used to answer `{ resources: [] }` when no provider was
+	 * configured, for a capability `initialize` never advertised — so a
+	 * client that asked anyway was told, in the protocol's own vocabulary,
+	 * that the answer is "none" rather than "not here". The two send a
+	 * client in opposite directions: one stops asking, the other looks for
+	 * the resource somewhere else.
+	 */
 	private handleResourcesList(): { resources: MCPResource[] } {
 		if (!this.resourceProvider) {
-			return { resources: [] }
+			throw new MCPMethodNotFound('resources/list')
 		}
 		return { resources: this.resourceProvider.listResources() }
 	}
 
+	private handlePromptsList(): { prompts: MCPPromptDefinition[] } {
+		if (!this.promptProvider) {
+			throw new MCPMethodNotFound('prompts/list')
+		}
+		return { prompts: this.promptProvider.listPrompts() }
+	}
+
+	private async handlePromptsGet(
+		params: Record<string, unknown>,
+	): Promise<{ description?: string; messages: MCPPromptMessage[] }> {
+		if (!this.promptProvider) {
+			throw new MCPMethodNotFound('prompts/get')
+		}
+		const name = params.name as string
+		if (!name) {
+			throw new Error('prompts/get requires a "name"')
+		}
+		const args = (params.arguments as Record<string, string> | undefined) ?? {}
+
+		// Required arguments are checked HERE rather than left to the
+		// provider. A prompt declares them, so a missing one is answerable
+		// from the declaration alone, and every provider would otherwise
+		// re-implement the same check or forget to.
+		const declared = this.promptProvider.listPrompts().find((p) => p.name === name)
+		if (!declared) {
+			throw new Error(`Unknown prompt: ${name}`)
+		}
+		const missing = (declared.arguments ?? [])
+			.filter((a) => a.required === true)
+			.map((a) => a.name)
+			.filter((n) => args[n] === undefined)
+		if (missing.length > 0) {
+			throw new Error(
+				`prompts/get "${name}" is missing required argument(s): ${missing.join(', ')}`,
+			)
+		}
+
+		return this.promptProvider.getPrompt(name, args)
+	}
+
 	private async handleResourcesRead(
 		params: Record<string, unknown>,
 	): Promise<{ contents: MCPContentBlock[] }> {

package/src/manager/agent/__tests__/depth-limit-authority.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import type { AgentTaskContext } from '../../../types/agent/index.js'
+
+/**
+ * Which `maxDepth` is in force.
+ *
+ * Two exist. `AgentManagerConfig.maxDepth` is enforced in
+ * `AgentManager.sendMessage`; `SupervisorAgentConfig.maxDepth` is read by
+ * nothing. For a recursion bound that is the worst way to be wrong — the
+ * number a reviewer sees in the supervisor config is not the number
+ * stopping runaway delegation.
+ *
+ * The first version of these tests passed the config where the registry
+ * goes, so every case silently ran against the default of 3 — and the case
+ * that used 3 "passed" while proving nothing. Configuring a value the
+ * default is not is what makes this a test.
+ */
+
+async function manager(maxDepth: number) {
+	const { AgentManager } = await import('../lifecycle.js')
+	const registry = { resolve: vi.fn(), get: vi.fn(), getAll: vi.fn(() => []) }
+	const deps = { createAgent: vi.fn(), taskStore: undefined }
+	return new AgentManager(registry as never, { maxDepth }, deps as never)
+}
+
+function contextAtDepth(depth: number): AgentTaskContext {
+	return {
+		parentRunId: 'run_x',
+		parentAgentId: 'agent_x',
+		parentAbortController: new AbortController(),
+		depth,
+		tenantId: 'tnt_x',
+	} as unknown as AgentTaskContext
+}
+
+function send(m: Awaited<ReturnType<typeof manager>>, depth: number) {
+	return m.sendMessage(
+		{ agentId: 'a', prompt: 'go', tenantId: 'tnt_x' } as never,
+		contextAtDepth(depth),
+	)
+}
+
+describe('the manager owns the recursion bound', () => {
+	it('refuses a task at the configured depth', async () => {
+		// 5, deliberately not the default of 3: a limit that happens to equal
+		// the default cannot tell "configured" from "ignored".
+		const mgr = await manager(5)
+
+		await expect(send(mgr, 5)).rejects.toThrow(/Max task depth 5/)
+	})
+
+	it('refuses past it too, not only exactly at it', async () => {
+		const mgr = await manager(2)
+
+		await expect(send(mgr, 7)).rejects.toThrow(/Max task depth 2/)
+	})
+
+	it('reports the depth reached alongside the limit', async () => {
+		const mgr = await manager(2)
+
+		// A limit without the current value sends someone to instrument the
+		// run to learn how deep it actually got.
+		await expect(send(mgr, 4)).rejects.toThrow(/current: 4/)
+	})
+
+	it('allows a task below the bound to proceed past this check', async () => {
+		const mgr = await manager(5)
+
+		// It gets past the depth gate and fails later on the stubbed
+		// registry — which is the point: the gate did not stop it.
+		await expect(send(mgr, 1)).rejects.not.toThrow(/Max task depth/)
+	})
+})

package/src/plugin/__tests__/discovery-scopes.test.ts

@@ -0,0 +1,133 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { PluginRuntimeConfigSchema } from '../../config/runtime.js'
+import {
+	PLUGIN_MANIFEST_FILENAME,
+	PROJECT_PLUGIN_DIR,
+	USER_PLUGIN_DIR,
+} from '../../constants/plugin/index.js'
+
+/**
+ * `allowedScopes` read exactly like a trust boundary and enforced nothing.
+ *
+ * A plugin is arbitrary code with hooks into tool execution, and the two
+ * scopes are not equally trusted: a project plugin is reviewable in the repo
+ * the agent works on, a user plugin comes from a home directory the repo's
+ * reviewers never see. `PluginRuntimeConfig` carried `enabled`,
+ * `autoDiscovery` and `allowedScopes`; nothing anywhere consulted any of the
+ * three, and discovery scanned both locations unconditionally.
+ */
+
+let home: string
+let workdir: string
+
+vi.mock('node:os', async () => {
+	const actual = await vi.importActual<typeof import('node:os')>('node:os')
+	return { ...actual, homedir: () => home }
+})
+
+async function plantPlugin(dir: string, name: string): Promise<void> {
+	const pluginDir = join(dir, name)
+	await mkdir(pluginDir, { recursive: true })
+	await writeFile(
+		join(pluginDir, PLUGIN_MANIFEST_FILENAME),
+		JSON.stringify({ name, version: '1.0.0' }),
+		'utf-8',
+	)
+}
+
+beforeEach(async () => {
+	home = await mkdtemp(join(tmpdir(), 'namzu-home-'))
+	workdir = await mkdtemp(join(tmpdir(), 'namzu-work-'))
+	await plantPlugin(join(workdir, PROJECT_PLUGIN_DIR), 'project-plugin')
+	await plantPlugin(join(home, USER_PLUGIN_DIR), 'user-plugin')
+})
+
+afterEach(async () => {
+	await Promise.all([
+		rm(home, { recursive: true, force: true }),
+		rm(workdir, { recursive: true, force: true }),
+	])
+})
+
+async function discover(
+	options?: Parameters<typeof import('../loader.js').discoverAllPluginDirs>[1],
+) {
+	const { discoverAllPluginDirs } = await import('../loader.js')
+	return discoverAllPluginDirs(workdir, options)
+}
+
+describe('a scope the host did not allow is not scanned', () => {
+	it('finds both when nothing is said', async () => {
+		const found = await discover()
+
+		expect(found.project).toHaveLength(1)
+		expect(found.user).toHaveLength(1)
+	})
+
+	it('keeps user plugins out when only project is allowed', async () => {
+		const found = await discover({ allowedScopes: ['project'] })
+
+		expect(found.project).toHaveLength(1)
+		// The setting that reads like a boundary now is one.
+		expect(found.user).toEqual([])
+	})
+
+	it('keeps project plugins out when only user is allowed', async () => {
+		const found = await discover({ allowedScopes: ['user'] })
+
+		expect(found.project).toEqual([])
+		expect(found.user).toHaveLength(1)
+	})
+
+	it('finds nothing when neither scope is allowed', async () => {
+		const found = await discover({ allowedScopes: [] })
+
+		expect(found).toEqual({ project: [], user: [] })
+	})
+})
+
+describe('the runtime switches turn discovery off', () => {
+	it('discovers nothing when the plugin runtime is disabled', async () => {
+		const found = await discover({ enabled: false })
+
+		expect(found).toEqual({ project: [], user: [] })
+	})
+
+	it('discovers nothing when auto-discovery is off', async () => {
+		const found = await discover({ autoDiscovery: false })
+
+		expect(found).toEqual({ project: [], user: [] })
+	})
+
+	it('a default-parsed config discovers nothing, because the runtime ships off', async () => {
+		// `enabled` defaults to false in the schema. A host who parses the
+		// config and passes it gets the documented default rather than a
+		// silently-on plugin runtime.
+		const found = await discover(PluginRuntimeConfigSchema.parse({}))
+
+		expect(found).toEqual({ project: [], user: [] })
+	})
+
+	it('an enabled default-parsed config finds both scopes', async () => {
+		const found = await discover(PluginRuntimeConfigSchema.parse({ enabled: true }))
+
+		expect(found.project).toHaveLength(1)
+		expect(found.user).toHaveLength(1)
+	})
+
+	it('a parsed config carries its scope restriction through', async () => {
+		const config = PluginRuntimeConfigSchema.parse({
+			enabled: true,
+			allowedScopes: ['project'],
+		})
+
+		const found = await discover(config)
+
+		expect(found.project).toHaveLength(1)
+		expect(found.user).toEqual([])
+	})
+})

package/src/plugin/__tests__/enable-contributions.test.ts

@@ -11,11 +11,15 @@ const mockDisconnect = vi.fn(async (): Promise<void> => undefined)
 const mockListTools = vi.fn(async (): Promise<unknown[]> => [])
 
 vi.mock('../../connector/mcp/client.js', () => ({
-	MCPClient: vi.fn().mockImplementation(() => ({
+	MCPClient: vi.fn().mockImplementation((config: { serverName: string }) => ({
 		id: 'mcp-client-mock',
 		connect: mockConnect,
 		disconnect: mockDisconnect,
 		listTools: mockListTools,
+		// The real client has always had this; the mock did not, which went
+		// unnoticed while nothing on this path asked the client which server
+		// it was talking to. Admission does — a policy is per server name.
+		getState: () => ({ serverName: config.serverName }),
 	})),
 }))