@namzu/sdk 11.0.0 → 12.0.1

package/src/contracts/api.ts

@@ -206,6 +206,11 @@ export type StreamEventType =
 	| 'plan.approved'
 	| 'plan.rejected'
 	| 'plan.step_updated'
+	// The outcome. Without these the plan stream stopped one event short of
+	// saying how it went, so a client could render a plan as in-flight
+	// indefinitely — it learned the plan was approved and never that it closed.
+	| 'plan.completed'
+	| 'plan.failed'
 	| 'agent.pending'
 	| 'agent.completed'
 	| 'agent.failed'

package/src/gateway/__tests__/a-progress-tee-cannot-name-a-task-that-does-not-exist.test.ts

@@ -0,0 +1,175 @@
+import { describe, expect, it } from 'vitest'
+
+import type { Agent } from '../../types/agent/core.js'
+import type { AgentManagerContract } from '../../types/agent/manager.js'
+import type {
+	AgentTask,
+	AgentTaskContext,
+	AgentTaskState,
+	SendMessageOptions,
+} from '../../types/agent/task.js'
+import type { AgentId, RunId, SessionId, TaskId, TenantId } from '../../types/ids/index.js'
+import type { RunEventListener } from '../../types/run/events.js'
+import type { ProjectId, ThreadId } from '../../types/session/ids.js'
+import { LocalTaskGateway } from '../local.js'
+
+/**
+ * A child that spoke before its own spawn resolved killed the launch.
+ *
+ * The progress tee handed to `sendMessage` read `task.taskId` — the `const`
+ * that the very same `await` assigns. So any run event emitted by the child
+ * before `sendMessage` returned reached that line inside the temporal dead
+ * zone and threw `Cannot access 'task' before initialization`, taking the whole
+ * `create_task` down with it.
+ *
+ * It survived review and a full unit suite because a single sequential launch
+ * usually resolves before the child says anything. A CONCURRENT fan-out does
+ * not — and that is the shape `create_task`'s own description tells the model
+ * to use. Observed live on the published package: four launches from one turn,
+ * three dead.
+ */
+
+const RUN = 'run_tee' as RunId
+
+/** Emits a run event DURING the spawn, before it resolves. */
+class TalksDuringSpawn implements AgentManagerContract {
+	/** Kept so a test can make the child speak AFTER the spawn resolved too. */
+	private lastListener?: RunEventListener
+
+	constructor(private readonly emitsBeforeResolve: number) {}
+
+	/** The child says something once the caller holds its handle. */
+	speakNow(): void {
+		this.lastListener?.({ type: 'iteration_started', runId: RUN, iteration: 99 } as never)
+	}
+
+	async sendMessage(
+		options: SendMessageOptions,
+		_context: AgentTaskContext,
+		listener?: RunEventListener,
+	): Promise<AgentTask> {
+		this.lastListener = listener
+		// The child is alive and streaming before the caller holds its handle.
+		for (let i = 0; i < this.emitsBeforeResolve; i += 1) {
+			listener?.({ type: 'iteration_started', runId: RUN, iteration: i } as never)
+		}
+		await Promise.resolve()
+		return {
+			taskId: 'task_spoke_early' as TaskId,
+			agentId: options.agentId,
+			agent: {} as Agent<never, never>,
+			childAbortController: new AbortController(),
+			context: {} as AgentTaskContext,
+			state: 'completed' as AgentTaskState,
+			pendingMessages: [],
+			createdAt: 1,
+		} as AgentTask
+	}
+
+	cancel(): void {}
+	cancelAll(): void {}
+	async continueTask(): Promise<void> {}
+	queueMessage(): void {}
+	drainMessages() {
+		return []
+	}
+	async waitForCompletion(): Promise<void> {}
+	getInstance(): AgentTask | undefined {
+		return undefined
+	}
+	listByParent(): AgentTask[] {
+		return []
+	}
+	listActive(): AgentTask[] {
+		return []
+	}
+	getState(): AgentTaskState | undefined {
+		return undefined
+	}
+	on(): void {}
+	off(): void {}
+	cleanup(): void {}
+	dispose(): void {}
+}
+
+function context(): AgentTaskContext {
+	return {
+		parentRunId: RUN,
+		parentAgentId: 'supervisor',
+		parentAbortController: new AbortController(),
+		depth: 0,
+		budgetTracker: { total: 100_000, remaining: 100_000 },
+		tenantId: 'tnt_t' as TenantId,
+		threadId: 'thd_t' as ThreadId,
+		sessionId: 'ses_t' as SessionId,
+		projectId: 'prj_t' as ProjectId,
+		parentActor: { kind: 'agent', agentId: 'supervisor' as AgentId, tenantId: 'tnt_t' as TenantId },
+	} as AgentTaskContext
+}
+
+describe('a launch survives a child that speaks before the spawn resolves', () => {
+	it('does not throw when an event arrives mid-spawn', async () => {
+		const gateway = new LocalTaskGateway(new TalksDuringSpawn(3), context())
+		// The listener is what makes this reproduce, and its absence is what
+		// made the bug invisible for so long: with no progress subscriber the
+		// loop body never runs, so `task.taskId` is never evaluated and the
+		// dead zone is never entered. `create_task` attaches one for the idle
+		// bound on every blocking launch, which is why it bit in production and
+		// not in any test.
+		gateway.onTaskProgress?.(() => {})
+
+		await expect(
+			gateway.createTask({ agentId: 'worker', prompt: 'go', workingDirectory: '/tmp' }),
+		).resolves.toMatchObject({ taskId: 'task_spoke_early' })
+	})
+
+	it('still forwards those events to the host listener', async () => {
+		// The tee is what broke, not the forwarding. A host watching the child
+		// must not lose its early events to this fix.
+		const seen: string[] = []
+		const gateway = new LocalTaskGateway(new TalksDuringSpawn(3), context(), (e) => {
+			seen.push(e.type)
+		})
+
+		await gateway.createTask({ agentId: 'worker', prompt: 'go', workingDirectory: '/tmp' })
+
+		expect(seen).toEqual(['iteration_started', 'iteration_started', 'iteration_started'])
+	})
+
+	it('reports progress once the task has an id to report it against', async () => {
+		// Before the id exists nothing is waiting on the task — the caller does
+		// not hold the handle yet — so silence there is correct. What must work
+		// is everything after.
+		const manager = new TalksDuringSpawn(1)
+		const gateway = new LocalTaskGateway(manager, context())
+		const progressed: TaskId[] = []
+		gateway.onTaskProgress?.((id) => progressed.push(id))
+
+		await gateway.createTask({ agentId: 'worker', prompt: 'go', workingDirectory: '/tmp' })
+		// The one emitted mid-spawn is not attributed — there was no id yet.
+		expect(progressed).toEqual([])
+
+		// Now the child speaks with the handle already in the caller's hands,
+		// which is the case an idle bound is actually measuring.
+		manager.speakNow()
+
+		expect(progressed).toEqual(['task_spoke_early' as TaskId])
+	})
+
+	it('survives a concurrent fan-out, which is how this was found', async () => {
+		const gateway = new LocalTaskGateway(new TalksDuringSpawn(2), context())
+		// Same reason as above: the live failure came through the idle bound's
+		// subscriber, so a fan-out test without one would not reproduce the
+		// thing it is named after.
+		gateway.onTaskProgress?.(() => {})
+
+		const launched = await Promise.all(
+			[1, 2, 3, 4].map(() =>
+				gateway.createTask({ agentId: 'worker', prompt: 'go', workingDirectory: '/tmp' }),
+			),
+		)
+
+		expect(launched).toHaveLength(4)
+		expect(launched.every((h) => h.taskId === 'task_spoke_early')).toBe(true)
+	})
+})

