@namzu/sdk 1.3.0 → 2.0.0

package/src/compaction/__tests__/verifier-empty-reply.test.ts

@@ -0,0 +1,96 @@
+/**
+ * The EMPTY VERIFIER REPLY.
+ *
+ * `buildVerifiedSummary` treats only the literal `COMPLETE` as "nothing to add".
+ * Anything else is appended under a `## LLM Verification Additions` heading —
+ * including the empty string, which is what a truncated turn, a refusal, or an
+ * exhausted `llmVerificationMaxTokens` produces. The result is a heading with
+ * nothing under it, and because the summary becomes a leading system message it
+ * then rides in EVERY subsequent prompt of the run.
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import { CompactionConfigSchema } from '../../config/runtime.js'
+import {
+	type Message,
+	createAssistantMessage,
+	createUserMessage,
+} from '../../types/message/index.js'
+import type { ChatCompletionParams } from '../../types/provider/chat.js'
+import type { LLMProvider } from '../../types/provider/interface.js'
+import type { StreamChunk } from '../../types/provider/stream.js'
+import { WorkingStateManager } from '../manager.js'
+import { buildVerifiedSummary } from '../verifier.js'
+
+const ADDITIONS_HEADING = '## LLM Verification Additions'
+
+function makeProvider(chunks: StreamChunk[]): LLMProvider & { calls: ChatCompletionParams[] } {
+	const calls: ChatCompletionParams[] = []
+	return {
+		id: 'mock',
+		name: 'mock',
+		calls,
+		chatStream(params: ChatCompletionParams): AsyncIterable<StreamChunk> {
+			calls.push(params)
+			return (async function* () {
+				for (const c of chunks) yield c
+			})()
+		},
+	}
+}
+
+function makeManager() {
+	const config = CompactionConfigSchema.parse({ llmVerification: true })
+	const manager = new WorkingStateManager(config)
+	manager.setTask('write the quarterly report')
+	manager.addDecision('built the report as .docx')
+	return { config, manager }
+}
+
+const OLDER: Message[] = [
+	createUserMessage('write the quarterly report'),
+	createAssistantMessage('on it — reading the source numbers first'),
+]
+
+describe('buildVerifiedSummary — empty verifier reply', () => {
+	it('does not append an empty "Additions" section when the verifier returns nothing', async () => {
+		const { config, manager } = makeManager()
+		const provider = makeProvider([])
+
+		const result = await buildVerifiedSummary(manager, OLDER, provider, config)
+
+		expect(result).not.toContain(ADDITIONS_HEADING)
+	})
+
+	it('does not append an empty "Additions" section when the turn is truncated by maxTokens', async () => {
+		const { config, manager } = makeManager()
+		// `length` finish reason with no content — llmVerificationMaxTokens exhausted.
+		const provider = makeProvider([{ id: 'c1', delta: { content: '' }, finishReason: 'length' }])
+
+		const result = await buildVerifiedSummary(manager, OLDER, provider, config)
+
+		expect(result).not.toContain(ADDITIONS_HEADING)
+	})
+
+	it('does not append an "Additions" section for a whitespace-only reply', async () => {
+		const { config, manager } = makeManager()
+		const provider = makeProvider([{ id: 'c1', delta: { content: '   \n\n  ' } }])
+
+		const result = await buildVerifiedSummary(manager, OLDER, provider, config)
+
+		expect(result).not.toContain(ADDITIONS_HEADING)
+	})
+
+	it('still appends real additions', async () => {
+		const { config, manager } = makeManager()
+		const provider = makeProvider([
+			{ id: 'c1', delta: { content: '- the user asked for EUR, not USD' } },
+		])
+
+		const result = await buildVerifiedSummary(manager, OLDER, provider, config)
+
+		expect(result).toContain(ADDITIONS_HEADING)
+		expect(result).toContain('EUR, not USD')
+	})
+})

package/src/compaction/verifier.ts

@@ -86,7 +86,16 @@ export async function buildVerifiedSummary(
 
 	const responseText = response.message.content?.trim() ?? ''
 
-	if (responseText === 'COMPLETE') {
+	// `COMPLETE` is the verifier saying it found nothing to add. An EMPTY reply
+	// says the same thing by accident — a turn truncated at
+	// `llmVerificationMaxTokens`, a refusal, or a provider that returned no
+	// content at all — and used to fall through to the append below, stamping a
+	// bare `## LLM Verification Additions` heading with nothing under it. That
+	// empty promise then rides in the compaction summary, and therefore in every
+	// subsequent system prompt, for the rest of the run. A heading with no body
+	// is not a verification result; treat a silent verifier the same as one that
+	// had nothing to say.
+	if (responseText === 'COMPLETE' || responseText.length === 0) {
 		return serialized
 	}
 

package/src/config/__tests__/compaction-budget-schema.test.ts

@@ -0,0 +1,114 @@
+/**
+ * The BUDGET SCHEMA.
+ *
+ * Every compaction count used to be `z.number().positive()`. Zod's base number
+ * check rejects only non-numbers and `NaN`, so `Infinity` and `0.5` both parsed.
+ * These are counts of messages, characters, sentences and tokens: a non-integer
+ * is meaningless, and `Infinity` does something worse than being meaningless —
+ * it turns a bound into a no-op rather than an error. `truncateMessages` compares
+ * `charCount > budget`, never true against `Infinity`, so the WHOLE older history
+ * was pasted into the verification prompt.
+ *
+ * They are `.int().positive()` now. `Number.isInteger` is false for `Infinity`
+ * and for any fraction, so one validator closes both. These tests are the guard:
+ * every count is checked against both illegal shapes, and the documented
+ * defaults are pinned so tightening the validator cannot have moved them.
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import { WorkingStateManager } from '../../compaction/manager.js'
+import { buildVerifiedSummary } from '../../compaction/verifier.js'
+import { type Message, createUserMessage } from '../../types/message/index.js'
+import type { ChatCompletionParams } from '../../types/provider/chat.js'
+import type { LLMProvider } from '../../types/provider/interface.js'
+import type { StreamChunk } from '../../types/provider/stream.js'
+import { CompactionConfigSchema, RuntimeConfigSchema } from '../runtime.js'
+
+/** Every integer count on CompactionConfigSchema. */
+const COUNT_FIELDS = [
+	'contextWindowTokens',
+	'keepRecentMessages',
+	'maxToolResults',
+	'maxListSize',
+	'llmVerificationMaxTokens',
+	'richStateThreshold',
+	'convoTextBudget',
+	'maxSentencesPerTurn',
+	'maxCharsPerNote',
+	'maxCharsPerRequirement',
+	'maxCharsPerTask',
+] as const
+
+describe('CompactionConfigSchema — count fields', () => {
+	for (const field of COUNT_FIELDS) {
+		it(`rejects Infinity for ${field}`, () => {
+			expect(() => CompactionConfigSchema.parse({ [field]: Number.POSITIVE_INFINITY })).toThrow()
+		})
+
+		it(`rejects a fractional value for ${field}`, () => {
+			expect(() => CompactionConfigSchema.parse({ [field]: 0.5 })).toThrow()
+		})
+	}
+
+	it('rejects Infinity through the RuntimeConfigSchema envelope', () => {
+		expect(() =>
+			RuntimeConfigSchema.parse({ compaction: { convoTextBudget: Number.POSITIVE_INFINITY } }),
+		).toThrow()
+	})
+
+	it('still accepts the documented defaults', () => {
+		const parsed = CompactionConfigSchema.parse({})
+		expect(parsed.convoTextBudget).toBe(12_000)
+		expect(parsed.keepRecentMessages).toBe(4)
+	})
+})
+
+/**
+ * Why the schema is the only defence, and what that leaves open.
+ *
+ * `truncateMessages` bounds the verification prompt with `charCount > budget`,
+ * which is never true against `Infinity` — that is the consequence the schema
+ * fix above exists to prevent, and it can no longer be reached THROUGH the
+ * schema. It is still reachable by a host that hand-builds a `CompactionConfig`
+ * object literal, because the inferred type is plain `number`; that is a stated
+ * limitation, not a covered case. No silent clamp was added inside
+ * `truncateMessages` — a budget that quietly repairs an illegal value hides the
+ * caller's bug instead of surfacing it, and the schema is where the boundary
+ * belongs.
+ *
+ * What this test does pin: with a LEGAL budget the prompt really is bounded, so
+ * the truncation the schema now guarantees is actually performed.
+ */
+describe('truncateMessages bounds the verification prompt at a legal budget', () => {
+	it('does not paste the entire older history into the verification prompt', async () => {
+		const config = CompactionConfigSchema.parse({
+			llmVerification: true,
+			convoTextBudget: 12_000,
+		})
+		const manager = new WorkingStateManager(config)
+		manager.setTask('write the quarterly report')
+
+		const calls: ChatCompletionParams[] = []
+		const provider: LLMProvider = {
+			id: 'mock',
+			name: 'mock',
+			chatStream(params: ChatCompletionParams): AsyncIterable<StreamChunk> {
+				calls.push(params)
+				return (async function* () {
+					yield { id: 'c1', delta: { content: 'COMPLETE' } } as StreamChunk
+				})()
+			},
+		}
+
+		// ~200 KB of older history — far past any sane verification budget.
+		const older: Message[] = Array.from({ length: 200 }, (_, i) =>
+			createUserMessage(`turn ${i} ${'y'.repeat(1000)}`),
+		)
+
+		await buildVerifiedSummary(manager, older, provider, config)
+
+		const promptChars = (calls[0]?.messages ?? []).reduce((n, m) => n + (m.content?.length ?? 0), 0)
+		expect(promptChars).toBeLessThan(100_000)
+	})
+})

