@namzu/sdk 14.0.6 → 15.0.0

package/src/tools/coordinator/__tests__/agent.test.ts

@@ -1,177 +0,0 @@
-/**
- * Behavioural contract for `buildAgentTool`:
- *
- * - Reports `success: true` only when BOTH the gateway task state and
- *   the underlying `BaseAgentResult.status` say completed.
- * - Reports `success: false` and surfaces `lastError` when either
- *   layer disagrees — the canonical bug review caught was that a
- *   failed subagent could be reported as successful when the gateway
- *   forwarded `state: 'completed'` from a manager that did not
- *   propagate the run's `status: 'failed'`.
- * - Returns the subagent's `result` string as the tool output on
- *   success.
- */
-
-import { describe, expect, it } from 'vitest'
-
-import type { TaskGateway, TaskHandle } from '../../../types/agent/gateway.js'
-import type { TaskId } from '../../../types/ids/index.js'
-import type { ToolContext } from '../../../types/tool/index.js'
-import { buildAgentTool } from '../agent.js'
-
-function makeContext(): ToolContext {
-	return {
-		runId: 'run_test' as never,
-		workingDirectory: '/tmp/test',
-		abortSignal: new AbortController().signal,
-		env: {},
-		log: () => {},
-	}
-}
-
-function fakeGateway(handle: TaskHandle, completed: TaskHandle): TaskGateway {
-	return {
-		async createTask() {
-			return handle
-		},
-		async waitForTask() {
-			return completed
-		},
-		async continueTask() {},
-		cancelTask() {},
-		getTask() {
-			return completed
-		},
-		listTasks() {
-			return [completed]
-		},
-		onTaskCompleted() {
-			return () => {}
-		},
-	}
-}
-
-const taskId = 'task_subagent' as TaskId
-
-const launched: TaskHandle = {
-	taskId,
-	agentId: 'sales-strategy',
-	state: 'running',
-	createdAt: 0,
-}
-
-describe('buildAgentTool', () => {
-	it('reports success when both task state and run status say completed', async () => {
-		const gateway = fakeGateway(launched, {
-			...launched,
-			state: 'completed',
-			result: {
-				runId: 'run_inner' as never,
-				status: 'completed',
-				usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 } as never,
-				cost: { inputCostUsd: 0, outputCostUsd: 0, totalCostUsd: 0 } as never,
-				iterations: 1,
-				durationMs: 10,
-				messages: [],
-				result: 'final report text',
-			},
-			completedAt: 10,
-		})
-
-		const tool = buildAgentTool({
-			gateway,
-			workingDirectory: '/tmp/test',
-			allowedAgentIds: ['sales-strategy'],
-		})
-
-		const result = await tool.execute(
-			{ description: 'plan', prompt: 'go', subagent_type: 'sales-strategy' },
-			makeContext(),
-		)
-
-		expect(result.success).toBe(true)
-		// The subagent's text is present and unaltered, inside a frame that
-		// says whose text it is. A host reading the result programmatically
-		// gets it verbatim off `data.result` instead.
-		expect(result.output).toContain('final report text')
-		expect(result.output.startsWith('<namzu-untrusted kind="agent-result"')).toBe(true)
-		expect(result.data).toMatchObject({ result: 'final report text' })
-	})
-
-	it('reports failure when run status is failed even though task state is completed', async () => {
-		const gateway = fakeGateway(launched, {
-			...launched,
-			state: 'completed',
-			result: {
-				runId: 'run_inner' as never,
-				status: 'failed',
-				usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 } as never,
-				cost: { inputCostUsd: 0, outputCostUsd: 0, totalCostUsd: 0 } as never,
-				iterations: 1,
-				durationMs: 10,
-				messages: [],
-				lastError: 'tool budget exceeded',
-			},
-			completedAt: 10,
-		})
-
-		const tool = buildAgentTool({
-			gateway,
-			workingDirectory: '/tmp/test',
-			allowedAgentIds: ['sales-strategy'],
-		})
-
-		const result = await tool.execute(
-			{ description: 'plan', prompt: 'go', subagent_type: 'sales-strategy' },
-			makeContext(),
-		)
-
-		expect(result.success).toBe(false)
-		expect(result.error).toContain('tool budget exceeded')
-		expect(result.error).toContain('failed')
-	})
-
-	it('reports failure when task state itself is failed', async () => {
-		const gateway = fakeGateway(launched, {
-			...launched,
-			state: 'failed',
-			result: undefined,
-			completedAt: 10,
-		})
-
-		const tool = buildAgentTool({
-			gateway,
-			workingDirectory: '/tmp/test',
-			allowedAgentIds: ['sales-strategy'],
-		})
-
-		const result = await tool.execute(
-			{ description: 'plan', prompt: 'go', subagent_type: 'sales-strategy' },
-			makeContext(),
-		)
-
-		expect(result.success).toBe(false)
-		expect(result.error).toContain('failed')
-	})
-
-	it("does not accept a taskStore or runId — plan-task lifecycle is the parent's job", () => {
-		// Compile-time pin: AgentToolOptions must NOT include `taskStore`
-		// or `runId`. The Agent tool used to manage a per-call plan task
-		// internally and review caught a leak: when the subagent failed,
-		// the plan task stayed `'in_progress'` forever because
-		// `TaskStatus` has no `'failed'` value to flip to. Drop the
-		// integration entirely; if a host wants to track delegations as
-		// plan tasks, it does so via `TaskCreate` / `TaskUpdate` on its
-		// own side, where it owns the status semantics. This test
-		// freezes that decision.
-		const allowedOpts: Parameters<typeof buildAgentTool>[0] = {
-			gateway: fakeGateway(launched, launched),
-			workingDirectory: '/tmp/test',
-			allowedAgentIds: ['sales-strategy'],
-			runtimeContext: undefined,
-			onTaskLaunched: undefined,
-		}
-		expect('taskStore' in allowedOpts).toBe(false)
-		expect('runId' in allowedOpts).toBe(false)
-	})
-})

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

