@namzu/sdk 10.0.0 → 12.0.0

package/src/runtime/query/__tests__/a-plan-that-succeeded-says-so.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from 'vitest'
+
+import type { PlanManager } from '../../../manager/plan/lifecycle.js'
+import { MockLLMProvider, registerMock } from '../../../provider/index.js'
+import { ToolRegistry } from '../../../registry/index.js'
+import {
+	generateProjectId,
+	generateSessionId,
+	generateTenantId,
+	generateThreadId,
+} from '../../../utils/id.js'
+import { drainQuery } from '../index.js'
+
+/**
+ * Nothing settled a plan that SUCCEEDED.
+ *
+ * The error path calls `failPlan`, so a run that blew up said so. The success
+ * path never touched the plan manager at all — so a plan could reach `failed`
+ * or sit at `executing` forever, but never `completed`. A host reading
+ * `plan.status` after a successful run was told the work was still going.
+ *
+ * Settlement is conditional on every step having reported, and the condition is
+ * read rather than caught: `completePlan` refuses an unreported step on
+ * purpose, and letting that throw here would turn a run that worked into a run
+ * that crashed on its way out — a worse version of the bug the refusal exists
+ * to prevent.
+ */
+
+registerMock()
+
+/** Run to completion, with a plan seeded through the host's own seam. */
+async function runWithPlan(seed: (pm: PlanManager) => void): Promise<PlanManager> {
+	let captured: PlanManager | undefined
+
+	await drainQuery({
+		provider: new MockLLMProvider({ responses: [{ content: 'done' }] } as never),
+		tools: new ToolRegistry(),
+		agentId: 'a',
+		agentName: 'A',
+		messages: [{ role: 'user', content: 'go' }],
+		workingDirectory: process.cwd(),
+		runConfig: { model: 'mock', tokenBudget: 100_000, timeoutMs: 30_000, maxIterations: 4 },
+		projectId: generateProjectId(),
+		sessionId: generateSessionId(),
+		threadId: generateThreadId(),
+		tenantId: generateTenantId(),
+		// The documented host seam: `drainQuery` hands the plan manager over
+		// BEFORE the iteration loop, which is exactly what makes a host-driven
+		// plan possible at all.
+		onContextCreated: ({ planManager }: { planManager: PlanManager }) => {
+			captured = planManager
+			seed(planManager)
+		},
+	} as never)
+
+	if (!captured) throw new Error('onContextCreated never fired')
+	return captured
+}
+
+function twoStepPlan(pm: PlanManager): void {
+	pm.startGenerating('the work')
+	pm.addStep({ id: 'step_1', description: 'first', dependsOn: [], order: 1 })
+	pm.addStep({ id: 'step_2', description: 'second', dependsOn: [], order: 2 })
+	pm.markReady()
+	pm.approve()
+	pm.startExecution()
+}
+
+describe('a run that succeeded settles the plan it was executing', () => {
+	it('reports completed when every step reported', async () => {
+		const pm = await runWithPlan((p) => {
+			twoStepPlan(p)
+			p.updateStepStatus('step_1', 'completed')
+			p.updateStepStatus('step_2', 'skipped')
+		})
+
+		expect(pm.active?.status).toBe('completed')
+	})
+
+	it('reports failed when a step actually failed', async () => {
+		const pm = await runWithPlan((p) => {
+			twoStepPlan(p)
+			p.updateStepStatus('step_1', 'completed')
+			p.updateStepStatus('step_2', 'failed')
+		})
+
+		expect(pm.active?.status).toBe('failed')
+	})
+
+	it('leaves it executing — and does not throw — when a step never reported', async () => {
+		// The honest answer. The caller and the plan disagree about whether the
+		// work is over, and the end of a successful run is not the place to
+		// resolve that by guessing. The run itself must still finish cleanly,
+		// which is the half that would break if the refusal were caught here
+		// instead of checked.
+		const pm = await runWithPlan((p) => {
+			twoStepPlan(p)
+			p.updateStepStatus('step_1', 'completed')
+		})
+
+		expect(pm.active?.status).toBe('executing')
+	})
+
+	it('does nothing when the run had no plan at all', async () => {
+		const pm = await runWithPlan(() => {})
+
+		expect(pm.active).toBeNull()
+	})
+})

