@namzu/sdk 3.1.0 → 3.3.0

package/src/runtime/query/__tests__/resume-run.test.ts

@@ -0,0 +1,262 @@
+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 { MockLLMProvider } from '../../../provider/mock.js'
+import { ToolRegistry } from '../../../registry/tool/execute.js'
+import type { CheckpointId, IterationCheckpoint } from '../../../types/hitl/index.js'
+import type { RunId, SessionId, TenantId } from '../../../types/ids/index.js'
+import { createUserMessage } from '../../../types/message/index.js'
+import type { CheckpointRunScope, CheckpointStore } from '../../../types/run/checkpoint-store.js'
+import type { ProjectId, ThreadId } from '../../../types/session/ids.js'
+import { resumeRun } from '../resume-run.js'
+import type { RunStateScope } from '../run-state.js'
+
+/**
+ * The pieces of a cross-process resume all existed and nothing joined them.
+ * `CheckpointManager` wrote the history, budgets, working state and any
+ * park; `loadRunState` read them back; `query` accepted `runId` +
+ * `resumeFromCheckpoint` and restored all of it. But `resumeFromCheckpoint`
+ * had no caller anywhere outside `packages/sdk/src`, so the whole path
+ * shipped untravelled — every host was expected to write the same wiring
+ * and none did.
+ *
+ * These cover the join, and especially its two refusals: a resume must not
+ * quietly become a fresh run under a recycled id, and it must not step past
+ * a park without the answer that park is waiting for.
+ */
+
+const SCOPE: RunStateScope = {
+	tenantId: 'tnt_resume' as TenantId,
+	projectId: 'prj_resume' as ProjectId,
+	sessionId: 'ses_resume' as SessionId,
+	runId: 'run_resume' as RunId,
+	threadId: 'thd_resume' as ThreadId,
+}
+
+const ZERO_USAGE = {
+	promptTokens: 0,
+	completionTokens: 0,
+	totalTokens: 0,
+	cachedTokens: 0,
+	cacheWriteTokens: 0,
+}
+
+const ZERO_COST = {
+	inputCostPer1M: 0,
+	outputCostPer1M: 0,
+	totalCost: 0,
+	cacheDiscount: 0,
+}
+
+class InMemoryCheckpointStore implements CheckpointStore {
+	readonly rows = new Map<string, IterationCheckpoint>()
+
+	private key(scope: CheckpointRunScope, id: CheckpointId): string {
+		return [scope.tenantId, scope.projectId, scope.sessionId, scope.runId, id].join('/')
+	}
+
+	async writeCheckpoint(scope: CheckpointRunScope, checkpoint: IterationCheckpoint): Promise<void> {
+		this.rows.set(this.key(scope, checkpoint.id), checkpoint)
+	}
+
+	async readCheckpoint(
+		scope: CheckpointRunScope,
+		id: CheckpointId,
+	): Promise<IterationCheckpoint | null> {
+		return this.rows.get(this.key(scope, id)) ?? null
+	}
+
+	async listCheckpoints(scope: CheckpointRunScope): Promise<IterationCheckpoint[]> {
+		const prefix = `${[scope.tenantId, scope.projectId, scope.sessionId, scope.runId].join('/')}/`
+		return [...this.rows.entries()]
+			.filter(([key]) => key.startsWith(prefix))
+			.map(([, cp]) => cp)
+			.sort((a, b) => a.createdAt - b.createdAt)
+	}
+
+	async deleteCheckpoint(scope: CheckpointRunScope, id: CheckpointId): Promise<void> {
+		this.rows.delete(this.key(scope, id))
+	}
+}
+
+function checkpoint(overrides: Partial<IterationCheckpoint> = {}): IterationCheckpoint {
+	return {
+		id: 'ckpt_1' as CheckpointId,
+		runId: SCOPE.runId,
+		iteration: 2,
+		messages: [createUserMessage('the work so far')],
+		tokenUsage: { ...ZERO_USAGE, promptTokens: 120, totalTokens: 120 },
+		costInfo: { ...ZERO_COST, totalCost: 0.4 },
+		guardState: { iterationCount: 2, elapsedMs: 9_000 },
+		createdAt: Date.now(),
+		...overrides,
+	} as IterationCheckpoint
+}
+
+let workdirs: string[] = []
+
+afterEach(async () => {
+	await Promise.all(workdirs.map((d) => rm(d, { recursive: true, force: true })))
+	workdirs = []
+})
+
+async function mkWorkdir(): Promise<string> {
+	const dir = await mkdtemp(join(tmpdir(), 'namzu-resume-run-'))
+	workdirs.push(dir)
+	return dir
+}
+
+async function baseParams(store: CheckpointStore) {
+	return {
+		scope: SCOPE,
+		checkpointStore: store,
+		provider: new MockLLMProvider({ turns: [{ text: 'continued' }] }),
+		tools: new ToolRegistry(),
+		runConfig: {
+			model: 'mock-model',
+			timeoutMs: 30_000,
+			tokenBudget: 100_000,
+			maxIterations: 2,
+			maxResponseTokens: 256,
+		},
+		agentId: 'agent_resume',
+		agentName: 'Resume Agent',
+		workingDirectory: await mkWorkdir(),
+		sessionId: SCOPE.sessionId,
+		threadId: SCOPE.threadId,
+		projectId: SCOPE.projectId,
+		tenantId: SCOPE.tenantId,
+		// Required by the contract, and rightly so: a resume that lands on a
+		// park has to have somewhere to ask.
+		resumeHandler: async () => ({ action: 'continue' as const }),
+	}
+}
+
+describe('a run is picked back up from its store', () => {
+	it('continues the same run id rather than starting a new one', async () => {
+		const store = new InMemoryCheckpointStore()
+		await store.writeCheckpoint(SCOPE, checkpoint())
+
+		const outcome = await resumeRun(await baseParams(store))
+
+		expect(outcome.resumed).toBe(true)
+		if (!outcome.resumed) return
+		// The whole point: a resume is the same run in a different process,
+		// so its id, budgets and trace all have to carry across.
+		expect(outcome.run.id).toBe(SCOPE.runId)
+		expect(outcome.state.checkpointId).toBe('ckpt_1')
+	})
+
+	it('carries the spent budget forward instead of granting a fresh one', async () => {
+		const store = new InMemoryCheckpointStore()
+		await store.writeCheckpoint(SCOPE, checkpoint())
+
+		const outcome = await resumeRun(await baseParams(store))
+
+		expect(outcome.resumed).toBe(true)
+		if (!outcome.resumed) return
+		// A run recalled at 120 tokens must not come back at zero — the
+		// budget belongs to the run, not to the process hosting it.
+		expect(outcome.run.tokenUsage.totalTokens).toBeGreaterThanOrEqual(120)
+	})
+
+	it('picks the newest checkpoint when the caller names none', async () => {
+		const store = new InMemoryCheckpointStore()
+		await store.writeCheckpoint(SCOPE, checkpoint({ id: 'ckpt_old' as CheckpointId, createdAt: 1 }))
+		await store.writeCheckpoint(
+			SCOPE,
+			checkpoint({ id: 'ckpt_new' as CheckpointId, createdAt: 2_000 }),
+		)
+
+		const outcome = await resumeRun(await baseParams(store))
+
+		expect(outcome.resumed).toBe(true)
+		if (!outcome.resumed) return
+		expect(outcome.state.checkpointId).toBe('ckpt_new')
+	})
+
+	it('honours an explicitly named checkpoint', async () => {
+		const store = new InMemoryCheckpointStore()
+		await store.writeCheckpoint(SCOPE, checkpoint({ id: 'ckpt_old' as CheckpointId, createdAt: 1 }))
+		await store.writeCheckpoint(
+			SCOPE,
+			checkpoint({ id: 'ckpt_new' as CheckpointId, createdAt: 2_000 }),
+		)
+
+		const outcome = await resumeRun({
+			...(await baseParams(store)),
+			checkpointId: 'ckpt_old' as CheckpointId,
+		})
+
+		expect(outcome.resumed).toBe(true)
+		if (!outcome.resumed) return
+		expect(outcome.state.checkpointId).toBe('ckpt_old')
+	})
+})
+
+describe('it refuses rather than guessing', () => {
+	it('reports no checkpoint instead of silently starting fresh', async () => {
+		const outcome = await resumeRun(await baseParams(new InMemoryCheckpointStore()))
+
+		// Starting a new run here would be the worst outcome: a different
+		// run wearing a recycled id, with the original's budget reset.
+		expect(outcome).toEqual({ resumed: false, reason: 'no-checkpoint' })
+	})
+
+	it('hands back the outstanding question instead of resuming past it', async () => {
+		const store = new InMemoryCheckpointStore()
+		await store.writeCheckpoint(
+			SCOPE,
+			checkpoint({
+				pending: {
+					request: {
+						type: 'tool_review',
+						runId: SCOPE.runId,
+						checkpointId: 'ckpt_1' as CheckpointId,
+						toolCalls: [{ id: 'call_1', name: 'write', input: {} }],
+					},
+					parkedAt: Date.now(),
+					deadlineAt: Date.now() + 60_000,
+				},
+			} as unknown as Partial<IterationCheckpoint>),
+		)
+
+		const outcome = await resumeRun(await baseParams(store))
+
+		expect(outcome.resumed).toBe(false)
+		if (outcome.resumed || outcome.reason !== 'awaiting-decision') {
+			throw new Error(`expected awaiting-decision, got ${JSON.stringify(outcome)}`)
+		}
+		// The host needs the request itself to put in front of a person.
+		expect(outcome.pending.request.type).toBe('tool_review')
+		expect(outcome.state.runId).toBe(SCOPE.runId)
+	})
+
+	it('treats an already-answered park as an ordinary resume', async () => {
+		const store = new InMemoryCheckpointStore()
+		await store.writeCheckpoint(
+			SCOPE,
+			checkpoint({
+				pending: {
+					request: {
+						type: 'tool_review',
+						runId: SCOPE.runId,
+						checkpointId: 'ckpt_1' as CheckpointId,
+						toolCalls: [{ id: 'call_1', name: 'write', input: {} }],
+					},
+					parkedAt: Date.now(),
+					deadlineAt: Date.now() + 60_000,
+					resolvedAt: Date.now(),
+				},
+			} as unknown as Partial<IterationCheckpoint>),
+		)
+
+		const outcome = await resumeRun(await baseParams(store))
+
+		// `resolvedAt` is what makes a park answered. Blocking on one that
+		// already has its answer would strand the run permanently.
+		expect(outcome.resumed).toBe(true)
+	})
+})