@@ -1,120 +0,0 @@
-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__/an-approver-is-never-shown-an-impossible-step.test.ts

@@ -1,153 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import { PlanManager } from '../../../manager/plan/lifecycle.js'
-import type { TaskGateway } from '../../../types/agent/gateway.js'
-import type { RunId } from '../../../types/ids/index.js'
-import type { PlanApprovalRequest } from '../../../types/plan/index.js'
-import type { ToolContext } from '../../../types/tool/index.js'
-import { buildCoordinatorTools } from '../index.js'
-
-/**
- * A plan could name an agent the launch would then refuse.
- *
- * `create_task` constrains `agent_id` with a closed enum; `approve_plan` typed
- * the same field as a bare string. So a model could propose, and a human could
- * approve, "delegate to X" for an X that `create_task` rejects at schema-parse
- * time — the run then burns a turn on a step a human had already blessed.
- *
- * The check lives in `execute`, not in the schema, and that is deliberate.
- * `approve_plan` is mounted even with an EMPTY roster, because planning with no
- * delegates and a human channel is a supported configuration — and `z.enum([])`
- * renders as `{"not":{}}`, the shape `delegateSchema` already refuses because a
- * strict tool-schema validator rejects the whole request over it rather than
- * the one tool. `create_task` escapes that by being withheld entirely; this
- * tool cannot be. Enforcing in `execute` as well is the precedent the canonical
- * `Agent` tool set for complete mediation.
- *
- * It runs BEFORE `startGenerating`, so the refusal costs no half-built plan and
- * the human is never shown the bad step at all.
- */
-
-const RUN = 'run_roster' as RunId
-
-function unusedGateway(): TaskGateway {
-	return {
-		async createTask() {
-			throw new Error('this test never launches')
-		},
-		async waitForTask() {
-			throw new Error('this test never waits')
-		},
-		async continueTask() {},
-		cancelTask() {},
-		getTask() {
-			return undefined
-		},
-		listTasks() {
-			return []
-		},
-		onTaskCompleted() {
-			return () => {}
-		},
-	}
-}
-
-function ctx(): ToolContext {
-	return {
-		runId: RUN,
-		workingDirectory: '/tmp/test',
-		abortSignal: new AbortController().signal,
-		env: {},
-		log: () => {},
-	}
-}
-
-/** Run `approve_plan`, reporting both its result and what the approver saw. */
-async function approve(
-	roster: string[],
-	steps: Array<{ description: string; agent_id?: string }>,
-): Promise<{ result: Awaited<ReturnType<ReturnType<typeof build>>>; seen?: PlanApprovalRequest }> {
-	let seen: PlanApprovalRequest | undefined
-	const pm = new PlanManager(RUN, async (request) => {
-		seen = request
-		return { approved: true }
-	})
-	const run = build(roster, pm)
-	const result = await run(steps)
-	return { result, ...(seen ? { seen } : {}) }
-}
-
-function build(roster: string[], pm: PlanManager) {
-	const tools = buildCoordinatorTools({
-		gateway: unusedGateway(),
-		workingDirectory: '/tmp/test',
-		allowedAgentIds: roster,
-		getPlanManager: () => pm,
-	})
-	const approvePlan = tools.find((t) => t.name === 'approve_plan')
-	if (!approvePlan) throw new Error('approve_plan missing from coordinator builder')
-	return (steps: Array<{ description: string; agent_id?: string }>) =>
-		approvePlan.execute({ title: 'do it', summary: 'a plan', steps }, ctx())
-}
-
-describe('a plan may only name an agent the run can actually launch', () => {
-	it('refuses a step naming an agent outside the roster', async () => {
-		const { result } = await approve(
-			['researcher', 'writer'],
-			[{ description: 'audit the deps', agent_id: 'security-auditor' }],
-		)
-
-		expect(result.success).toBe(false)
-		expect(result.error).toContain('security-auditor')
-	})
-
-	it('names the roster, so the model can correct itself in one turn', async () => {
-		const { result } = await approve(
-			['researcher', 'writer'],
-			[{ description: 'audit', agent_id: 'nobody' }],
-		)
-
-		expect(result.error).toContain('researcher')
-		expect(result.error).toContain('writer')
-	})
-
-	it('never shows the approver the step it refused', async () => {
-		// The whole point of checking before `startGenerating`: a human must
-		// not be asked to approve work that cannot run.
-		const { seen } = await approve(
-			['researcher'],
-			[{ description: 'audit', agent_id: 'security-auditor' }],
-		)
-
-		expect(seen).toBeUndefined()
-	})
-
-	it('leaves no half-built plan behind', async () => {
-		const pm = new PlanManager(RUN, async () => ({ approved: true }))
-		const run = build(['researcher'], pm)
-
-		await run([{ description: 'audit', agent_id: 'ghost' }])
-
-		expect(pm.active).toBeNull()
-	})
-
-	it('says something different when the run has no delegates at all', async () => {
-		// `approve_plan` is mounted on an empty roster on purpose — planning
-		// without delegation is supported — so the message has to explain that
-		// rather than list an empty set.
-		const { result } = await approve([], [{ description: 'audit', agent_id: 'anyone' }])
-
-		expect(result.success).toBe(false)
-		expect(result.error).toContain('no delegates')
-	})
-
-	it('still admits a plan that delegates only within the roster', async () => {
-		const { result, seen } = await approve(
-			['researcher', 'writer'],
-			[{ description: 'gather', agent_id: 'researcher' }, { description: 'summarize' }],
-		)
-
-		expect(result.success).toBe(true)
-		expect(seen?.steps.map((s) => s.agentId)).toEqual(['researcher', undefined])
-	})
-})

