@namzu/sdk 2.0.0 → 3.0.0

package/src/agents/RouterAgent.ts

@@ -9,6 +9,7 @@ import type {
 	RouterAgentResult,
 	RoutingDecision,
 } from '../types/agent/index.js'
+import { type TokenUsage, accumulateTokenUsage } from '../types/common/index.js'
 import type { FallbackStrategy } from '../types/decision/index.js'
 import { deriveChildState } from '../types/invocation/index.js'
 import { createSystemMessage, createUserMessage } from '../types/message/index.js'
@@ -33,10 +34,29 @@ export class RouterAgent extends AbstractAgent<RouterAgentConfig, RouterAgentRes
 		})
 	}
 
+	/**
+	 * One run at a time per instance.
+	 *
+	 * `abortController` and `currentRunId` are instance state, so two
+	 * overlapping runs share one abort controller — cancelling either kills
+	 * both — and the second clobbers the first's run id, so a later
+	 * `cancel()` cancels the wrong run. Neither failure announces itself.
+	 * A host that wants parallelism constructs a second instance.
+	 */
 	async run(
 		input: AgentInput,
 		config: RouterAgentConfig,
 		listener?: RunEventListener,
+	): Promise<RouterAgentResult> {
+		return await this.underIdempotencyKey(config.idempotencyKey, () =>
+			this.underInvocationLock(() => this.runExclusive(input, config, listener)),
+		)
+	}
+
+	private async runExclusive(
+		input: AgentInput,
+		config: RouterAgentConfig,
+		listener?: RunEventListener,
 	): Promise<RouterAgentResult> {
 		const startTime = Date.now()
 		const runId = this.createRunId()
@@ -110,7 +130,9 @@ export class RouterAgent extends AbstractAgent<RouterAgentConfig, RouterAgentRes
 			runId,
 			status: delegateResult.status,
 			stopReason: delegateResult.stopReason,
-			usage: delegateResult.usage,
+			// Routing is a model call the run paid for; reporting only the
+			// delegate's usage silently under-reports every routed run.
+			usage: accumulateTokenUsage(delegateResult.usage, decision.usage ?? EMPTY_TOKEN_USAGE),
 			cost: delegateResult.cost,
 			iterations: delegateResult.iterations + 1,
 			durationMs: Date.now() - startTime,
@@ -175,6 +197,10 @@ export class RouterAgent extends AbstractAgent<RouterAgentConfig, RouterAgentRes
 			.filter((c): c is string => c !== null)
 			.join('\n')
 
+		// Every routing attempt is a billed model call; a fallback after
+		// three failed parses still cost three calls.
+		let routingUsage: TokenUsage = { ...EMPTY_TOKEN_USAGE }
+
 		for (let attempt = 0; attempt < maxRetries; attempt++) {
 			try {
 				const response = await collect(
@@ -186,6 +212,8 @@ export class RouterAgent extends AbstractAgent<RouterAgentConfig, RouterAgentRes
 					}),
 				)
 
+				routingUsage = accumulateTokenUsage(routingUsage, response.usage)
+
 				const parseResult = parser.parse(response.message.content)
 
 				if (parseResult.ok && parseResult.source === 'parsed') {
@@ -194,6 +222,7 @@ export class RouterAgent extends AbstractAgent<RouterAgentConfig, RouterAgentRes
 						confidence: parseResult.decision.confidence,
 						reasoning: parseResult.decision.reasoning,
 						routingSource: 'provider',
+						usage: routingUsage,
 					}
 				}
 
@@ -209,6 +238,7 @@ export class RouterAgent extends AbstractAgent<RouterAgentConfig, RouterAgentRes
 							confidence: parseResult.decision.confidence,
 							reasoning: parseResult.decision.reasoning,
 							routingSource: 'fallback',
+							usage: routingUsage,
 						}
 					}
 
@@ -233,6 +263,6 @@ export class RouterAgent extends AbstractAgent<RouterAgentConfig, RouterAgentRes
 			}
 		}
 
-		return fallbackResolver.resolve(userContent, validAgentIds)
+		return { ...fallbackResolver.resolve(userContent, validAgentIds), usage: routingUsage }
 	}
 }

package/src/agents/SupervisorAgent.ts

@@ -3,6 +3,7 @@ import { LocalTaskGateway } from '../gateway/local.js'
 import { ToolRegistry } from '../registry/tool/execute.js'
 import { drainQuery } from '../runtime/query/index.js'
 import type { LaunchedTaskMeta } from '../runtime/query/iteration/phases/context.js'