package/src/config/runtime.ts

@@ -26,20 +26,29 @@ export const CompactionConfigSchema = z.object({
 	 * `tokenBudget` unlimited (0) set this so compaction fires on
 	 * window-pressure instead of being a silent no-op.
 	 */
-	contextWindowTokens: z.number().positive().optional(),
+	// Every field below counts something — tokens, messages, characters,
+	// sentences. `z.number().positive()` was the wrong validator for all of them:
+	// Zod's base number check rejects only non-numbers and NaN, so `Infinity` and
+	// `0.5` both passed. `Infinity` is the dangerous one, because it turns a bound
+	// into a no-op rather than an error — `convoTextBudget: Infinity` makes the
+	// verifier's `charCount > budget` test never true, so `truncateMessages` stops
+	// truncating and the WHOLE history is pasted into the verification prompt.
+	// A fraction is merely nonsense (`keepRecentMessages: 2.5`). `.int()` rejects
+	// both: `Number.isInteger` is false for Infinity and for any fraction.
+	contextWindowTokens: z.number().int().positive().optional(),
 	triggerThreshold: z.number().min(0).max(1).default(0.7),
 	resetThreshold: z.number().min(0).max(1).default(0.4),
-	keepRecentMessages: z.number().positive().default(4),
-	maxToolResults: z.number().positive().default(30),
-	maxListSize: z.number().positive().default(25),
+	keepRecentMessages: z.number().int().positive().default(4),
+	maxToolResults: z.number().int().positive().default(30),
+	maxListSize: z.number().int().positive().default(25),
 	llmVerification: z.boolean().default(true),
-	llmVerificationMaxTokens: z.number().positive().default(2048),
-	richStateThreshold: z.number().positive().default(15),
-	convoTextBudget: z.number().positive().default(12_000),
-	maxSentencesPerTurn: z.number().positive().default(5),
-	maxCharsPerNote: z.number().positive().default(500),
-	maxCharsPerRequirement: z.number().positive().default(300),
-	maxCharsPerTask: z.number().positive().default(400),
+	llmVerificationMaxTokens: z.number().int().positive().default(2048),
+	richStateThreshold: z.number().int().positive().default(15),
+	convoTextBudget: z.number().int().positive().default(12_000),
+	maxSentencesPerTurn: z.number().int().positive().default(5),
+	maxCharsPerNote: z.number().int().positive().default(500),
+	maxCharsPerRequirement: z.number().int().positive().default(300),
+	maxCharsPerTask: z.number().int().positive().default(400),
 })
 
 export type CompactionConfig = z.infer<typeof CompactionConfigSchema>

