@namzu/sdk 10.0.0 → 11.0.0

package/src/tools/coordinator/__tests__/a-listing-is-not-a-back-door.test.ts

@@ -0,0 +1,171 @@
+import { describe, expect, it } from 'vitest'
+
+import type { TaskGateway, TaskHandle } from '../../../types/agent/gateway.js'
+import type { TaskId } from '../../../types/ids/index.js'
+import type { ToolContext } from '../../../types/tool/index.js'
+import { buildCoordinatorTools } from '../index.js'
+
+/**
+ * A supervisor could read a sibling run's worker output by listing.
+ *
+ * `SupervisorAgentConfig.gateway` exists so a host can hand the SAME gateway to
+ * several runs, which makes `listTasks()` gateway-wide by design.
+ * `agent_task_list` handed that straight to the model — including each task's
+ * `result`, the worker's actual output — and `wait_for_task` had the same reach
+ * through `getTask`.
+ *
+ * `CompletionInbox` closed exactly this on the push side, because
+ * `onTaskCompleted` is a broadcast and a shared gateway would otherwise hand
+ * each supervisor the other's completions. The pull side kept no such record
+ * and asked the gateway directly, so the same leak stayed open through a
+ * different door.
+ */
+
+const AGENTS = ['reviewer', 'researcher']
+
+function makeContext(): ToolContext {
+	return {
+		runId: 'run_scope' as never,
+		workingDirectory: '/tmp/test',
+		abortSignal: new AbortController().signal,
+		env: {},
+		log: () => {},
+	}
+}
+
+/** One gateway, as a host sharing it between two supervisors would have. */
+function sharedGateway() {
+	const handles = new Map<string, TaskHandle>()
+	let seq = 0
+
+	const gateway = {
+		createTask: async (opts: { agentId: string }) => {
+			seq += 1
+			const taskId = `tsk_${seq}` as TaskId
+			const handle: TaskHandle = {
+				taskId,
+				agentId: opts.agentId,
+				state: 'completed',
+				createdAt: 1_000,
+				completedAt: 2_000,
+				result: {
+					status: 'completed',
+					result: `output of ${opts.agentId} on ${taskId}`,
+				} as TaskHandle['result'],
+			}
+			handles.set(taskId, handle)
+			return handle
+		},
+		waitForTask: async (taskId: TaskId) => handles.get(taskId) as TaskHandle,
+		getTask: (taskId: TaskId) => handles.get(taskId),
+		listTasks: () => [...handles.values()],
+		cancelTask: () => undefined,
+		continueTask: async () => undefined,
+		onTaskCompleted: () => () => {},
+	} as unknown as TaskGateway
+
+	return gateway
+}
+
+/** A run's own coordinator surface over a gateway it may be sharing. */
+function runOver(gateway: TaskGateway) {
+	const tools = buildCoordinatorTools({
+		gateway,
+		workingDirectory: '/tmp/test',
+		allowedAgentIds: AGENTS,
+	})
+	const named = (name: string) => {
+		const t = tools.find((tool) => tool.name === name)
+		if (!t) throw new Error(`${name} missing from coordinator builder`)
+		return t
+	}
+	return {
+		launch: (agentId: string) =>
+			named('create_task').execute(
+				{ agent_id: agentId, prompt: 'work', description: `${agentId} work` },
+				makeContext(),
+			),
+		list: () => named('agent_task_list').execute({}, makeContext()),
+		waitFor: (taskId: string) => named('wait_for_task').execute({ task_id: taskId }, makeContext()),
+	}
+}
+
+describe('one run cannot read another run through the listing', () => {
+	it('lists only the tasks this run launched', async () => {
+		const gateway = sharedGateway()
+		const first = runOver(gateway)
+		const second = runOver(gateway)
+
+		await first.launch('reviewer')
+		await second.launch('researcher')
+
+		const listed = await second.list()
+
+		// Its own, yes.
+		expect(listed.output).toContain('tsk_2')
+		// The sibling's task, and — the part that matters — the sibling's
+		// worker output, which the listing renders inline.
+		expect(listed.output).not.toContain('tsk_1')
+		expect(listed.output).not.toContain('output of reviewer')
+	})
+
+	it('counts only its own in the summary', async () => {
+		// The summary is what a supervisor reads to decide "done vs not done".
+		// A total that includes a sibling's tasks is a wrong answer to that
+		// question even when no output leaks with it.
+		const gateway = sharedGateway()
+		const first = runOver(gateway)
+		const second = runOver(gateway)
+
+		await first.launch('reviewer')
+		await first.launch('reviewer')
+		await second.launch('researcher')
+
+		const listed = await second.list()
+		const data = listed.data as { summary: { total: number }; items: unknown[] }
+
+		expect(data.summary.total).toBe(1)
+		expect(data.items).toHaveLength(1)
+	})
+
+	it('refuses to wait on a task another run launched', async () => {
+		const gateway = sharedGateway()
+		const first = runOver(gateway)
+		const second = runOver(gateway)
+
+		await first.launch('reviewer')
+
+		const waited = await second.waitFor('tsk_1')
+
+		expect(waited.success).toBe(false)
+		expect(waited.output).not.toContain('output of reviewer')
+	})
+
+	it('says the same thing about a task that never existed', async () => {
+		// The refusal must not distinguish "belongs to someone else" from
+		// "never existed". Confirming a real id to a run that should not know
+		// it is the leak in miniature.
+		const gateway = sharedGateway()
+		const first = runOver(gateway)
+		const second = runOver(gateway)
+
+		await first.launch('reviewer')
+
+		const sibling = await second.waitFor('tsk_1')
+		const fictional = await second.waitFor('tsk_9999')
+
+		expect(sibling.output).toBe(fictional.output.replace('tsk_9999', 'tsk_1'))
+	})
+
+	it('still lets a run wait on its own task', async () => {
+		// The scope has to be a filter, not a wall — a run that launched a task
+		// must still be able to read it back, or the fix breaks delegation.
+		const gateway = sharedGateway()
+		const only = runOver(gateway)
+
+		await only.launch('reviewer')
+		const waited = await only.waitFor('tsk_1')
+
+		expect(waited.success).toBe(true)
+	})
+})