package/src/gateway/local.ts

@@ -60,6 +60,12 @@ export class LocalTaskGateway implements TaskGateway {
 	}
 
 	async createTask(options: CreateTaskOptions): Promise<TaskHandle> {
+		// Filled once the spawn resolves. A box rather than a bare binding
+		// because the assignment happens AFTER the `await` that the reader is
+		// passed into — see the progress tee below for why it cannot simply
+		// read the `task` const it is declared beside.
+		const launched: { id?: TaskId } = {}
+
 		const task = await this.agentManager.sendMessage(
 			{
 				agentId: options.agentId,
@@ -109,12 +115,30 @@ export class LocalTaskGateway implements TaskGateway {
 			// idle bound measures. The event itself is not forwarded — a
 			// progress signal that carried the child's output would be a
 			// second, undocumented way to read a worker's work.
+			//
+			// The id comes from `launched.id`, NOT from the `task` const
+			// below. This callback is handed to the very `await` that assigns
+			// `task`, so a child that emits anything before `sendMessage`
+			// resolves reached it inside the temporal dead zone and threw
+			// `Cannot access 'task' before initialization` — killing the launch
+			// outright.
+			//
+			// It survived because a single sequential launch usually resolves
+			// before the child says anything. A concurrent fan-out does not:
+			// with four `create_task` calls from one turn — the shape this
+			// tool's own description tells the model to use — the event loop
+			// interleaves and three of the four died. Found by running one.
 			(event) => {
 				this.listener?.(event)
-				for (const notify of this.progressListeners) notify(task.taskId)
+				// No id yet means nothing is waiting on this task: the caller
+				// does not hold the handle, so an idle bound cannot be running
+				// against it. There is no progress to report to anyone.
+				if (launched.id === undefined) return
+				for (const notify of this.progressListeners) notify(launched.id)
 			},
 		)
 
+		launched.id = task.taskId
 		this.trackedTaskIds.add(task.taskId)
 
 		this.agentManager

package/src/manager/plan/lifecycle.ts

@@ -276,11 +276,16 @@ export class PlanManager {
 		return this.currentPlan
 	}
 
-	failPlan(_error: string): Plan | null {
+	failPlan(error: string): Plan | null {
 		if (!this.currentPlan) return null
 
 		this.currentPlan.status = 'failed'
 		this.currentPlan.completedAt = Date.now()
+		// Recorded rather than discarded. This argument was named `_error`
+		// because nothing read it, so a failed plan carried no account of what
+		// went wrong — and the event that now reports the failure would have
+		// had nothing to say beyond the word.
+		this.currentPlan.failureReason = error
 
 		for (const step of this.currentPlan.steps) {
 			if (step.status === 'pending' || step.status === 'running') {

package/src/run/reporter.ts

@@ -93,6 +93,8 @@ export function createRunReporter(parentLogger?: Logger): RunReporter {
 			case 'plan_approved':
 			case 'plan_rejected':
 			case 'plan_step_updated':
+			case 'plan_completed':
+			case 'plan_failed':
 			case 'tool_review_requested':
 			case 'tool_review_completed':
 			case 'checkpoint_created':

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/types/plan/index.ts

@@ -68,6 +68,20 @@ export interface Plan {
 	rejectedAt?: number
 	completedAt?: number
 	rejectionReason?: string
+
+	/**
+	 * Why the plan failed, when it did.
+	 *
+	 * `failPlan` has always taken this and thrown it away — the parameter was
+	 * spelled `_error` because nothing read it. So a plan settled as `failed`
+	 * carried no account of what went wrong, and the `plan_failed` event that
+	 * reports it would have said "failed" and nothing else, which puts a reader
+	 * exactly where the silence did.
+	 *
+	 * Distinct from {@link rejectionReason}: that is a human declining a plan
+	 * before it ran, this is a plan that ran and did not finish.
+	 */
+	failureReason?: string
 }
 
 export interface PlanApprovalRequest {

package/src/types/run/events.ts

@@ -434,6 +434,30 @@ type CoreRunEvent =
 			stepId: string
 			status: PlanStep['status']
 	  }
+	/**
+	 * The plan is over, and it went the way it was supposed to.
+	 *
+	 * The plan events used to stop before the outcome: `plan_ready`,
+	 * `plan_approved`, `plan_rejected` and `plan_step_updated` all reached the
+	 * wire, and the two terminal ones were folded into a bare `break` in the
+	 * translator. So a host watching the stream saw the steps report and then
+	 * silence — it could tell a plan had been approved and never that it
+	 * closed, which leaves a plan rendered as in-flight forever.
+	 *
+	 * Found by the first live end-to-end run rather than by a test, and the
+	 * reason is worth keeping: the 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.
+	 */
+	| { type: 'plan_completed'; runId: RunId; planId: PlanId }
+	/**
+	 * The plan is over and it did not finish.
+	 *
+	 * `reason` is the text handed to `failPlan`, which used to be discarded —
+	 * an event that says "failed" without saying why puts the reader back
+	 * where the missing event did.
+	 */
+	| { type: 'plan_failed'; runId: RunId; planId: PlanId; reason?: string }
 	| {
 			type: 'agent_pending'
 			runId: RunId