@namzu/sdk 1.0.0 → 1.2.0

package/src/runtime/query/iteration/phases/checkpoint.ts

@@ -1,13 +1,43 @@
 import type { RunEvent } from '../../../../types/run/index.js'
 import { CheckpointManager } from '../../checkpoint.js'
-import { type IterationContext, type PhaseSignal, handleHITLDecision } from './context.js'
+import {
+	type IterationContext,
+	type PhaseSignal,
+	awaitDecisionOrAbort,
+	handleHITLDecision,
+} from './context.js'
+
+/**
+ * Cadence gate for the per-iteration checkpoint (`runConfig.checkpointEvery`,
+ * default 1 = every iteration). Off-cadence iterations skip the whole phase —
+ * no checkpoint, no `checkpoint_created` event, and no HITL
+ * `iteration_checkpoint` park (there is no checkpoint id to park on).
+ * Iterations 1, 1+N, 1+2N, … checkpoint, so the first tool iteration is
+ * always covered (a crash before the first cadence hit would otherwise leave
+ * nothing to resume from).
+ */
+function isOnCheckpointCadence(iterationNum: number, checkpointEvery: number | undefined): boolean {
+	const every = Math.max(1, Math.floor(checkpointEvery ?? 1))
+	return (iterationNum - 1) % every === 0
+}
 
 export async function* runIterationCheckpoint(
 	ctx: IterationContext,
 	iterationNum: number,
 ): AsyncGenerator<RunEvent, PhaseSignal> {
+	if (!isOnCheckpointCadence(iterationNum, ctx.runConfig.checkpointEvery)) {
+		return 'continue'
+	}
+
 	const iterCheckpoint = await ctx.checkpointMgr.create(ctx.runMgr, iterationNum)
 
+	// Growth control: keep only the newest N checkpoints when the host asked
+	// for pruning. Default undefined ⇒ never prune (today's behavior).
+	const pruneKeepLast = ctx.runConfig.pruneKeepLast
+	if (pruneKeepLast !== undefined && pruneKeepLast >= 1) {
+		await ctx.checkpointMgr.prune(Math.floor(pruneKeepLast))
+	}
+
 	await ctx.emitEvent({
 		type: 'checkpoint_created',
 		runId: ctx.runMgr.id,
@@ -17,7 +47,7 @@ export async function* runIterationCheckpoint(
 	yield* ctx.drainPending()
 
 	const summary = CheckpointManager.buildSummary(ctx.runMgr, iterationNum)
-	const iterDecision = await ctx.resumeHandler({
+	const iterDecision = await awaitDecisionOrAbort(ctx, {
 		type: 'iteration_checkpoint',
 		runId: ctx.runMgr.id,
 		checkpointId: iterCheckpoint.id,

package/src/runtime/query/iteration/phases/compaction.ts

@@ -1,12 +1,37 @@
+import { findSafeTrimIndex } from '../../../../compaction/dangling.js'
 import { serializeState } from '../../../../compaction/serializer.js'
 import { buildVerifiedSummary } from '../../../../compaction/verifier.js'
 import { CHARS_PER_TOKEN } from '../../../../constants/limits.js'
 import { createSystemMessage } from '../../../../types/message/index.js'
 import type { IterationContext } from './context.js'
+import { isWorkingMemoryMessage } from './working-memory.js'
 
 const COMPACTION_HEADER =
 	'[COMPACTED CONTEXT] The following is a structured summary of the conversation so far.'
 
+/**
+ * Identity check for a prior compaction summary in the leading floor. Used to
+ * REPLACE one in place on the per-iteration (contextWindowTokens) path so at
+ * most one `[COMPACTED CONTEXT]` block ever lives in the never-trimmed floor,
+ * and by the checkpoint-restore path to PRESERVE the summary across a resume
+ * (it is the only surviving record of the older history the run compacted away).
+ */
+export function isCompactionMessage(content: string | null | undefined): boolean {
+	return typeof content === 'string' && content.startsWith(COMPACTION_HEADER)
+}
+
+/**
+ * Minimum number of compactable (older) messages required before a compaction
+ * pass is worth running. When there is NOTHING between the never-trimmed
+ * leading floor and the recent window, a pass would only replace nothing with a
+ * `[COMPACTED CONTEXT]` summary that joins the floor — pure overhead that fires
+ * again next iteration (the permanent-floor thrash, ses_055 D7). Set to the
+ * literal EMPTY guard so any existing compaction consumer with ≥1 older message
+ * stays byte-identical; the per-iteration Vandal path additionally defangs the
+ * cost with `llmVerification:false`.
+ */
+const MIN_OLDER_MESSAGES_TO_COMPACT = 1
+
 function estimateTokens(ctx: IterationContext): number {
 	let chars = 0
 	for (const msg of ctx.runMgr.messages) {
@@ -31,7 +56,13 @@ export async function runCompactionCheck(ctx: IterationContext): Promise<void> {
 	if (!manager) return
 
 	const estimatedTokens = estimateTokens(ctx)
-	const budget = ctx.runConfig.tokenBudget
+	// F1: measure the CURRENT window against the model context window when the
+	// host supplies one, falling back to the run-level cumulative `tokenBudget`
+	// otherwise. Repointing the SINGLE `budget` assignment moves BOTH the
+	// `<= 0` guard AND the divisor at once — so "compaction on + tokenBudget=0"
+	// is no longer a silent no-op. Existing consumers (no contextWindowTokens)
+	// stay byte-identical.
+	const budget = config.contextWindowTokens ?? ctx.runConfig.tokenBudget
 	if (budget <= 0) return
 
 	const usage = estimatedTokens / budget
@@ -63,10 +94,34 @@ export async function runCompactionCheck(ctx: IterationContext): Promise<void> {
 	}
 	if (systemMessages.length === 0) return
 
-	const keepStart = messages.length - config.keepRecentMessages
+	// Tool-pair atomicity guard. A naive cut at `length - keepRecentMessages`
+	// can land BETWEEN an assistant-with-toolCalls (which would be dropped into
+	// `olderMessages`) and its `tool` results (kept in `recentMessages`),
+	// leaving orphaned `tool_result` blocks at the head of the recent window.
+	// The Anthropic provider then emits a `tool_result` with no matching
+	// `tool_use` and the API rejects the next turn with a 400 — so compaction,
+	// whose whole job is to keep a long run alive, instead kills it. Snap the
+	// boundary FORWARD to a safe point (existing `findSafeTrimIndex`, previously
+	// only wired to the unused ConversationManager strategy classes) so no pair
+	// is split. Any message this moves out of the recent window is already
+	// represented in the extracted WorkingState the summary is built from.
+	const keepStart = findSafeTrimIndex(messages, messages.length - config.keepRecentMessages)
 	const recentMessages = messages.slice(keepStart)
 	const olderMessages = messages.slice(systemMessages.length, keepStart)
 
+	// D7: nothing meaningful to compact — skip instead of thrashing the
+	// permanent leading floor every iteration (and avoid an LLM verification
+	// call when there is no older history to summarize). Scoped to the new
+	// contextWindowTokens path so any existing consumer (tokenBudget-only) keeps
+	// its exact prior behavior — byte-identical (ses_055 verify).
+	if (config.contextWindowTokens != null && olderMessages.length < MIN_OLDER_MESSAGES_TO_COMPACT) {
+		ctx.log.debug('Skipping compaction — too few older messages', {
+			runId: ctx.runMgr.id,
+			olderMessages: olderMessages.length,
+		})
+		return
+	}
+
 	let compactedContent: string
 
 	if (config.llmVerification && manager.slotCount() < config.richStateThreshold) {
@@ -77,7 +132,38 @@ export async function runCompactionCheck(ctx: IterationContext): Promise<void> {
 
 	const compactionMessage = createSystemMessage(`${COMPACTION_HEADER}\n\n${compactedContent}`)
 
-	const newMessages = [...systemMessages, compactionMessage, ...recentMessages]
+	// On the new per-iteration (contextWindowTokens) path, drop any PRIOR
+	// `[COMPACTED CONTEXT]` summary from the leading floor — `serializeState` is
+	// cumulative, so the new summary supersedes it. Without this the never-trimmed
+	// floor accumulates one redundant summary per pass and the frequent
+	// per-iteration trigger makes that bloat unbounded (ses_055 verify, MEDIUM).
+	// Legacy consumers (no contextWindowTokens) keep their exact prior
+	// accumulation behavior — byte-identical.
+	const preservedSystem =
+		config.contextWindowTokens != null
+			? systemMessages.filter((m) => !isCompactionMessage(m.content))
+			: systemMessages
+	const newMessages = [...preservedSystem, compactionMessage, ...recentMessages]
+
+	// OPAQUE survival guard (ses_055 D1): the pinned working-memory slot is a
+	// leading system message, so it is kept in `preservedSystem` (the compaction
+	// filter only drops prior `[COMPACTED CONTEXT]` summaries, never the WM slot)
+	// and survives for free — this branch is DEFENSIVE-ONLY, exercised only if a
+	// future change drops the slot from the rebuilt set. It re-pins the block
+	// already present in `messages` (the one `refreshWorkingMemory` placed).
+	// Identity is the sentinel HEADER only — no path parsing, no second provider
+	// call, no host format knowledge in the SDK.
+	const survives = newMessages.some((m) => m.role === 'system' && isWorkingMemoryMessage(m.content))
+	if (!survives) {
+		const priorSlot = messages.find((m) => m.role === 'system' && isWorkingMemoryMessage(m.content))
+		if (priorSlot) {
+			// Re-pin as the last leading system message, before the summary.
+			newMessages.splice(preservedSystem.length, 0, priorSlot)
+			ctx.log.warn('Re-pinned working-memory slot dropped by compaction', {
+				runId: ctx.runMgr.id,
+			})
+		}
+	}
 
 	const oldCount = messages.length
 	messages.length = 0

package/src/runtime/query/iteration/phases/context.ts

@@ -5,7 +5,8 @@ import type { CompactionConfig } from '../../../../config/runtime.js'
 import type { PlanManager } from '../../../../manager/plan/lifecycle.js'
 import type { RunPersistence } from '../../../../manager/run/persistence.js'
 import type { ActivityStore } from '../../../../store/activity/memory.js'
-import type { TaskGateway, TaskHandle } from '../../../../types/agent/gateway.js'
+import type { TaskGateway } from '../../../../types/agent/gateway.js'
+import type { WorkingMemoryProvider } from '../../../../types/agent/working-memory.js'
 import type { HITLResumeDecision, ResumeHandler } from '../../../../types/hitl/index.js'
 import type { TaskId } from '../../../../types/ids/index.js'
 import type { LLMProvider } from '../../../../types/provider/index.js'
@@ -55,14 +56,14 @@ export interface IterationContext {
 
 	readonly taskStore?: TaskStore
 
-	readonly pendingNotifications: TaskHandle[]
-
 	readonly launchedTasks: Map<TaskId, LaunchedTaskMeta>
 
 	readonly compactionConfig?: CompactionConfig
 
 	readonly workingStateManager?: WorkingStateManager
 
+	readonly workingMemoryProvider?: WorkingMemoryProvider
+
 	readonly advisoryCtx?: AdvisoryContext
 
 	readonly agentBus?: AgentBus
@@ -74,6 +75,57 @@ export interface IterationContext {
 
 export type PhaseSignal = 'continue' | 'stop'
 
+/**
+ * Await a HITL `resumeHandler` decision, but RACE it against the run's abort
+ * signal. A Stop that arrives while the run is parked on a tool-review or
+ * iteration checkpoint used to do nothing until the host eventually answered
+ * (the park await was not cancellable). Racing the signal lets a Stop resolve
+ * the park immediately as an `abort` decision, which `handleHITLDecision`
+ * turns into `setStopReason('cancelled') + markCancelled + stop`. Fails closed:
+ * a resume-handler rejection also resolves to `abort` rather than hanging.
+ */
+export async function awaitDecisionOrAbort(
+	ctx: IterationContext,
+	request: Parameters<ResumeHandler>[0],
+): Promise<HITLResumeDecision> {
+	const signal = ctx.abortController?.signal
+	// No abort signal wired (e.g. a minimal test harness) → behave exactly as a
+	// direct resumeHandler await, no race. In production RunContextFactory always
+	// provides the controller, so the race below is live.
+	if (!signal) return ctx.resumeHandler(request)
+	const abortDecision: HITLResumeDecision = {
+		action: 'abort',
+		reason: 'run aborted while parked for HITL',
+	}
+	if (signal.aborted) return abortDecision
+	return new Promise<HITLResumeDecision>((resolve) => {
+		let settled = false
+		const onAbort = (): void => {
+			if (settled) return
+			settled = true
+			resolve(abortDecision)
+		}
+		signal.addEventListener('abort', onAbort, { once: true })
+		Promise.resolve(ctx.resumeHandler(request)).then(
+			(decision) => {
+				if (settled) return
+				settled = true
+				signal.removeEventListener('abort', onAbort)
+				resolve(decision)
+			},
+			(err) => {
+				if (settled) return
+				settled = true
+				signal.removeEventListener('abort', onAbort)
+				resolve({
+					action: 'abort',
+					reason: err instanceof Error ? err.message : 'resume handler failed',
+				})
+			},
+		)
+	})
+}
+
 export async function* handleHITLDecision(
 	ctx: IterationContext,
 	decision: HITLResumeDecision,
@@ -125,6 +177,10 @@ export async function* handleHITLDecision(
 		case 'approve_tools':
 		case 'modify_tools':
 		case 'reject_tools':
+		// 'answer_question' can only arrive misdirected at an iteration
+		// checkpoint (answers are consumed inside the ask_user_question
+		// tool's own park); treat it as a plain continue.
+		case 'answer_question':
 			return 'continue'
 		default: {
 			const _exhaustive: never = decision

package/src/runtime/query/iteration/phases/hitl-abort-race.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'vitest'
+
+import type { HITLResumeDecision } from '../../../../types/hitl/index.js'
+import type { RunId } from '../../../../types/ids/index.js'
+import { type IterationContext, awaitDecisionOrAbort } from './context.js'
+
+/**
+ * C12: a Stop that arrives while the run is parked on a HITL decision must
+ * interrupt the park (resolve as `abort`) instead of hanging until the host
+ * eventually answers. `awaitDecisionOrAbort` races `resumeHandler` against
+ * `ctx.abortController.signal`.
+ */
+
+function ctxWith(opts: {
+	controller?: AbortController
+	resumeHandler: IterationContext['resumeHandler']
+}): IterationContext {
+	return {
+		abortController: opts.controller,
+		resumeHandler: opts.resumeHandler,
+		runMgr: { id: 'run_abort_test' as RunId },
+	} as unknown as IterationContext
+}
+
+const REVIEW_REQUEST = {
+	type: 'tool_review' as const,
+	runId: 'run_abort_test' as RunId,
+	checkpointId: 'cp_1' as `cp_${string}`,
+	toolCalls: [],
+}
+
+describe('awaitDecisionOrAbort (C12 — cancellable HITL park)', () => {
+	it('returns abort immediately when the signal is already aborted', async () => {
+		const controller = new AbortController()
+		controller.abort()
+		const ctx = ctxWith({
+			controller,
+			// A handler that never resolves — proving we did not wait on it.
+			resumeHandler: () => new Promise<HITLResumeDecision>(() => {}),
+		})
+		const decision = await awaitDecisionOrAbort(ctx, REVIEW_REQUEST)
+		expect(decision.action).toBe('abort')
+	})
+
+	it('resolves as abort when the signal fires DURING the park', async () => {
+		const controller = new AbortController()
+		const ctx = ctxWith({
+			controller,
+			resumeHandler: () => new Promise<HITLResumeDecision>(() => {}), // never answers
+		})
+		const pending = awaitDecisionOrAbort(ctx, REVIEW_REQUEST)
+		controller.abort()
+		const decision = await pending
+		expect(decision.action).toBe('abort')
+	})
+
+	it('returns the real decision when the handler answers before any abort', async () => {
+		const controller = new AbortController()
+		const ctx = ctxWith({
+			controller,
+			resumeHandler: async () => ({ action: 'approve_tools' }) as HITLResumeDecision,
+		})
+		const decision = await awaitDecisionOrAbort(ctx, REVIEW_REQUEST)
+		expect(decision.action).toBe('approve_tools')
+	})
+
+	it('degrades to a direct resumeHandler await when no controller is wired', async () => {
+		const ctx = ctxWith({
+			resumeHandler: async () => ({ action: 'reject_tools' }) as HITLResumeDecision,
+		})
+		const decision = await awaitDecisionOrAbort(ctx, REVIEW_REQUEST)
+		expect(decision.action).toBe('reject_tools')
+	})
+
+	it('fails closed to abort when the resume handler rejects', async () => {
+		const controller = new AbortController()
+		const ctx = ctxWith({
+			controller,
+			resumeHandler: async () => {
+				throw new Error('handler boom')
+			},
+		})
+		const decision = await awaitDecisionOrAbort(ctx, REVIEW_REQUEST)
+		expect(decision.action).toBe('abort')
+	})
+})

package/src/runtime/query/iteration/phases/hitl-answer-question.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, it } from 'vitest'
+
+import { type HITLResumeDecision, autoApproveHandler } from '../../../../types/hitl/index.js'
+import type { CheckpointId, RunId } from '../../../../types/ids/index.js'
+import type { ChatCompletionResponse } from '../../../../types/provider/index.js'
+import type { RunEvent } from '../../../../types/run/index.js'
+import { type IterationContext, handleHITLDecision } from './context.js'
+import { runToolReview } from './tool-review.js'
+
+async function drainGenerator<TReturn>(
+	gen: AsyncGenerator<RunEvent, TReturn>,
+): Promise<{ events: RunEvent[]; value: TReturn }> {
+	const events: RunEvent[] = []
+	let next = await gen.next()
+	while (!next.done) {
+		events.push(next.value)
+		next = await gen.next()
+	}
+	return { events, value: next.value }
+}
+
+describe('autoApproveHandler user_question case', () => {
+	it('returns the non-fabricating no-answer sentinel with the questionId echoed', async () => {
+		const decision = await autoApproveHandler({
+			type: 'user_question',
+			runId: 'run_headless_test' as RunId,
+			checkpointId: 'cp_question_toolu_1' as CheckpointId,
+			question: {
+				questionId: 'toolu_1',
+				question: 'Pick one?',
+				options: [
+					{ id: 'opt_1', label: 'A' },
+					{ id: 'opt_2', label: 'B' },
+				],
+				multiSelect: false,
+				allowFreeText: true,
+			},
+		})
+
+		expect(decision).toEqual({
+			action: 'answer_question',
+			selectedOptionIds: [],
+			freeText: 'No user is available to answer. Proceed using your best judgment.',
+			questionId: 'toolu_1',
+		})
+	})
+})
+
+describe('handleHITLDecision answer_question case', () => {
+	it("treats a misdirected 'answer_question' at an iteration checkpoint as continue", async () => {
+		// The branch returns without touching the context — answers are
+		// consumed inside the ask_user_question tool's own park, so an
+		// answer arriving here can only be misdirected.
+		const ctx = {} as IterationContext
+		const { events, value } = await drainGenerator(
+			handleHITLDecision(
+				ctx,
+				{ action: 'answer_question', selectedOptionIds: ['opt_1'] },
+				'cp_checkpoint_1',
+				'iteration checkpoint',
+			),
+		)
+		expect(value).toBe('continue')
+		expect(events).toEqual([])
+	})
+})
+
+describe('runToolReview answer_question case', () => {
+	function reviewContext(decision: HITLResumeDecision) {
+		const warns: string[] = []
+		const pushed: unknown[] = []
+		let batches = 0
+		const ctx = {
+			tools: { get: () => undefined },
+			checkpointMgr: {
+				create: async () => ({ id: 'cp_review_1' as CheckpointId }),
+			},
+			emitEvent: async () => {},
+			drainPending: (): Generator<RunEvent> => [][Symbol.iterator]() as Generator<RunEvent>,
+			resumeHandler: async () => decision,
+			log: {
+				debug: () => {},
+				info: () => {},
+				warn: (message: string) => {
+					warns.push(message)
+				},
+				error: () => {},
+			},
+			runMgr: {
+				id: 'run_tool_review_test' as RunId,
+				pushMessage: (message: unknown) => {
+					pushed.push(message)
+				},
+			},
+			toolExecutor: {
+				executeBatch: async () => {
+					batches += 1
+					return { messages: [], results: [] }
+				},
+			},
+		} as unknown as IterationContext
+		return { ctx, warns, pushed, batchCount: () => batches }
+	}
+
+	const response: ChatCompletionResponse = {
+		id: 'resp_1',
+		model: 'test-model',
+		message: {
+			role: 'assistant',
+			content: null,
+			toolCalls: [
+				{
+					id: 'toolu_review_1',
+					type: 'function',
+					function: { name: 'ask_user_question', arguments: '{}' },
+				},
+			],
+		},
+		finishReason: 'tool_calls',
+		usage: {
+			promptTokens: 0,
+			completionTokens: 0,
+			totalTokens: 0,
+			cachedTokens: 0,
+			cacheWriteTokens: 0,
+		},
+	}
+
+	it("warns and executes the batch on a misdirected 'answer_question' instead of stalling", async () => {
+		const { ctx, warns, batchCount } = reviewContext({
+			action: 'answer_question',
+			selectedOptionIds: [],
+		})
+		const { value } = await drainGenerator(runToolReview(ctx, response, 1))
+		expect(value).toBe('executed')
+		expect(batchCount()).toBe(1)
+		expect(warns).toHaveLength(1)
+	})
+})

package/src/runtime/query/iteration/phases/tool-review.ts

@@ -2,7 +2,7 @@ import { createUserMessage } from '../../../../types/message/index.js'
 import type { ChatCompletionResponse } from '../../../../types/provider/index.js'
 import type { RunEvent } from '../../../../types/run/index.js'
 import type { VerificationGate } from '../../../../verification/index.js'
-import type { IterationContext } from './context.js'
+import { type IterationContext, awaitDecisionOrAbort } from './context.js'
 
 interface VerificationAwareContext extends IterationContext {
 	readonly verificationGate?: VerificationGate
@@ -94,7 +94,7 @@ export async function* runToolReview(
 	})
 	yield* ctx.drainPending()
 
-	const reviewDecision = await ctx.resumeHandler({
+	const reviewDecision = await awaitDecisionOrAbort(ctx, {
 		type: 'tool_review',
 		runId: ctx.runMgr.id,
 		checkpointId: reviewCheckpoint.id,
@@ -198,7 +198,11 @@ export async function* runToolReview(
 		}
 
 		case 'approve_plan':
-		case 'reject_plan': {
+		case 'reject_plan':
+		// 'answer_question' belongs to an ask_user_question park, not a
+		// tool review — like the misdirected plan decisions above, warn
+		// and proceed with execution rather than stalling the run.
+		case 'answer_question': {
 			ctx.log.warn('Unexpected plan decision during tool review', {
 				action: reviewDecision.action,
 			})