package/src/runtime/query/__tests__/a-settled-plan-reaches-the-host.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it } from 'vitest'
+
+import type { PlanManager } from '../../../manager/plan/lifecycle.js'
+import { MockLLMProvider, registerMock } from '../../../provider/index.js'
+import { ToolRegistry } from '../../../registry/index.js'
+import type { RunEvent } from '../../../types/run/index.js'
+import {
+	generateProjectId,
+	generateSessionId,
+	generateTenantId,
+	generateThreadId,
+} from '../../../utils/id.js'
+import { drainQuery } from '../index.js'
+
+/**
+ * The plan stream stopped one event short of the outcome.
+ *
+ * `plan_ready`, `plan_approved`, `plan_rejected` and `plan_step_updated` all
+ * reached the wire; `plan.completed` and `plan.failed` were folded into a bare
+ * `break` in the translator and emitted nothing. So a host watching the stream
+ * saw the steps report and then silence — it could learn a plan had been
+ * approved and never that it closed, which leaves a plan rendered as in-flight
+ * indefinitely.
+ *
+ * **This was found by a live end-to-end run, not by a test, and that is the
+ * point worth keeping.** The settlement tests read the outcome off
+ * `PlanManager` through `onContextCreated`, so they proved the plan settled
+ * without ever asking whether a consumer of the EVENT STREAM could see it. A
+ * verification can be entirely sound about a thing that is no longer the thing
+ * you need to know.
+ */
+
+registerMock()
+
+async function runWithPlan(seed: (pm: PlanManager) => void): Promise<RunEvent[]> {
+	const events: RunEvent[] = []
+
+	await drainQuery(
+		{
+			provider: new MockLLMProvider({ responses: [{ content: 'done' }] } as never),
+			tools: new ToolRegistry(),
+			agentId: 'a',
+			agentName: 'A',
+			messages: [{ role: 'user', content: 'go' }],
+			workingDirectory: process.cwd(),
+			runConfig: { model: 'mock', tokenBudget: 100_000, timeoutMs: 30_000, maxIterations: 4 },
+			projectId: generateProjectId(),
+			sessionId: generateSessionId(),
+			threadId: generateThreadId(),
+			tenantId: generateTenantId(),
+			onContextCreated: ({ planManager }: { planManager: PlanManager }) => seed(planManager),
+		} as never,
+		(event: RunEvent) => {
+			events.push(event)
+		},
+	)
+
+	return events
+}
+
+function twoStepPlan(pm: PlanManager): void {
+	pm.startGenerating('the work')
+	pm.addStep({ id: 'step_1', description: 'first', dependsOn: [], order: 1 })
+	pm.addStep({ id: 'step_2', description: 'second', dependsOn: [], order: 2 })
+	pm.markReady()
+	pm.approve()
+	pm.startExecution()
+}
+
+const typesOf = (events: RunEvent[]) => events.map((e) => e.type)
+
+describe('a settled plan says so on the run stream', () => {
+	it('emits plan_completed when the run settles a successful plan', async () => {
+		const events = await runWithPlan((p) => {
+			twoStepPlan(p)
+			p.updateStepStatus('step_1', 'completed')
+			p.updateStepStatus('step_2', 'skipped')
+		})
+
+		expect(typesOf(events)).toContain('plan_completed')
+	})
+
+	it('emits plan_failed, carrying the reason failPlan was given', async () => {
+		// `failPlan` took this argument and discarded it — the parameter was
+		// spelled `_error`. An event that says "failed" without saying why puts
+		// the reader back where the missing event did.
+		const events = await runWithPlan((p) => {
+			twoStepPlan(p)
+			p.failPlan('the provider refused the request')
+		})
+
+		const failed = events.find((e) => e.type === 'plan_failed')
+		expect(failed).toBeDefined()
+		expect((failed as { reason?: string }).reason).toBe('the provider refused the request')
+	})
+
+	it('emits plan_failed when a step actually failed', async () => {
+		const events = await runWithPlan((p) => {
+			twoStepPlan(p)
+			p.updateStepStatus('step_1', 'completed')
+			p.updateStepStatus('step_2', 'failed')
+		})
+
+		expect(typesOf(events)).toContain('plan_failed')
+		expect(typesOf(events)).not.toContain('plan_completed')
+	})
+
+	it('says nothing terminal while a step has not reported', async () => {
+		// The plan is genuinely unsettled, so the silence here is correct — it
+		// is the silence AFTER settlement that was the defect.
+		const events = await runWithPlan((p) => {
+			twoStepPlan(p)
+			p.updateStepStatus('step_1', 'completed')
+		})
+
+		expect(typesOf(events)).not.toContain('plan_completed')
+		expect(typesOf(events)).not.toContain('plan_failed')
+		// ...and the step that DID report is still announced, so this is not a
+		// stream that has simply gone quiet.
+		expect(typesOf(events)).toContain('plan_step_updated')
+	})
+})

package/src/runtime/query/events.ts

@@ -193,10 +193,28 @@ export class EventTranslator {
 						})
 					}
 					break
-				case 'plan.generating':
-				case 'plan.executing':
 				case 'plan.completed':