+import { PendingAnswers, QuestionParkBinding } from '../runtime/query/question-park.js'
 import { buildCoordinatorTools } from '../tools/coordinator/index.js'
 import type { TaskGateway, TaskHandle } from '../types/agent/gateway.js'
 import type {
@@ -32,7 +33,7 @@ import { AbstractAgent } from './AbstractAgent.js'
  * The earlier implementation cast `handle.state` onto the synthesized result's
  * status, letting a worker that ended without a result count toward
  * `completedTasks`. That produced fabricated "done" workers with empty outputs
- * (cowork task 02c5cf2b): the supervisor reported "3 workers done, 40KB
+ * (observed in a live supervised run): the supervisor reported "3 workers done, 40KB
  * reports" when the workers never started. Real workers (those with a present
  * `result`) are unaffected — their `result` is preserved verbatim.
  */
@@ -77,10 +78,29 @@ export class SupervisorAgent extends AbstractAgent<SupervisorAgentConfig, Superv
 		})
 	}
 
+	/**
+	 * One run at a time per instance.
+	 *
+	 * `abortController` and `currentRunId` are instance state, so two
+	 * overlapping runs share one abort controller — cancelling either kills
+	 * both — and the second clobbers the first's run id, so a later
+	 * `cancel()` cancels the wrong run. Neither failure announces itself.
+	 * A host that wants parallelism constructs a second instance.
+	 */
 	async run(
 		input: AgentInput,
 		config: SupervisorAgentConfig,
 		listener?: RunEventListener,
+	): Promise<SupervisorAgentResult> {
+		return await this.underIdempotencyKey(config.idempotencyKey, () =>
+			this.underInvocationLock(() => this.runExclusive(input, config, listener)),
+		)
+	}
+
+	private async runExclusive(
+		input: AgentInput,
+		config: SupervisorAgentConfig,
+		listener?: RunEventListener,
 	): Promise<SupervisorAgentResult> {
 		const startTime = Date.now()
 		const runId = this.createRunId()
@@ -141,6 +161,12 @@ export class SupervisorAgent extends AbstractAgent<SupervisorAgentConfig, Superv
 
 		let planManagerRef: import('../manager/plan/lifecycle.js').PlanManager | undefined
 
+		// Created here because the TOOLS are created here: the durability
+		// channel has to reach the tool instance, and the run that supplies
+		// it does not exist yet. `query` binds them once it does.
+		const questionParks = new QuestionParkBinding()
+		const pendingAnswers = new PendingAnswers()
+
 		const coordinatorToolDefs = buildCoordinatorTools({
 			gateway,
 			workingDirectory: input.workingDirectory,
@@ -156,6 +182,8 @@ export class SupervisorAgent extends AbstractAgent<SupervisorAgentConfig, Superv
 			// 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()
@@ -187,6 +215,8 @@ export class SupervisorAgent extends AbstractAgent<SupervisorAgentConfig, Superv
 					temperature: config.temperature,
 					env: config.env,
 				},
+				questionParks,
+				pendingAnswers,
 				agentId: this.metadata.id,
 				agentName: this.metadata.name,
 				workingDirectory: input.workingDirectory,

package/src/agents/__tests__/idempotency-key.test.ts

@@ -0,0 +1,177 @@
+import { describe, expect, it } from 'vitest'
+
+import { ToolRegistry } from '../../registry/index.js'
+import type { AgentInput } from '../../types/agent/base.js'
+import type { ReactiveAgentConfig } from '../../types/agent/reactive.js'
+import { ReactiveAgent } from '../ReactiveAgent.js'
+
+/**
+ * A caller sends a request, the connection drops, the caller retries.
+ * Without a key the retry is a second full run — a second set of model
+ * calls, and a second set of whatever the tools did. The invocation lock
+ * alone does not help: refusing the retry with an error is not what the
+ * caller wanted either. They wanted the answer.
+ */
+
+/**
+ * A provider that blocks until released, so two invocations can overlap.
+ *
+ * The gate is created UP FRONT rather than assigned inside the generator:
+ * a generator body does not run until its consumer pulls, so a test that
+ * released immediately after calling `run` would be resolving a promise
+ * that did not exist yet and would hang.
+ */
+function blockingProvider() {
+	let open: (() => void) | undefined
+	let gate = new Promise<void>((resolve) => {
+		open = resolve
+	})
+	let calls = 0
+
+	const provider = {
+		id: 'test',
+		name: 'Test',
+		capabilities: {},
+		async *chatStream() {
+			calls++
+			await gate
+			yield { id: 'c', delta: { content: 'ok' }, finishReason: 'stop' }
+		},
+	}
+
+	return {
+		provider,
+		calls: () => calls,
+		release: () => open?.(),
+		/** Re-close it, so a second invocation can be held the same way. */
+		reset: () => {
+			gate = new Promise<void>((resolve) => {
+				open = resolve
+			})
+		},
+	}
+}
+
+function failingProvider() {
+	let calls = 0
+	return {
+		calls: () => calls,
+		provider: {
+			id: 'test',
+			name: 'Test',
+			capabilities: {},
+			// biome-ignore lint/correctness/useYield: it fails before producing anything
+			async *chatStream() {
+				calls++
+				await new Promise((resolve) => setTimeout(resolve, 5))
+				throw new Error('the provider is down')
+			},
+		},
+	}
+}
+
+const config = (provider: unknown, idempotencyKey?: string): ReactiveAgentConfig =>
+	({
+		provider,
+		tools: new ToolRegistry(),
+		model: 'm',
+		tokenBudget: 1_000,
+		timeoutMs: 10_000,
+		sessionId: 'ses_1',
+		threadId: 'thr_1',
+		projectId: 'prj_1',
+		tenantId: 'ten_1',
+		...(idempotencyKey ? { idempotencyKey } : {}),
+	}) as unknown as ReactiveAgentConfig
+
+const input: AgentInput = { messages: [{ role: 'user', content: 'go' }] } as AgentInput
+
+const agent = () =>
+	new ReactiveAgent({
+		id: 'a',
+		name: 'A',
+		type: 'reactive',
+		capabilities: {},
+	} as never)
+
+describe('a retried invocation carrying the same key', () => {
+	it('joins the one already running instead of starting a second', async () => {
+		const { provider, calls, release } = blockingProvider()
+		const a = agent()
+
+		const first = a.run(input, config(provider, 'req_1'))
+		const retry = a.run(input, config(provider, 'req_1'))
+		release()
+		const [one, two] = await Promise.all([first, retry])
+
+		// One model call, and both callers hold the same answer — not an
+		// error telling the second one to go away.
+		expect(calls()).toBe(1)
+		expect(two.runId).toBe(one.runId)
+	})
+
+	it('shares the failure too', async () => {
+		// Both callers asked the same question once. Telling one of them
+		// something different would make the key a lie.
+		const { provider, calls } = failingProvider()
+		const a = agent()
+
+		const first = a.run(input, config(provider, 'req_1'))
+		const retry = a.run(input, config(provider, 'req_1'))
+		const [one, two] = await Promise.all([first, retry].map((p) => p.catch((e) => e)))
+
+		expect(calls()).toBe(1)
+		expect(two).toBe(one)
+	})
+
+	it('runs again once the first has settled', async () => {
+		// In-flight only. Keeping the answer would turn deduplication into
+		// caching, and staleness is the host's judgement, not the SDK's.
+		const { provider, calls, release, reset } = blockingProvider()
+		const a = agent()
+
+		const first = a.run(input, config(provider, 'req_1'))
+		release()
+		await first
+
+		reset()
+		const second = a.run(input, config(provider, 'req_1'))
+		release()
+		await second
+
+		expect(calls()).toBe(2)
+	})
+})
+
+describe('an invocation without a key', () => {
+	it('is refused while another is running, as before', async () => {
+		// The lock still owns the no-key case: two overlapping runs share one
+		// abort controller and one run id, and neither failure announces
+		// itself.
+		const { provider, release } = blockingProvider()
+		const a = agent()
+
+		const first = a.run(input, config(provider))
+		const overlapping = a.run(input, config(provider)).catch((err: Error) => err)
+		release()
+
+		await first
+		expect(await overlapping).toBeInstanceOf(Error)
+	})
+
+	it('does not join an invocation carrying a different key', async () => {
+		const { provider, calls, release } = blockingProvider()
+		const a = agent()
+
+		const first = a.run(input, config(provider, 'req_1'))
+		const other = a.run(input, config(provider, 'req_2')).catch((err: Error) => err)
+		release()
+		await first
+		await other
+
+		// A different key is a different request; it must not be answered
+		// with this one's result.
+		expect(calls()).toBe(1)
+		expect(await other).toBeInstanceOf(Error)
+	})
+})

package/src/agents/__tests__/invocation-lock.test.ts

@@ -0,0 +1,154 @@
+import { describe, expect, it } from 'vitest'
+
+import type { AgentInput } from '../../types/agent/base.js'
+import type { ReactiveAgentConfig } from '../../types/agent/reactive.js'
+import { ReactiveAgent } from '../ReactiveAgent.js'
+import { ConcurrentInvocationError } from '../lock.js'
+
+/**
+ * The lock existed, was exported, and had no caller — so concurrent
+ * invocations of one agent instance were never prevented, and the error
+ * type that announces the refusal could not be thrown by anything.
+ *
+ * They genuinely are unsafe: `abortController` and `currentRunId` are
+ * INSTANCE state. Two overlapping runs share one abort controller, so
+ * cancelling either kills both, and the second clobbers the first's run
+ * id, so a later `cancel()` cancels the wrong run. Neither failure
+ * announces itself — the first run simply stops, or the wrong one does.
+ */
+
+/** A provider that blocks until released, so two runs can overlap. */
+function blockingProvider() {
+	let release: (() => void) | undefined
+	const started: number[] = []
+	let n = 0
+
+	const provider = {
+		id: 'test',
+		name: 'Test',
+		capabilities: {},
+		async *chatStream() {
+			started.push(++n)
+			await new Promise<void>((resolve) => {
+				release = resolve
+			})
+			yield { id: 'c', delta: { content: 'ok' }, finishReason: 'stop' }
+		},
+	}
+
+	return { provider, started, release: () => release?.() }
+}
+
+function agentConfig(provider: unknown): ReactiveAgentConfig {
+	return {
+		provider,
+		model: 'm',
+		tokenBudget: 1_000,
+		timeoutMs: 10_000,
+		sessionId: 'ses_1',
+		threadId: 'thr_1',
+		projectId: 'prj_1',
+		tenantId: 'ten_1',
+	} as unknown as ReactiveAgentConfig
+}
+
+const input: AgentInput = { messages: [{ role: 'user', content: 'go' }] } as AgentInput
+
+describe('one run at a time per instance', () => {
+	it('refuses a second concurrent run on the same instance', async () => {
+		const { provider, release } = blockingProvider()
+		const agent = new ReactiveAgent({ id: 'a', name: 'A' } as never)
+
+		const first = agent.run(input, agentConfig(provider))
+		// The refusal is what makes the shared-state hazard visible instead
+		// of letting two runs quietly cancel each other.
+		await expect(agent.run(input, agentConfig(provider))).rejects.toBeInstanceOf(
+			ConcurrentInvocationError,
+		)
+
+		release()
+		await first.catch(() => undefined)
+	})
+
+	it('names the agent it refused', async () => {
+		const { provider, release } = blockingProvider()
+		const agent = new ReactiveAgent({ id: 'named-agent', name: 'A' } as never)
+
+		const first = agent.run(input, agentConfig(provider))
+		await expect(agent.run(input, agentConfig(provider))).rejects.toThrow(/named-agent/)
+
+		release()
+		await first.catch(() => undefined)
+	})
+
+	it('releases the lock once a run settles, so the instance is reusable', async () => {
+		const { provider, release } = blockingProvider()
+		const agent = new ReactiveAgent({ id: 'a', name: 'A' } as never)
+
+		const first = agent.run(input, agentConfig(provider))
+		release()
+		await first.catch(() => undefined)
+
+		// A one-shot lock would be worse than none: the instance would be
+		// permanently unusable after its first run.
+		const { provider: second, release: releaseSecond } = blockingProvider()
+		const next = agent.run(input, agentConfig(second))
+		releaseSecond()
+		await expect(next.catch(() => 'settled')).resolves.toBeDefined()
+	})
+
+	it('releases the lock even when the run throws', async () => {
+		const failing = {
+			id: 'test',
+			name: 'Test',
+			capabilities: {},
+			async *chatStream(): AsyncGenerator<never> {
+				// biome-ignore lint/correctness/useYield: the point is that it throws
+				throw new Error('provider exploded')
+			},
+		}
+		const agent = new ReactiveAgent({ id: 'a', name: 'A' } as never)
+
+		await agent.run(input, agentConfig(failing)).catch(() => undefined)
+		// Without the `finally`, one failed run would brick the instance —
+		// and the second call would report a concurrency error for a run
+		// that is not running.
+		await expect(
+			agent.run(input, agentConfig(failing)).catch((err: unknown) => err),
+		).resolves.not.toBeInstanceOf(ConcurrentInvocationError)
+	})
+
+	it('leaves separate instances independent', async () => {
+		// The supported shape for parallelism: a second instance is cheap,
+		// and each owns its own abort controller and run id.
+		const a = blockingProvider()
+		const b = blockingProvider()
+		const first = new ReactiveAgent({ id: 'a', name: 'A' } as never)
+		const second = new ReactiveAgent({ id: 'b', name: 'B' } as never)
+
+		const runA = first.run(input, agentConfig(a.provider))
+		const runB = second.run(input, agentConfig(b.provider))
+
+		a.release()
+		b.release()
+		const settled = await Promise.allSettled([runA, runB])
+
+		// The claim is about the LOCK, so assert on the lock. An earlier
+		// version counted provider calls, which is a side effect these runs
+		// may never reach — it failed for a reason that had nothing to do
+		// with what the test is named for.
+		for (const outcome of settled) {
+			if (outcome.status === 'rejected') {
+				expect(outcome.reason).not.toBeInstanceOf(ConcurrentInvocationError)
+			}
+		}
+	})
+})
+
+describe('the error itself', () => {
+	it('carries the agent id rather than only a message', () => {
+		const err = new ConcurrentInvocationError('agent-7')
+		expect(err.agentId).toBe('agent-7')
+		expect(err).toBeInstanceOf(Error)
+	})
+})