@namzu/sdk 6.0.0 → 6.2.0

package/src/tools/coordinator/__tests__/allow-delegation.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it } from 'vitest'
+
+import type { TaskGateway } from '../../../types/agent/gateway.js'
+import { buildCoordinatorTools } from '../index.js'
+
+/**
+ * Whether a run may delegate is not the same question as who it may delegate
+ * to, and only the caller can answer the first.
+ *
+ * The roster answers WHO. It cannot answer WHETHER, because two runs are
+ * indistinguishable in it: a supervisor whose roster happens to hold one
+ * specialist, where delegating is the point; and a run whose own persona IS
+ * that specialist, where delegating is delegating to itself. A host builds the
+ * second by putting a specialist's persona into the supervisor shell and its
+ * id into the roster — so a predicate comparing the roster against the
+ * executing agent sees two different ids and cheerfully says "can delegate".
+ *
+ * Measured before this existed: such a run carried `create_task`,
+ * `wait_for_task`, `cancel_task` and `agent_task_list`, byte-identical to a
+ * run that could actually delegate, and the model could only discover the
+ * refusal by spending a turn on it.
+ */
+
+const gateway = {
+	listTasks: () => [],
+	onTaskCompleted: () => () => {},
+} as unknown as TaskGateway
+
+function namesFor(opts: {
+	agentIds: string[]
+	allowDelegation?: boolean
+	withHitl?: boolean
+}): string[] {
+	return buildCoordinatorTools({
+		gateway,
+		workingDirectory: '/tmp/test',
+		allowedAgentIds: opts.agentIds,
+		...(opts.allowDelegation !== undefined ? { allowDelegation: opts.allowDelegation } : {}),
+		...(opts.withHitl
+			? { resumeHandler: (async () => ({ action: 'continue' })) as never, runId: 'run_1' as never }
+			: {}),
+	}).map((t) => t.name)
+}
+
+describe('a run can decline to delegate while still naming who it would have called', () => {
+	it('withholds the delegation tools when delegation is off', () => {
+		const names = namesFor({ agentIds: ['specialist'], allowDelegation: false })
+
+		expect(names).not.toContain('create_task')
+		expect(names).not.toContain('wait_for_task')
+		expect(names).not.toContain('cancel_task')
+	})
+
+	it('produces exactly the empty-roster surface', () => {
+		// The two reasons differ but the outcome is the same one tool, so a
+		// reader does not have to hold two shapes in their head.
+		expect(namesFor({ agentIds: ['specialist'], allowDelegation: false })).toEqual(
+			namesFor({ agentIds: [] }),
+		)
+	})
+
+	it('keeps the listing, because a run may still want to see what is running', () => {
+		expect(namesFor({ agentIds: ['specialist'], allowDelegation: false })).toContain(
+			'agent_task_list',
+		)
+	})
+
+	it('leaves the human channel alone — that is not delegation', () => {
+		// `approve_plan` and `ask_user_question` are the HITL park surface. A
+		// run that must not delegate needs them as much as any other.
+		const names = namesFor({ agentIds: ['specialist'], allowDelegation: false, withHitl: true })
+
+		expect(names).toContain('ask_user_question')
+	})
+})
+
+describe('an absent flag changes nothing', () => {
+	it('mounts the full surface, as it always did', () => {
+		const names = namesFor({ agentIds: ['specialist'] })
+
+		expect(names).toContain('create_task')
+		expect(names).toContain('wait_for_task')
+		expect(names).toContain('cancel_task')
+		expect(names).toContain('agent_task_list')
+	})
+
+	it('is identical to opting in explicitly', () => {
+		// So adopting the flag cannot change a caller that says yes out loud.
+		expect(namesFor({ agentIds: ['a', 'b'], allowDelegation: true })).toEqual(
+			namesFor({ agentIds: ['a', 'b'] }),
+		)
+	})
+
+	it('still withholds everything on an empty roster, flag or no flag', () => {
+		expect(namesFor({ agentIds: [], allowDelegation: true })).toEqual(['agent_task_list'])
+	})
+})
+
+describe('the flag is absolute', () => {
+	it('cannot be overridden back on', () => {
+		// Worth a test precisely because the opposite is the intuitive guess:
+		// "explicit beats implicit" would say a runtime override should win.
+		// It cannot, mechanically — the override pass in SupervisorAgent runs
+		// over the array this builder returns, and there is no entry for it to
+		// act on. And it should not: both values come from the same caller in
+		// the same call, so "this run must not delegate" plus "give it
+		// create_task" is a caller contradicting itself, not one who knows
+		// something extra.
+		//
+		// Same rule the empty roster has always had.
+		const tools = buildCoordinatorTools({
+			gateway,
+			workingDirectory: '/tmp/test',
+			allowedAgentIds: ['specialist'],
+			allowDelegation: false,
+		})
+
+		expect(tools.find((t) => t.name === 'create_task')).toBeUndefined()
+	})
+})

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')
 	})
 })