package/src/tools/coordinator/__tests__/approve-plan.test.ts

@@ -1,160 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import { PlanManager } from '../../../manager/plan/lifecycle.js'
-import type { TaskGateway } from '../../../types/agent/gateway.js'
-import type { RunId } from '../../../types/ids/index.js'
-import type { PlanApprovalResponse } from '../../../types/plan/index.js'
-import type { ToolContext } from '../../../types/tool/index.js'
-import { buildCoordinatorTools } from '../index.js'
-
-function unusedGateway(): TaskGateway {
-	return {
-		async createTask() {
-			throw new Error('not used')
-		},
-		async waitForTask() {
-			throw new Error('not used')
-		},
-		async continueTask() {},
-		cancelTask() {},
-		getTask() {
-			return undefined
-		},
-		listTasks() {
-			return []
-		},
-		onTaskCompleted() {
-			return () => {}
-		},
-	}
-}
-
-function testToolContext(): ToolContext {
-	return {
-		runId: 'run_approve_plan_test' as RunId,
-		workingDirectory: '/tmp/test',
-		abortSignal: new AbortController().signal,
-		env: {},
-		log: () => {},
-	}
-}
-
-async function executeApprovePlan(approval: PlanApprovalResponse) {
-	const pm = new PlanManager('run_approve_plan_test' as RunId, async () => approval)
-	const tools = buildCoordinatorTools({
-		gateway: unusedGateway(),
-		workingDirectory: '/tmp/test',
-		allowedAgentIds: ['sales-strategy'],
-		getPlanManager: () => pm,
-	})
-
-	const approvePlan = tools.find((tool) => tool.name === 'approve_plan')
-	if (!approvePlan) throw new Error('approve_plan tool missing from coordinator builder')
-
-	return approvePlan.execute(
-		{
-			title: 'Review uploaded documents',
-			summary: 'Inspect the documents and prepare the worker plan.',
-			steps: [{ description: 'Extract uploaded DOCX files' }],
-		},
-		testToolContext(),
-	)
-}
-
-describe('coordinator approve_plan tool', () => {
-	it('normalizes plain-text plan steps into canonical step objects', () => {
-		const tools = buildCoordinatorTools({
-			gateway: unusedGateway(),
-			workingDirectory: '/tmp/test',
-			allowedAgentIds: ['sales-strategy'],
-			getPlanManager: () => undefined,
-		})
-
-		const approvePlan = tools.find((tool) => tool.name === 'approve_plan')
-		if (!approvePlan) throw new Error('approve_plan tool missing from coordinator builder')
-
-		const parsed = approvePlan.inputSchema.safeParse({
-			title: 'Review uploaded documents',
-			summary: 'Inspect the documents and prepare the worker plan.',
-			steps: '1. Extract uploaded DOCX files\n2. Launch architecture worker',
-		})
-
-		expect(parsed.success).toBe(true)
-		if (!parsed.success) return
-		const data = parsed.data as { steps: Array<{ description: string }> }
-		expect(data.steps).toEqual([
-			{ description: 'Extract uploaded DOCX files' },
-			{ description: 'Launch architecture worker' },
-		])
-	})
-
-	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.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 () => {
-		const result = await executeApprovePlan({
-			approved: true,
-			feedback: 'Skip step 2 and use the staging database instead.',
-		})
-
-		expect(result.success).toBe(true)
-		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.',
-		})
-	})
-
-	it('keeps the rejection output carrying the feedback verbatim with follow-the-feedback guidance', async () => {
-		const result = await executeApprovePlan({
-			approved: false,
-			feedback: 'Wrong scope — focus on invoices only',
-		})
-
-		expect(result.success).toBe(false)
-		// Guidance must FOLLOW the feedback rather than bake in a revise
-		// loop — stop-style feedback ("do not plan again") and a trailing
-		// "revise and call approve_plan again" are contradictory
-		// instructions, and the model kept generating plans after a
-		// rejection meant to halt.
-		expect(result.output).toBe(
-			'Plan rejected. User feedback: Wrong scope — focus on invoices only. Follow this feedback: if it requests changes, revise your plan and call approve_plan again; if it asks you to stop, acknowledge briefly and end your turn. If no feedback was provided, ask the user how to proceed before planning again.',
-		)
-		expect(result.data).toEqual({
-			approved: false,
-			feedback: 'Wrong scope — focus on invoices only',
-		})
-	})
-})