@namzu/sdk 2.0.0 → 3.0.0

package/src/runtime/query/__tests__/reasoning-stream.test.ts

@@ -0,0 +1,177 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import type { RunId } from '../../../types/ids/index.js'
+import type { LLMProvider, StreamChunk } from '../../../types/provider/index.js'
+import { isEphemeralEvent } from '../../../types/run/events.js'
+import type { RunEvent } from '../../../types/run/index.js'
+import type { Logger } from '../../../utils/logger.js'
+import { streamProviderTurn } from '../iteration/stream-turn.js'
+
+/**
+ * Reasoning had no channel at all: `StreamChunk.delta` carried only
+ * `content` / `toolCalls`, so `thinking_delta` and `signature_delta` fell
+ * through the driver's `default: // ignore` and the blocks could
+ * not be stored even in principle. Two consequences — the verbatim-echo
+ * contract was unsatisfiable, and a streaming UI showed a multi-second
+ * stall with zero events while the model was demonstrably working.
+ */
+
+const RUN_ID = 'run_reasoning' as RunId
+
+function makeLogger(): Logger {
+	const stub = { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() }
+	return { ...stub, child: vi.fn(() => ({ ...stub, child: vi.fn() })) } as unknown as Logger
+}
+
+function providerOf(chunks: StreamChunk[]): LLMProvider {
+	return {
+		id: 'fake',
+		name: 'Fake',
+		chatStream: async function* () {
+			for (const c of chunks) yield c
+		},
+	} as unknown as LLMProvider
+}
+
+/** Drive the turn, collecting every event it emits. */
+async function run(chunks: StreamChunk[]) {
+	const events: RunEvent[] = []
+	const pending: RunEvent[] = []
+	const emitEvent = async (e: RunEvent) => {
+		events.push(e)
+		pending.push(e)
+	}
+	const drainPending = function* (): Generator<RunEvent> {
+		while (pending.length > 0) {
+			const next = pending.shift()
+			if (next) yield next
+		}
+	}
+
+	const gen = streamProviderTurn(
+		providerOf(chunks),
+		{ model: 'm', messages: [] } as never,
+		emitEvent,
+		drainPending,
+		RUN_ID,
+		1,
+		false,
+		makeLogger(),
+	)
+	let next = await gen.next()
+	while (!next.done) next = await gen.next()
+	return { result: next.value, events }
+}
+
+const finish = (): StreamChunk => ({
+	id: 'c',
+	delta: {},
+	finishReason: 'stop',
+	usage: {
+		promptTokens: 1,
+		completionTokens: 1,
+		totalTokens: 2,
+		cachedTokens: 0,
+		cacheWriteTokens: 0,
+	},
+})
+
+describe('reasoning blocks survive the stream', () => {
+	it('accumulates fragments into one block and keeps the signature', async () => {
+		const { result } = await run([
+			{ id: 'c', delta: { reasoning: { index: 0, type: 'thinking' } } },
+			{ id: 'c', delta: { reasoning: { index: 0, text: 'first ' } } },
+			{ id: 'c', delta: { reasoning: { index: 0, text: 'second' } } },
+			{ id: 'c', delta: { reasoning: { index: 0, signature: 'sig-xyz' } } },
+			{ id: 'c', delta: { reasoning: { index: 0, done: true } } },
+			{ id: 'c', delta: { content: 'answer' } },
+			finish(),
+		])
+
+		expect(result.response.message.reasoning).toEqual([
+			{ type: 'thinking', text: 'first second', signature: 'sig-xyz' },
+		])
+		expect(result.response.message.content).toBe('answer')
+	})
+
+	it('emits the started → delta → completed lifecycle', async () => {
+		const { events } = await run([
+			{ id: 'c', delta: { reasoning: { index: 0, type: 'thinking' } } },
+			{ id: 'c', delta: { reasoning: { index: 0, text: 'hm' } } },
+			{ id: 'c', delta: { reasoning: { index: 0, signature: 's' } } },
+			{ id: 'c', delta: { reasoning: { index: 0, done: true } } },
+			finish(),
+		])
+
+		const kinds = events.filter((e) => e.type.startsWith('reasoning_')).map((e) => e.type)
+		expect(kinds).toEqual(['reasoning_started', 'reasoning_delta', 'reasoning_completed'])
+
+		const completed = events.find((e) => e.type === 'reasoning_completed')
+		expect(completed).toMatchObject({ text: 'hm', signed: true, blockIndex: 0 })
+	})
+
+	it('reports signed:false when the provider sent no signature', async () => {
+		const { events } = await run([
+			{ id: 'c', delta: { reasoning: { index: 0, type: 'thinking', text: 'x' } } },
+			{ id: 'c', delta: { reasoning: { index: 0, done: true } } },
+			finish(),
+		])
+		expect(events.find((e) => e.type === 'reasoning_completed')).toMatchObject({ signed: false })
+	})
+
+	it('keeps a redacted block by its opaque payload', async () => {
+		const { result } = await run([
+			{
+				id: 'c',
+				delta: { reasoning: { index: 0, type: 'redacted_thinking', encrypted: 'blob' } },
+			},
+			{ id: 'c', delta: { reasoning: { index: 0, done: true } } },
+			finish(),
+		])
+		expect(result.response.message.reasoning).toEqual([
+			{ type: 'redacted_thinking', encrypted: 'blob' },
+		])
+	})
+
+	it('returns multiple blocks in stream-index order, not arrival order', async () => {
+		// A provider that opens index 1 before index 0 must still replay in
+		// block order — the echo contract is about the original ordering.
+		const { result } = await run([
+			{ id: 'c', delta: { reasoning: { index: 1, type: 'thinking', text: 'second' } } },
+			{ id: 'c', delta: { reasoning: { index: 0, type: 'thinking', text: 'first' } } },
+			{ id: 'c', delta: { reasoning: { index: 0, done: true } } },
+			{ id: 'c', delta: { reasoning: { index: 1, done: true } } },
+			finish(),
+		])
+		expect(result.response.message.reasoning?.map((b) => b.text)).toEqual(['first', 'second'])
+	})
+
+	it('omits `reasoning` entirely when the model emitted none', async () => {
+		const { result } = await run([{ id: 'c', delta: { content: 'plain' } }, finish()])
+		expect(result.response.message.reasoning).toBeUndefined()
+	})
+
+	it('marks reasoning_delta ephemeral so the transcript is not flooded', () => {
+		expect(
+			isEphemeralEvent({
+				type: 'reasoning_delta',
+				runId: RUN_ID,
+				iteration: 1,
+				messageId: 'msg_x',
+				blockIndex: 0,
+				text: 'x',
+			} as unknown as RunEvent),
+		).toBe(true)
+		// The completed block carries the full text and IS recorded.
+		expect(
+			isEphemeralEvent({
+				type: 'reasoning_completed',
+				runId: RUN_ID,
+				iteration: 1,
+				messageId: 'msg_x',
+				blockIndex: 0,
+				signed: true,
+			} as unknown as RunEvent),
+		).toBe(false)
+	})
+})

