@namzu/sdk 5.2.0 → 6.1.0

package/src/runtime/query/index.ts

@@ -410,6 +410,16 @@ export interface QueryParams {
 
 	taskGateway?: import('../../types/agent/gateway.js').TaskGateway
 
+	/**
+	 * Where a worker completion goes when no tool call is waiting for it.
+	 *
+	 * Supplied by whoever built the coordinator tools, because the tools and
+	 * this loop have to share one inbox: the tools claim what they deliver,
+	 * and the loop delivers what is left. Omitted, the loop drains nothing and
+	 * the behaviour is exactly what it was before the inbox existed.
+	 */
+	completionInbox?: import('../../gateway/completion-inbox.js').CompletionInbox
+
 	launchedTasks?: Map<
 		import('../../types/ids/index.js').TaskId,
 		import('./iteration/phases/context.js').LaunchedTaskMeta
@@ -842,6 +852,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		checkpointMgr,
 		planManager: ctx.planManager,
 		taskGateway: params.taskGateway,
+		completionInbox: params.completionInbox,
 		taskStore: params.taskStore,
 		launchedTasks: params.launchedTasks ?? new Map(),
 		// Run-scoped. An approval is a statement about this run's work;

package/src/runtime/query/iteration/index.ts

@@ -5,6 +5,7 @@ import {
 	DEFAULT_STRUCTURED_OUTPUT_RETRIES,
 	STRUCTURED_OUTPUT_REPROMPT,
 } from '../../../constants/tools/index.js'
+import { formatCompletionNotification } from '../../../gateway/completion-inbox.js'
 import { renderSkillsSection } from '../../../persona/assembler.js'
 import { collect } from '../../../provider/collect.js'
 import {
@@ -61,6 +62,16 @@ export type { ToolReviewOutcome } from './phases/index.js'
  */
 const DEFAULT_ANSWER_REVIEW_LIMIT = 3
 
+/**
+ * How long a finishing run waits for a background worker it launched.
+ *
+ * Long enough to be worth having — a delegated worker doing real work takes
+ * minutes — and bounded because a worker that never finishes must not hold
+ * the run open forever. `maxIterations` bounds how many times this can
+ * happen, and the run's own timeout bounds the whole thing regardless.
+ */
+const BACKGROUND_TASK_GRACE_MS = 120_000
+
 export class IterationOrchestrator {
 	private ctx: IterationContext
 	/** Rejections so far. See {@link DEFAULT_ANSWER_REVIEW_LIMIT}. */
@@ -207,7 +218,13 @@ export class IterationOrchestrator {
 				// supplied no hook.
 				const step = await this.prepareStep(iterationNum)
 
-				const llmTools = this.ctx.tools.toLLMTools(step.allowedTools ?? this.ctx.allowedTools)
+				const stepAllowedTools = step.allowedTools ?? this.ctx.allowedTools
+				const llmTools = this.ctx.tools.toLLMTools(stepAllowedTools)
+				// The same list the request was built from now also bounds what
+				// may run. Narrowing only the request left the restriction
+				// presentational — the model was shown fewer tools and could
+				// still call any of them by name.
+				this.ctx.toolExecutor.setStepAllowedTools(stepAllowedTools)
 				const enforceToolInputSchema = enforcedModelInputToolNames(this.ctx.tools, llmTools)
 				const stepModel = step.model ?? model
 
@@ -551,6 +568,36 @@ export class IterationOrchestrator {
 						}
 					}
 
+					// A background worker is still out there, and this turn was
+					// about to end the run.
+					//
+					// Settling here would throw away the very thing the launch
+					// existed to produce: the supervisor said "launched", the
+					// worker had not finished, and the run closed over it. So
+					// the run is held open — bounded by the deadline below and
+					// by `maxIterations` above, so a worker that never finishes
+					// cannot keep it open forever — and the completion arrives
+					// as a notification the next turn reads.
+					if (!forceFinalize && this.ctx.completionInbox?.hasPendingWork) {
+						this.ctx.log.info('Holding the run open for a background task', {
+							runId: runMgr.id,
+							iteration: iterationNum,
+						})
+						await this.ctx.completionInbox.waitForArrival(BACKGROUND_TASK_GRACE_MS)
+						const arrived = this.ctx.completionInbox.drain()
+						if (arrived.length > 0) {
+							runMgr.pushMessage(createUserMessage(formatCompletionNotification(arrived)))
+							await this.ctx.emitEvent({
+								type: 'iteration_completed',
+								runId: runMgr.id,
+								iteration: iterationNum,
+								hasToolCalls: false,
+							})
+							yield* this.ctx.drainPending()
+							continue
+						}
+					}
+
 					if (!hasContent && !forceFinalize) {
 						this.ctx.log.warn('Empty completion detected — requesting final summary', {
 							iteration: iterationNum,
@@ -674,6 +721,35 @@ export class IterationOrchestrator {
 					return
 				}
 
+				// Workers that finished with nobody listening.
+				//
+				// A completion normally reaches the supervisor as the
+				// `tool_result` of the `create_task` that launched it. Two
+				// cases have no such call: a launch made in the background on
+				// purpose, and a blocking launch whose deadline passed — the
+				// model was told "timed out, it may still be running" and the
+				// worker then finished, holding a result nothing would read.
+				//
+				// This is the channel that was removed in `dc16d58` because it
+				// double-delivered: it fired for completions the blocking tool
+				// had already handed over, so the supervisor saw each result
+				// twice. The inbox restores it with the distinction that was
+				// missing — a tool that delivers a completion claims it, and
+				// only unclaimed ones arrive here.
+				//
+				// Placed beside the advisory phase deliberately: that is the
+				// established seam for putting a user message in after tool
+				// results and before the next turn.
+				const unheard = this.ctx.completionInbox?.drain() ?? []
+				if (unheard.length > 0) {
+					this.ctx.log.info('Delivering unawaited task completions', {
+						runId: runMgr.id,
+						iteration: iterationNum,
+						tasks: unheard.map((h) => h.taskId),
+					})
+					runMgr.pushMessage(createUserMessage(formatCompletionNotification(unheard)))
+				}
+
 				await runAdvisoryPhase(this.ctx, iterationNum, response)
 
 				if (this.ctx.pluginManager) {

package/src/runtime/query/iteration/phases/context.ts

@@ -3,6 +3,7 @@ import type { AgentBus } from '../../../../bus/index.js'
 import type { WorkingStateManager } from '../../../../compaction/manager.js'
 import type { ContextReducer } from '../../../../compaction/reducer.js'
 import type { CompactionConfig } from '../../../../config/runtime.js'
+import type { CompletionInbox } from '../../../../gateway/completion-inbox.js'
 import type { PlanManager } from '../../../../manager/plan/lifecycle.js'
 import type { RunPersistence } from '../../../../manager/run/persistence.js'
 import type { ActivityStore } from '../../../../store/activity/memory.js'
@@ -103,6 +104,15 @@ export interface IterationContext {
 
 	readonly taskGateway?: TaskGateway
 
+	/**
+	 * Completions no call is waiting for, on their way to the transcript.
+	 *
+	 * Absent means the loop behaves exactly as it did before this existed:
+	 * a blocking `create_task` still delivers its own result, and a
+	 * completion nobody awaited is simply never mentioned.
+	 */
+	readonly completionInbox?: CompletionInbox
+
 	readonly taskStore?: TaskStore
 
 	readonly launchedTasks: Map<TaskId, LaunchedTaskMeta>

package/src/runtime/query/result.ts

@@ -129,6 +129,12 @@ export class ResultAssembler {
 					providerId: err.providerId,
 					...(err.status !== undefined ? { status: err.status } : {}),
 					...(err.retryAfterMs !== undefined ? { retryAfterMs: err.retryAfterMs } : {}),
+					// The provider's own sentence, already truncated and scrubbed
+					// by the driver. Without it a host rendering this metadata
+					// knows a request was rejected but not which field, and has to
+					// go re-parse `error` to find out — which is exactly the
+					// re-parsing the line above says this exists to avoid.
+					...(err.detail !== undefined ? { detail: err.detail } : {}),
 				}
 			: undefined
 		runMgr.markFailed(errorMessage, providerError)

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

@@ -0,0 +1,347 @@
+import { describe, expect, it } from 'vitest'
+
+import { CompletionInbox } from '../../../gateway/completion-inbox.js'
+import type { TaskGateway, TaskHandle } from '../../../types/agent/gateway.js'
+import type { TaskId } from '../../../types/ids/index.js'
+import type { ToolDefinition } from '../../../types/tool/index.js'
+import { DELEGATION_TIMEOUT_MS, buildCoordinatorTools } from '../index.js'
+
+/**
+ * Who claims a completion, and who is left to announce it.
+ *
+ * A worker's output normally rides back as the `tool_result` of the
+ * `create_task` that launched it. Two situations have no such call:
+ *
+ *  - the launch was made in the background on purpose;
+ *  - the launch blocked, the executor's deadline passed, and the model was
+ *    told *"timed out… it may still be running"*. The worker then finished
+ *    normally and its result had no reader at all.
+ *
+ * The second one was the live defect: a supervisor whose `create_task` timed
+ * out lost both the task id and the output, and `agent_task_list` — the only
+ * tool it had left — reported id, state and duration while withholding the
+ * one field it was looking for. `agent_task_list` in a sleep loop was not the
+ * model misbehaving; it was the only move on the board.
+ *
+ * These tests drive the claim/announce split from the tool side, because the
+ * inbox can only tell a delivered completion from an abandoned one if the
+ * tools tell it the truth.
+ */
+
+interface Harness {
+	tools: ToolDefinition[]
+	inbox: CompletionInbox
+	settle: (handle: TaskHandle) => void
+	/** Resolve the pending `waitForTask` for this task. */
+	finish: (taskId: string, result: string) => void
+}
+
+function harness(opts: { autoFinish?: boolean } = {}): Harness {
+	const listeners = new Set<(h: TaskHandle) => void>()
+	const waiters = new Map<string, (h: TaskHandle) => void>()
+	const handles = new Map<string, TaskHandle>()
+	let seq = 0
+
+	const makeHandle = (taskId: string, result?: string): TaskHandle => ({
+		taskId: taskId as TaskId,
+		agentId: 'reviewer',
+		state: 'completed',
+		createdAt: 1_000,
+		completedAt: 2_000,
+		...(result !== undefined
+			? { result: { status: 'completed', result } as TaskHandle['result'] }
+			: {}),
+	})
+
+	const gateway = {
+		createTask: async () => {
+			seq += 1
+			const taskId = `tsk_${seq}`
+			const handle: TaskHandle = { ...makeHandle(taskId), state: 'running' }
+			handles.set(taskId, handle)
+			return handle
+		},
+		waitForTask: (taskId: TaskId) =>
+			new Promise<TaskHandle>((resolve) => {
+				if (opts.autoFinish) {
+					resolve(makeHandle(taskId, 'the worker output'))
+					return
+				}
+				waiters.set(taskId, resolve)
+			}),
+		getTask: (taskId: TaskId) => handles.get(taskId),
+		listTasks: () => [...handles.values()],
+		cancelTask: () => undefined,
+		continueTask: async () => undefined,
+		onTaskCompleted: (cb: (h: TaskHandle) => void) => {
+			listeners.add(cb)
+			return () => listeners.delete(cb)
+		},
+	} as unknown as TaskGateway
+
+	const inbox = new CompletionInbox()
+	inbox.attach(gateway)
+
+	return {
+		inbox,
+		tools: buildCoordinatorTools({
+			gateway,
+			completionInbox: inbox,
+			workingDirectory: '/tmp/test',
+			allowedAgentIds: ['reviewer'],
+		}),
+		settle: (handle) => {
+			handles.set(handle.taskId, handle)
+			for (const cb of listeners) cb(handle)
+		},
+		finish: (taskId, result) => {
+			const handle = makeHandle(taskId, result)
+			handles.set(taskId, handle)
+			waiters.get(taskId)?.(handle)
+		},
+	}
+}
+
+function toolNamed(tools: ToolDefinition[], name: string): ToolDefinition {
+	const tool = tools.find((t) => t.name === name)
+	if (!tool) throw new Error(`${name} is not registered`)
+	return tool
+}
+
+describe('the supervisor has a tool for every move it needs', () => {
+	it('registers a way to wait, so polling is no longer the only option', () => {
+		// Before this, waiting meant `continue_task` — which blocks only as a
+		// side effect of sending a message, so a supervisor that just wanted
+		// to wait had to invent something to say.
+		const names = harness().tools.map((t) => t.name)
+
+		expect(names).toContain('wait_for_task')
+	})
+
+	it('registers a way to cancel, which background launching makes necessary', () => {
+		// `cancel_task` was defined in this file and never returned from it.
+		// It matters now: a background launch can leave a worker running with
+		// nothing waiting on it, and without this the supervisor could start
+		// one it had no way to stop.
+		expect(harness().tools.map((t) => t.name)).toContain('cancel_task')
+	})
+
+	it('gives the launching tool a deadline a real worker can meet', () => {
+		// The run default is two minutes; a delegated worker doing real work
+		// takes longer, and every expiry past that point produced the state
+		// this whole change exists to repair. Not firing at all beats
+		// recovering well.
+		expect(toolNamed(harness().tools, 'create_task').timeoutMs).toBe(DELEGATION_TIMEOUT_MS)
+	})
+
+	it('gives the waiting tool a deadline longer than the executor default', () => {
+		// A tool whose entire job is to wait must not be killed for waiting.
+		// `ToolExecutor` reads `timeoutMs` before falling back to the run
+		// default, so declaring one here is the supported way to say so.
+		expect(toolNamed(harness().tools, 'wait_for_task').timeoutMs).toBe(DELEGATION_TIMEOUT_MS)
+	})
+
+	it('mounts none of them when there is no roster to delegate to', () => {
+		const tools = buildCoordinatorTools({
+			gateway: { onTaskCompleted: () => () => {} } as unknown as TaskGateway,
+			workingDirectory: '/tmp/test',
+			allowedAgentIds: [],
+		})
+
+		expect(tools.map((t) => t.name)).toEqual(['agent_task_list'])
+	})
+})
+
+describe('a blocking launch claims its own completion', () => {
+	it('delivers the output inline and leaves nothing to announce', () => {
+		// The `dc16d58` case: this result reached the model as a tool_result,
+		// so an envelope carrying it again would be the duplicate delivery
+		// that removal fixed.
+		const h = harness({ autoFinish: true })
+
+		return toolNamed(h.tools, 'create_task')
+			.execute({ agent_id: 'reviewer', prompt: 'go', description: 'review' }, {} as never)
+			.then((result) => {
+				expect(result.success).toBe(true)
+				expect(result.output).toContain('the worker output')
+				expect(h.inbox.drain()).toEqual([])
+			})
+	})
+})
+
+describe('an abandoned launch leaves its completion to be announced', () => {
+	it('does not claim when the executor already gave up on the call', async () => {
+		// This is the whole fix. The executor's deadline passed, the model was
+		// told the tool timed out, and whatever this call returns now is
+		// discarded — so claiming here would delete the worker's output for
+		// good.
+		const h = harness({ autoFinish: true })
+		const aborted = AbortSignal.abort()
+
+		const result = await toolNamed(h.tools, 'create_task').execute(
+			{ agent_id: 'reviewer', prompt: 'go', description: 'review' },
+			{ abortSignal: aborted } as never,
+		)
+
+		expect(result.success).toBe(false)
+		// It also says where the result WILL turn up, rather than leaving the
+		// model to conclude the work was lost.
+		expect(result.output).toContain('task notification')
+
+		h.settle({
+			taskId: 'tsk_1' as TaskId,
+			agentId: 'reviewer',
+			state: 'completed',
+			createdAt: 1_000,
+			completedAt: 2_000,
+			result: {
+				status: 'completed',
+				result: 'the worker output',
+			} as TaskHandle['result'],
+		})
+
+		expect(h.inbox.drain().map((x) => x.taskId)).toEqual(['tsk_1'])
+	})
+})
+
+describe('a background launch returns a handle instead of a result', () => {
+	it('hands back the task id straight away and does not wait', async () => {
+		// `autoFinish` is off, so `waitForTask` never resolves here. If the
+		// background path awaited it, this test would hang — which is the
+		// point: returning is what lets the supervisor keep working.
+		const h = harness()
+
+		const result = await toolNamed(h.tools, 'create_task').execute(
+			{
+				agent_id: 'reviewer',
+				prompt: 'go',
+				description: 'review',
+				background: true,
+			},
+			{} as never,
+		)
+
+		expect(result.success).toBe(true)
+		expect((result.data as { task_id?: string } | undefined)?.task_id).toBe('tsk_1')
+		// In `output` too, not only in `data` — the executor builds the
+		// tool_result from `output` alone, so an id that lives only in `data`
+		// is an id the model never receives.
+		expect(result.output).toContain('tsk_1')
+		// And it tells the model what happens next, so "launched" does not
+		// read as "finished".
+		expect(result.output).toContain('task notification')
+	})
+
+	it('leaves the completion for the transcript', async () => {
+		const h = harness()
+		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',
+			state: 'completed',
+			createdAt: 1_000,
+			completedAt: 2_000,
+			result: { status: 'completed', result: 'done' } as TaskHandle['result'],
+		})
+
+		expect(h.inbox.drain()).toHaveLength(1)
+	})
+})
+
+describe('waiting explicitly beats listing in a loop', () => {
+	it('returns the output and claims it', async () => {
+		const h = harness({ autoFinish: true })
+		await toolNamed(h.tools, 'create_task').execute(
+			{
+				agent_id: 'reviewer',
+				prompt: 'go',
+				description: 'review',
+				background: true,
+			},
+			{} as never,
+		)
+
+		const result = await toolNamed(h.tools, 'wait_for_task').execute(
+			{ task_id: 'tsk_1' },
+			{} as never,
+		)
+
+		expect(result.success).toBe(true)
+		expect(result.output).toContain('the worker output')
+		// Claimed, so it is not also announced.
+		expect(h.inbox.drain()).toEqual([])
+	})
+
+	it('says so plainly rather than hanging on an id that does not exist', async () => {
+		const h = harness()
+
+		const result = await toolNamed(h.tools, 'wait_for_task').execute(
+			{ task_id: 'tsk_nope' },
+			{} as never,
+		)
+
+		expect(result.success).toBe(false)
+		expect(result.output).toContain('No task')
+	})
+})
+
+describe('the task listing carries the output it always had', () => {
+	async function listWith(result: string): Promise<string> {
+		const h = harness()
+		h.settle({
+			taskId: 'tsk_1' as TaskId,
+			agentId: 'reviewer',
+			state: 'completed',
+			createdAt: 1_000,
+			completedAt: 2_000,
+			result: { status: 'completed', result } as TaskHandle['result'],
+		})
+		const listed = await toolNamed(h.tools, 'agent_task_list').execute({}, {} as never)
+		return listed.output
+	}
+
+	it('puts the worker result where the model can actually read it', async () => {
+		// Two failures stacked here. The projection read `h.result` for the
+		// status and the error and stopped one property short of the thing the
+		// task was launched to produce — and the obvious repair, adding it to
+		// `data`, would have been invisible: the executor builds the
+		// tool_result from `output` alone and never reads `data`. So the fix
+		// has to land in the RENDERED text, and this asserts on `output` for
+		// that reason.
+		expect(await listWith('the findings')).toContain('the findings')
+	})
+
+	it('names the tool that fetches the rest when it truncates', async () => {
+		const output = await listWith('x'.repeat(6_000))
+
+		expect(output).toContain('truncated')
+		expect(output).toContain('wait_for_task with "tsk_1"')
+	})
+
+	it('still lists a task that has produced nothing yet', async () => {
+		const h = harness()
+		await toolNamed(h.tools, 'create_task').execute(
+			{
+				agent_id: 'reviewer',
+				prompt: 'go',
+				description: 'review',
+				background: true,
+			},
+			{} as never,
+		)
+
+		const listed = await toolNamed(h.tools, 'agent_task_list').execute({}, {} as never)
+
+		expect(listed.output).toContain('tsk_1')
+		expect(listed.output).toContain('running')
+	})
+})

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

@@ -180,7 +180,7 @@ describe('coordinator agent_task_list tool', () => {
 		expect(names).not.toContain('task_list')
 	})
 
-	it('does not advertise per-task cancellation on the blocking coordinator surface', () => {
+	it('advertises per-task cancellation now that a task can outlive its launch', () => {
 		const coordinatorTools = buildCoordinatorTools({
 			gateway: gatewayWith([]),
 			workingDirectory: '/tmp/test',
@@ -188,11 +188,17 @@ describe('coordinator agent_task_list tool', () => {
 		})
 		const names = coordinatorTools.map((tool) => tool.name)
 
-		// create_task returns only after the worker is terminal, so the
-		// supervisor cannot know a live task id in a later model turn.
-		// Keeping cancel_task here only manufactured success for missing
-		// or terminal ids because every gateway cancellation is a void
-		// no-op in those states.
-		expect(names).not.toContain('cancel_task')
+		// This assertion used to be its own inverse, and the reasoning was
+		// correct at the time: create_task returned only after the worker was
+		// terminal, so the supervisor could never hold a LIVE task id in a
+		// later turn, and cancel_task could only manufacture success for
+		// something already finished.
+		//
+		// `background: true` reinstates the precondition that argument rested
+		// on. A background launch hands back an id while the worker is still
+		// running, and a supervisor able to start one it cannot stop is a
+		// hole — so the tool comes back with the capability that makes it
+		// mean something.
+		expect(names).toContain('cancel_task')
 	})
 })