package/src/runtime/query/index.ts

@@ -9,6 +9,8 @@ import {
 import { findDanglingMessages, removeDanglingMessages } from '../../compaction/dangling.js'
 import { extractFromUserMessage } from '../../compaction/extractor.js'
 import { WorkingStateManager } from '../../compaction/manager.js'
+import type { ContextReducer } from '../../compaction/reducer.js'
+import { serializeState as serializeWorkingState } from '../../compaction/serializer.js'
 import { restoreWorkingState, snapshotWorkingState } from '../../compaction/wire.js'
 import type { CompactionConfig } from '../../config/runtime.js'
 import { TOOL_OUTPUT_DIR_NAME } from '../../constants/tools/index.js'
@@ -421,6 +423,16 @@ export interface QueryParams {
 	 */
 	workingMemoryProvider?: WorkingMemoryProvider
 
+	/**
+	 * Replace context reduction for this run.
+	 *
+	 * Outranks `compactionConfig.strategy`, and the built-in structured pass
+	 * does not also run: two mechanisms editing one history in the same pass
+	 * cannot both be reasoned about. See `ContextReducer` for the invariants a
+	 * reducer is expected to keep.
+	 */
+	contextReducer?: ContextReducer
+
 	agentBus?: import('../../bus/index.js').AgentBus
 
 	verificationGate?: VerificationGateConfig
@@ -752,6 +764,31 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			params.advisory.budget,
 		)
 
+		// What the run looks like when the MODEL consults an advisor, as
+		// opposed to when a trigger does. The trigger path has always passed
+		// this; the tool path passed an empty context, so an advisor the model
+		// asked for help saw the question and nothing else.
+		//
+		// `includeToolCatalog` and `useCompactedContext` are read here and
+		// nowhere else. Both were declared on `AdvisoryConfig` /
+		// `AdvisorDefinition` and consulted by nothing, so a host who turned
+		// the catalogue off still paid for it in every advisory prompt.
+		const advisoryConfig = params.advisory
+		advisoryCtx.setCallContextProvider(() => {
+			const summary =
+				workingStateManager && advisoryConfig.advisors.some((a) => a.useCompactedContext)
+					? serializeWorkingState(workingStateManager.getState())
+					: undefined
+			return {
+				messages: ctx.runMgr.messages,
+				...(summary !== undefined ? { workingStateSummary: summary } : {}),
+				...(advisoryConfig.includeToolCatalog
+					? { toolCatalog: params.tools.toLLMTools(effectiveAllowedTools) }
+					: {}),
+				iteration: ctx.runMgr.currentIteration,
+			}
+		})
+
 		if (params.advisory.enableAgentTool) {
 			const advisoryTools = buildAdvisoryTools({ advisoryCtx })
 			const overrides = params.runtimeToolOverrides
@@ -800,6 +837,8 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		toolGrants: new ToolGrantSet(),
 		compactionConfig: params.compactionConfig,
 		workingStateManager,
+		taskRouter: params.taskRouter,
+		contextReducer: params.contextReducer,
 		workingMemoryProvider: params.workingMemoryProvider,
 		advisoryCtx,
 		agentBus: params.agentBus,

package/src/runtime/query/iteration/index.ts

@@ -5,6 +5,7 @@ import {
 	DEFAULT_STRUCTURED_OUTPUT_RETRIES,
 	STRUCTURED_OUTPUT_REPROMPT,
 } from '../../../constants/tools/index.js'
+import { renderSkillsSection } from '../../../persona/assembler.js'
 import { collect } from '../../../provider/collect.js'
 import {
 	GENAI,
@@ -21,6 +22,7 @@ import {
 	createSystemMessage,
 	createUserMessage,
 } from '../../../types/message/index.js'
+import type { ToolChoice } from '../../../types/provider/chat.js'
 import { classifyProviderError } from '../../../types/provider/errors.js'
 import type { ChatCompletionResponse } from '../../../types/provider/index.js'
 import type { AnswerReview } from '../../../types/run/answer-review.js'
@@ -30,6 +32,7 @@ import type {
 	StepResult,
 	StopReason,
 } from '../../../types/run/index.js'
+import type { Skill } from '../../../types/skills/index.js'
 import type { LLMToolSchema, ToolRegistryContract } from '../../../types/tool/index.js'
 import { toErrorMessage } from '../../../utils/error.js'
 import { generateMessageId } from '../../../utils/id.js'
@@ -150,23 +153,27 @@ export class IterationOrchestrator {
 				{},
 				parentContext(this.ctx.rootSpan),
 			)
-			// Tool spans for this turn belong under this iteration.
-			this.ctx.toolExecutor.setParentSpan(iterSpan)
+			try {
+				// Tool spans for this turn belong under this iteration. Inside
+				// the try rather than before it: a throw from any of these left
+				// the span open, and an iteration span that never ends is a
+				// trace that never closes — the export is incomplete for exactly
+				// the run that failed.
+				this.ctx.toolExecutor.setParentSpan(iterSpan)
 
-			iterSpan.setAttributes({
-				[NAMZU.ITERATION]: iterationNum,
-				[NAMZU.RUN_ID]: runMgr.id,
-				[GENAI.REQUEST_MODEL]: model,
-			})
+				iterSpan.setAttributes({
+					[NAMZU.ITERATION]: iterationNum,
+					[NAMZU.RUN_ID]: runMgr.id,
+					[GENAI.REQUEST_MODEL]: model,
+				})
 
-			await this.ctx.emitEvent({
-				type: 'iteration_started',
-				runId: runMgr.id,
-				iteration: iterationNum,
-			})
-			yield* this.ctx.drainPending()
+				await this.ctx.emitEvent({
+					type: 'iteration_started',
+					runId: runMgr.id,
+					iteration: iterationNum,
+				})
+				yield* this.ctx.drainPending()
 
-			try {
 				if (this.ctx.pluginManager) {
 					const hookResults = await this.ctx.pluginManager.executeHooks(
 						'iteration_start',
@@ -225,8 +232,17 @@ export class IterationOrchestrator {
 				// exactly this reason. Shallow is enough: the defect is array
 				// mutation, and per-iteration this is trivial next to the model
 				// call it precedes.
-				const messages = step.system
-					? [...baseMessages, createSystemMessage(step.system)]
+				// A step's skills and its guidance ride the same ephemeral
+				// trailing system message. Appending leaves the cached prefix
+				// intact; rewriting the run's own prompt to carry a phase's
+				// skills would invalidate it on every iteration.
+				// `renderSkillsSection` already answers null for an empty list, so
+				// there is no length check here — a second guard for the same
+				// case is one more thing to keep in agreement with the first.
+				const stepSkills = step.skills ? renderSkillsSection([...step.skills]) : null
+				const stepPreamble = [step.system, stepSkills].filter(Boolean).join('\n\n')
+				const messages = stepPreamble
+					? [...baseMessages, createSystemMessage(stepPreamble)]
 					: [...baseMessages]
 
 				if (this.ctx.pluginManager) {
@@ -269,7 +285,17 @@ export class IterationOrchestrator {
 						messages,
 						tools: llmTools.length > 0 ? llmTools : undefined,
 						...(enforceToolInputSchema ? { enforceToolInputSchema } : {}),
-						toolChoice: forceFinalize && llmTools.length > 0 ? 'none' : undefined,
+						// The forced-final turn wins: a step that asked to force a
+						// tool cannot override the loop's own decision to stop
+						// asking for them. Otherwise the step's choice applies —
+						// and only to this step, because the next one is prepared
+						// from scratch.
+						toolChoice:
+							forceFinalize && llmTools.length > 0
+								? 'none'
+								: llmTools.length > 0
+									? step.toolChoice
+									: undefined,
 						temperature: step.temperature ?? runConfig.temperature,
 						maxTokens: step.maxResponseTokens ?? runConfig.maxResponseTokens,
 						cacheControl: { type: 'auto' },
@@ -446,7 +472,6 @@ export class IterationOrchestrator {
 							hasToolCalls: false,
 						})
 						yield* this.ctx.drainPending()
-						iterSpan.end()
 						continue
 					}
 
@@ -464,7 +489,6 @@ export class IterationOrchestrator {
 								attempts: attempt - 1,
 							})
 							runMgr.setStopReason('structured_output_failed')
-							iterSpan.end()
 							break
 						}
 						this.ctx.log.info('Re-prompting for structured output', {
@@ -480,7 +504,6 @@ export class IterationOrchestrator {
 							hasToolCalls: false,
 						})
 						yield* this.ctx.drainPending()
-						iterSpan.end()
 						continue
 					}
 
@@ -509,7 +532,6 @@ export class IterationOrchestrator {
 									limit,
 								})
 								runMgr.setStopReason('answer_rejected')
-								iterSpan.end()
 								break
 							}
 							this.ctx.log.info('Answer rejected — returning it to the model', {
@@ -525,7 +547,6 @@ export class IterationOrchestrator {
 								hasToolCalls: false,
 							})
 							yield* this.ctx.drainPending()
-							iterSpan.end()
 							continue
 						}
 					}
@@ -553,11 +574,9 @@ export class IterationOrchestrator {
 					if (this.ctx.abortController.signal.aborted) {
 						runMgr.setStopReason('cancelled')
 						runMgr.markCancelled()
-						iterSpan.end()
 						break
 					}
 					runMgr.setStopReason('end_turn')
-					iterSpan.end()
 					break
 				}
 
@@ -579,12 +598,10 @@ export class IterationOrchestrator {
 				})
 
 				if (reviewOutcome.decision === 'stop') {
-					iterSpan.end()
 					return
 				}
 
 				if (reviewOutcome.decision === 'rejected') {
-					iterSpan.end()
 					continue
 				}
 
@@ -604,7 +621,6 @@ export class IterationOrchestrator {
 						hasToolCalls: true,
 					})
 					yield* this.ctx.drainPending()
-					iterSpan.end()
 					break
 				}
 
