@namzu/sdk 10.0.0 → 11.0.0

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