package/src/tools/coordinator/__tests__/a-plan-step-reports-its-own-outcome.test.ts

@@ -0,0 +1,215 @@
+import { describe, expect, it } from 'vitest'
+
+import { PlanManager } from '../../../manager/plan/lifecycle.js'
+import type { TaskGateway, TaskHandle } from '../../../types/agent/gateway.js'
+import type { RunId, TaskId } from '../../../types/ids/index.js'
+import type { ToolContext, ToolDefinition } from '../../../types/tool/index.js'
+import { buildCoordinatorTools } from '../index.js'
+
+/**
+ * A plan's steps had no relationship to the work that carried them out.
+ *
+ * `approve_plan` built steps, `create_task` launched workers, and nothing
+ * connected the two — so no step could ever be observed, `updateStepStatus` had
+ * no production caller, and a plan could reach `failed` (the error path calls
+ * `failPlan`) or sit at `executing` forever, but never `completed`.
+ *
+ * Two bindings close it, because there are two kinds of step. A DELEGATED step
+ * reports through the `create_task` that carries it out. An ORCHESTRATOR-OWNED
+ * step has no tool call to bind to at all, and reports through
+ * `update_plan_step` — without which a plan containing one could never settle
+ * however well it went.
+ */
+
+const RUN = 'run_step_binding' as RunId
+
+function gatewayReturning(outcome: 'ok' | 'failed'): TaskGateway {
+	const handle = (taskId: TaskId): TaskHandle => ({
+		taskId,
+		agentId: 'worker',
+		state: 'completed',
+		createdAt: 1_000,
+		completedAt: 2_000,
+		result: (outcome === 'ok'
+			? { status: 'completed', result: 'the work' }
+			: { status: 'failed', lastError: 'the worker died' }) as TaskHandle['result'],
+	})
+	return {
+		async createTask() {
+			return handle('tsk_1' as TaskId)
+		},
+		async waitForTask(id) {
+			return handle(id)
+		},
+		async continueTask() {},
+		cancelTask() {},
+		getTask(id) {
+			return handle(id)
+		},
+		listTasks() {
+			return []
+		},
+		onTaskCompleted() {
+			return () => {}
+		},
+	}
+}
+
+function ctx(): ToolContext {
+	return {
+		runId: RUN,
+		workingDirectory: '/tmp/test',
+		abortSignal: new AbortController().signal,
+		env: {},
+		log: () => {},
+	}
+}
+
+/** An approved two-step plan: one delegated, one the orchestrator's own. */
+function approvedPlan(): PlanManager {
+	const pm = new PlanManager(RUN, async () => ({ approved: true }))
+	pm.startGenerating('do the work')
+	pm.addStep({
+		id: 'step_1',
+		description: 'delegated work',
+		agentId: 'worker',
+		dependsOn: [],
+		order: 1,
+	})
+	pm.addStep({ id: 'step_2', description: 'my own work', dependsOn: [], order: 2 })
+	pm.markReady()
+	pm.approve()
+	pm.startExecution()
+	return pm
+}
+
+function toolsOver(pm: PlanManager, gateway: TaskGateway): (name: string) => ToolDefinition {
+	const tools = buildCoordinatorTools({
+		gateway,
+		workingDirectory: '/tmp/test',
+		allowedAgentIds: ['worker'],
+		getPlanManager: () => pm,
+	})
+	return (name: string) => {
+		const t = tools.find((tool) => tool.name === name)
+		if (!t) throw new Error(`${name} missing from coordinator builder`)
+		return t
+	}
+}
+
+const stepStatus = (pm: PlanManager, id: string) =>
+	pm.active?.steps.find((s) => s.id === id)?.status
+
+describe('a delegated step reports through the launch that carries it out', () => {
+	it('completes the step when the worker succeeded', async () => {
+		const pm = approvedPlan()
+		const named = toolsOver(pm, gatewayReturning('ok'))
+
+		await named('create_task').execute(
+			{ agent_id: 'worker', prompt: 'go', description: 'do it', plan_step_id: 'step_1' },
+			ctx(),
+		)
+
+		expect(stepStatus(pm, 'step_1')).toBe('completed')
+	})
+
+	it('fails the step when the worker failed, from both authorities', async () => {
+		// The handle is `state: 'completed'` with `result.status: 'failed'` —
+		// the split that made a failed worker read as an answer. The step must
+		// follow the run status, not the gateway state.
+		const pm = approvedPlan()
+		const named = toolsOver(pm, gatewayReturning('failed'))
+
+		await named('create_task').execute(
+			{ agent_id: 'worker', prompt: 'go', description: 'do it', plan_step_id: 'step_1' },
+			ctx(),
+		)
+
+		expect(stepStatus(pm, 'step_1')).toBe('failed')
+	})
+
+	it('leaves the plan alone when the launch names no step', async () => {
+		// A launch outside the approved plan must not silently settle one.
+		const pm = approvedPlan()
+		const named = toolsOver(pm, gatewayReturning('ok'))
+
+		await named('create_task').execute(
+			{ agent_id: 'worker', prompt: 'go', description: 'unrelated work' },
+			ctx(),
+		)
+
+		expect(stepStatus(pm, 'step_1')).toBe('pending')
+	})
+})
+
+describe('an orchestrator-owned step reports through update_plan_step', () => {
+	it('records the outcome and says what is still outstanding', async () => {
+		const pm = approvedPlan()
+		const named = toolsOver(pm, gatewayReturning('ok'))
+
+		const result = await named('update_plan_step').execute(
+			{ step_id: 'step_2', status: 'completed' },
+			ctx(),
+		)
+
+		expect(result.success).toBe(true)
+		expect(stepStatus(pm, 'step_2')).toBe('completed')
+		// step_1 has not reported, and saying so is the point — this is what
+		// tells the model the plan cannot settle yet.
+		expect(result.output).toContain('step_1')
+	})
+
+	it('treats skipped as a real outcome, not a failure', async () => {
+		const pm = approvedPlan()
+		const named = toolsOver(pm, gatewayReturning('ok'))
+
+		await named('update_plan_step').execute({ step_id: 'step_2', status: 'skipped' }, ctx())
+
+		expect(stepStatus(pm, 'step_2')).toBe('skipped')
+	})
+
+	it('refuses an id the plan does not have, and names the ones it does', async () => {
+		const pm = approvedPlan()
+		const named = toolsOver(pm, gatewayReturning('ok'))
+
+		const result = await named('update_plan_step').execute(
+			{ step_id: 'step_9', status: 'completed' },
+			ctx(),
+		)
+
+		expect(result.success).toBe(false)
+		expect(result.error).toContain('step_1')
+		expect(result.error).toContain('step_2')
+	})
+})
+
+describe('the two bindings together let a plan settle', () => {
+	it('reaches completed once every step has reported', async () => {
+		const pm = approvedPlan()
+		const named = toolsOver(pm, gatewayReturning('ok'))
+
+		await named('create_task').execute(
+			{ agent_id: 'worker', prompt: 'go', description: 'do it', plan_step_id: 'step_1' },
+			ctx(),
+		)
+		await named('update_plan_step').execute({ step_id: 'step_2', status: 'completed' }, ctx())
+
+		expect(pm.unreportedSteps).toHaveLength(0)
+		expect(pm.completePlan()?.status).toBe('completed')
+	})
+
+	it('leaves the plan unsettled while a step is still silent', async () => {
+		// The state the kernel reads before deciding whether to settle. An
+		// unreported step means the caller and the plan disagree about whether
+		// the work is over, and the run must not resolve that by guessing.
+		const pm = approvedPlan()
+		const named = toolsOver(pm, gatewayReturning('ok'))
+
+		await named('create_task').execute(
+			{ agent_id: 'worker', prompt: 'go', description: 'do it', plan_step_id: 'step_1' },
+			ctx(),
+		)
+
+		expect(pm.unreportedSteps.map((s) => s.id)).toEqual(['step_2'])
+	})
+})

