@namzu/sdk 7.0.0 → 9.0.0

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/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 } : {}),
 		}),
 	},
 

package/src/contracts/api.ts

@@ -155,6 +155,7 @@ export type StreamEventType =
 	 * transcript needs to know its middle was dropped, not infer it.
 	 */
 	| 'compaction.completed'
+	| 'compaction.failed'
 	/** A guardrail refused or corrected the run. */
 	| 'guardrail.triggered'
 	/**

package/src/gateway/__tests__/a-knob-nobody-can-turn.test.ts

@@ -0,0 +1,139 @@
+import type { Span } from '@opentelemetry/api'
+import { describe, expect, it } from 'vitest'
+
+import type { Agent } from '../../types/agent/core.js'
+import type { AgentManagerContract } from '../../types/agent/manager.js'
+import type {
+	AgentTask,
+	AgentTaskContext,
+	AgentTaskState,
+	SendMessageOptions,
+} from '../../types/agent/task.js'
+import type { AgentId, RunId, SessionId, TaskId, TenantId } from '../../types/ids/index.js'
+import type { ProjectId, ThreadId } from '../../types/session/ids.js'
+import { LocalTaskGateway } from '../local.js'
+
+/**
+ * `CreateTaskOptions.configOverrides` was declared, typed, and never read.
+ *
+ * `createTask` built its OWN `configOverrides` object out of `parentSpan`
+ * alone, so a caller pinning a delegated run to a cheaper model, or capping
+ * its iterations, got the agent's defaults and nothing to say otherwise. The
+ * field type-checked, the call succeeded, and the run was not the run that was
+ * asked for.
+ *
+ * Reachability, not behaviour: what `configOverrides` DOES once it lands on
+ * `sendMessage` is the agent manager's business and is tested there. What was
+ * broken is the hop.
+ */
+
+/** Records what the gateway actually asked the manager for. */
+class RecordingManager implements AgentManagerContract {
+	readonly sent: SendMessageOptions[] = []
+
+	async sendMessage(options: SendMessageOptions): Promise<AgentTask> {
+		this.sent.push(options)
+		return {
+			taskId: `task_${this.sent.length}` as TaskId,
+			agentId: options.agentId,
+			agent: {} as Agent<never, never>,
+			childAbortController: new AbortController(),
+			context: {} as AgentTaskContext,
+			state: 'completed' as AgentTaskState,
+			pendingMessages: [],
+			createdAt: 1,
+		} as AgentTask
+	}
+
+	cancel(): void {}
+	cancelAll(): void {}
+	async continueTask(): Promise<void> {}
+	queueMessage(): void {}
+	drainMessages() {
+		return []
+	}
+	async waitForCompletion(): Promise<void> {}
+	getInstance(): AgentTask | undefined {
+		return undefined
+	}
+	listByParent(): AgentTask[] {
+		return []
+	}
+	listActive(): AgentTask[] {
+		return []
+	}
+	getState(): AgentTaskState | undefined {
+		return undefined
+	}
+	on(): void {}
+	off(): void {}
+	cleanup(): void {}
+	dispose(): void {}
+}
+
+function context(): AgentTaskContext {
+	return {
+		parentRunId: 'run_parent' as RunId,
+		parentAgentId: 'supervisor',
+		parentAbortController: new AbortController(),
+		depth: 0,
+		budgetTracker: { total: 100_000, remaining: 100_000 },
+		tenantId: 'tnt_k' as TenantId,
+		threadId: 'thd_k' as ThreadId,
+		sessionId: 'ses_k' as SessionId,
+		projectId: 'prj_k' as ProjectId,
+		parentActor: { kind: 'agent', agentId: 'supervisor' as AgentId, tenantId: 'tnt_k' as TenantId },
+	} as AgentTaskContext
+}
+
+describe('a delegated run is built with the config its caller asked for', () => {
+	it('forwards configOverrides to the spawn', async () => {
+		const manager = new RecordingManager()
+		const gateway = new LocalTaskGateway(manager, context())
+
+		await gateway.createTask({
+			agentId: 'worker',
+			prompt: 'work',
+			workingDirectory: '/tmp',
+			configOverrides: { model: 'cheap-model', maxIterations: 3 },
+		})
+
+		expect(manager.sent[0]?.configOverrides).toMatchObject({
+			model: 'cheap-model',
+			maxIterations: 3,
+		})
+	})
+
+	it('keeps the dedicated parentSpan option winning when both name a span', async () => {
+		// A caller who sets both is saying the same thing twice, and the named
+		// field is the specific one for the job — so it is applied last.
+		const manager = new RecordingManager()
+		const gateway = new LocalTaskGateway(manager, context())
+		const named = { spanContext: () => ({ traceId: 'named' }) } as unknown as Span
+		const buried = { spanContext: () => ({ traceId: 'buried' }) } as unknown as Span
+
+		await gateway.createTask({
+			agentId: 'worker',
+			prompt: 'work',
+			workingDirectory: '/tmp',
+			parentSpan: named,
+			configOverrides: { parentSpan: buried, model: 'cheap-model' },
+		})
+
+		expect(manager.sent[0]?.configOverrides?.parentSpan).toBe(named)
+		// ...and the rest of the caller's overrides survive alongside it.
+		expect(manager.sent[0]?.configOverrides?.model).toBe('cheap-model')
+	})
+
+	it('still sends no configOverrides at all when the caller set neither', async () => {
+		// The absent case has to stay absent: an empty object here would put
+		// `configOverrides: {}` on every spawn and override nothing, which is
+		// harmless until something starts reading its presence as intent.
+		const manager = new RecordingManager()
+		const gateway = new LocalTaskGateway(manager, context())
+
+		await gateway.createTask({ agentId: 'worker', prompt: 'work', workingDirectory: '/tmp' })
+
+		expect(manager.sent[0]).not.toHaveProperty('configOverrides')
+	})
+})