@namzu/sdk 3.1.0 → 3.2.0

package/src/plugin/__tests__/mcp-admission.test.ts

@@ -0,0 +1,242 @@
+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 type { MCPToolDefinition } from '../../types/connector/index.js'
+
+/**
+ * A plugin's MCP server decided what entered the agent's tool registry.
+ *
+ * `MCPToolDiscovery` has held the admission boundary — a per-server
+ * allow/deny policy, and detection for a server whose tool set changes
+ * between discoveries — since it was written, and nothing outside its own
+ * tests ever constructed one. `PluginLifecycleManager.attachMCPServer`, the
+ * only code in the tree that connects a real MCP server, called
+ * `client.listTools()` and registered whatever came back.
+ *
+ * So least privilege was inverted at the one place it mattered: the remote
+ * side chose. Tools land as `deferred` and a run's `allowedTools` filters the
+ * model-visible catalogue, so this was not "arbitrary tools reach the model
+ * immediately" — but the check written for exactly this was not on the path.
+ */
+
+let advertised: MCPToolDefinition[] = []
+let clientCount = 0
+
+vi.mock('../../connector/mcp/client.js', () => ({
+	MCPClient: class {
+		readonly id: string
+		private serverName: string
+		constructor(config: { serverName: string }) {
+			this.id = `client_${clientCount++}`
+			this.serverName = config.serverName
+		}
+		async connect(): Promise<void> {}
+		async disconnect(): Promise<void> {}
+		isConnected(): boolean {
+			return true
+		}
+		getState() {
+			return { serverName: this.serverName }
+		}
+		async listTools(): Promise<MCPToolDefinition[]> {
+			return advertised
+		}
+	},
+}))
+
+function tool(name: string): MCPToolDefinition {
+	return { name, description: name, inputSchema: { type: 'object', properties: {} } }
+}
+
+const log = {
+	debug: vi.fn(),
+	info: vi.fn(),
+	warn: vi.fn(),
+	error: vi.fn(),
+	child: () => log,
+} as never
+
+let root: string
+
+interface Harness {
+	readonly registered: string[]
+	readonly manager: import('../lifecycle.js').PluginLifecycleManager
+	enable(name: string): Promise<import('../../types/ids/index.js').PluginId>
+}
+
+async function harness(config: Record<string, unknown> = {}): Promise<Harness> {
+	const { PluginLifecycleManager } = await import('../lifecycle.js')
+	const { PluginRegistry } = await import('../../registry/plugin/index.js')
+
+	const registered: string[] = []
+	const toolRegistry = {
+		register: (definition: { name: string }) => registered.push(definition.name),
+		unregister: () => undefined,
+		get: () => undefined,
+	} as never
+
+	const manager = new PluginLifecycleManager({
+		pluginRegistry: new PluginRegistry(),
+		toolRegistry,
+		log,
+		...config,
+	} as never)
+
+	return {
+		registered,
+		manager,
+		enable: async (name: string) => {
+			const dir = join(root, name)
+			await mkdir(dir, { recursive: true })
+			await writeFile(
+				join(dir, 'plugin.json'),
+				JSON.stringify({
+					name,
+					version: '1.0.0',
+					description: 'MCP server plugin fixture',
+					mcpServers: [{ name: 'files', command: 'node', args: ['server.js'] }],
+				}),
+				'utf-8',
+			)
+			const plugin = await manager.install(dir, 'project')
+			await manager.enable(plugin.id)
+			return plugin.id
+		},
+	}
+}
+
+beforeEach(async () => {
+	root = await mkdtemp(join(tmpdir(), 'namzu-mcp-admit-'))
+	clientCount = 0
+	advertised = [tool('read_file'), tool('write_file'), tool('delete_everything')]
+})
+
+afterEach(async () => {
+	await rm(root, { recursive: true, force: true })
+	vi.clearAllMocks()
+})
+
+describe('what a plugin server advertises is not what the registry gets', () => {
+	it('admits only the tools an allowlist names', async () => {
+		const h = await harness({ mcpToolPolicies: { files: { allow: ['read_file', 'write_file'] } } })
+
+		await h.enable('srv')
+
+		expect(h.registered.some((n) => n.endsWith('read_file'))).toBe(true)
+		expect(h.registered.some((n) => n.endsWith('write_file'))).toBe(true)
+		// The one the server offered and the host never agreed to.
+		expect(h.registered.some((n) => n.endsWith('delete_everything'))).toBe(false)
+	})
+
+	it('refuses a denied tool through the wildcard policy', async () => {
+		const h = await harness({ mcpToolPolicies: { '*': { deny: ['delete_everything'] } } })
+
+		await h.enable('srv')
+
+		expect(h.registered).toHaveLength(2)
+		expect(h.registered.some((n) => n.endsWith('delete_everything'))).toBe(false)
+	})
+
+	it('still admits everything when no policy is configured', async () => {
+		// Adding a boundary must not turn every existing host's working plugin
+		// into a broken one.
+		const h = await harness()
+
+		await h.enable('srv')
+
+		expect(h.registered).toHaveLength(3)
+	})
+
+	it('namespaces what it admits, exactly as before', async () => {
+		const h = await harness({ mcpToolPolicies: { files: { allow: ['read_file'] } } })
+
+		await h.enable('srv')
+
+		expect(h.registered[0]).toContain('mcp__files__read_file')
+	})
+})
+
+describe('a server that changes its tools between connections is reported', () => {
+	it('says nothing the first time, having nothing to compare against', async () => {
+		const onMCPToolDrift = vi.fn()
+		const h = await harness({ onMCPToolDrift })
+
+		await h.enable('srv')
+
+		expect(onMCPToolDrift).not.toHaveBeenCalled()
+	})
+
+	it('reports a tool the server grew after it was first approved', async () => {
+		const onMCPToolDrift = vi.fn()
+		const h = await harness({ onMCPToolDrift })
+		const first = await h.enable('srv-a')
+
+		// The rug pull: advertise something benign while a host is deciding,
+		// swap it afterwards. A NEW client connects to the SAME server, which
+		// is why the remembered set is keyed by server name — keyed by client
+		// id, as it was, every connection was its own first and this could
+		// never fire.
+		await h.manager.disable(first)
+		advertised = [...advertised, tool('exfiltrate')]
+		await h.enable('srv-b')
+
+		expect(onMCPToolDrift).toHaveBeenCalledTimes(1)
+		expect(onMCPToolDrift.mock.calls[0]?.[0]).toMatchObject({
+			serverName: 'files',
+			drift: { added: ['exfiltrate'] },
+		})
+	})
+
+	it('reports a tool whose shape changed under the same name', async () => {
+		const onMCPToolDrift = vi.fn()
+		const h = await harness({ onMCPToolDrift })
+		const first = await h.enable('srv-a')
+
+		await h.manager.disable(first)
+		// Same name, different input shape — the version a name-only check
+		// misses entirely.
+		advertised = [
+			{
+				name: 'read_file',
+				description: 'read a file',
+				inputSchema: { type: 'object', properties: { path: { type: 'string' } } },
+			},
+			tool('write_file'),
+			tool('delete_everything'),
+		]
+		await h.enable('srv-b')
+
+		expect(onMCPToolDrift).toHaveBeenCalledTimes(1)
+		expect(onMCPToolDrift.mock.calls[0]?.[0]).toMatchObject({ drift: { changed: ['read_file'] } })
+	})
+
+	it('says nothing when the server offers exactly what it offered before', async () => {
+		const onMCPToolDrift = vi.fn()
+		const h = await harness({ onMCPToolDrift })
+		const first = await h.enable('srv-a')
+
+		await h.manager.disable(first)
+		await h.enable('srv-b')
+
+		expect(onMCPToolDrift).not.toHaveBeenCalled()
+	})
+
+	it('compares what was ADMITTED, not what was advertised', async () => {
+		const onMCPToolDrift = vi.fn()
+		const h = await harness({
+			mcpToolPolicies: { files: { allow: ['read_file'] } },
+			onMCPToolDrift,
+		})
+		const first = await h.enable('srv-a')
+
+		await h.manager.disable(first)
+		// A tool the policy refuses either way. Reporting drift for it would
+		// train a host to ignore the warning that matters.
+		advertised = [...advertised, tool('another_denied_one')]
+		await h.enable('srv-b')
+
+		expect(onMCPToolDrift).not.toHaveBeenCalled()
+	})
+})