package/src/tools/coordinator/__tests__/approve-plan.test.ts

@@ -88,14 +88,30 @@ describe('coordinator approve_plan tool', () => {
 		])
 	})
 
-	it('keeps the bare-approve tool_result output byte-identical', async () => {
+	it('opens with the historical approval sentence, then names the steps', async () => {
+		// This assertion used to be `toBe` on the whole string, guarding the
+		// approve-with-edits change against disturbing the bare-approve path.
+		// It was never a promise that the output would carry nothing more, and
+		// it now carries the step roster — without which `plan_step_id` and
+		// `update_plan_step` name ids the model has never been told.
 		const result = await executeApprovePlan({ approved: true })
 
 		expect(result.success).toBe(true)
-		expect(result.output).toBe(
-			'Plan approved by user. Proceed with execution — launch workers via create_task.',
-		)
-		expect(result.data).toEqual({ approved: true, feedback: undefined })
+		expect(
+			result.output.startsWith(
+				'Plan approved by user. Proceed with execution — launch workers via create_task.',
+			),
+		).toBe(true)
+		expect(result.output).toContain('step_1 — Extract uploaded DOCX files')
+		expect(result.data).toMatchObject({ approved: true, feedback: undefined })
+	})
+
+	it('carries the step ids in data, so a host does not have to parse prose', async () => {
+		const result = await executeApprovePlan({ approved: true })
+
+		expect((result.data as { steps: unknown }).steps).toEqual([
+			{ step_id: 'step_1', description: 'Extract uploaded DOCX files', agent_id: undefined },
+		])
 	})
 
 	it('embeds approve-with-edits feedback in the output and data', async () => {
@@ -105,12 +121,17 @@ describe('coordinator approve_plan tool', () => {
 		})
 
 		expect(result.success).toBe(true)
-		expect(result.output).toBe(
-			'Plan approved by user with required edits — apply them during execution:\n' +
-				'Skip step 2 and use the staging database instead.\n' +
-				'Proceed with execution — launch workers via create_task.',
-		)
-		expect(result.data).toEqual({
+		expect(
+			result.output.startsWith(
+				'Plan approved by user with required edits — apply them during execution:\n' +
+					'Skip step 2 and use the staging database instead.\n' +
+					'Proceed with execution — launch workers via create_task.',
+			),
+		).toBe(true)
+		// The edits stay ahead of the roster: what the user demanded is the
+		// first thing read, and the step list is reference material after it.
+		expect(result.output.indexOf('staging database')).toBeLessThan(result.output.indexOf('step_1'))
+		expect(result.data).toMatchObject({
 			approved: true,
 			feedback: 'Skip step 2 and use the staging database instead.',
 		})

package/src/tools/coordinator/__tests__/completion-delivery.test.ts

@@ -298,6 +298,13 @@ describe('waiting explicitly beats listing in a loop', () => {
 describe('the task listing carries the output it always had', () => {
 	async function listWith(result: string): Promise<string> {
 		const h = harness()
+		// Launch it first. The listing is scoped to what this run launched, so
+		// settling a task the tools never created describes a sibling run's
+		// work — which the listing now declines to show, correctly.
+		await toolNamed(h.tools, 'create_task').execute(
+			{ agent_id: 'reviewer', prompt: 'go', description: 'review', background: true },
+			{} as never,
+		)
 		h.settle({
 			taskId: 'tsk_1' as TaskId,
 			agentId: 'reviewer',

package/src/tools/coordinator/__tests__/task-list.test.ts

@@ -27,13 +27,27 @@ function makeContext(): ToolContext {
 	}
 }
 
+/**
+ * Hands back the seeded handles in order, one per `createTask`.
+ *
+ * The listing is scoped to what this tool set launched, so a fixture that
+ * only stuffed `listTasks()` would now list nothing — and a gateway holding
+ * tasks these tools never launched is precisely the sibling-run case the
+ * scope exists to refuse. So the tests launch through the front door and the
+ * fixture plays along.
+ */
 function gatewayWith(handles: TaskHandle[]): TaskGateway {
+	let nextLaunch = 0
 	return {
 		async createTask() {
-			throw new Error('not used')
+			const h = handles[nextLaunch++]
+			if (!h) throw new Error('fixture ran out of seeded handles')
+			return h
 		},
-		async waitForTask() {
-			throw new Error('not used')
+		async waitForTask(id) {
+			const h = handles.find((x) => x.taskId === id)
+			if (!h) throw new Error(`fixture has no handle ${id}`)
+			return h
 		},
 		async continueTask() {},
 		cancelTask() {},
@@ -79,12 +93,29 @@ function handle(input: {
 	}
 }
 
-function findAgentTaskList(gateway: TaskGateway) {
+/**
+ * Build the coordinator surface, launch each seeded handle through
+ * `create_task`, and return `agent_task_list`.
+ *
+ * Launching is what puts the tasks in this run's scope. Reaching past it to
+ * seed the gateway directly would test a listing nobody can produce.
+ */
+async function agentTaskListOver(seeded: TaskHandle[]) {
 	const tools = buildCoordinatorTools({
-		gateway,
+		gateway: gatewayWith(seeded),
 		workingDirectory: '/tmp/test',
 		allowedAgentIds: ['solution-architecture', 'enterprise-architecture'],
 	})
+
+	const createTask = tools.find((tool) => tool.name === 'create_task')
+	if (!createTask) throw new Error('create_task tool missing from coordinator builder')
+	for (const h of seeded) {
+		await createTask.execute(
+			{ agent_id: h.agentId, prompt: 'work', description: `launch ${h.taskId}` },
+			makeContext(),
+		)
+	}
+
 	const t = tools.find((tool) => tool.name === 'agent_task_list')
 	if (!t) throw new Error('agent_task_list tool missing from coordinator builder')
 	return t
@@ -92,7 +123,7 @@ function findAgentTaskList(gateway: TaskGateway) {
 
 describe('coordinator agent_task_list tool', () => {
 	it('lists every task with state, agent, and timing', async () => {
-		const gateway = gatewayWith([
+		const seeded = [
 			handle({
 				id: 'task_a',
 				agentId: 'solution-architecture',
@@ -114,9 +145,8 @@ describe('coordinator agent_task_list tool', () => {
 				completedAt: 4000,
 				lastError: 'bash exit 1',
 			}),
-		])
-
-		const tool = findAgentTaskList(gateway)
+		]
+		const tool = await agentTaskListOver(seeded)
 		const result = await tool.execute({}, makeContext())
 		expect(result.success).toBe(true)
 		expect(result.output).toMatch(/Tasks: 3 total/)
@@ -131,7 +161,7 @@ describe('coordinator agent_task_list tool', () => {
 	})
 
 	it('filters by state', async () => {
-		const gateway = gatewayWith([
+		const seeded = [
 			handle({
 				id: 'task_a',
 				agentId: 'solution-architecture',
@@ -145,9 +175,8 @@ describe('coordinator agent_task_list tool', () => {
 				state: 'running',
 				createdAt: 1000,
 			}),
-		])
-
-		const tool = findAgentTaskList(gateway)
+		]
+		const tool = await agentTaskListOver(seeded)
 		const result = await tool.execute({ state: 'running' }, makeContext())
 		expect(result.success).toBe(true)
 		const data = result.data as { items: Array<{ task_id: string }> }
@@ -157,7 +186,7 @@ describe('coordinator agent_task_list tool', () => {
 	})
 
 	it('handles an empty gateway', async () => {
-		const tool = findAgentTaskList(gatewayWith([]))
+		const tool = await agentTaskListOver([])
 		const result = await tool.execute({}, makeContext())
 		expect(result.success).toBe(true)
 		expect(result.output).toMatch(/Tasks: 0 total/)
@@ -224,7 +253,7 @@ describe('agent_task_list frames what a worker said', () => {
 	}
 
 	async function render(text: string): Promise<string> {
-		const tool = findAgentTaskList(gatewayWith([withResult(text)]))
+		const tool = await agentTaskListOver([withResult(text)])
 		const out = await tool.execute({}, makeContext())
 		return out.output
 	}
@@ -263,11 +292,9 @@ describe('agent_task_list frames what a worker said', () => {
 	})
 
 	it('says nothing extra for a task that produced no output', async () => {
-		const tool = findAgentTaskList(
-			gatewayWith([
-				handle({ id: 'task_none', agentId: 'reviewer', state: 'running', createdAt: 0 }),
-			]),
-		)
+		const tool = await agentTaskListOver([
+			handle({ id: 'task_none', agentId: 'reviewer', state: 'running', createdAt: 0 }),
+		])
 
 		const out = await tool.execute({}, makeContext())