@namzu/sdk 6.2.0 → 8.0.0

package/src/agents/SupervisorAgent.ts

@@ -185,177 +185,190 @@ 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,
-				},
-				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,
+					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__/supervisor-inbox-scope.test.ts

@@ -0,0 +1,149 @@
+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/runAgent.ts

@@ -2,7 +2,7 @@ import { ToolRegistry } from '../registry/tool/execute.js'
 import { drainQuery } from '../runtime/query/index.js'
 import type { ProjectId, SessionId, TenantId, ThreadId } from '../types/ids/index.js'
 import type { Message } from '../types/message/index.js'
-import type { LLMProvider } from '../types/provider/index.js'
+import type { LLMProvider, ReasoningEffort, ThinkingConfig } from '../types/provider/index.js'
 import type { Run, RunEventListener } from '../types/run/index.js'
 import type { Skill } from '../types/skills/index.js'
 import type { ToolRegistryContract } from '../types/tool/index.js'
@@ -83,6 +83,25 @@ export interface RunAgentOptions extends AgentIdentity {
 	timeoutMs?: number
 	temperature?: number
 
+	/**
+	 * Extended-thinking request and response-effort level, forwarded on every
+	 * model call.
+	 *
+	 * These are here because the run config below is assembled by HAND, and a
+	 * hand-listed literal silently drops whatever nobody remembered to add —
+	 * which is precisely what happened. `thinking` shipped on `AgentRunConfig`
+	 * and was reachable only from the raw kernel entry point, because this
+	 * function, `ReactiveAgent` and `SupervisorAgent` each rebuilt the object
+	 * from a fixed list. So the capability existed and the front door could not
+	 * open it.
+	 *
+	 * A live run is what found it: the unit tests passed because they drove the
+	 * kernel directly, and a real agent run through this function put no effort
+	 * on the wire at all.
+	 */
+	thinking?: ThinkingConfig
+	effort?: ReasoningEffort
+
 	/** Names the agent in traces and events. Defaults to `Agent`. */
 	name?: string
 
@@ -184,6 +203,8 @@ export async function runAgent(options: RunAgentOptions): Promise<RunAgentResult
 				tokenBudget: options.tokenBudget ?? DEFAULT_TOKEN_BUDGET,
 				timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
 				...(options.temperature !== undefined ? { temperature: options.temperature } : {}),
+				...(options.thinking ? { thinking: options.thinking } : {}),
+				...(options.effort ? { effort: options.effort } : {}),
 			},
 			// One option covers both. `drainQuery` separates the id from the
 			// display name because a fleet needs a stable key and a readable

package/src/bridge/a2a/mapper.ts

@@ -188,6 +188,10 @@ const MAPPING: {
 	// Context management is kernel-internal bookkeeping; A2A peers model a
 	// task lifecycle, not the host runtime's memory strategy.
 	compaction_completed: null,
+	// Compaction, succeeded or declined, is a property of how this runtime
+	// manages its own context. A peer models a task lifecycle and cannot act on
+	// either outcome.
+	compaction_failed: null,
 	// A refusal is the run's own policy decision; the peer sees it in the
 	// terminal task state, not as a separate signal.
 	guardrail_triggered: null,

package/src/bridge/sse/mapper.ts

@@ -92,6 +92,21 @@ const MAPPING: {
 		}),
 	},
 
+	// Carried for the same reason its sibling is: a host that can show a user
+	// context was dropped must also be able to show them it was not, because a
+	// run continuing at full context is the state that ends in an opaque
+	// provider rejection later.
+	compaction_failed: {
+		wire: 'compaction.failed',
+		transform: (e, runId) => ({
+			run_id: runId,
+			iteration: e.iteration,
+			cause: e.cause,
+			messages: e.messages,
+			...(e.error !== undefined ? { error: e.error } : {}),
+		}),
+	},
+
 	tool_executing: {
 		wire: 'tool.executing',
 		transform: (e, runId) => ({
@@ -212,6 +227,16 @@ const MAPPING: {
 			run_id: runId,
 			usage: e.usage,
 			cost: e.cost,
+			// Carried, and named apart from `usage` on the wire as well as in
+			// the type. A remote surface has exactly the same opportunity to
+			// divide cumulative spend by a context window as a local one, and
+			// no more information with which to notice.
+			...(e.contextTokens !== undefined ? { context_tokens: e.contextTokens } : {}),
+			...(e.contextMeasuredBy !== undefined ? { context_measured_by: e.contextMeasuredBy } : {}),
+			...(e.contextWindowTokens !== undefined
+				? { context_window_tokens: e.contextWindowTokens }
+				: {}),
+			...(e.windowSource !== undefined ? { window_source: e.windowSource } : {}),
 		}),
 	},