@namzu/sdk 9.0.0 → 11.0.0

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

package/src/tools/coordinator/index.ts

@@ -308,6 +308,33 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 		// compatibility (Agent tool consumes it from its own path).
 	} = opts
 	const cwd = opts.workingDirectory
+
+	/**
+	 * The tasks THIS surface launched — the scope of everything it will read back.
+	 *
+	 * A `TaskGateway` is shared on purpose: `SupervisorAgentConfig.gateway`
+	 * exists so a host can hand the same one to several runs. `listTasks()` is
+	 * therefore gateway-wide by design, and `agent_task_list` used to hand that
+	 * straight to the model — so a supervisor could read a sibling run's worker
+	 * output, including the `result` field, by listing. `wait_for_task` had the
+	 * same reach through `getTask`.
+	 *
+	 * That is the leak `CompletionInbox` closed on the push side, through a
+	 * different door: the inbox refuses a completion for a task it was not told
+	 * about, precisely because `onTaskCompleted` is a broadcast. The pull side
+	 * kept no such record and asked the gateway directly.
+	 *
+	 * The scope lives here rather than in `listTasks()` because the two answer
+	 * different questions. A host calling `listTasks()` is the operator and may
+	 * legitimately want everything on its gateway; a model calling
+	 * `agent_task_list` is one run asking about its own work. Narrowing the
+	 * gateway method would take the operator's view away to fix the model's.
+	 *
+	 * Consequence worth stating: a task launched through a DIFFERENT surface on
+	 * the same gateway — `buildAgentTool`, or the host itself — is not listed
+	 * here. That is the same rule, not an exception to it.
+	 */
+	const launchedHere = new Set<TaskId>()
 	void opts.onTaskLaunched
 
 	const agentIdEnum = delegateSchema(agentIds)
@@ -386,6 +413,12 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 				.describe(
 					'Existing planning task ID to link. If omitted, a planning task is auto-created.',
 				),