+					await this.emitEvent({
+						type: 'plan_completed',
+						runId,
+						planId: plan.id,
+					})
+					break
 				case 'plan.failed':
+					await this.emitEvent({
+						type: 'plan_failed',
+						runId,
+						planId: plan.id,
+						...(plan.failureReason ? { reason: plan.failureReason } : {}),
+					})
+					break
+				// Deliberately silent, and not for the same reason the terminal
+				// pair used to be. `plan.generating` and `plan.executing` are
+				// already bracketed by `plan_ready` and `plan_approved` — a
+				// consumer learns both facts from events it already gets, so an
+				// event here would carry nothing a reader did not have.
+				case 'plan.generating':
+				case 'plan.executing':
 					break
 				default: {
 					// `PlanEvent.type` is scoped to plan-manager events; sub-session

package/src/runtime/query/index.ts

@@ -552,8 +552,6 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		return { approved: false, feedback: `Action: ${decision.action}` }
 	})
 
-	params.onContextCreated?.({ planManager: ctx.planManager })
-
 	const eventTranslator = new EventTranslator(ctx.runMgr)
 	eventTranslator.wireActivityStore(ctx.activityStore, ctx.runId)
 	eventTranslator.wirePlanManager(ctx.planManager, ctx.runId)
@@ -977,6 +975,21 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		try {
 			await ctx.runMgr.init()
 
+			// Handed over here, and the position is load-bearing in BOTH
+			// directions. It has to follow `wirePlanManager`, or a host that
+			// builds its plan in this callback — which is what the callback is
+			// for — does it into silence: `plan_ready`, `plan_approved` and
+			// every `plan_step_updated` are emitted with nothing subscribed,
+			// and the host then watches a stream that never mentions the plan
+			// it just created. It also has to follow `runMgr.init()`, because
+			// emitting appends to the run store and an uninitialised store
+			// throws — moving it up to the wiring alone traded a silent drop
+			// for 25 unhandled rejections.
+			//
+			// Still before the iteration loop, which is the guarantee the
+			// callback actually makes.
+			params.onContextCreated?.({ planManager: ctx.planManager })
+
 			ctx.log.info('Starting query', {
 				runId: ctx.runMgr.id,
 				agent: params.agentName,

package/src/runtime/query/result.ts

@@ -37,12 +37,29 @@ export class ResultAssembler {
 	}
 
 	async *completeRun(rootSpan: Span): AsyncGenerator<RunEvent> {
-		const { runMgr, activityStore, log, emitEvent, drainPending } = this.config
+		const { runMgr, planManager, activityStore, log, emitEvent, drainPending } = this.config
 
 		if (runMgr.status === 'running') {
 			runMgr.markCompleted(runMgr.stopReason)
 		}
 
+		// Settle the plan, which nothing did on this path — so a plan could
+		// reach `failed` (the error path calls `failPlan`) or stay `executing`
+		// forever, but never `completed`. A host reading `plan.status` after a
+		// successful run saw "still running".
+		//
+		// Only when every step has reported, and the check is a read rather
+		// than a caught throw: `completePlan` refuses an unreported step on
+		// purpose, and turning a run that worked into a run that crashed on its
+		// way out would be a worse version of the bug the refusal prevents.
+		//
+		// A plan with steps nobody reported is LEFT `executing`, which is the
+		// honest answer — the caller and the plan disagree about whether the
+		// work is over, and this is not the place to resolve that by guessing.
+		if (planManager.isActive && planManager.unreportedSteps.length === 0) {
+			planManager.completePlan()
+		}
+
 		await emitEvent({
 			type: 'run_completed',
 			runId: runMgr.id,

package/src/tools/coordinator/__tests__/a-listing-is-not-a-back-door.test.ts

@@ -0,0 +1,171 @@
+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 { buildCoordinatorTools } from '../index.js'
+
+/**
+ * A supervisor could read a sibling run's worker output by listing.
+ *
+ * `SupervisorAgentConfig.gateway` exists so a host can hand the SAME gateway to
+ * several runs, which makes `listTasks()` gateway-wide by design.
+ * `agent_task_list` handed that straight to the model — including each task's
+ * `result`, the worker's actual output — and `wait_for_task` had the same reach
+ * through `getTask`.
+ *
+ * `CompletionInbox` closed exactly this on the push side, because
+ * `onTaskCompleted` is a broadcast and a shared gateway would otherwise hand
+ * each supervisor the other's completions. The pull side kept no such record
+ * and asked the gateway directly, so the same leak stayed open through a
+ * different door.
+ */
+
+const AGENTS = ['reviewer', 'researcher']
+
+function makeContext(): ToolContext {
+	return {
+		runId: 'run_scope' as never,
+		workingDirectory: '/tmp/test',
+		abortSignal: new AbortController().signal,
+		env: {},
+		log: () => {},
+	}
+}
+
+/** One gateway, as a host sharing it between two supervisors would have. */
+function sharedGateway() {
+	const handles = new Map<string, TaskHandle>()
+	let seq = 0
+
+	const gateway = {
+		createTask: async (opts: { agentId: string }) => {
+			seq += 1
+			const taskId = `tsk_${seq}` as TaskId
+			const handle: TaskHandle = {
+				taskId,
+				agentId: opts.agentId,
+				state: 'completed',
+				createdAt: 1_000,
+				completedAt: 2_000,
+				result: {
+					status: 'completed',
+					result: `output of ${opts.agentId} on ${taskId}`,
+				} as TaskHandle['result'],
+			}
+			handles.set(taskId, handle)
+			return handle
+		},
+		waitForTask: async (taskId: TaskId) => handles.get(taskId) as TaskHandle,
+		getTask: (taskId: TaskId) => handles.get(taskId),
+		listTasks: () => [...handles.values()],
+		cancelTask: () => undefined,
+		continueTask: async () => undefined,
+		onTaskCompleted: () => () => {},
+	} as unknown as TaskGateway
+
+	return gateway
+}
+
+/** A run's own coordinator surface over a gateway it may be sharing. */
+function runOver(gateway: TaskGateway) {
+	const tools = buildCoordinatorTools({
+		gateway,
+		workingDirectory: '/tmp/test',
+		allowedAgentIds: AGENTS,
+	})
+	const named = (name: string) => {
+		const t = tools.find((tool) => tool.name === name)
+		if (!t) throw new Error(`${name} missing from coordinator builder`)
+		return t
+	}
+	return {
+		launch: (agentId: string) =>
+			named('create_task').execute(
+				{ agent_id: agentId, prompt: 'work', description: `${agentId} work` },
+				makeContext(),
+			),
+		list: () => named('agent_task_list').execute({}, makeContext()),
+		waitFor: (taskId: string) => named('wait_for_task').execute({ task_id: taskId }, makeContext()),
+	}
+}
+
+describe('one run cannot read another run through the listing', () => {
+	it('lists only the tasks this run launched', async () => {
+		const gateway = sharedGateway()
+		const first = runOver(gateway)
+		const second = runOver(gateway)
+
+		await first.launch('reviewer')
+		await second.launch('researcher')
+
+		const listed = await second.list()
+
+		// Its own, yes.
+		expect(listed.output).toContain('tsk_2')
+		// The sibling's task, and — the part that matters — the sibling's
+		// worker output, which the listing renders inline.
+		expect(listed.output).not.toContain('tsk_1')
+		expect(listed.output).not.toContain('output of reviewer')
+	})
+
+	it('counts only its own in the summary', async () => {
+		// The summary is what a supervisor reads to decide "done vs not done".
+		// A total that includes a sibling's tasks is a wrong answer to that
+		// question even when no output leaks with it.
+		const gateway = sharedGateway()
+		const first = runOver(gateway)
+		const second = runOver(gateway)
+
+		await first.launch('reviewer')
+		await first.launch('reviewer')
+		await second.launch('researcher')
+
+		const listed = await second.list()
+		const data = listed.data as { summary: { total: number }; items: unknown[] }
+
+		expect(data.summary.total).toBe(1)
+		expect(data.items).toHaveLength(1)
+	})
+
+	it('refuses to wait on a task another run launched', async () => {
+		const gateway = sharedGateway()
+		const first = runOver(gateway)
+		const second = runOver(gateway)
+
+		await first.launch('reviewer')
+
+		const waited = await second.waitFor('tsk_1')
+
+		expect(waited.success).toBe(false)
+		expect(waited.output).not.toContain('output of reviewer')
+	})
+
+	it('says the same thing about a task that never existed', async () => {
+		// The refusal must not distinguish "belongs to someone else" from
+		// "never existed". Confirming a real id to a run that should not know
+		// it is the leak in miniature.
+		const gateway = sharedGateway()
+		const first = runOver(gateway)
+		const second = runOver(gateway)
+
+		await first.launch('reviewer')
+
+		const sibling = await second.waitFor('tsk_1')
+		const fictional = await second.waitFor('tsk_9999')
+
+		expect(sibling.output).toBe(fictional.output.replace('tsk_9999', 'tsk_1'))
+	})
+
+	it('still lets a run wait on its own task', async () => {
+		// The scope has to be a filter, not a wall — a run that launched a task
+		// must still be able to read it back, or the fix breaks delegation.
+		const gateway = sharedGateway()
+		const only = runOver(gateway)
+
+		await only.launch('reviewer')
+		const waited = await only.waitFor('tsk_1')
+
+		expect(waited.success).toBe(true)
+	})
+})