package/src/runtime/query/__tests__/recoverable-settle.test.ts

@@ -0,0 +1,145 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { NamzuError } from '../../../types/errors/index.js'
+import type { CheckpointId } from '../../../types/hitl/index.js'
+import type { RunId } from '../../../types/ids/index.js'
+import { ProviderError } from '../../../types/provider/errors.js'
+import type { RunEvent } from '../../../types/run/index.js'
+import { ResultAssembler } from '../result.js'
+
+/**
+ * A 503 that survived every in-turn recovery — retry with jitter, the
+ * one-shot compaction relief, mid-stream salvage — settled the run as
+ * `failed`, identically to a bad API key. The host could not tell them
+ * apart, and recovering meant knowing about checkpoints and driving
+ * replay itself.
+ *
+ * The state was never the problem: checkpoints are written every iteration
+ * by default and the failed run is persisted with full messages. Only the
+ * settle and the signal were missing.
+ */
+
+const RID = 'run_1' as RunId
+const CP = 'cp_7' as CheckpointId
+
+function makeLogger() {
+	const calls: Array<{ level: string; message: string }> = []
+	const self = {
+		calls,
+		info: (m: string) => calls.push({ level: 'info', message: m }),
+		warn: (m: string) => calls.push({ level: 'warn', message: m }),
+		error: (m: string) => calls.push({ level: 'error', message: m }),
+		debug: vi.fn(),
+	}
+	;(self as unknown as { child: () => unknown }).child = () => self
+	return self
+}
+
+async function settle(err: unknown, resumeFrom?: CheckpointId) {
+	const emitted: RunEvent[] = []
+	const pending: RunEvent[] = []
+	const marks: string[] = []
+	const spanStatus: number[] = []
+
+	const assembler = new ResultAssembler({
+		runMgr: {
+			id: RID,
+			currentIteration: 4,
+			stopReason: undefined,
+			markFailed: () => marks.push('failed'),
+			setStopReason: (reason: string) => marks.push(`stop:${reason}`),
+			setLastError: () => marks.push('lastError'),
+			getRun: () => ({ id: RID }),
+		} as never,
+		planManager: { isActive: false, failPlan: () => marks.push('planFailed') } as never,
+		activityStore: { enabled: false } as never,
+		log: makeLogger() as never,
+		emitEvent: async (event: RunEvent) => {
+			emitted.push(event)
+			pending.push(event)
+		},
+		drainPending: function* () {
+			while (pending.length > 0) {
+				const next = pending.shift()
+				if (next) yield next
+			}
+		},
+		resumeCheckpointId: () => resumeFrom,
+	} as never)
+
+	const span = {
+		setAttributes: () => {},
+		setStatus: (s: { code: number }) => spanStatus.push(s.code),
+		recordException: () => {},
+		end: () => {},
+	} as never
+
+	for await (const _event of assembler.handleError(err, span)) {
+		// drain
+	}
+	return { emitted, marks, spanStatus }
+}
+
+const transient = () =>
+	new ProviderError({ code: 'overloaded', message: 'try later', providerId: 'test', status: 529 })
+
+const permanent = () =>
+	new ProviderError({ code: 'auth', message: 'bad key', providerId: 'test', status: 401 })
+
+describe('a transient failure with somewhere to resume from', () => {
+	it('settles paused, not failed', async () => {
+		const { emitted, marks } = await settle(transient(), CP)
+
+		expect(emitted.map((e) => e.type)).toEqual(['run_paused'])
+		expect(marks).toContain('stop:paused')
+		expect(marks).not.toContain('failed')
+	})
+
+	it('names the checkpoint a host should resume from', async () => {
+		const { emitted } = await settle(transient(), CP)
+		const paused = emitted[0]
+		expect(paused?.type === 'run_paused' && paused.checkpointId).toBe(CP)
+	})
+
+	it('leaves the span OK, so it does not land in an error dashboard', async () => {
+		// SpanStatusCode.OK === 1, ERROR === 2.
+		const { spanStatus } = await settle(transient(), CP)
+		expect(spanStatus).toEqual([1])
+	})
+
+	it('records why it stopped without marking the run failed', async () => {
+		const { marks } = await settle(transient(), CP)
+		expect(marks).toContain('lastError')
+	})
+})
+
+describe('a failure that pausing would not help', () => {
+	it('still fails on a permanent error', async () => {
+		// Pausing on a bad API key would invite a resume that cannot work.
+		const { emitted, marks } = await settle(permanent(), CP)
+
+		expect(emitted.map((e) => e.type)).toEqual(['run_failed'])
+		expect(marks).toContain('failed')
+	})
+
+	it('still fails when there is no checkpoint to resume from', async () => {
+		// Pausing with nowhere to resume from is a run that can never be
+		// picked up again — strictly worse than reporting the failure.
+		const { emitted } = await settle(transient(), undefined)
+		expect(emitted.map((e) => e.type)).toEqual(['run_failed'])
+	})
+
+	it('still fails on a namzu error that is not retryable', async () => {
+		const { emitted } = await settle(
+			new NamzuError({ code: 'invalid_config', message: 'no model' }),
+			CP,
+		)
+		expect(emitted.map((e) => e.type)).toEqual(['run_failed'])
+	})
+
+	it('carries the explanation on the failure it does report', async () => {
+		const { emitted } = await settle(permanent(), CP)
+		const failed = emitted[0]
+		expect(failed?.type === 'run_failed' && failed.explanation?.id).toBe('provider.auth')
+	})
+})

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

