@namzu/sdk 14.0.6 → 15.0.0

package/src/agents/__tests__/supervisor-coordinator-registration.test.ts

@@ -1,185 +0,0 @@
-import { mkdtemp } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { describe, expect, it, vi } from 'vitest'
-import { z } from 'zod'
-
-import { MockLLMProvider } from '../../provider/mock.js'
-import { ToolNameCollisionError, ToolRegistry } from '../../registry/tool/execute.js'
-import { defineTool } from '../../tools/defineTool.js'
-import { SupervisorAgent } from '../SupervisorAgent.js'
-
-/**
- * How the supervisor mounts its own coordinator tools.
- *
- * `runtimeToolOverrides` is this SDK's declared way for a host to decline a
- * kernel-mounted tool. It is honoured for the task tools and the advisory
- * tools inside `drainQuery`, and the supervisor forwards it there — but the
- * supervisor registered the coordinator tools BEFORE that call and
- * unconditionally, so `{ create_task: 'disabled' }` was obeyed everywhere
- * except the one surface a host would most want to decline.
- *
- * The second case is the collision: `ManagedRegistry` warns and overwrites, so
- * a host tool sharing a coordinator name vanished into a log line and the
- * model kept a `create_task` whose behaviour depended on registration order.
- */
-
-const HOST_TOOL_DESCRIPTION = 'a tool this host registered deliberately'
-
-function stubManager() {
-	return {
-		sendMessage: vi.fn(async () => ({ taskId: 'task_1', status: 'completed' })),
-		await: vi.fn(async () => undefined),
-		cancel: vi.fn(),
-		dispose: vi.fn(),
-		on: vi.fn(),
-		off: vi.fn(),
-	}
-}
-
-const hostTool = (name: string) =>
-	defineTool({
-		name,
-		description: HOST_TOOL_DESCRIPTION,
-		inputSchema: z.object({}),
-		category: 'custom',
-		permissions: [],
-		readOnly: true,
-		destructive: false,
-		concurrencySafe: true,
-		async execute() {
-			return { success: true as const, output: 'host tool ran' }
-		},
-	})
-
-async function runWith(options: {
-	hostTools?: string[]
-	runtimeToolOverrides?: Record<string, 'active' | 'deferred' | 'disabled'>
-	allowDelegation?: boolean
-}) {
-	const agent = new SupervisorAgent({
-		id: 'supervisor',
-		name: 'Supervisor',
-		version: '1',
-		category: 'test',
-		description: 'coordinates workers',
-	})
-
-	const provider = new MockLLMProvider({ turns: [{ text: 'nothing to delegate' }] })
-
-	const tools = new ToolRegistry()
-	for (const name of options.hostTools ?? []) tools.register(hostTool(name))
-
-	await agent.run(
-		{
-			messages: [{ role: 'user', content: 'go', timestamp: 1 }],
-			workingDirectory: await mkdtemp(join(tmpdir(), 'namzu-sup-reg-')),
-			...(options.runtimeToolOverrides
-				? { runtimeToolOverrides: options.runtimeToolOverrides }
-				: {}),
-		} as never,
-		{
-			provider,
-			agentIds: ['worker'],
-			...(options.allowDelegation !== undefined
-				? { allowDelegation: options.allowDelegation }
-				: {}),
-			agentManager: stubManager(),
-			tools,
-			systemPrompt: 'You coordinate.',
-			model: 'mock-model',
-			tokenBudget: 100_000,
-			timeoutMs: 30_000,
-			maxIterations: 2,
-			sessionId: 'ses_sup',
-			threadId: 'thd_sup',
-			projectId: 'prj_sup',
-			tenantId: 'tnt_sup',
-		} as never,
-	)
-
-	const advertised = provider.requests[0]?.tools ?? []
-	return {
-		names: new Set(advertised.map((t) => t.function.name)),
-		describedAs: (name: string) =>
-			advertised.find((t) => t.function.name === name)?.function.description ?? '',
-	}
-}
-
-describe('supervisor coordinator-tool registration', () => {
-	it('advertises create_task by default', async () => {
-		expect((await runWith({})).names).toContain('create_task')
-	})
-
-	it('does not advertise a coordinator tool the host disabled', async () => {
-		const { names } = await runWith({ runtimeToolOverrides: { create_task: 'disabled' } })
-
-		expect(names).not.toContain('create_task')
-		// Declining one coordinator tool must not decline the rest.
-		expect(names).toContain('agent_task_list')
-	})
-
-	it('leaves a host tool that shares no coordinator name alone', async () => {
-		const { names } = await runWith({ hostTools: ['host_only'] })
-
-		expect(names).toContain('host_only')
-		expect(names).toContain('create_task')
-	})
-
-	it('refuses to take a name the host already registered', async () => {
-		// Named and carrying the name, so a host can catch it narrowly rather
-		// than match on message text — the shape `DuplicateProviderError`
-		// already set in this repo.
-		await expect(runWith({ hostTools: ['create_task'] })).rejects.toThrow(ToolNameCollisionError)
-		await expect(runWith({ hostTools: ['create_task'] })).rejects.toThrow(
-			/runtimeToolOverrides: \{ "create_task": "disabled" \}/,
-		)
-	})
-
-	it('lets the host keep its own tool under that name by declining the coordinator one', async () => {
-		const { names, describedAs } = await runWith({
-			hostTools: ['create_task'],
-			runtimeToolOverrides: { create_task: 'disabled' },
-		})
-
-		expect(names).toContain('create_task')
-		expect(names).toContain('agent_task_list')
-		// The name surviving is not the assertion — WHOSE tool holds it is.
-		// Overwriting also leaves the name present, so a membership check
-		// alone passes against the very behaviour this replaces.
-		expect(describedAs('create_task')).toBe(HOST_TOOL_DESCRIPTION)
-	})
-})
-
-/**
- * The one hop between `SupervisorAgentConfig.allowDelegation` and the builder
- * that acts on it.
- *
- * These go through `SupervisorAgent` rather than calling the builder directly,
- * and that is the entire point. The builder has its own unit tests, and they
- * pass whether or not the supervisor actually forwards the flag — measured:
- * deleting the forward left the type-check clean and all 143 coordinator and
- * agent tests green, with the field settable, documented, and read by nobody.
- * That is the shape of a declaration this repository has had to go and delete
- * before, so it gets a test that fails when the road is cut.
- */
-describe('allowDelegation reaches the tool surface', () => {
-	it('withholds the delegation tools when the run declines to delegate', async () => {
-		const { names } = await runWith({ allowDelegation: false })
-
-		expect(names, 'the flag never reached buildCoordinatorTools').not.toContain('create_task')
-		expect(names).not.toContain('wait_for_task')
-		expect(names).not.toContain('cancel_task')
-	})
-
-	it('keeps the listing, so a non-delegating run can still see what is running', async () => {
-		expect((await runWith({ allowDelegation: false })).names).toContain('agent_task_list')
-	})
-
-	it('leaves an opting-in run exactly as it was', async () => {
-		const { names } = await runWith({ allowDelegation: true })
-
-		expect(names).toContain('create_task')
-		expect(names).toContain('agent_task_list')
-	})
-})

