@namzu/sdk 3.1.0 → 3.3.0

package/dist/types/run/prepare-step.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prepare-step.d.ts","sourceRoot":"","sources":["../../../src/types/run/prepare-step.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AAC5C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAE3C;;;;;;;;;;GAUG;AACH,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,mEAAmE;IACnE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAA;IACrC,sCAAsC;IACtC,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAA;IAErC;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,iBAAiB,CAAC,CAAA;CAC9C;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IACjC;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAExC,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IAEvB;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IAExB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;CACnC;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG,CACzB,OAAO,EAAE,kBAAkB,KACvB,iBAAiB,GAAG,SAAS,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAAA;AAE3E;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,SAAS,WAAW,EAAE,CAAA"}
+{"version":3,"file":"prepare-step.d.ts","sourceRoot":"","sources":["../../../src/types/run/prepare-step.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AAC5C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AACrD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAA;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAE3C;;;;;;;;;;GAUG;AACH,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,mEAAmE;IACnE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAA;IACrC,sCAAsC;IACtC,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAA;IAErC;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,iBAAiB,CAAC,CAAA;CAC9C;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IACjC;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAExC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAA;IAEhC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,KAAK,EAAE,CAAA;IAElC,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IAEvB;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IAExB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;CACnC;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG,CACzB,OAAO,EAAE,kBAAkB,KACvB,iBAAiB,GAAG,SAAS,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAAA;AAE3E;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,SAAS,WAAW,EAAE,CAAA"}

package/dist/types/toolset/index.d.ts

@@ -1,4 +1,20 @@
 import type { LLMToolSchema, ToolDefinition, ToolPermission } from '../tool/index.js';
+/**
+ * @deprecated Slated for removal in the next major. Nothing produces or
+ * reads it — no code constructs any member, and `ToolsetPolicy.surfaces`,
+ * the only field that carries it, is never consulted.
+ *
+ * It is also the wrong axis. Which tools a run may use is already
+ * expressible four ways, all of them per-run and dynamic where this is
+ * fixed at definition: `allowedTools` on the query, `ToolAvailability`
+ * (`active` / `deferred` / `suspended`) with mid-run activation,
+ * `runtimeToolOverrides`, and capability negotiation stripping tools a
+ * driver cannot carry. Prefer `allowedTools`.
+ *
+ * The member names encode deployment shapes this kernel does not own,
+ * which is the deeper reason not to keep them: a host's surfaces are the
+ * host's to name.
+ */
 export type ToolCatalogSurface = 'chat' | 'supervised' | 'managed-agent' | 'worker' | 'code';
 export type ToolSourceKind = 'host_tool' | 'provider_builtin' | 'mcp_server' | 'skill' | 'plugin' | 'connector';
 export type ToolLoadingMode = 'eager' | 'deferred' | 'disabled' | 'suspended';
@@ -30,6 +46,12 @@ export interface ToolsetPolicy {
     readonly enabled?: boolean;
     readonly loading?: ToolLoadingMode;
     readonly preferred?: boolean;
+    /**
+     * @deprecated Slated for removal in the next major. Never read by
+     * anything — setting it has no effect today. Use `allowedTools` on the
+     * query to bound which tools a run may use; it says the same thing per
+     * run instead of per definition. See {@link ToolCatalogSurface}.
+     */
     readonly surfaces?: readonly ToolCatalogSurface[];
     readonly providerConfig?: Record<string, unknown>;
 }

package/dist/types/toolset/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/toolset/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/toolset/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namzu/sdk",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "description": "Open-source AI agent SDK with a built-in runtime. Nothing between you and your agents.",
   "license": "FSL-1.1-MIT",
   "type": "module",

package/src/advisory/__tests__/consultation-context.test.ts

@@ -0,0 +1,191 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import type { AdvisorDefinition } from '../../types/advisory/index.js'
+import type { Message } from '../../types/message/index.js'
+import { AdvisoryContext } from '../context.js'
+import { TriggerEvaluator } from '../evaluator.js'
+import { AdvisoryExecutor } from '../executor.js'
+import { ADVISORY_RESPONSE_CONTRACT } from '../parse.js'
+import { AdvisorRegistry } from '../registry.js'
+
+/**
+ * An advisor consulted BY THE MODEL saw the question and nothing else.
+ *
+ * Two paths reach `AdvisoryExecutor.consult`. The trigger path
+ * (`iteration/phases/advisory.ts`) has always passed the live messages, the
+ * working state and the tool catalogue. The tool path passed
+ * `{ messages: [], iteration: 0 }` — a literal empty context — so the
+ * model's own `include_context: true` had nothing to include, and the
+ * advisor answered a question about a situation it could not see.
+ */
+
+function recordingProvider(): { provider: AdvisorDefinition['provider']; calls: Message[][] } {
+	const calls: Message[][] = []
+	const provider = {
+		chatStream: async function* (params: { messages: Message[] }) {
+			calls.push(params.messages)
+			yield { id: 'a1', delta: { content: 'ADVICE: do the thing' } }
+			yield {
+				id: 'a1',
+				delta: {},
+				finishReason: 'stop',
+				usage: { promptTokens: 1, completionTokens: 1, totalTokens: 2 },
+			}
+		},
+	} as unknown as AdvisorDefinition['provider']
+	return { provider, calls }
+}
+
+function advisor(over: Partial<AdvisorDefinition> = {}): AdvisorDefinition {
+	return {
+		id: 'adv_1',
+		name: 'Reviewer',
+		provider: recordingProvider().provider,
+		model: 'mock-model',
+		...over,
+	} as AdvisorDefinition
+}
+
+const log = {
+	debug: vi.fn(),
+	info: vi.fn(),
+	warn: vi.fn(),
+	error: vi.fn(),
+	child: () => log,
+} as never
+
+function contextFor(a: AdvisorDefinition): AdvisoryContext {
+	return new AdvisoryContext(
+		new AdvisorRegistry([a]),
+		new AdvisoryExecutor(log),
+		new TriggerEvaluator([]),
+	)
+}
+
+describe('the context a tool-initiated consultation is given', () => {
+	it('is empty until the runtime supplies one', () => {
+		const ctx = contextFor(advisor())
+
+		// The fallback exists for a context built without a runtime, and it is
+		// what every tool-initiated call used to get.
+		expect(ctx.callContext()).toEqual({ messages: [], iteration: 0 })
+	})
+
+	it('is the live run once the runtime wires it', () => {
+		const ctx = contextFor(advisor())
+		const messages: Message[] = [{ role: 'user', content: 'the situation', timestamp: 1 }]
+
+		ctx.setCallContextProvider(() => ({ messages, iteration: 7 }))
+
+		expect(ctx.callContext().messages).toBe(messages)
+		expect(ctx.callContext().iteration).toBe(7)
+	})
+
+	it('is read at call time, not at construction', () => {
+		const ctx = contextFor(advisor())
+		let iteration = 1
+		ctx.setCallContextProvider(() => ({ messages: [], iteration }))
+
+		iteration = 4
+
+		// The tool is built once per run and called at an unknown later point.
+		// A snapshot would hand every advisor the state the run started with.
+		expect(ctx.callContext().iteration).toBe(4)
+	})
+})
+
+describe('what the advisor actually receives', () => {
+	it('sees the conversation when context is included', async () => {
+		const { provider, calls } = recordingProvider()
+		const executor = new AdvisoryExecutor(log)
+
+		await executor.consult(
+			advisor({ provider }),
+			{ advisorId: 'adv_1', question: 'what next?', includeContext: true },
+			{ messages: [{ role: 'user', content: 'deploy is failing', timestamp: 1 }], iteration: 2 },
+		)
+
+		const sent = JSON.stringify(calls[0])
+		expect(sent).toContain('deploy is failing')
+	})
+
+	it('sees none of it when the caller says not to', async () => {
+		const { provider, calls } = recordingProvider()
+		const executor = new AdvisoryExecutor(log)
+
+		await executor.consult(
+			advisor({ provider }),
+			{ advisorId: 'adv_1', question: 'what next?', includeContext: false },
+			{ messages: [{ role: 'user', content: 'deploy is failing', timestamp: 1 }], iteration: 2 },
+		)
+
+		expect(JSON.stringify(calls[0])).not.toContain('deploy is failing')
+	})
+
+	it('is told when the caller marked the request urgent', async () => {
+		const { provider, calls } = recordingProvider()
+		const executor = new AdvisoryExecutor(log)
+
+		await executor.consult(
+			advisor({ provider }),
+			{ advisorId: 'adv_1', question: 'what next?', urgency: 'high' },
+			{ messages: [], iteration: 1 },
+		)
+
+		// The value used to reach exactly one debug log line, so 'high' and
+		// 'low' produced byte-identical requests.
+		expect(String(calls[0]?.[0]?.content)).toContain('URGENT')
+	})
+
+	it('is told when there is room to consider alternatives', async () => {
+		const { provider, calls } = recordingProvider()
+		const executor = new AdvisoryExecutor(log)
+
+		await executor.consult(
+			advisor({ provider }),
+			{ advisorId: 'adv_1', question: 'what next?', urgency: 'low' },
+			{ messages: [], iteration: 1 },
+		)
+
+		expect(String(calls[0]?.[0]?.content)).toContain('low urgency')
+	})
+
+	it("appends nothing at all for 'normal', which is the point of not stating it", async () => {
+		const { provider, calls } = recordingProvider()
+		const executor = new AdvisoryExecutor(log)
+		const a = advisor({ provider })
+
+		await executor.consult(
+			a,
+			{ advisorId: 'adv_1', question: 'what next?', urgency: 'normal' },
+			{ messages: [], iteration: 1 },
+		)
+		await executor.consult(
+			a,
+			{ advisorId: 'adv_1', question: 'what next?', urgency: 'high' },
+			{ messages: [], iteration: 1 },
+		)
+
+		// Asserting "does not contain the other two phrases" is too weak — it
+		// would let ANY new sentence in. The response contract is the last
+		// thing the prompt says when urgency contributes nothing, so ending on
+		// it is what "appended nothing" actually means.
+		expect(String(calls[0]?.[0]?.content).trimEnd().endsWith(ADVISORY_RESPONSE_CONTRACT)).toBe(true)
+		expect(String(calls[1]?.[0]?.content).trimEnd().endsWith(ADVISORY_RESPONSE_CONTRACT)).toBe(
+			false,
+		)
+	})
+
+	it('says nothing about urgency when the caller did not', async () => {
+		const { provider, calls } = recordingProvider()
+		const executor = new AdvisoryExecutor(log)
+
+		await executor.consult(
+			advisor({ provider }),
+			{ advisorId: 'adv_1', question: 'what next?' },
+			{ messages: [], iteration: 1 },
+		)
+
+		expect(String(calls[0]?.[0]?.content).trimEnd().endsWith(ADVISORY_RESPONSE_CONTRACT)).toBe(true)
+	})
+})

package/src/advisory/context.ts

@@ -1,8 +1,20 @@
 import type { AdvisoryBudget, AdvisoryCallRecord } from '../types/advisory/index.js'
 import type { TriggerEvaluator } from './evaluator.js'
+import type { AdvisoryCallContext } from './executor.js'
 import type { AdvisoryExecutor } from './executor.js'
 import type { AdvisorRegistry } from './registry.js'
 
+/**
+ * What the run looks like right now, for an advisory call that did not come
+ * from the iteration loop.
+ *
+ * A function rather than a snapshot because the tool is built once per run
+ * and called at an unknown later point: capturing the context at
+ * construction would hand every advisor the state the run had before it
+ * started.
+ */
+export type AdvisoryCallContextProvider = () => AdvisoryCallContext
+
 export class AdvisoryContext {
 	readonly registry: AdvisorRegistry
 	readonly executor: AdvisoryExecutor
@@ -10,6 +22,7 @@ export class AdvisoryContext {
 	readonly callHistory: AdvisoryCallRecord[] = []
 
 	private readonly budget: AdvisoryBudget | undefined
+	private callContextProvider: AdvisoryCallContextProvider | undefined
 
 	constructor(
 		registry: AdvisorRegistry,
@@ -23,6 +36,25 @@ export class AdvisoryContext {
 		this.budget = budget
 	}
 
+	/** Wired by the runtime once the run exists. */
+	setCallContextProvider(provider: AdvisoryCallContextProvider): void {
+		this.callContextProvider = provider
+	}
+
+	/**
+	 * The call context for a tool-initiated consultation.
+	 *
+	 * The trigger path (`iteration/phases/advisory.ts`) has always passed the
+	 * live messages, working state and tool catalogue. The TOOL path passed
+	 * `{ messages: [], iteration: 0 }` — a literal empty context — so an
+	 * advisor consulted by the model saw the question and nothing else, and
+	 * the model's `include_context` had nothing to include either way. The
+	 * empty fallback survives only for a context built without a runtime.
+	 */
+	callContext(): AdvisoryCallContext {
+		return this.callContextProvider?.() ?? { messages: [], iteration: 0 }
+	}
+
 	recordCall(record: AdvisoryCallRecord): void {
 		this.callHistory.push(record)
 	}

package/src/advisory/executor.ts

@@ -11,6 +11,19 @@ import { calculateCost } from '../utils/cost.js'
 import { type Logger, getRootLogger } from '../utils/logger.js'
 import { ADVISORY_RESPONSE_CONTRACT, parseAdvisoryResponse } from './parse.js'
 
+/**
+ * What the advisor is told about how urgent the caller said this is.
+ *
+ * `'normal'` says nothing on purpose. A sentence asserting the ordinary case
+ * is prompt weight that changes no answer, and stating it on every call
+ * would make the two that matter harder to notice.
+ */
+const URGENCY_DIRECTION: Record<'low' | 'normal' | 'high', string | undefined> = {
+	high: 'This request is marked URGENT. Lead with the single most important action and keep the reasoning to what is needed to justify it.',
+	normal: undefined,
+	low: 'This request is marked low urgency. There is room to note secondary considerations and alternatives worth weighing.',
+}
+
 export interface AdvisoryCallContext {
 	readonly messages: Message[]
 	readonly workingStateSummary?: string
@@ -53,7 +66,7 @@ export class AdvisoryExecutor {
 	): Promise<AdvisoryExecutionResult> {
 		const startMs = Date.now()
 
-		const systemPrompt = this.buildSystemPrompt(advisor)
+		const systemPrompt = this.buildSystemPrompt(advisor, request.urgency)
 		const contextMessages = this.buildContext(advisor, request, callCtx)
 
 		const messages: Message[] = [
@@ -100,11 +113,25 @@ export class AdvisoryExecutor {
 		}
 	}
 
-	private buildSystemPrompt(advisor: AdvisorDefinition): string {
+	private buildSystemPrompt(
+		advisor: AdvisorDefinition,
+		urgency?: AdvisoryRequest['urgency'],
+	): string {
 		// The contract is appended to every branch, not folded into the
 		// default: an advisor with its own prompt or a persona is still read
 		// back by the same parser, and used to be the one never told so.
-		return `${this.describeAdvisor(advisor)}\n\n${ADVISORY_RESPONSE_CONTRACT}`
+		const parts = [this.describeAdvisor(advisor), ADVISORY_RESPONSE_CONTRACT]
+
+		// The caller is invited to say how urgent this is, and the value used
+		// to reach exactly one debug log line — `urgency: 'high'` and
+		// `urgency: 'low'` produced byte-identical requests. Telling the
+		// ADVISOR is the honest minimum: it is the party that can act on the
+		// answer, and it costs one sentence rather than a routing policy this
+		// kernel has no business inventing.
+		const direction = URGENCY_DIRECTION[urgency ?? 'normal']
+		if (direction) parts.push(direction)
+
+		return parts.join('\n\n')
 	}
 
 	private describeAdvisor(advisor: AdvisorDefinition): string {

package/src/agents/SupervisorAgent.ts

@@ -146,6 +146,12 @@ export class SupervisorAgent extends AbstractAgent<SupervisorAgentConfig, Superv
 					remaining: config.tokenBudget,
 				},
 				factoryOptions: mergedFactoryOptions,
+				// The supervisor already hands this to its OWN run and its own
+				// coordinator tools; handing it to the spawn context is what
+				// makes a worker ask the same person the supervisor asks.
+				// Without it the two disagreed: the supervisor paused for a
+				// human and the workers it launched approved themselves.
+				...(config.resumeHandler ? { resumeHandler: config.resumeHandler } : {}),
 				tenantId,
 				threadId,
 				sessionId,

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

@@ -0,0 +1,131 @@
+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()
+	})
+})