@namzu/sdk 10.0.0 → 12.0.0

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())