@namzu/sdk 3.1.0 → 3.3.0

package/src/manager/agent/__tests__/hitl-across-spawn.test.ts

@@ -0,0 +1,273 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { AgentRegistry } from '../../../registry/agent/definitions.js'
+import { DefaultCapacityValidator } from '../../../session/handoff/capacity.js'
+import { SessionSummaryMaterializer } from '../../../session/summary/materialize.js'
+import { WorkspaceBackendRegistry } from '../../../session/workspace/registry.js'
+import { InMemorySessionStore } from '../../../store/session/memory.js'
+import { InMemoryThreadStore } from '../../../store/thread/memory.js'
+import type { BaseAgentConfig, BaseAgentResult } from '../../../types/agent/base.js'
+import type { Agent } from '../../../types/agent/core.js'
+import type { AgentTaskContext, SendMessageOptions } from '../../../types/agent/task.js'
+import type { ResumeHandler } from '../../../types/hitl/index.js'
+import type { TenantId } from '../../../types/ids/index.js'
+import type { ActorRef } from '../../../types/session/actor.js'
+import { ThreadManager } from '../../thread/lifecycle.js'
+import { AgentManager } from '../lifecycle.js'
+
+/**
+ * A human's approval did not cross the spawn boundary.
+ *
+ * `BaseAgentConfig` carried no resume handler, and
+ * `SendMessageOptions.configOverrides` is a `Partial` of it — so a parent
+ * could not hand its channel to a child AT THE TYPE LEVEL. Every delegated
+ * child fell through to `autoApproveHandler` however carefully its parent
+ * had been wired.
+ *
+ * The cost is narrower than "no gate in children", and worth stating
+ * exactly. A `VerificationGate` DENY still bites inside a child, because
+ * denials are threaded into the executor and no later approval releases
+ * them. What was lost is the REVIEW tier — every call the gate left
+ * undecided reached the resume handler, and for a child that handler
+ * auto-approved. A host running "ask before acting" had a human review
+ * `write` at the top level and never see the same `write` one hop down.
+ */
+
+const tenant = 'tnt_hitl' as TenantId
+const actor = (tenantId: TenantId): ActorRef =>
+	({ kind: 'user', userId: 'usr_root', tenantId }) as unknown as ActorRef
+
+/** Records the config the child was actually handed. */
+function recordingAgent(seen: BaseAgentConfig[]): Agent<BaseAgentConfig, BaseAgentResult> {
+	return {
+		metadata: {
+			type: 'reactive',
+			id: 'worker',
+			name: 'Worker',
+			version: '1',
+			category: 'test',
+			description: 'records its config',
+			capabilities: {
+				supportsTools: true,
+				supportsStreaming: true,
+				supportsConcurrency: true,
+				supportsSubAgents: false,
+			},
+		},
+		async run(_input: unknown, config: BaseAgentConfig) {
+			seen.push(config)
+			return {
+				runId: 'run_child' as never,
+				status: 'completed',
+				usage: { promptTokens: 1, completionTokens: 1, totalTokens: 2 },
+				cost: { totalCost: 0 },
+				iterations: 1,
+				durationMs: 1,
+				messages: [],
+				result: 'done',
+			} as unknown as BaseAgentResult
+		},
+	} as unknown as Agent<BaseAgentConfig, BaseAgentResult>
+}
+
+async function harness() {
+	const seen: BaseAgentConfig[] = []
+	const store = new InMemorySessionStore()
+	const threadStore = new InMemoryThreadStore()
+	const threadManager = new ThreadManager({ threadStore, sessionStore: store })
+	const project = await store.createProject({ tenantId: tenant, name: 'p' }, tenant)
+	const thread = await threadStore.createThread({ projectId: project.id, title: 'hitl' }, tenant)
+	const parent = await store.createSession(
+		{ threadId: thread.id, projectId: project.id, currentActor: actor(tenant) },
+		tenant,
+	)
+	await store.updateSession({ ...parent, status: 'active' }, tenant)
+
+	const registry = new AgentRegistry()
+	const agent = recordingAgent(seen)
+	registry.register({
+		info: {
+			id: agent.metadata.id,
+			name: agent.metadata.name,
+			version: agent.metadata.version,
+			category: agent.metadata.category,
+			description: agent.metadata.description,
+			tools: [],
+			defaults: { model: 'test', tokenBudget: 1_000 },
+		},
+		typedAgent: agent,
+	} as never)
+
+	// A second registration WITH a configBuilder. That is the branch a real
+	// registered agent takes, and the first version of these tests covered
+	// only the bare one — so three mutations of the branch that matters
+	// survived untouched.
+	registry.register({
+		info: {
+			id: 'built-worker',
+			name: 'Built Worker',
+			version: '1',
+			category: 'test',
+			description: 'has a configBuilder',
+			tools: [],
+			defaults: { model: 'test', tokenBudget: 1_000 },
+		},
+		typedAgent: agent,
+		configBuilder: (opts: Record<string, unknown>) => ({
+			model: 'test',
+			tokenBudget: (opts.tokenBudget as number) ?? 1_000,
+			timeoutMs: (opts.timeoutMs as number) ?? 30_000,
+		}),
+	} as never)
+
+	const manager = new AgentManager(registry, undefined, {
+		sessionStore: store,
+		summaryMaterializer: new SessionSummaryMaterializer({
+			store,
+			generateSummaryId: () => 'sum_1' as never,
+		}),
+		workspaceRegistry: new WorkspaceBackendRegistry(),
+		capacity: new DefaultCapacityValidator(store),
+		threadManager,
+	})
+
+	const context = (over: Partial<AgentTaskContext> = {}): AgentTaskContext =>
+		({
+			parentRunId: 'run_parent',
+			parentAgentId: 'supervisor',
+			parentAbortController: new AbortController(),
+			depth: 0,
+			budgetTracker: { total: 100_000, remaining: 100_000 },
+			tenantId: tenant,
+			threadId: thread.id,
+			sessionId: parent.id,
+			projectId: project.id,
+			parentActor: actor(tenant),
+			...over,
+		}) as AgentTaskContext
+
+	const options = (over: Partial<SendMessageOptions> = {}): SendMessageOptions =>
+		({
+			agentId: 'worker',
+			input: { messages: [], workingDirectory: '/tmp' },
+			parentSessionId: parent.id,
+			tenantId: tenant,
+			projectId: project.id,
+			parentActor: actor(tenant),
+			...over,
+		}) as SendMessageOptions
+
+	const spawn = async (ctx: AgentTaskContext, opts?: Partial<SendMessageOptions>) => {
+		await manager.sendMessage(options(opts), ctx)
+		// The child runs detached; give it a tick to reach `agent.run`.
+		await new Promise((r) => setTimeout(r, 20))
+	}
+
+	return { seen, context, spawn }
+}
+
+describe('a child asks the same person its parent asks', () => {
+	it('inherits the parent channel', async () => {
+		const h = await harness()
+		const handler = vi.fn(async () => ({ action: 'approve_tools' })) as unknown as ResumeHandler
+
+		await h.spawn(h.context({ resumeHandler: handler }))
+
+		expect(h.seen[0]?.resumeHandler).toBe(handler)
+	})
+
+	it('leaves a child without one when the parent has none', async () => {
+		const h = await harness()
+
+		await h.spawn(h.context())
+
+		// Absent still means auto-approve, so a host that never wired a
+		// handler is unaffected by any of this.
+		expect(h.seen[0]?.resumeHandler).toBeUndefined()
+	})
+
+	it('lets an explicit override win, so one child can be given a different channel', async () => {
+		const h = await harness()
+		const parentHandler = vi.fn() as unknown as ResumeHandler
+		const childHandler = vi.fn() as unknown as ResumeHandler
+
+		await h.spawn(h.context({ resumeHandler: parentHandler }), {
+			configOverrides: { resumeHandler: childHandler },
+		})
+
+		expect(h.seen[0]?.resumeHandler).toBe(childHandler)
+	})
+
+	it('does not disturb the scoping the manager already stamps', async () => {
+		const h = await harness()
+		const handler = vi.fn() as unknown as ResumeHandler
+
+		await h.spawn(h.context({ resumeHandler: handler }))
+
+		// The handler is stamped beside the trace parent and the tenant
+		// triple, for the same reason: a configBuilder cannot be trusted to
+		// forward something it was never told about.
+		const config = h.seen[0]
+		expect(config?.tenantId).toBe(tenant)
+		expect(config?.depth).toBe(1)
+	})
+})
+
+describe('the type allows what the spawn path needs', () => {
+	it('accepts a handler through configOverrides', () => {
+		const handler = vi.fn() as unknown as ResumeHandler
+
+		// The assertion the whole change exists for. The field lived on
+		// `ReactiveAgentConfig`, not on `BaseAgentConfig`, and
+		// `configOverrides` is `Partial<BaseAgentConfig>` — so this line did
+		// not compile, which is why no runtime path could ever have carried
+		// one.
+		const overrides: Partial<BaseAgentConfig> = { resumeHandler: handler }
+
+		expect(overrides.resumeHandler).toBe(handler)
+	})
+})
+
+/**
+ * The same three questions against the branch a REAL registered agent
+ * takes. `configBuilder` is written by whoever registered the agent and
+ * cannot be trusted to forward something it was never told about, so the
+ * manager stamps the handler afterwards — exactly as it does the trace
+ * parent and the tenant triple.
+ *
+ * These exist because the first version of this file covered only the
+ * bare-config branch, and three mutations of this one survived unnoticed.
+ */
+describe('a child built by a configBuilder inherits it too', () => {
+	it('inherits the parent channel', async () => {
+		const h = await harness()
+		const handler = vi.fn() as unknown as ResumeHandler
+
+		await h.spawn(h.context({ resumeHandler: handler }), { agentId: 'built-worker' })
+
+		expect(h.seen[0]?.resumeHandler).toBe(handler)
+	})
+
+	it('is left without one when the parent has none', async () => {
+		const h = await harness()
+
+		await h.spawn(h.context(), { agentId: 'built-worker' })
+
+		// Nothing is invented. A host that never wired a handler still gets
+		// the auto-approving default, which is what every child got before.
+		expect(h.seen[0]?.resumeHandler).toBeUndefined()
+	})
+
+	it('lets an explicit override win over the parent', async () => {
+		const h = await harness()
+		const parentHandler = vi.fn() as unknown as ResumeHandler
+		const childHandler = vi.fn() as unknown as ResumeHandler
+
+		await h.spawn(h.context({ resumeHandler: parentHandler }), {
+			agentId: 'built-worker',
+			configOverrides: { resumeHandler: childHandler },
+		})
+
+		expect(h.seen[0]?.resumeHandler).toBe(childHandler)
+	})
+})

package/src/manager/agent/lifecycle.ts

@@ -273,6 +273,17 @@ export class AgentManager {
 			if (options.configOverrides?.parentSpan) {
 				childConfig.parentSpan = options.configOverrides.parentSpan
 			}
+			// Stamped for the same reason as the trace parent above: a
+			// `configBuilder` is written by whoever registered the agent and
+			// cannot be trusted to forward something it was never told about.
+			// An explicit override still wins, so a host can hand one child a
+			// different channel — or none.
+			//
+			// Without this every delegated child fell through to
+			// `autoApproveHandler`, so a host's "ask before acting" gate
+			// covered the top-level run and nothing it delegated.
+			const inheritedHandler = options.configOverrides?.resumeHandler ?? context.resumeHandler
+			if (inheritedHandler) childConfig.resumeHandler = inheritedHandler
 		} else {
 			this.log.warn('No configBuilder, using bare config', {
 				agentId: options.agentId,
@@ -292,6 +303,7 @@ export class AgentManager {
 				tenantId: context.tenantId,
 				parentRunId: context.parentRunId,
 				depth: context.depth + 1,
+				resumeHandler: options.configOverrides?.resumeHandler ?? context.resumeHandler,
 			}
 		}
 

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