@namzu/sdk 3.0.0 → 3.2.0

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 }),
 	})),
 }))
 

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'
@@ -215,7 +221,14 @@ export type { LocalSandboxProviderOptions } from './sandbox/index.js'
 // The classified provider-failure surface: a driver states what went wrong
 // first-hand, and the run boundary reads it to choose between a pause and a
 // failure.
-export {
+// `classifyProviderHttpStatus` and `bodySaysContextOverflow` are here
+// because a driver outside this repo needs the same classification the
+// first-party ones use — a status code alone does not separate a context
+// overflow from an ordinary bad request, and re-deriving that per driver
+// is how the classifications drift apart.
+export {
+	bodySaysContextOverflow,
+	classifyProviderHttpStatus,
 	isCallerAbortError,
 	isProviderRequestError,
 	providerHttpError,
@@ -254,6 +267,7 @@ export {
 	HybridExecutionContext,
 	LocalExecutionContext,
 	MCPClient,
+	MCPMethodNotFound,
 	MCPConnectorBridge,
 	MCPServer,
 	MCPToolDiscovery,
@@ -489,6 +503,7 @@ export {
 	lookupContextWindow,
 	resolveContextWindow,
 	createConversationManager,
+	createSlidingWindowReducer,
 	extractFromAssistantMessage,
 	extractFromToolCall,
 	extractFromToolResult,