package/src/manager/run/persistence.ts

@@ -5,6 +5,7 @@ import { RunDiskStore } from '../../store/run/disk.js'
 import { type CostInfo, type TokenUsage, accumulateTokenUsage } from '../../types/common/index.js'
 import type { RunId, SessionId, TenantId } from '../../types/ids/index.js'
 import type { Message } from '../../types/message/index.js'
+import type { ProviderErrorInfo } from '../../types/provider/index.js'
 import type { CheckpointRunScope, CheckpointStore } from '../../types/run/checkpoint-store.js'
 import type { EmergencySaveData } from '../../types/run/emergency.js'
 import type { Run, RunPersistenceConfig, StopReason } from '../../types/run/index.js'
@@ -164,10 +165,11 @@ export class RunPersistence {
 		this.resolveResult()
 	}
 
-	markFailed(error: string): void {
+	markFailed(error: string, providerError?: ProviderErrorInfo): void {
 		this.run.status = 'failed'
 		this.run.stopReason = 'error'
 		this.run.lastError = error
+		if (providerError) this.run.lastProviderError = providerError
 		this.run.endedAt = Date.now()
 	}
 

package/src/provider/__tests__/errors.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+	ProviderRequestError,
+	bodySaysContextOverflow,
+	classifyProviderHttpStatus,
+	isCallerAbortError,
+	isProviderRequestError,
+	parseRetryAfterMs,
+	providerVendorError,
+} from '../errors.js'
+
+describe('provider error taxonomy', () => {
+	it('classifies only context-specific limit messages as context overflow', () => {
+		expect(bodySaysContextOverflow('input token count exceeds the maximum for this model')).toBe(
+			true,
+		)
+		expect(bodySaysContextOverflow('tool count exceeds the maximum allowed')).toBe(false)
+		expect(bodySaysContextOverflow('reduce the tool list length')).toBe(false)
+	})
+
+	it('does not treat a generic HTTP 413 as model context overflow', () => {
+		expect(classifyProviderHttpStatus(413, 'request body too large at reverse proxy')).toBe(
+			'bad_request',
+		)
+		expect(classifyProviderHttpStatus(413, 'prompt is too long for requested model')).toBe(
+			'context_overflow',
+		)
+	})
+
+	it('parses both Retry-After forms and rejects stale or invalid values', () => {
+		expect(parseRetryAfterMs('2', 0)).toBe(2000)
+		expect(parseRetryAfterMs('Thu, 01 Jan 1970 00:00:05 GMT', 1000)).toBe(4000)
+		expect(parseRetryAfterMs('Thu, 01 Jan 1970 00:00:01 GMT', 1000)).toBeUndefined()
+		expect(parseRetryAfterMs('later', 0)).toBeUndefined()
+	})
+
+	it('drops the vendor object and its non-enumerable cause entirely', () => {
+		const secret = 'sk-FAKE-DO-NOT-LOG'
+		const vendor = new Error(`invalid api key ${secret}`, {
+			cause: new Error(`response body ${secret}`),
+		})
+		Object.assign(vendor, { status: 401 })
+
+		const classified = providerVendorError({
+			providerId: 'test-provider',
+			error: vendor,
+		})
+
+		expect(classified).toMatchObject({
+			name: 'ProviderRequestError',
+			kind: 'auth',
+			status: 401,
+			providerId: 'test-provider',
+		})
+		expect(classified.message).not.toContain(secret)
+		expect('cause' in classified).toBe(false)
+	})
+
+	it('recognizes a caller abort only when that signal actually aborted', () => {
+		const controller = new AbortController()
+		const sdkAbort = Object.assign(new Error('request aborted'), {
+			name: 'APIUserAbortError',
+		})
+
+		expect(isCallerAbortError(sdkAbort, controller.signal)).toBe(false)
+		controller.abort(new Error('user stopped'))
+		expect(isCallerAbortError(sdkAbort, controller.signal)).toBe(true)
+		expect(isCallerAbortError(controller.signal.reason, controller.signal)).toBe(true)
+	})
+
+	it('requires the complete structural contract when SDK copies differ', () => {
+		const classified = new ProviderRequestError({
+			kind: 'server',
+			providerId: 'test-provider',
+		})
+		expect(isProviderRequestError(classified)).toBe(true)
+
+		const impostor = Object.assign(new Error('not classified'), {
+			name: 'ProviderRequestError',
+			kind: 'anything',
+		})
+		expect(isProviderRequestError(impostor)).toBe(false)
+	})
+})