@namzu/sdk 7.0.0 → 9.0.0

package/src/manager/plan/__tests__/a-plan-that-succeeded-is-not-failed.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest'
+
+import type { RunId } from '../../../types/ids/index.js'
+import { PlanManager } from '../lifecycle.js'
+
+/**
+ * `completePlan` scored an unreported step as a failure.
+ *
+ * The test was "is every step completed or skipped", and everything else fell
+ * to the same branch — so a step still `pending` produced `failed`. Since
+ * `addStep` defaults every step to `pending`, a caller that added steps, did
+ * the work, and settled the plan without reporting each one got `failed` for a
+ * plan that had fully succeeded. That is the path of least effort, not an
+ * unusual one.
+ *
+ * A step that FAILED is an outcome. A step nobody reported on is not — it says
+ * the caller and the plan disagree about whether the work is over, and
+ * answering "failed" settles that by inventing a result.
+ */
+
+const RUN = 'run_plan_outcome' as RunId
+
+function planWithSteps(count: number): PlanManager {
+	const manager = new PlanManager(RUN)
+	manager.startGenerating('a plan')
+	for (let i = 0; i < count; i += 1) {
+		manager.addStep({
+			id: `step-${i + 1}`,
+			description: `step ${i + 1}`,
+			dependsOn: [],
+			order: i,
+		})
+	}
+	manager.markReady()
+	return manager
+}
+
+describe('a plan settles on what its steps actually reported', () => {
+	it('completes when every step reported success', () => {
+		const manager = planWithSteps(2)
+		for (const step of manager.active?.steps ?? []) {
+			manager.updateStepStatus(step.id, 'completed')
+		}
+
+		expect(manager.completePlan()?.status).toBe('completed')
+	})
+
+	it('counts a skipped step as settled, not as a failure', () => {
+		const manager = planWithSteps(2)
+		const steps = manager.active?.steps ?? []
+		manager.updateStepStatus(steps[0]?.id as string, 'completed')
+		manager.updateStepStatus(steps[1]?.id as string, 'skipped')
+
+		expect(manager.completePlan()?.status).toBe('completed')
+	})
+
+	it('fails when a step actually failed', () => {
+		const manager = planWithSteps(2)
+		const steps = manager.active?.steps ?? []
+		manager.updateStepStatus(steps[0]?.id as string, 'completed')
+		manager.updateStepStatus(steps[1]?.id as string, 'failed')
+
+		expect(manager.completePlan()?.status).toBe('failed')
+	})
+
+	it('refuses rather than scoring a step nobody reported on', () => {
+		// The defect, in the shape a caller reaches it: steps added, work done,
+		// nothing reported. Answering `failed` here is the invented result.
+		const manager = planWithSteps(2)
+		manager.updateStepStatus(manager.active?.steps[0]?.id as string, 'completed')
+
+		expect(() => manager.completePlan()).toThrow(/have not reported an outcome/)
+	})
+
+	it('names the way out rather than only the refusal', () => {
+		// A caller in this position either forgot to report progress or called
+		// too early, and only they know which — so the message has to carry
+		// both moves, not just the complaint.
+		const manager = planWithSteps(1)
+
+		expect(() => manager.completePlan()).toThrow(/updateStepStatus/)
+		expect(() => manager.completePlan()).toThrow(/failPlan/)
+	})
+
+	it('still returns null when there is no plan at all', () => {
+		expect(new PlanManager(RUN).completePlan()).toBeNull()
+	})
+})

package/src/manager/plan/lifecycle.ts

@@ -26,6 +26,33 @@ export type PlanEventListener = (event: PlanEvent) => void
 
 export type PlanApprovalHandler = (request: PlanApprovalRequest) => Promise<PlanApprovalResponse>
 
