@namzu/sdk 7.0.0 → 9.0.0

package/src/agents/SupervisorAgent.ts

@@ -159,7 +159,14 @@ export class SupervisorAgent extends AbstractAgent<SupervisorAgentConfig, Superv
 				projectId,
 				parentActor,
 			}
-			gateway = new LocalTaskGateway(config.agentManager, taskContext, listener, input)
+			// The only hop between the config and the gateway's policy. Omit it
+			// and the field is settable, documented, and read by nothing —
+			// which is exactly the state it was in before.
+			gateway = new LocalTaskGateway(config.agentManager, taskContext, listener, input, {
+				...(config.siblingFailurePolicy
+					? { siblingFailurePolicy: config.siblingFailurePolicy }
+					: {}),
+			})
 		} else {
 			throw new Error("SupervisorAgentConfig requires either 'gateway' or 'agentManager'")
 		}
@@ -185,181 +192,196 @@ export class SupervisorAgent extends AbstractAgent<SupervisorAgentConfig, Superv
 		const completionInbox = new CompletionInbox()
 		completionInbox.attach(gateway)
 
-		const coordinatorToolDefs = buildCoordinatorTools({
-			gateway,
-			completionInbox,
-			workingDirectory: input.workingDirectory,
-			runtimeContext: input.runtimeContext,
-			allowedAgentIds: config.agentIds,
-			// The only hop between the config and the decision. Omit it and
-			// everything still compiles: the field is settable, documented, and
-			// read by nothing — which is the shape of a declaration this repo
-			// has had to go and delete before.
-			allowDelegation: config.allowDelegation,
-			taskStore: input.taskStore,
-			runId,
-			getPlanManager: () => planManagerRef,
-			onTaskLaunched: (agentTaskId, meta) => {
-				launchedTasks.set(agentTaskId, meta)
-			},
-			// With a resume handler present the coordinator surface gains
-			// ask_user_question — the model can park the run on a question
-			// routed through the same HITL channel as plan approvals.
-			...(config.resumeHandler ? { resumeHandler: config.resumeHandler } : {}),
-			questionParks,
-			pendingAnswers,
-		})
+		// From here to the return in a try/finally, so the listener is released
+		// on every way out. The registration loop below can throw
+		// ToolNameCollisionError, and a host that hits that fixes its config and
+		// runs again — which is how a leak of one listener per run becomes a leak
+		// of one per ATTEMPT.
+		try {
+			const coordinatorToolDefs = buildCoordinatorTools({
+				gateway,
+				completionInbox,
+				workingDirectory: input.workingDirectory,
+				runtimeContext: input.runtimeContext,
+				allowedAgentIds: config.agentIds,
+				// The only hop between the config and the decision. Omit it and
+				// everything still compiles: the field is settable, documented, and
+				// read by nothing — which is the shape of a declaration this repo
+				// has had to go and delete before.
+				allowDelegation: config.allowDelegation,
+				taskStore: input.taskStore,
+				runId,
+				getPlanManager: () => planManagerRef,
+				onTaskLaunched: (agentTaskId, meta) => {
+					launchedTasks.set(agentTaskId, meta)
+				},
+				// With a resume handler present the coordinator surface gains
+				// ask_user_question — the model can park the run on a question
+				// routed through the same HITL channel as plan approvals.
+				...(config.resumeHandler ? { resumeHandler: config.resumeHandler } : {}),
+				questionParks,
+				pendingAnswers,
+			})
 
-		const tools = new ToolRegistry()
-		if (config.tools) {
-			for (const tool of config.tools.getAll()) {
-				tools.register(tool, config.tools.getAvailability(tool.name))
+			const tools = new ToolRegistry()
+			if (config.tools) {
+				for (const tool of config.tools.getAll()) {
+					tools.register(tool, config.tools.getAvailability(tool.name))
+				}
 			}
-		}
-		// Registered the way every other kernel-mounted tool in this SDK is
-		// registered: honouring `runtimeToolOverrides`, and refusing to take a
-		// name the host already used.
-		//
-		// Both halves were missing here and nowhere else. `runtimeToolOverrides`
-		// is declared on `AgentInput`, is forwarded into this very `drainQuery`
-		// call below, and is consulted for the task tools and for the advisory
-		// tools — but the coordinator tools were registered before that and
-		// unconditionally, so `{ create_task: 'disabled' }` was honoured
-		// everywhere except the one surface a host would most want to decline.
-		// A run that must not delegate had prompt text and a gateway refusal as
-		// its only defences.
-		//
-		// Collision REFUSES rather than overwrites, and the principle is
-		// complete mediation rather than fail-safe defaults: "proposals to gain
-		// performance by remembering the result of an authority check [must] be
-		// examined skeptically. If a change in authority occurs, such remembered
-		// results must be systematically updated" (Saltzer & Schroeder 1975,
-		// §I.A.3(c)). A registry entry is a remembered binding of a name to an
-		// authority, and a later write that rebinds the name leaves every
-		// decision made about the old binding stale.
-		//
-		// The counter-argument is that today the host's tool merely loses
-		// quietly and the run still works, so six reserved names is a real cost
-		// on a name a consumer may have chosen long ago. It does not hold,
-		// because "loses quietly" is not what happens. `registerOne` ends with
-		// `availability.set(id, state)` and this call passes no state, so a tool
-		// the host registered `deferred` or `suspended` is silently PROMOTED to
-		// active under someone else's implementation; and because the store is a
-		// Map, the replacement inherits the host's insertion position in the
-		// prompt-cache prefix. That is a different authorization surface, not a
-		// lost registration. CWE-390 is the shape `ManagedRegistry` has here —
-		// detection of an error condition without action — and CWE-694's own
-		// mitigation is nearly this fix: do not operate any resource with a
-		// non-unique identifier, and report the error.
-		//
-		// Refusing is also what the peer set does. One runtime's registry
-		// primitive throws on both duplicate and reserved names; another refuses
-		// its injected delegation name in a pre-flight that tells the author to
-		// rename. Closer to home, `ProviderRegistry.register` already throws
-		// unless the caller passes `{ replace: true }` — declared intent is what
-		// separates a legitimate replacement from an accidental one, and no such
-		// intent is expressible here.
-		const overrides = input.runtimeToolOverrides
-		for (const tool of coordinatorToolDefs) {
-			const override = overrides?.[tool.name]
-			if (override === 'disabled') continue
-			if (config.tools?.has(tool.name)) {
-				throw new ToolNameCollisionError(tool.name, 'the supervisor coordinator surface')
+			// Registered the way every other kernel-mounted tool in this SDK is
+			// registered: honouring `runtimeToolOverrides`, and refusing to take a
+			// name the host already used.
+			//
+			// Both halves were missing here and nowhere else. `runtimeToolOverrides`
+			// is declared on `AgentInput`, is forwarded into this very `drainQuery`
+			// call below, and is consulted for the task tools and for the advisory
+			// tools — but the coordinator tools were registered before that and
+			// unconditionally, so `{ create_task: 'disabled' }` was honoured
+			// everywhere except the one surface a host would most want to decline.
+			// A run that must not delegate had prompt text and a gateway refusal as
+			// its only defences.
+			//
+			// Collision REFUSES rather than overwrites, and the principle is
+			// complete mediation rather than fail-safe defaults: "proposals to gain
+			// performance by remembering the result of an authority check [must] be
+			// examined skeptically. If a change in authority occurs, such remembered
+			// results must be systematically updated" (Saltzer & Schroeder 1975,
+			// §I.A.3(c)). A registry entry is a remembered binding of a name to an
+			// authority, and a later write that rebinds the name leaves every
+			// decision made about the old binding stale.
+			//
+			// The counter-argument is that today the host's tool merely loses
+			// quietly and the run still works, so six reserved names is a real cost
+			// on a name a consumer may have chosen long ago. It does not hold,
+			// because "loses quietly" is not what happens. `registerOne` ends with
+			// `availability.set(id, state)` and this call passes no state, so a tool
+			// the host registered `deferred` or `suspended` is silently PROMOTED to
+			// active under someone else's implementation; and because the store is a
+			// Map, the replacement inherits the host's insertion position in the
+			// prompt-cache prefix. That is a different authorization surface, not a
+			// lost registration. CWE-390 is the shape `ManagedRegistry` has here —
+			// detection of an error condition without action — and CWE-694's own
+			// mitigation is nearly this fix: do not operate any resource with a
+			// non-unique identifier, and report the error.
+			//
+			// Refusing is also what the peer set does. One runtime's registry
+			// primitive throws on both duplicate and reserved names; another refuses
+			// its injected delegation name in a pre-flight that tells the author to
+			// rename. Closer to home, `ProviderRegistry.register` already throws
+			// unless the caller passes `{ replace: true }` — declared intent is what
+			// separates a legitimate replacement from an accidental one, and no such
+			// intent is expressible here.
+			const overrides = input.runtimeToolOverrides
+			for (const tool of coordinatorToolDefs) {
+				const override = overrides?.[tool.name]
+				if (override === 'disabled') continue
+				if (config.tools?.has(tool.name)) {
+					throw new ToolNameCollisionError(tool.name, 'the supervisor coordinator surface')
+				}
+				tools.register(tool, override ?? 'active')
 			}
-			tools.register(tool, override ?? 'active')
-		}
 
-		const childInvocationState = deriveChildState(
-			config.invocationState ?? { tenantId },
-			this.metadata.id,
-		)
+			const childInvocationState = deriveChildState(
+				config.invocationState ?? { tenantId },
+				this.metadata.id,
+			)
 
-		const run = await drainQuery(
-			{
-				systemPrompt: config.systemPrompt,
-				skills: config.skills,
-				provider: config.provider,
-				tools,
-				runConfig: {
-					model: config.model,
-					tokenBudget: config.tokenBudget,
-					timeoutMs: config.timeoutMs,
-					maxIterations: config.maxIterations,
-					temperature: config.temperature,
-					env: config.env,
-					// See ReactiveAgent: a hand-listed literal drops what nobody
-					// remembered to add, and reports nothing when it does.
-					...(config.thinking ? { thinking: config.thinking } : {}),
-					...(config.effort ? { effort: config.effort } : {}),
-				},
-				questionParks,
-				pendingAnswers,
-				agentId: this.metadata.id,
-				agentName: this.metadata.name,
-				workingDirectory: input.workingDirectory,
-				messages: input.messages,
-				signal: input.signal,
-				sessionId,
-				threadId,
-				projectId,
-				tenantId,
-				runId,
-				parentRunId: config.parentRunId,
-				depth: config.depth,
-				contextLevel: 'full',
-				onContextCreated: ({ planManager }) => {
-					planManagerRef = planManager
+			const run = await drainQuery(
+				{
+					systemPrompt: config.systemPrompt,
+					skills: config.skills,
+					provider: config.provider,
+					tools,
+					runConfig: {
+						model: config.model,
+						tokenBudget: config.tokenBudget,
+						timeoutMs: config.timeoutMs,
+						maxIterations: config.maxIterations,
+						temperature: config.temperature,
+						env: config.env,
+						// See ReactiveAgent: a hand-listed literal drops what nobody
+						// remembered to add, and reports nothing when it does.
+						...(config.thinking ? { thinking: config.thinking } : {}),
+						...(config.effort ? { effort: config.effort } : {}),
+					},
+					questionParks,
+					pendingAnswers,
+					// How wide a fan-out actually runs. Absent leaves the kernel
+					// default — the same forwarding ReactiveAgent has always done,
+					// missing from the one agent whose job is delegation.
+					...(config.maxToolConcurrency !== undefined
+						? { maxToolConcurrency: config.maxToolConcurrency }
+						: {}),
+					agentId: this.metadata.id,
+					agentName: this.metadata.name,
+					workingDirectory: input.workingDirectory,
+					messages: input.messages,
+					signal: input.signal,
+					sessionId,
+					threadId,
+					projectId,
+					tenantId,
+					runId,
+					parentRunId: config.parentRunId,
+					depth: config.depth,
+					contextLevel: 'full',
+					onContextCreated: ({ planManager }) => {
+						planManagerRef = planManager
+					},
+					taskStore: input.taskStore,
+					runtimeToolOverrides: input.runtimeToolOverrides,
+					runtimeContext: input.runtimeContext,
+					taskGateway: gateway,
+					completionInbox,
+					launchedTasks,
+					advisory: config.advisory,
+					invocationState: childInvocationState,
+					// HITL surface: forward optional review-time hooks so hosts can
+					// run "Ask before acting" supervisors instead of the default
+					// auto-approve. drainQuery falls back to autoApproveHandler
+					// when resumeHandler is omitted (= same behaviour as before).
+					...(config.resumeHandler ? { resumeHandler: config.resumeHandler } : {}),
+					// Forwarded for the same reason the handler is. A capability the
+					// kernel honours in `drainQuery` but that never reaches the
+					// surface a host actually constructs is a capability nobody can
+					// use — which is the shape of defect this file has already been
+					// corrected for twice.
+					...(config.steering ? { steering: config.steering } : {}),
+					...(config.verificationGate ? { verificationGate: config.verificationGate } : {}),
+					...(config.sandboxProvider ? { sandboxProvider: config.sandboxProvider } : {}),
+					// Working-memory / compaction seam (optional; absent => unchanged
+					// run path, byte-identical for every existing consumer).
+					...(config.compactionConfig ? { compactionConfig: config.compactionConfig } : {}),
+					...(config.workingMemoryProvider
+						? { workingMemoryProvider: config.workingMemoryProvider }
+						: {}),
 				},
-				taskStore: input.taskStore,
-				runtimeToolOverrides: input.runtimeToolOverrides,
-				runtimeContext: input.runtimeContext,
-				taskGateway: gateway,
-				completionInbox,
-				launchedTasks,
-				advisory: config.advisory,
-				invocationState: childInvocationState,
-				// HITL surface: forward optional review-time hooks so hosts can
-				// run "Ask before acting" supervisors instead of the default
-				// auto-approve. drainQuery falls back to autoApproveHandler
-				// when resumeHandler is omitted (= same behaviour as before).
-				...(config.resumeHandler ? { resumeHandler: config.resumeHandler } : {}),
-				// Forwarded for the same reason the handler is. A capability the
-				// kernel honours in `drainQuery` but that never reaches the
-				// surface a host actually constructs is a capability nobody can
-				// use — which is the shape of defect this file has already been
-				// corrected for twice.
-				...(config.steering ? { steering: config.steering } : {}),
-				...(config.verificationGate ? { verificationGate: config.verificationGate } : {}),
-				...(config.sandboxProvider ? { sandboxProvider: config.sandboxProvider } : {}),
-				// Working-memory / compaction seam (optional; absent => unchanged
-				// run path, byte-identical for every existing consumer).
-				...(config.compactionConfig ? { compactionConfig: config.compactionConfig } : {}),
-				...(config.workingMemoryProvider
-					? { workingMemoryProvider: config.workingMemoryProvider }
-					: {}),
-			},
-			listener,
-		)
+				listener,
+			)
 
-		const taskHandles = gateway.listTasks()
-		const taskResults = synthesizeTaskResults(taskHandles, runId)
+			const taskHandles = gateway.listTasks()
+			const taskResults = synthesizeTaskResults(taskHandles, runId)
 
-		const completedTasks = countCompletedTasks(taskResults)
+			const completedTasks = countCompletedTasks(taskResults)
 
-		return {
-			runId: run.id,
-			status: run.status === 'completed' ? 'completed' : 'failed',
-			stopReason: run.stopReason,
-			usage: run.tokenUsage,
-			cost: run.costInfo,
-			iterations: run.currentIteration,
-			durationMs: Date.now() - startTime,
-			messages: run.messages,
-			result: run.result,
-			lastError: run.lastError,
-			taskResults,
-			completedTasks,
-			totalTasks: taskResults.length,
+			return {
+				runId: run.id,
+				status: run.status === 'completed' ? 'completed' : 'failed',
+				stopReason: run.stopReason,
+				usage: run.tokenUsage,
+				cost: run.costInfo,
+				iterations: run.currentIteration,
+				durationMs: Date.now() - startTime,
+				messages: run.messages,
+				result: run.result,
+				lastError: run.lastError,
+				taskResults,
+				completedTasks,
+				totalTasks: taskResults.length,
+			}
+		} finally {
+			completionInbox.close()
 		}
 	}
 }

package/src/agents/__tests__/a-policy-nobody-can-select.test.ts

@@ -0,0 +1,202 @@
+import { mkdtemp } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+import { MockLLMProvider, registerMock } from '../../provider/index.js'
+import { ToolRegistry } from '../../registry/index.js'
+import type { Agent } from '../../types/agent/core.js'
+import type { SiblingFailurePolicy } from '../../types/agent/gateway.js'
+import type { AgentManagerContract } from '../../types/agent/manager.js'
+import type {
+	AgentTask,
+	AgentTaskContext,
+	AgentTaskState,
+	SendMessageOptions,
+} from '../../types/agent/task.js'
+import type { RunId, TaskId } from '../../types/ids/index.js'
+import { SupervisorAgent } from '../SupervisorAgent.js'
+
+/**
+ * `'cancel-siblings'` was unreachable from every entry point.
+ *
+ * `LocalTaskGateway` has honoured the policy since it was written and the
+ * cancellation machinery behind it is complete — but the policy was the fifth
+ * constructor argument of a gateway the supervisor builds itself, and the
+ * supervisor passed four. So every host in existence ran `'continue'`, and the
+ * only way to reach the other value was to construct the gateway by hand and
+ * hand it in through `config.gateway`. A policy nobody can select is not a
+ * policy, and the tests it had all constructed the gateway directly, so they
+ * passed while nothing upstream could turn it on.
+ *
+ * The assertion is deliberately the cancellation itself. Asserting that the run
+ * completed would pass with the forwarding deleted — a fan-out under
+ * `'continue'` completes too — and prove nothing.
+ */
+
+registerMock()
+
+const FAILING = 'doomed' as const
+const SLOW = 'patient' as const
+
+/**
+ * A manager whose slow child only settles when someone cancels it — which is
+ * what an abort actually does, and what lets this run terminate at all.
+ */
+class FanOutManager implements AgentManagerContract {
+	readonly cancelled: TaskId[] = []
+	private readonly tasks = new Map<TaskId, AgentTask>()
+	private releaseSlow?: () => void
+	private readonly slowSettled = new Promise<void>((resolve) => {
+		this.releaseSlow = resolve
+	})
+	private markLaunched?: () => void
+	/**
+	 * The doomed child does not settle until BOTH have launched.
+	 *
+	 * Without this the test is a race it usually wins: the sibling policy only
+	 * cancels tasks the gateway is already tracking, so if the failure lands
+	 * before the slow child finishes registering, nothing is cancelled, nothing
+	 * releases the slow child, and the run hangs until the delegation timeout.
+	 * That happened once here. A fan-out where one leg dies while another is
+	 * genuinely in flight is the scenario being tested, so the harness states
+	 * it instead of hoping for it.
+	 */
+	private readonly bothLaunched = new Promise<void>((resolve) => {
+		this.markLaunched = resolve
+	})
+
+	async sendMessage(options: SendMessageOptions): Promise<AgentTask> {
+		const failing = options.agentId === FAILING
+		const taskId = (failing ? 'task_doomed' : 'task_patient') as TaskId
+		const task = {
+			taskId,
+			agentId: options.agentId,
+			agent: {} as Agent<never, never>,
+			childAbortController: new AbortController(),
+			context: {} as AgentTaskContext,
+			// The failing child is `completed` at the gateway layer and
+			// `failed` in its own result — the two-authority split that makes
+			// this worth checking at all.
+			state: (failing ? 'completed' : 'running') as AgentTaskState,
+			pendingMessages: [],
+			createdAt: 1,
+			...(failing
+				? { result: { runId: 'run_child' as RunId, status: 'failed', result: 'it broke' } }
+				: {}),
+		} as AgentTask
+
+		this.tasks.set(taskId, task)
+		if (this.tasks.size === 2) this.markLaunched?.()
+		return task
+	}
+
+	cancel(taskId: TaskId): void {
+		this.cancelled.push(taskId)
+		const task = this.tasks.get(taskId)
+		if (task) task.state = 'failed' as AgentTaskState
+		this.releaseSlow?.()
+	}
+
+	async waitForCompletion(taskId: TaskId): Promise<void> {
+		if (taskId === ('task_patient' as TaskId)) await this.slowSettled
+		// The doomed child fails only once its sibling is actually in flight —
+		// see `bothLaunched`. Registration happens inside `createTask` right
+		// after `sendMessage` returns, so waiting a further microtask turn is
+		// what puts this after it rather than racing it.
+		else {
+			await this.bothLaunched.then(() => undefined)
+			// Safety valve, and it is what makes a REGRESSION legible. If the
+			// policy never reaches the gateway, nothing cancels the slow child
+			// and this run hangs until the delegation timeout — so the test
+			// would report "timed out after 60s" instead of "the sibling was
+			// not cancelled". Releasing it here means the assertion below is
+			// what fails, and it fails in a second.
+			setTimeout(() => this.releaseSlow?.(), 250).unref?.()
+		}
+	}
+
+	getInstance(taskId: TaskId): AgentTask | undefined {
+		return this.tasks.get(taskId)
+	}
+
+	cancelAll(): void {}
+	async continueTask(): Promise<void> {}
+	queueMessage(): void {}
+	drainMessages() {
+		return []
+	}
+	listByParent(): AgentTask[] {
+		return []
+	}
+	listActive(): AgentTask[] {
+		return []
+	}
+	getState(): AgentTaskState | undefined {
+		return undefined
+	}
+	on(): void {}
+	off(): void {}
+	cleanup(): void {}
+	dispose(): void {}
+}
+
+async function fanOut(policy?: SiblingFailurePolicy): Promise<FanOutManager> {
+	const agentManager = new FanOutManager()
+	const agent = new SupervisorAgent({
+		id: 'sup_policy',
+		name: 'Supervisor',
+		version: '1',
+		category: 'test',
+		description: 'coordinates workers',
+	})
+
+	await agent.run(
+		{
+			messages: [{ role: 'user', content: 'go', timestamp: 1 }],
+			workingDirectory: await mkdtemp(join(tmpdir(), 'namzu-sibling-policy-')),
+		} as never,
+		{
+			provider: new MockLLMProvider({
+				turns: [
+					{
+						toolCalls: [
+							{
+								name: 'create_task',
+								args: { agent_id: SLOW, prompt: 'long work', description: 'the patient one' },
+							},
+							{
+								name: 'create_task',
+								args: { agent_id: FAILING, prompt: 'doomed work', description: 'the doomed one' },
+							},
+						],
+					},
+					{ text: 'done' },
+				],
+			}),
+			agentIds: [SLOW, FAILING],
+			agentManager,
+			tools: new ToolRegistry(),
+			systemPrompt: 'You coordinate.',
+			model: 'mock-model',
+			tokenBudget: 100_000,
+			timeoutMs: 30_000,
+			maxIterations: 3,
+			sessionId: 'ses_policy',
+			threadId: 'thd_policy',
+			projectId: 'prj_policy',
+			tenantId: 'tnt_policy',
+			...(policy ? { siblingFailurePolicy: policy } : {}),
+		} as never,
+	)
+
+	return agentManager
+}
+
+describe('a supervisor can say what a failed child means for its siblings', () => {
+	it('reaches the gateway, so cancel-siblings actually stops the rest', async () => {
+		const manager = await fanOut('cancel-siblings')
+
+		expect(manager.cancelled).toContain('task_patient' as TaskId)
+	}, 60_000)
+})