@@ -631,7 +647,6 @@ export class IterationOrchestrator {
 						hasToolCalls: true,
 					})
 					yield* this.ctx.drainPending()
-					iterSpan.end()
 					break
 				}
 
@@ -651,13 +666,11 @@ export class IterationOrchestrator {
 						hasToolCalls: true,
 					})
 					yield* this.ctx.drainPending()
-					iterSpan.end()
 					break
 				}
 
 				const checkpointSignal = yield* runIterationCheckpoint(this.ctx, iterationNum)
 				if (checkpointSignal === 'stop') {
-					iterSpan.end()
 					return
 				}
 
@@ -680,7 +693,6 @@ export class IterationOrchestrator {
 					hasToolCalls: true,
 				})
 				yield* this.ctx.drainPending()
-				iterSpan.end()
 			} catch (err) {
 				// A Stop that aborted the in-flight turn surfaces here as a
 				// thrown abort (the provider stream was raced against the run
@@ -692,7 +704,6 @@ export class IterationOrchestrator {
 				if (this.ctx.abortController.signal.aborted) {
 					runMgr.setStopReason('cancelled')
 					runMgr.markCancelled()
-					iterSpan.end()
 					break
 				}
 
@@ -722,7 +733,6 @@ export class IterationOrchestrator {
 						if (iterationActivity) {
 							this.ctx.activityStore.complete(iterationActivity.id)
 						}
-						iterSpan.end()
 						continue
 					}
 				}
@@ -736,8 +746,13 @@ export class IterationOrchestrator {
 					message: toErrorMessage(err),
 				})
 				iterSpan.recordException(err instanceof Error ? err : new Error(String(err)))