+			plan_step_id: z
+				.string()
+				.optional()
+				.describe(
+					'The approve_plan step this launch carries out (e.g. "step_2"). Pass it and the step reports its own outcome — running on launch, completed or failed when the worker settles — so the plan can say how it went. Omit it only when this launch is not part of the approved plan.',
+				),
 			...(canLaunchInBackground
 				? {
 						background: z
@@ -407,9 +440,24 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 		// children were observed at 8m04s, which it would have survived by
 		// under two minutes.
 		timeoutMs: DELEGATION_TIMEOUT_MS,
-		async execute({ agent_id, prompt, description, plan_task_id, background }, _context) {
+		async execute(
+			{ agent_id, prompt, description, plan_task_id, plan_step_id, background },
+			_context,
+		) {
 			let resolvedPlanTaskId = plan_task_id
 
+			// The binding between a plan step and the work that carries it out.
+			// Without it a plan's steps had no relationship to any tool call, so
+			// nothing could ever observe how a step went — which is why a plan
+			// could report `failed` or stay `executing` forever but never
+			// `completed`.
+			const planStepId = plan_step_id
+			const reportStep = (status: 'running' | 'completed' | 'failed', error?: string): void => {
+				if (!planStepId) return
+				getPlanManager?.()?.updateStepStatus(planStepId, status, error)
+			}
+			reportStep('running')
+
 			if (taskStore) {
 				if (resolvedPlanTaskId) {
 					await taskStore.update(resolvedPlanTaskId as `task_${string}`, {
@@ -446,6 +494,9 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 			// is exactly the blocking launch whose wait was abandoned.
 			completionInbox?.launched(handle.taskId)
 
+			// ...and whose it is for the READ side too. See `launchedHere`.
+			launchedHere.add(handle.taskId)
+
 			// A background launch asked for with nowhere to deliver it is
 			// REFUSED, not quietly turned into a blocking one.
 			//
@@ -469,6 +520,10 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 						description: 'Failed: the launch was refused before any worker started',
 					})
 				}
+				// Same reason the plan task is closed here: nothing is running,
+				// so a step left `running` would show work underway with no
+				// worker behind it, and the plan could never settle.
+				reportStep('failed', 'the launch was refused before any worker started')
 				return {
 					success: false,
 					output: '',
@@ -569,6 +624,11 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 				})
 			}
 
+			// The step reports the same outcome, from the same two authorities.
+			// This is the only point in a delegated launch where the answer is
+			// actually known.
+			reportStep(success ? 'completed' : 'failed', success ? undefined : resultText.slice(0, 200))
+
 			return {
 				success,
 				// Framed, because a delegated worker is the component MOST
@@ -631,6 +691,21 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 		// waiting. Same bound as the launch it is waiting on.
 		timeoutMs: DELEGATION_TIMEOUT_MS,
 		async execute({ task_id }, _context) {
+			// Same scope as the listing — see `launchedHere`. Asked FIRST, so a
+			// task belonging to a sibling run on a shared gateway is refused
+			// here rather than waited on and then read.
+			if (!launchedHere.has(task_id as TaskId)) {
+				// Deliberately does not distinguish "never existed" from
+				// "belongs to someone else". The second answer is itself the
+				// leak in miniature: it confirms a task id a run was not
+				// supposed to know about.
+				return {
+					success: false,
+					output: `No task ${task_id} was launched by this run. Call agent_task_list to see the tasks you can wait on.`,
+					data: { task_id },
+				}
+			}
+
 			const known = gateway.getTask(task_id as TaskId)
 			if (!known) {
 				return {
@@ -716,7 +791,7 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 
 	const agentTaskList = defineTool({
 		name: 'agent_task_list',
-		description: `Inspect the live state of every agent task launched on this gateway via create_task: returns each task's id, agent, state (pending/running/completed/failed/canceled), and timing. Distinct from the plan-task store's \`task_list\` (which lists planning tasks): this tool lists running/completed worker invocations. ${listingAdvice}`,
+		description: `Inspect the live state of the agent tasks YOU launched with create_task: returns each task's id, agent, state (pending/running/completed/failed/canceled), and timing. Tasks launched by another run are not listed, even when it shares this gateway. Distinct from the plan-task store's \`task_list\` (which lists planning tasks): this tool lists running/completed worker invocations. ${listingAdvice}`,
 		inputSchema: z.object({
 			state: z
 				.enum(['pending', 'running', 'completed', 'failed', 'canceled'])
@@ -729,7 +804,10 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 		destructive: false,
 		concurrencySafe: true,
 		async execute({ state }) {
-			const handles = gateway.listTasks()
+			// Scoped to this run's own launches — see `launchedHere`. The
+			// gateway may hold a sibling run's tasks, and this listing is not
+			// the door to them.
+			const handles = gateway.listTasks().filter((h) => launchedHere.has(h.taskId))
 			const filtered = state ? handles.filter((h) => h.state === state) : handles
 			const items = filtered.map((h) => {
 				const runStatus = h.result?.status
@@ -965,17 +1043,38 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 
 				if (response.approved) {
 					pm.startExecution()
+
+					// The step ids, because nothing else tells the model what
+					// they are. `plan_step_id` on create_task and `step_id` on
+					// update_plan_step are both unusable without them — a
+					// binding the caller cannot name is a binding that does not
+					// exist. Rendered from the plan as approved, so a plan the
+					// user edited lists the steps they actually approved.
+					const roster = (pm.active?.steps ?? [])
+						.map((s) => `  ${s.id} — ${s.description}${s.agentId ? ` (${s.agentId})` : ''}`)
+						.join('\n')
+					const howToReport = roster
+						? `\nSteps, and how each reports its outcome:\n${roster}\nPass plan_step_id to create_task for a delegated step; call update_plan_step for one you do yourself. The plan cannot report success until every step has reported.`
+						: ''
+
 					// Approve-with-edits: when the user attached feedback to an
 					// approval, embed it in the model-visible output so the
-					// supervisor applies the edits during execution. A bare
-					// approve keeps the historical output byte-identical.
+					// supervisor applies the edits during execution.
 					const output = response.feedback
-						? `Plan approved by user with required edits — apply them during execution:\n${response.feedback}\nProceed with execution — launch workers via create_task.`
-						: 'Plan approved by user. Proceed with execution — launch workers via create_task.'
+						? `Plan approved by user with required edits — apply them during execution:\n${response.feedback}\nProceed with execution — launch workers via create_task.${howToReport}`
+						: `Plan approved by user. Proceed with execution — launch workers via create_task.${howToReport}`
 					return {
 						success: true,
 						output,
-						data: { approved: true, feedback: response.feedback },
+						data: {
+							approved: true,
+							feedback: response.feedback,
+							steps: (pm.active?.steps ?? []).map((s) => ({
+								step_id: s.id,
+								description: s.description,
+								agent_id: s.agentId,
+							})),
+						},
 					}
 				}
 
@@ -991,6 +1090,76 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 			},
 		})
 		tools.push(approvePlan)
+
+		/**
+		 * How a step the ORCHESTRATOR did reports its own outcome.
+		 *
+		 * `create_task` reports the steps it carries out, which covers every
+		 * delegated step. A step with no `agent_id` is the orchestrator's own
+		 * work and has no tool call to bind to — so without this there is no
+		 * way for it to ever report, and a plan containing one could never
+		 * settle no matter how well it went.
+		 *
+		 * `skipped` is a first-class outcome and not a euphemism for failure:
+		 * a plan that turned out not to need a step went right, and forcing
+		 * that into `completed` or `failed` would make the plan lie in one
+		 * direction or the other.
+		 */
+		const updatePlanStep = defineTool({
+			name: 'update_plan_step',
+			description:
+				'Report how a step of the approved plan went. Use it for steps YOU carried out — steps delegated with create_task report themselves when you pass plan_step_id. Call it as each step settles, not in a batch at the end: the plan cannot say it succeeded until every step has reported, and an unreported step is not scored as a failure, it simply leaves the plan unsettled. Use "skipped" for a step that turned out not to be needed; that is a successful outcome, not a failure.',
+			inputSchema: z.object({
+				step_id: z.string().describe('The plan step id, e.g. "step_2".'),
+				status: z
+					.enum(['completed', 'skipped', 'failed'])
+					.describe(
+						'How it went. "skipped" means the step was not needed and the plan is still on track.',
+					),
+				error: z
+					.string()
+					.optional()
+					.describe('What went wrong. Only meaningful with status "failed".'),
+			}),
+			category: 'custom',
+			permissions: [],
+			readOnly: false,
+			destructive: false,
+			concurrencySafe: true,
+			async execute({ step_id, status, error }) {
+				const pm = getPlanManager?.()
+				if (!pm?.active) {
+					return {
+						success: false,
+						output: '',
+						error: 'There is no active plan to report against. Call approve_plan first.',
+					}
+				}
+
+				const step = pm.updateStepStatus(step_id, status, error)
+				if (!step) {
+					const known = pm.active.steps.map((s) => s.id).join(', ')
+					return {
+						success: false,
+						output: '',
+						error: `No plan step "${step_id}". This plan's steps are: ${known || '(none)'}.`,
+					}
+				}
+
+				const outstanding = pm.unreportedSteps
+				return {
+					success: true,
+					output:
+						outstanding.length === 0
+							? `Step ${step_id} reported as ${status}. Every step has now reported.`
+							: `Step ${step_id} reported as ${status}. Still unreported: ${outstanding
+									.map((s) => s.id)
+									.join(', ')}.`,
+					data: { step_id, status, unreported: outstanding.map((s) => s.id) },
+				}
+			},
+		})
+		tools.push(updatePlanStep)
 	}
 
 	if (resumeHandler && runId) {