package/src/agents/__tests__/supervisor-hands-down-hitl.test.ts

@@ -1,131 +0,0 @@
-import { mkdtemp } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { describe, expect, it, vi } from 'vitest'
-
-import { MockLLMProvider } from '../../provider/mock.js'
-import { ToolRegistry } from '../../registry/tool/execute.js'
-import type { AgentTaskContext } from '../../types/agent/task.js'
-import type { ResumeHandler } from '../../types/hitl/index.js'
-import { SupervisorAgent } from '../SupervisorAgent.js'
-
-/**
- * The supervisor already handed its resume handler to its OWN run and its
- * own coordinator tools. It did not hand it to the spawn context, so the
- * two disagreed: the supervisor paused for a human, and every worker it
- * launched approved itself.
- *
- * This is the link a mutation run found untested — the previous version of
- * these tests drove `AgentManager` with a context built by hand, which is
- * not the path a host takes.
- */
-
-/** Captures the context the supervisor builds for its spawns. */
-function spyManager(): {
-	contexts: AgentTaskContext[]
-	manager: unknown
-} {
-	const contexts: AgentTaskContext[] = []
-	const manager = {
-		sendMessage: vi.fn(async (_options: unknown, context: AgentTaskContext) => {
-			contexts.push(context)
-			return {
-				taskId: 'task_1',
-				status: 'completed',
-				result: {
-					runId: 'run_child',
-					status: 'completed',
-					usage: { promptTokens: 1, completionTokens: 1, totalTokens: 2 },
-					cost: { totalCost: 0 },
-					iterations: 1,
-					durationMs: 1,
-					messages: [],
-					result: 'worker done',
-				},
-			}
-		}),
-		await: vi.fn(async () => undefined),
-		cancel: vi.fn(),
-		dispose: vi.fn(),
-		on: vi.fn(),
-		off: vi.fn(),
-	}
-	return { contexts, manager }
-}
-
-async function runSupervisor(resumeHandler?: ResumeHandler) {
-	const { contexts, manager } = spyManager()
-	const agent = new SupervisorAgent({
-		id: 'supervisor',
-		name: 'Supervisor',
-		version: '1',
-		category: 'test',
-		description: 'coordinates workers',
-	})
-
-	const provider = new MockLLMProvider({
-		turns: [
-			{
-				toolCalls: [
-					{
-						id: 'c1',
-						name: 'create_task',
-						rawArguments: JSON.stringify({
-							agent_id: 'worker',
-							prompt: 'do the thing',
-							description: 'a task',
-						}),
-					},
-				],
-			},
-			{ text: 'all done' },
-		],
-	})
-
-	await agent
-		.run(
-			{
-				messages: [{ role: 'user', content: 'go', timestamp: 1 }],
-				workingDirectory: await mkdtemp(join(tmpdir(), 'namzu-sup-')),
-			},
-			{
-				provider,
-				agentIds: ['worker'],
-				agentManager: manager,
-				tools: new ToolRegistry(),
-				systemPrompt: 'You coordinate.',
-				model: 'mock-model',
-				tokenBudget: 100_000,
-				timeoutMs: 30_000,
-				maxIterations: 4,
-				sessionId: 'ses_sup',
-				threadId: 'thd_sup',
-				projectId: 'prj_sup',
-				tenantId: 'tnt_sup',
-				...(resumeHandler ? { resumeHandler } : {}),
-			} as never,
-		)
-		.catch(() => undefined)
-
-	return contexts
-}
-
-describe('a supervisor hands its decision channel to the workers it launches', () => {
-	it('puts its own handler on the spawn context', async () => {
-		const handler = vi.fn(async () => ({ action: 'approve_tools' })) as unknown as ResumeHandler
-
-		const contexts = await runSupervisor(handler)
-
-		expect(contexts.length).toBeGreaterThan(0)
-		expect(contexts[0]?.resumeHandler).toBe(handler)
-	})
-
-	it('leaves the context without one when it has none itself', async () => {
-		const contexts = await runSupervisor()
-
-		expect(contexts.length).toBeGreaterThan(0)
-		// Absent still means the worker auto-approves, which is what every
-		// worker did before any of this.
-		expect(contexts[0]?.resumeHandler).toBeUndefined()
-	})
-})