package/src/plugin/lifecycle.ts

@@ -2,6 +2,9 @@ import { join } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { mcpToolToToolDefinition } from '../connector/mcp/adapter.js'
 import { MCPClient } from '../connector/mcp/client.js'
+import { MCPToolDiscovery } from '../connector/mcp/discovery.js'
+import type { MCPToolDiscoveryOptions } from '../connector/mcp/discovery.js'
+import type { MCPToolPolicy } from '../connector/mcp/policy.js'
 import {
 	DEFAULT_HOOK_PRIORITY,
 	HOOK_TIMEOUT_MS,
@@ -37,6 +40,32 @@ export interface PluginLifecycleManagerConfig {
 	toolRegistry: ToolRegistryContract
 	log: Logger
 	hookTimeoutMs?: number
+
+	/**
+	 * What each MCP server a plugin brings is allowed to contribute, keyed by
+	 * server name. `'*'` covers every server not named explicitly.
+	 *
+	 * Absent admits everything, which is what this path did unconditionally
+	 * until now. `MCPToolDiscovery` has held this boundary — and the drift
+	 * detection below — since it was written, and nothing outside its own
+	 * tests ever constructed one: `attachMCPServer` called `listTools()`
+	 * directly and registered whatever came back. So the least-privilege
+	 * check existed, was tested, was exported, and was not on the path any
+	 * real MCP server takes.
+	 */
+	mcpToolPolicies?: Readonly<Record<string, MCPToolPolicy>>
+
+	/**
+	 * Called when a server's admitted tool set differs from the last time it
+	 * was discovered.
+	 *
+	 * Reported rather than blocked, for the reason `MCPToolDiscovery`
+	 * already gives: a development 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.
+	 */
+	onMCPToolDrift?: MCPToolDiscoveryOptions['onDrift']
 }
 
 export class PluginLifecycleManager {
@@ -55,12 +84,32 @@ export class PluginLifecycleManager {
 	private pluginContributions: Map<PluginId, PluginContributionRecord> = new Map()
 	private hookTimeoutMs: number
 	private log: Logger
+	/**
+	 * The admission boundary for everything a plugin's MCP servers advertise.
+	 *
+	 * One instance for the whole manager rather than one per plugin, and that
+	 * is the part that matters: the instance is what remembers each server's
+	 * previously admitted tool set, so a server that changes between one
+	 * plugin being disabled and the next being enabled is still noticed. A
+	 * per-plugin instance would forget on every teardown, which is precisely
+	 * the window a rug pull uses.
+	 *
+	 * Its client list is deliberately left empty — `discoverFrom` takes the
+	 * client directly, so registering it here would be bookkeeping nothing
+	 * reads.
+	 */
+	private mcpDiscovery: MCPToolDiscovery
 
 	constructor(config: PluginLifecycleManagerConfig) {
 		this.pluginRegistry = config.pluginRegistry
 		this.toolRegistry = config.toolRegistry
 		this.hookTimeoutMs = config.hookTimeoutMs ?? HOOK_TIMEOUT_MS
 		this.log = config.log.child({ component: 'PluginLifecycleManager' })
+		this.mcpDiscovery = new MCPToolDiscovery([], {
+			...(config.mcpToolPolicies ? { policies: config.mcpToolPolicies } : {}),
+			...(config.onMCPToolDrift ? { onDrift: config.onMCPToolDrift } : {}),
+			logger: this.log,
+		})
 	}
 
 	/**
@@ -257,7 +306,14 @@ export class PluginLifecycleManager {
 		await client.connect()
 		contributions.mcpClients.push(client)
 
-		const mcpTools = await client.listTools()
+		// Through the boundary, not around it. This used to call
+		// `client.listTools()` and register everything the server answered
+		// with, so the remote side decided what entered the agent's registry
+		// — least privilege inverted. `discoverFrom` applies the per-server
+		// allow/deny policy and reports a tool set that changed since the
+		// last discovery.
+		const discovered = await this.mcpDiscovery.discoverFrom(client)
+		const mcpTools = discovered.map((d) => d.tool)
 		for (const mcpTool of mcpTools) {
 			const baseDef = mcpToolToToolDefinition(mcpTool, client, config.name)
 			// Double-underscore between serverName and toolName so that e.g.

package/src/plugin/loader.ts

@@ -88,23 +88,77 @@ export function assertEnableable(manifest: PluginManifest): void {
 	)
 }
 
+/** Where a plugin came from. Project plugins ship with the repo; user plugins live in the home directory. */
+export type PluginScope = 'project' | 'user'
+
 /**
- * Discovers plugin directories from both project-level and user-level locations.
- * Returns categorized arrays of absolute paths.
+ * The discovery half of {@link PluginRuntimeConfig}.
+ *
+ * Structural rather than an import so this module keeps depending on nothing
+ * — a parsed `PluginRuntimeConfig` satisfies it as-is.
+ */
+export interface PluginDiscoveryOptions {
+	/** Whether the plugin runtime is on at all. `false` discovers nothing. */
+	readonly enabled?: boolean
+	/** Whether to scan for plugins. `false` discovers nothing. */
+	readonly autoDiscovery?: boolean
+	/** Which locations may be scanned. Absent means both. */
+	readonly allowedScopes?: readonly PluginScope[]
+}
+
+/**
+ * Find plugin directories, in the locations the caller permits.
+ *
+ * `allowedScopes` is a trust boundary, not a filter applied afterwards. A
+ * plugin is arbitrary code with hooks into tool execution, and the two scopes
+ * are not equally trusted: project plugins are reviewable in the repo the
+ * agent is working on, while user plugins come from a home directory the
+ * repo's reviewers never see. `['project']` is how a host says the second
+ * kind is not allowed to run here.
+ *
+ * It was previously declared and unread — `PluginRuntimeConfig` carried
+ * `enabled`, `autoDiscovery` and `allowedScopes`, nothing anywhere consulted
+ * any of them, and this function scanned both locations unconditionally. A
+ * host who set `allowedScopes: ['project']` got user plugins anyway, from a
+ * setting that reads exactly like a boundary.
+ *
+ * A disallowed scope is NOT SCANNED rather than scanned and dropped.
+ * Filtering after the fact still reads the directory, which is both pointless
+ * work and a small disclosure — the returned count would tell a caller how
+ * many plugins live somewhere they said they would not look.
+ *
+ * Passing nothing keeps the old behaviour: both scopes, no gate. Existing
+ * callers are unaffected, and a caller who opts in gets what the config says.
  */
 export async function discoverAllPluginDirs(
 	workingDirectory?: string,
+	options?: PluginDiscoveryOptions,
 ): Promise<{ project: string[]; user: string[] }> {
+	if (options?.enabled === false || options?.autoDiscovery === false) {
+		logger.debug('Plugin discovery skipped', {
+			enabled: options.enabled,
+			autoDiscovery: options.autoDiscovery,
+		})
+		return { project: [], user: [] }
+	}
+
+	const scopes = options?.allowedScopes
+	const mayScan = (scope: PluginScope): boolean => !scopes || scopes.includes(scope)
+
 	const projectDir = workingDirectory
 		? join(workingDirectory, PROJECT_PLUGIN_DIR)
 		: join(process.cwd(), PROJECT_PLUGIN_DIR)
 	const userDir = join(homedir(), USER_PLUGIN_DIR)
 
-	const [project, user] = await Promise.all([discoverPlugins(projectDir), discoverPlugins(userDir)])
+	const [project, user] = await Promise.all([
+		mayScan('project') ? discoverPlugins(projectDir) : Promise.resolve([]),
+		mayScan('user') ? discoverPlugins(userDir) : Promise.resolve([]),
+	])
 
 	logger.debug('Plugin discovery complete', {
 		projectCount: project.length,
 		userCount: user.length,
+		...(scopes ? { allowedScopes: scopes } : {}),
 	})
 
 	return { project, user }

package/src/public-runtime.ts

@@ -89,6 +89,12 @@ export type { ToolGrantKeys } from './runtime/query/tool-grants.js'
 export { toWireRunStatus } from './contracts/run-status.js'
 // Durable run state: the snapshot a different process picks a run up from.
 export { captureRunState, loadRunState } from './runtime/query/run-state.js'
+// …and the driver that joins the snapshot back to a running loop. Without
+// it every host wrote the same wiring, and in practice none did.
+export { resumeRun } from './runtime/query/resume-run.js'
+export type { ResumeOutcome, ResumeRunParams } from './runtime/query/resume-run.js'
+// The scope type was internal, so a host calling `loadRunState` could not
+// name the argument it had to construct.
 export type { RunStateScope } from './runtime/query/run-state.js'
 export { prepareReplayState } from './runtime/query/replay/prepare.js'
 export { listCheckpoints } from './runtime/query/replay/list.js'
@@ -261,6 +267,7 @@ export {
 	HybridExecutionContext,
 	LocalExecutionContext,
 	MCPClient,
+	MCPMethodNotFound,
 	MCPConnectorBridge,
 	MCPServer,
 	MCPToolDiscovery,
@@ -496,6 +503,7 @@ export {
 	lookupContextWindow,
 	resolveContextWindow,
 	createConversationManager,
+	createSlidingWindowReducer,
 	extractFromAssistantMessage,
 	extractFromToolCall,
 	extractFromToolResult,

package/src/public-types.ts

@@ -134,6 +134,7 @@ export type {
 	HybridExecutionContextOptions,
 	LocalExecutionContextOptions,
 	MCPServerResourceProvider,
+	MCPServerPromptProvider,
 	MCPServerToolProvider,
 	RemoteExecutionContextOptions,
 	TenantConnectorManagerConfig,
@@ -157,6 +158,10 @@ export type { ToolCallContext } from './verification/index.js'
 export type { DiskSessionStoreConfig, LinkageView } from './store/session/index.js'
 
 export type {
+	ContextReducer,
+	ContextReduction,
+	ContextReductionReason,
+	SlidingWindowOptions,
 	ConversationManager,
 	CompactionStrategy,
 	DanglingResult,

package/src/rag/__tests__/namespace-isolation.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from 'vitest'
+
+import type { EmbeddingProvider, TenantScope } from '../../types/rag/index.js'
+import { DefaultIngestionPipeline } from '../ingestion.js'
+import { DefaultRetriever } from '../retriever.js'
+import { InMemoryVectorStore } from '../vector-store.js'
+
+/**
+ * `TenantScope.namespace` and `KnowledgeBaseConfig.namespace` were declared
+ * from the start and neither reached storage. Ingestion copied
+ * `scope.tenantId` onto every chunk and dropped the namespace; the store
+ * filtered on tenant alone. So a partition a host asked for did not exist,
+ * and every namespace in a tenant saw every other one's documents.
+ */
+
+/** Deterministic and content-derived, so similarity is stable across runs. */
+const embedder: EmbeddingProvider = {
+	async embed(texts: string[]) {
+		return texts.map((t) => [t.length % 7, t.charCodeAt(0) % 5, 1])
+	},
+	async embedQuery(text: string) {
+		return [text.length % 7, text.charCodeAt(0) % 5, 1]
+	},
+	dimensions: 3,
+	model: 'test-embedder',
+	id: 'test-embedder',
+}
+
+const tenant = 'tnt_one' as TenantScope['tenantId']
+
+function scope(namespace?: string): TenantScope {
+	return { tenantId: tenant, ...(namespace !== undefined ? { namespace } : {}) }
+}
+
+async function seed() {
+	const store = new InMemoryVectorStore()
+	const ingestion = new DefaultIngestionPipeline(store, embedder)
+	const kb = 'kb_one' as never
+
+	await ingestion.ingest('alpha partition content', {}, scope('alpha'), kb)
+	await ingestion.ingest('beta partition content', {}, scope('beta'), kb)
+	await ingestion.ingest('default partition content', {}, scope(), kb)
+
+	return { store, retriever: new DefaultRetriever(store, embedder), kb }
+}
+
+const texts = (r: { chunks: { chunk: { content: string } }[] }) =>
+	r.chunks.map((c) => c.chunk.content)
+
+describe('a namespace partitions what a query can see', () => {
+	it('returns only its own partition', async () => {
+		const { retriever, kb } = await seed()
+
+		const found = await retriever.retrieve({ text: 'partition content' }, scope('alpha'), kb)
+
+		expect(texts(found)).toEqual(['alpha partition content'])
+	})
+
+	it('does not leak the other partition', async () => {
+		const { retriever, kb } = await seed()
+
+		const found = await retriever.retrieve({ text: 'partition content' }, scope('beta'), kb)
+
+		expect(texts(found).join()).not.toContain('alpha')
+	})
+
+	it('treats an absent namespace as the default partition, not as no filter', async () => {
+		const { retriever, kb } = await seed()
+
+		const found = await retriever.retrieve({ text: 'partition content' }, scope(), kb)
+
+		// The whole point. Reading absence as "no filter" is how the boundary
+		// leaks: a caller who never asked for a namespace would see every
+		// namespaced chunk in the tenant.
+		expect(texts(found)).toEqual(['default partition content'])
+	})
+
+	it('keeps tenants apart as it always did', async () => {
+		const { retriever, kb } = await seed()
+
+		const found = await retriever.retrieve(
+			{ text: 'partition content' },
+			{
+				tenantId: 'tnt_other' as TenantScope['tenantId'],
+				namespace: 'alpha',
+			},
+			kb,
+		)
+
+		expect(found.chunks).toEqual([])
+	})
+
+	it('stamps the namespace onto the chunk at ingest', async () => {
+		const { store } = await seed()
+
+		const results = await store.search({
+			embedding: await embedder.embedQuery('partition content'),
+			topK: 10,
+			tenantId: tenant,
+			namespace: 'alpha',
+		})
+
+		// Ingest is where it has to land — filtering at search against a value
+		// nothing writes returns zero rows, and "no results" reads as "nothing
+		// matched" rather than "this scope was never stored".
+		expect(results.every((r) => r.chunk.content.startsWith('alpha'))).toBe(true)
+		expect(results.length).toBeGreaterThan(0)
+	})
+})

package/src/rag/ingestion.ts

@@ -48,6 +48,7 @@ export class DefaultIngestionPipeline implements IngestionPipeline {
 			documentId,
 			knowledgeBaseId,
 			tenantId: scope.tenantId,
+			...(scope.namespace !== undefined ? { namespace: scope.namespace } : {}),
 			content: cc.content,
 			index: cc.index,
 			tokenCount: estimateTokens(cc.content),

package/src/rag/retriever.ts

@@ -76,6 +76,7 @@ export class DefaultRetriever implements Retriever {
 			embedding,
 			topK: config.topK,
 			tenantId: scope.tenantId,
+			...(scope.namespace !== undefined ? { namespace: scope.namespace } : {}),
 			knowledgeBaseId,
 			minScore: config.minScore,
 		})
@@ -92,6 +93,7 @@ export class DefaultRetriever implements Retriever {
 			embedding,
 			topK: config.topK * 2,
 			tenantId: scope.tenantId,
+			...(scope.namespace !== undefined ? { namespace: scope.namespace } : {}),
 			knowledgeBaseId,
 			minScore: 0,
 		})

package/src/rag/vector-store.ts

@@ -20,6 +20,11 @@ export class InMemoryVectorStore implements VectorStore {
 
 		for (const chunk of this.chunks.values()) {
 			if (chunk.tenantId !== query.tenantId) continue
+			// Equality INCLUDING absence: an omitted namespace is the default
+			// partition, not the absence of a filter. Treating it as no filter
+			// is how the boundary leaks — a caller who never asked for a
+			// namespace would see every namespaced chunk in the tenant.
+			if (chunk.namespace !== query.namespace) continue
 			if (query.knowledgeBaseId && chunk.knowledgeBaseId !== query.knowledgeBaseId) continue
 			if (!chunk.embedding) continue