-				iterSpan.end()
 				throw err
+			} finally {
+				// The only place the iteration span ends. It used to be ended at each of
+				// seventeen exits, which is a rule every future edit has to
+				// remember; a generator abandoned by its consumer never reached
+				// any of them.
+				iterSpan.end()
 			}
 		}
 	}
@@ -752,8 +767,10 @@ export class IterationOrchestrator {
 	 */
 	private async prepareStep(stepNumber: number): Promise<{
 		allowedTools?: string[]
+		toolChoice?: ToolChoice
 		model?: string
 		system?: string
+		skills?: readonly Skill[]
 		temperature?: number
 		maxResponseTokens?: number
 	}> {
@@ -789,8 +806,10 @@ export class IterationOrchestrator {
 
 		const prepared: {
 			allowedTools?: string[]
+			toolChoice?: ToolChoice
 			model?: string
 			system?: string
+			skills?: readonly Skill[]
 			temperature?: number
 			maxResponseTokens?: number
 		} = {}
@@ -809,8 +828,10 @@ export class IterationOrchestrator {
 			}
 			prepared.allowedTools = known
 		}
+		if (result.toolChoice !== undefined) prepared.toolChoice = result.toolChoice
 		if (result.model !== undefined) prepared.model = result.model
 		if (result.system !== undefined) prepared.system = result.system
+		if (result.skills !== undefined) prepared.skills = result.skills
 		if (result.temperature !== undefined) prepared.temperature = result.temperature
 		if (result.maxResponseTokens !== undefined) {
 			prepared.maxResponseTokens = result.maxResponseTokens