package/src/agents/__tests__/supervisor-inbox-scope.test.ts

@@ -1,149 +0,0 @@
-import { mkdtemp } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { describe, expect, it } from 'vitest'
-import { z } from 'zod'
-
-import { MockLLMProvider } from '../../provider/mock.js'
-import { ToolNameCollisionError, ToolRegistry } from '../../registry/tool/execute.js'
-import { defineTool } from '../../tools/defineTool.js'
-import type { TaskGateway, TaskHandle } from '../../types/agent/gateway.js'
-import type { TaskId } from '../../types/ids/index.js'
-import { SupervisorAgent } from '../SupervisorAgent.js'
-
-/**
- * A gateway the HOST owns, which is the case that goes wrong.
- *
- * `SupervisorAgentConfig.gateway` is a first-class option, and a host that
- * built a gateway reuses it — across sequential runs, and across concurrent
- * ones. The supervisor attached a fresh `CompletionInbox` to it on every run
- * and never detached, so the subscription set only grew: three runs, three
- * live listeners, each still holding its own run's handles and each still
- * being handed every other run's completions.
- */
-class HostGateway implements TaskGateway {
-	readonly listeners = new Set<(h: TaskHandle) => void>()
-
-	async createTask(): Promise<TaskHandle> {
-		throw new Error('this test never launches')
-	}
-	async waitForTask(): Promise<TaskHandle> {
-		throw new Error('this test never waits')
-	}
-	async continueTask(): Promise<void> {}
-	cancelTask(): void {}
-	getTask(): TaskHandle | undefined {
-		return undefined
-	}
-	listTasks(): TaskHandle[] {
-		return []
-	}
-	onTaskCompleted(cb: (h: TaskHandle) => void): () => void {
-		this.listeners.add(cb)
-		return () => this.listeners.delete(cb)
-	}
-}
-
-/** A host tool whose name the coordinator surface also wants. */
-const collidingTool = defineTool({
-	name: 'create_task',
-	description: 'a tool this host registered under a coordinator name',
-	inputSchema: z.object({}),
-	category: 'custom',
-	permissions: [],
-	readOnly: true,
-	destructive: false,
-	concurrencySafe: true,
-	async execute() {
-		return { success: true as const, output: 'never runs' }
-	},
-})
-
-async function runOnce(
-	gateway: TaskGateway,
-	id: string,
-	options: { collide?: boolean } = {},
-): Promise<void> {
-	const agent = new SupervisorAgent({
-		id,
-		name: 'Supervisor',
-		version: '1',
-		category: 'test',
-		description: 'coordinates workers',
-	})
-
-	const tools = new ToolRegistry()
-	if (options.collide) tools.register(collidingTool)
-
-	await agent.run(
-		{
-			messages: [{ role: 'user', content: 'go', timestamp: 1 }],
-			workingDirectory: await mkdtemp(join(tmpdir(), 'namzu-inbox-scope-')),
-		} as never,
-		{
-			provider: new MockLLMProvider({ turns: [{ text: 'nothing to delegate' }] }),
-			agentIds: ['worker'],
-			gateway,
-			tools,
-			systemPrompt: 'You coordinate.',
-			model: 'mock-model',
-			tokenBudget: 100_000,
-			timeoutMs: 30_000,
-			maxIterations: 2,
-			sessionId: 'ses_scope',
-			threadId: 'thd_scope',
-			projectId: 'prj_scope',
-			tenantId: 'tnt_scope',
-		} as never,
-	)
-}
-
-describe('a supervisor releases the gateway it borrowed', () => {
-	it('leaves no listener behind, however many runs the host makes', async () => {
-		const gateway = new HostGateway()
-
-		for (let i = 0; i < 3; i++) {
-			await runOnce(gateway, `sup_${i}`)
-			expect(gateway.listeners.size, `run ${i + 1} left its completion listener attached`).toBe(0)
-		}
-	}, 60_000)
-
-	it('releases it when setup throws before the run ever starts', async () => {
-		// The reason it is a `finally` covering the whole body and not a line
-		// after `drainQuery`. A host whose tool shares a coordinator name gets
-		// `ToolNameCollisionError` from the registration loop — after the inbox
-		// attached — then fixes its config and runs again. A leak of one
-		// listener per run becomes one per ATTEMPT, and the attempts are what
-		// there are most of.
-		const gateway = new HostGateway()
-
-		await expect(runOnce(gateway, 'sup_collide', { collide: true })).rejects.toThrow(
-			ToolNameCollisionError,
-		)
-
-		expect(gateway.listeners.size, 'a run that threw left its listener attached').toBe(0)
-	}, 60_000)
-
-	it('never hands a completion to a run that did not launch it', async () => {
-		// Two supervisors, one gateway. The second run's inbox is gone by the
-		// time this fires, but the assertion that matters is the one above it:
-		// nothing is listening that should not be.
-		const gateway = new HostGateway()
-		await runOnce(gateway, 'sup_a')
-		await runOnce(gateway, 'sup_b')
-
-		let delivered = 0
-		for (const cb of gateway.listeners) {
-			delivered += 1
-			cb({
-				taskId: 'tsk_foreign' as TaskId,
-				agentId: 'worker',
-				state: 'completed',
-				createdAt: 0,
-				completedAt: 1,
-			} as TaskHandle)
-		}
-
-		expect(delivered).toBe(0)
-	}, 60_000)
-})