@@ -0,0 +1,158 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import type { RunPersistence } from '../../../manager/run/persistence.js'
+import { GuardCoordinator } from '../guard.js'
+
+/**
+ * Budgets belong to the RUN, not to the process hosting it.
+ *
+ * A run checkpointed at $4.80 of a $5 cap used to come back with a brand-new
+ * $5 and a brand-new timeout clock, because the resume path replayed messages
+ * and nothing else — while the checkpoint had faithfully persisted usage,
+ * cost and elapsed time all along. A task that parked five times spent 5x its
+ * cap with every invocation truthfully reporting itself in budget.
+ */
+
+function runMgrAt(opts: {
+	totalTokens?: number
+	totalCost?: number
+	iteration?: number
+}): RunPersistence {
+	return {
+		tokenUsage: { totalTokens: opts.totalTokens ?? 0 },
+		costInfo: { totalCost: opts.totalCost ?? 0 },
+		currentIteration: opts.iteration ?? 0,
+	} as unknown as RunPersistence
+}
+
+const live = new AbortController().signal
+
+describe('GuardCoordinator — elapsed time survives a resume', () => {
+	it('a fresh guard has spent none of its timeout', () => {
+		const guard = new GuardCoordinator({ tokenBudget: 0, timeoutMs: 10_000 })
+		expect(guard.beforeIteration(runMgrAt({}), live).shouldStop).toBe(false)
+	})
+
+	it('stops immediately when the restored elapsed time already exceeds the timeout', () => {
+		const guard = new GuardCoordinator({ tokenBudget: 0, timeoutMs: 10_000 })
+		guard.restoreElapsed(11_000)
+
+		const result = guard.beforeIteration(runMgrAt({}), live)
+		expect(result.shouldStop).toBe(true)
+		expect(result.stopReason).toBe('timeout')
+	})
+
+	it('force-finalizes when the restored elapsed time is past the warning threshold', () => {
+		const guard = new GuardCoordinator({ tokenBudget: 0, timeoutMs: 10_000 })
+		guard.restoreElapsed(9_500) // 95% of budget, warn at 90%
+
+		const result = guard.beforeIteration(runMgrAt({}), live)
+		expect(result.shouldStop).toBe(false)
+		expect(result.forceFinalize).toBe(true)
+	})
+
+	it('accepts the offset at construction too', () => {
+		const guard = new GuardCoordinator({
+			tokenBudget: 0,
+			timeoutMs: 10_000,
+			elapsedMsOffset: 11_000,
+		})
+		expect(guard.beforeIteration(runMgrAt({}), live).stopReason).toBe('timeout')
+	})
+
+	it('treats a negative offset as zero rather than buying extra time', () => {
+		const guard = new GuardCoordinator({
+			tokenBudget: 0,
+			timeoutMs: 10_000,
+			elapsedMsOffset: -60_000,
+		})
+		expect(guard.beforeIteration(runMgrAt({}), live).shouldStop).toBe(false)
+	})
+
+	it('a resumed run already over its cost cap stops on its first iteration', () => {
+		const guard = new GuardCoordinator({ tokenBudget: 0, timeoutMs: 600_000, costLimitUsd: 5 })
+		// Post-restore state: the run had already spent $4.90 before the park.
+		const result = guard.beforeIteration(runMgrAt({ totalCost: 5.1 }), live)
+		expect(result.shouldStop).toBe(true)
+		expect(result.stopReason).toBe('cost_limit')
+	})
+
+	it('a resumed run already at its iteration cap stops on its first iteration', () => {
+		const guard = new GuardCoordinator({
+			tokenBudget: 0,
+			timeoutMs: 600_000,
+			maxIterations: 20,
+		})
+		expect(guard.beforeIteration(runMgrAt({ iteration: 20 }), live).stopReason).toBe(
+			'max_iterations',
+		)
+	})
+})
+
+describe('RunPersistence.restoreUsage', () => {
+	it('replaces the counters rather than adding to them', async () => {
+		const { RunPersistence } = await import('../../../manager/run/persistence.js')
+		const mgr = new RunPersistence({
+			runId: 'run_x',
+			agentId: 'a',
+			agentName: 'A',
+			runConfig: {},
+			providerId: 'mock',
+			outputDir: '/tmp',
+			log: {
+				info: vi.fn(),
+				warn: vi.fn(),
+				error: vi.fn(),
+				debug: vi.fn(),
+				child: vi.fn(() => ({
+					info: vi.fn(),
+					warn: vi.fn(),
+					error: vi.fn(),
+					debug: vi.fn(),
+					child: vi.fn(),
+				})),
+			},
+			sessionId: 's',
+			threadId: 't',
+			projectId: 'p',
+			tenantId: 'tn',
+		} as any)
+
+		mgr.accumulateUsage({
+			promptTokens: 10,
+			completionTokens: 5,
+			totalTokens: 15,
+			cachedTokens: 0,
+			cacheWriteTokens: 0,
+		})
+		expect(mgr.tokenUsage.totalTokens).toBe(15)
+
+		mgr.restoreUsage(
+			{
+				promptTokens: 900,
+				completionTokens: 100,
+				totalTokens: 1000,
+				cachedTokens: 0,
+				cacheWriteTokens: 0,
+			},
+			{ inputCostPer1M: 0, outputCostPer1M: 0, totalCost: 4.8, cacheDiscount: 0 },
+			7,
+		)
+
+		// Restore, not accumulate: the checkpoint holds absolute totals.
+		expect(mgr.tokenUsage.totalTokens).toBe(1000)
+		expect(mgr.costInfo.totalCost).toBe(4.8)
+		expect(mgr.currentIteration).toBe(7)
+
+		// And the run keeps accumulating from the restored point.
+		mgr.accumulateUsage({
+			promptTokens: 1,
+			completionTokens: 1,
+			totalTokens: 2,
+			cachedTokens: 0,
+			cacheWriteTokens: 0,
+		})
+		expect(mgr.tokenUsage.totalTokens).toBe(1002)
+		expect(mgr.incrementIteration()).toBe(8)
+	})
+})