+/**
+ * The plan a run declares, and the gate a host approves it through.
+ *
+ * **The kernel deliberately drives only part of this class.** It builds a plan
+ * (`approve_plan` calls `startGenerating` / `addStep` / `markReady`), gates it
+ * (`iteration/phases/context.ts` calls `approve` and `startExecution`),
+ * translates its events onto the run stream (`EventTranslator.wirePlanManager`),
+ * and settles it on failure (`runtime/query/result.ts` calls `failPlan`). It
+ * never reports a step outcome and never settles a plan that succeeded.
+ *
+ * That is a split, not an omission — `drainQuery` hands the manager to the host
+ * through `onContextCreated({ planManager })` BEFORE the iteration loop starts,
+ * precisely so a host can drive the half the kernel does not. So a grep for
+ * callers of `updateStepStatus` or `completePlan` inside this package finds
+ * none, and that is not evidence the methods are dead: the callers are hosts,
+ * and they are outside the repository. `PlanManager` is exported from
+ * `public-runtime.ts` for this reason.
+ *
+ * Recorded here because the absence has already been read once as a dead layer
+ * and proposed for deletion. What it would have deleted is a working
+ * human-in-the-loop approval gate.
+ *
+ * The one genuine gap in the split is tracked separately: nothing settles a
+ * plan that SUCCEEDED, so its status can reach `failed` or stay `executing`
+ * but never `completed`. Fixing that needs a decision about what a
+ * kernel-built plan's steps mean, not a guessed status — see `completePlan`.
+ */
 export class PlanManager {
 	private currentPlan: Plan | null = null
 	private runId: RunId
@@ -185,9 +212,43 @@ export class PlanManager {
 		return step
 	}
 
+	/**
+	 * Settle the plan, computing its outcome from its steps.
+	 *
+	 * A step that is still `pending` or `running` used to land here as
+	 * **`failed`**, because the test was "is every step completed or skipped"
+	 * and anything else fell to the same branch. So a caller that added steps,
+	 * did the work, and settled the plan without reporting each step got
+	 * `failed` for a plan that fully succeeded — and `addStep` defaults every
+	 * step to `pending`, so that is the path of least effort, not an unusual
+	 * one.
+	 *
+	 * The two cases are different facts and want different responses. A step
+	 * that FAILED is an outcome: the plan failed, report it. A step nobody
+	 * reported on is not an outcome at all — it says the caller and this plan
+	 * disagree about whether the work is over, and answering "failed" resolves
+	 * that disagreement by inventing a result.
+	 *
+	 * So an unfinished step is refused rather than scored. The message names
+	 * the steps and the two ways out, because a caller in this position either
+	 * forgot to report progress or called too early, and only they know which.
+	 */
 	completePlan(): Plan | null {
 		if (!this.currentPlan) return null
 
+		const unfinished = this.currentPlan.steps.filter(
+			(s) => s.status === 'pending' || s.status === 'running',
+		)
+		if (unfinished.length > 0) {
+			const named = unfinished.slice(0, 3).map((s) => s.description)
+			const rest = unfinished.length - named.length
+			const listed = rest > 0 ? `${named.join('; ')}, and ${rest} more` : named.join('; ')
+			const counted = `${unfinished.length} of ${this.currentPlan.steps.length} steps`
+			throw new Error(
+				`Cannot complete plan "${this.currentPlan.title}": ${counted} have not reported an outcome (${listed}). Report each step with updateStepStatus — 'skipped' is a valid outcome — or call failPlan if the plan is being abandoned. Scoring an unreported step as a failure would report a plan that succeeded as one that did not.`,
+			)
+		}
+
 		const allDone = this.currentPlan.steps.every(
 			(s) => s.status === 'completed' || s.status === 'skipped',
 		)

package/src/manager/run/persistence.ts

@@ -270,6 +270,18 @@ export class RunPersistence {
 		this.run.structuredOutput = value
 	}
 
+	/**
+	 * Name the delegated work this run ended without waiting for.
+	 *
+	 * See {@link Run.abandonedTaskIds}. Recording rather than cancelling is
+	 * the point: the kernel owes the caller the truth about what it walked
+	 * away from, and nothing more.
+	 */
+	setAbandonedTaskIds(taskIds: readonly string[]): void {
+		if (taskIds.length === 0) return
+		this.run.abandonedTaskIds = [...taskIds]
+	}
+
 	setSteps(steps: readonly StepResult[]): void {
 		this.run.steps = steps
 	}

package/src/run/reporter.ts

@@ -270,6 +270,18 @@ export function createRunReporter(parentLogger?: Logger): RunReporter {
 				})
 				break
 
+			case 'compaction_failed':
+				// warn rather than info: the run is now continuing at a context
+				// size it had already decided was too large.
+				log.warn('Context compaction shed nothing', {
+					runId: event.runId,
+					iteration: event.iteration,
+					cause: event.cause,
+					messages: event.messages,
+					...(event.error !== undefined ? { error: event.error } : {}),
+				})
+				break
+
 			case 'capability_warning':
 				log.warn('Provider capability mismatch', {
 					runId: event.runId,

package/src/runtime/query/__tests__/completion-does-not-erase-the-answer.test.ts

@@ -0,0 +1,163 @@
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { z } from 'zod'
+
+import { CompletionInbox } from '../../../gateway/completion-inbox.js'
+import { ToolRegistry } from '../../../registry/tool/execute.js'
+import { defineTool } from '../../../tools/defineTool.js'
+import type { TaskHandle } from '../../../types/agent/gateway.js'
+import type { SessionId, TaskId, TenantId } from '../../../types/ids/index.js'
+import { createUserMessage } from '../../../types/message/index.js'
+import type { LLMProvider, StreamChunk } from '../../../types/provider/index.js'
+import type { ProjectId, ThreadId } from '../../../types/session/ids.js'
+import { drainQuery } from '../index.js'
+
+/**
+ * A notification appended after the answer must not become the answer's grave.
+ *
+ * `RunPersistence.resolveResult` assembles `Run.result` by walking the message
+ * tail BACKWARDS and stopping at the first non-assistant message, and it runs
+ * at `markCompleted` — after the loop has finished. So a task notification
+ * pushed after the final assistant turn hides that turn from the assembler
+ * entirely.
+ *
+ * This is not hypothetical. It was introduced by the change that made every
+ * exit hand over a finished worker's output, and measured here: a run whose
+ * model had just said "THIS IS THE RUN ANSWER." returned `run.result ===
+ * undefined`. Trading a lost worker result for a lost RUN result is strictly
+ * worse than the defect the delivery exists to fix, and every one of the
+ * suite's 2,600 tests passed while it was true, because none of them asserted
+ * `run.result` on a path where a completion could land last.
+ */
+
+const ZERO_USAGE = {
+	promptTokens: 0,
+	completionTokens: 0,
+	totalTokens: 0,
+	cachedTokens: 0,
+	cacheWriteTokens: 0,
+}
+
+const ANSWER = 'THIS IS THE RUN ANSWER.'
+
+function completed(): TaskHandle {
+	return {
+		taskId: 'tsk_bg' as TaskId,
+		agentId: 'reviewer',
+		state: 'completed',
+		createdAt: 0,
+		completedAt: 1,
+		result: { status: 'completed', result: 'THE WORKER RESULT' },
+	} as TaskHandle
+}
+
+const noop = defineTool({
+	name: 'noop',
+	description: 'does nothing',
+	inputSchema: z.object({}),
+	category: 'analysis',
+	permissions: [],
+	readOnly: true,
+	destructive: false,
+	concurrencySafe: true,
+	async execute() {
+		return { success: true, output: 'ok' }
+	},
+})
+
+const workdirs: string[] = []
+afterEach(async () => {
+	await Promise.all(workdirs.map((dir) => rm(dir, { recursive: true, force: true })))
+	workdirs.length = 0
+})
+
+describe('a completion delivered on the way out leaves the answer readable', () => {
+	it('keeps run.result when the worker lands during the closing turn', async () => {
+		const workingDirectory = await mkdtemp(join(tmpdir(), 'namzu-answer-'))
+		workdirs.push(workingDirectory)
+
+		const inbox = new CompletionInbox()
+		let announce: ((h: TaskHandle) => void) | undefined
+		inbox.launched('tsk_bg' as TaskId)
+		inbox.attach({
+			onTaskCompleted: (cb: (h: TaskHandle) => void) => {
+				announce = cb
+				return () => {
+					announce = undefined
+				}
+			},
+			getTask: () => undefined,
+		} as never)
+
+		/**
+		 * One tool call, then the iteration ceiling forces a closing turn. The
+		 * worker settles DURING that closing turn — after the last in-loop
+		 * drain, so the only thing left to deliver it is the exit path.
+		 */
+		class ClosingTurnProvider implements LLMProvider {
+			readonly id = 'closing-turn'
+			readonly name = 'Closing Turn Provider'
+			calls = 0
+			async *chatStream(): AsyncIterable<StreamChunk> {
+				this.calls += 1
+				if (this.calls === 1) {
+					yield {
+						id: 'm1',
+						delta: {
+							toolCalls: [
+								{
+									index: 0,
+									id: 'toolu_1',
+									type: 'function',
+									function: { name: 'noop', arguments: '{}' },
+								},
+							],
+						},
+					}
+					yield { id: 'm1', delta: {}, finishReason: 'tool_calls', usage: ZERO_USAGE }
+					return
+				}
+				announce?.(completed())
+				yield { id: 'm2', delta: { content: ANSWER } }
+				yield { id: 'm2', delta: {}, finishReason: 'stop', usage: ZERO_USAGE }
+			}
+		}
+
+		const tools = new ToolRegistry()
+		tools.register(noop)
+
+		const run = await drainQuery({
+			provider: new ClosingTurnProvider(),
+			tools,
+			completionInbox: inbox,
+			agentId: 'agent_test',
+			agentName: 'Test Agent',
+			messages: [createUserMessage('go')],
+			workingDirectory,
+			runConfig: {
+				model: 'mock-model',
+				timeoutMs: 20_000,
+				tokenBudget: 100_000,
+				maxIterations: 1,
+				maxResponseTokens: 256,
+			},
+			sessionId: 'ses_answer' as SessionId,
+			threadId: 'thd_answer' as ThreadId,
+			projectId: 'prj_answer' as ProjectId,
+			tenantId: 'tnt_answer' as TenantId,
+		} as never)
+
+		// Both halves, because either one alone is satisfied by a broken fix:
+		// dropping the delivery keeps the answer, and dropping the answer fix
+		// keeps the notification.
+		expect(run.result, 'the notification buried the run answer').toBe(ANSWER)
+		expect(
+			(run.messages as { content: unknown }[]).some(
+				(m) => typeof m.content === 'string' && m.content.includes('THE WORKER RESULT'),
+			),
+			'the worker result was not delivered',
+		).toBe(true)
+	}, 60_000)
+})