package/src/agents/__tests__/supervisor-ledger.test.ts

@@ -1,185 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import type { TaskHandle } from '../../types/agent/gateway.js'
-import type { AgentTaskResult, BaseAgentResult } from '../../types/agent/index.js'
-import type { RunId, TaskId } from '../../types/ids/index.js'
-import { countCompletedTasks, synthesizeTaskResults } from '../SupervisorAgent.js'
-
-const RUN_ID = 'run-supervisor' as RunId
-const NOW = 1_000_000
-
-function at(results: AgentTaskResult[], index: number): AgentTaskResult {
-	const entry = results[index]
-	if (!entry) {
-		throw new Error(`expected a task result at index ${index}, got ${results.length} results`)
-	}
-	return entry
-}
-
-function handle(overrides: Partial<TaskHandle> & Pick<TaskHandle, 'state'>): TaskHandle {
-	return {
-		taskId: 'task-1' as TaskId,
-		agentId: 'worker-1',
-		createdAt: NOW - 5_000,
-		...overrides,
-	}
-}
-
-function completedResult(): BaseAgentResult {
-	return {
-		runId: 'run-worker' as RunId,
-		status: 'completed',
-		usage: {
-			promptTokens: 10,
-			completionTokens: 20,
-			totalTokens: 30,
-			cachedTokens: 0,
-			cacheWriteTokens: 0,
-		},
-		cost: {
-			inputCostPer1M: 0,
-			outputCostPer1M: 0,
-			totalCost: 0,
-			cacheDiscount: 0,
-		},
-		iterations: 3,
-		durationMs: 4_200,
-		messages: [],
-		result: 'real worker output',
-	}
-}
-
-describe('supervisor ledger truthfulness', () => {
-	describe('synthesizeTaskResults', () => {
-		it('synthesizes a FAILED result when a handle has no result, regardless of state', () => {
-			// A worker that ended with no result is NOT a success even when the
-			// handle reports a terminal 'completed' state — this is the exact
-			// fabrication that made the supervisor claim "3 workers done" with
-			// empty outputs (observed in a live supervised run).
-			const results = synthesizeTaskResults(
-				[handle({ state: 'completed', result: undefined })],
-				RUN_ID,
-				NOW,
-			)
-
-			expect(results).toHaveLength(1)
-			expect(at(results, 0).result.status).toBe('failed')
-			expect(at(results, 0).result.status).not.toBe('completed')
-			expect(at(results, 0).result.runId).toBe(RUN_ID)
-			expect(at(results, 0).result.durationMs).toBe(NOW - (NOW - 5_000))
-		})
-
-		it('synthesizes a FAILED result for a genuinely failed handle', () => {
-			const results = synthesizeTaskResults(
-				[handle({ state: 'failed', result: undefined })],
-				RUN_ID,
-				NOW,
-			)
-
-			expect(at(results, 0).result.status).toBe('failed')
-		})
-
-		it('synthesizes a FAILED result for a canceled handle with no result', () => {
-			const results = synthesizeTaskResults(
-				[handle({ state: 'canceled', result: undefined })],
-				RUN_ID,
-				NOW,
-			)
-
-			expect(at(results, 0).result.status).toBe('failed')
-		})
-
-		it('preserves a present completed result verbatim (real workers unaffected)', () => {
-			const real = completedResult()
-			const results = synthesizeTaskResults(
-				[handle({ state: 'completed', result: real })],
-				RUN_ID,
-				NOW,
-			)
-
-			expect(at(results, 0).result).toBe(real)
-			expect(at(results, 0).result.status).toBe('completed')
-			expect(at(results, 0).result.result).toBe('real worker output')
-		})
-
-		it('preserves a present failed result verbatim', () => {
-			const failed: BaseAgentResult = { ...completedResult(), status: 'failed' }
-			const results = synthesizeTaskResults(
-				[handle({ state: 'failed', result: failed })],
-				RUN_ID,
-				NOW,
-			)
-
-			expect(at(results, 0).result).toBe(failed)
-			expect(at(results, 0).result.status).toBe('failed')
-		})
-	})
-
-	describe('countCompletedTasks', () => {
-		it('excludes an absent-result handle from completedTasks', () => {
-			const taskResults = synthesizeTaskResults(
-				[
-					handle({
-						taskId: 'task-a' as TaskId,
-						agentId: 'a',
-						state: 'completed',
-						result: undefined,
-					}),
-					handle({
-						taskId: 'task-b' as TaskId,
-						agentId: 'b',
-						state: 'completed',
-						result: completedResult(),
-					}),
-				],
-				RUN_ID,
-				NOW,
-			)
-
-			// Two handles, both with handle.state === 'completed', but only the
-			// one that actually produced a result counts.
-			expect(taskResults).toHaveLength(2)
-			expect(countCompletedTasks(taskResults)).toBe(1)
-		})
-
-		it('counts every present completed result', () => {
-			const taskResults = synthesizeTaskResults(
-				[
-					handle({
-						taskId: 'task-a' as TaskId,
-						agentId: 'a',
-						state: 'completed',
-						result: completedResult(),
-					}),
-					handle({
-						taskId: 'task-b' as TaskId,
-						agentId: 'b',
-						state: 'completed',
-						result: completedResult(),
-					}),
-				],
-				RUN_ID,
-				NOW,
-			)
-
-			expect(countCompletedTasks(taskResults)).toBe(2)
-		})
-
-		it('reports zero completed when no worker produced a result', () => {
-			const taskResults = synthesizeTaskResults(
-				[
-					handle({
-						taskId: 'task-a' as TaskId,
-						agentId: 'a',
-						state: 'completed',
-						result: undefined,
-					}),
-					handle({ taskId: 'task-b' as TaskId, agentId: 'b', state: 'running', result: undefined }),
-				],
-				RUN_ID,
-				NOW,
-			)
-
-			expect(countCompletedTasks(taskResults)).toBe(0)
-		})
-	})
-})