@namzu/sdk 14.0.7 → 15.0.0

package/src/types/invocation/__tests__/state.test.ts

@@ -1,218 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import type { TenantId } from '../../ids/index.js'
-import { deriveChildState } from '../index.js'
-import type { InvocationState } from '../index.js'
-
-const ROOT_TENANT = 'tnt_root' as TenantId
-
-describe('InvocationState', () => {
-	describe('deriveChildState', () => {
-		it('seeds parentChain from a root seed when no parent state exists', () => {
-			const childState = deriveChildState({ tenantId: ROOT_TENANT }, 'agent-123')
-
-			expect(childState.parentChain).toEqual(['agent-123'])
-			expect(childState.tenantId).toBe(ROOT_TENANT)
-			expect(childState.metadata).toBeUndefined()
-			expect(childState.services).toBeUndefined()
-		})
-
-		it('seeds parentChain when parent has no parentChain', () => {
-			const parent: InvocationState = {
-				tenantId: 'tnt_abc' as TenantId,
-				metadata: { userId: 'user-123' },
-			}
-
-			const childState = deriveChildState(parent, 'agent-456')
-
-			expect(childState.parentChain).toEqual(['agent-456'])
-			expect(childState.tenantId).toBe(parent.tenantId)
-			expect(childState.metadata).toBe(parent.metadata)
-		})
-
-		it('extends parentChain with current agent', () => {
-			const parent: InvocationState = {
-				parentChain: ['supervisor', 'router'],
-				tenantId: 'tnt_xyz' as TenantId,
-			}
-
-			const childState = deriveChildState(parent, 'worker-agent')
-
-			expect(childState.parentChain).toEqual(['supervisor', 'router', 'worker-agent'])
-		})
-
-		it('preserves tenantId through derivation', () => {
-			const tenantId = 'tnt_tenant123' as TenantId
-			const parent: InvocationState = {
-				tenantId,
-				parentChain: ['agent-1'],
-			}
-
-			const childState = deriveChildState(parent, 'agent-2')
-
-			expect(childState.tenantId).toBe(tenantId)
-		})
-
-		it('preserves metadata through derivation', () => {
-			const metadata = {
-				userId: 'user-456',
-				sessionId: 'ses_789',
-				correlationId: 'corr_abc',
-			}
-			const parent: InvocationState = {
-				tenantId: ROOT_TENANT,
-				metadata,
-				parentChain: ['agent-1'],
-			}
-
-			const childState = deriveChildState(parent, 'agent-2')
-
-			expect(childState.metadata).toBe(metadata)
-			expect(childState.metadata?.userId).toBe('user-456')
-		})
-
-		it('preserves services through derivation', () => {
-			const services = {
-				db: { pool: 'mock-pool' },
-				cache: { client: 'mock-redis' },
-			}
-			const parent: InvocationState = {
-				tenantId: ROOT_TENANT,
-				services,
-				parentChain: ['agent-1'],
-			}
-
-			const childState = deriveChildState(parent, 'agent-2')
-
-			expect(childState.services).toBe(services)
-		})
-
-		it('preserves all fields through multi-level derivation', () => {
-			const tenantId = 'tnt_multi' as TenantId
-			const metadata = { userId: 'user-multi' }
-			const services = { db: 'postgres' }
-
-			const level1 = deriveChildState({ tenantId }, 'supervisor')
-			expect(level1.parentChain).toEqual(['supervisor'])
-
-			const parent: InvocationState = {
-				tenantId,
-				metadata,
-				services,
-				parentChain: level1.parentChain,
-			}
-
-			const level2 = deriveChildState(parent, 'router')
-			expect(level2.parentChain).toEqual(['supervisor', 'router'])
-			expect(level2.tenantId).toBe(tenantId)
-			expect(level2.metadata).toBe(metadata)
-			expect(level2.services).toBe(services)
-
-			const level3 = deriveChildState(level2, 'worker')
-			expect(level3.parentChain).toEqual(['supervisor', 'router', 'worker'])
-			expect(level3.tenantId).toBe(tenantId)
-			expect(level3.metadata).toBe(metadata)
-			expect(level3.services).toBe(services)
-		})
-
-		it('creates immutable parentChain', () => {
-			const parent: InvocationState = {
-				tenantId: ROOT_TENANT,
-				parentChain: ['agent-1'],
-			}
-
-			const childState = deriveChildState(parent, 'agent-2')
-
-			// Ensure the parentChain is a new array, not mutated
-			expect(parent.parentChain).toEqual(['agent-1'])
-			expect(childState.parentChain).toEqual(['agent-1', 'agent-2'])
-		})
-
-		it('handles empty parentChain in parent', () => {
-			const parent: InvocationState = {
-				tenantId: ROOT_TENANT,
-				parentChain: [],
-			}
-
-			const childState = deriveChildState(parent, 'agent-first')
-
-			expect(childState.parentChain).toEqual(['agent-first'])
-		})
-
-		it('allows complex agent IDs in parentChain', () => {
-			const agentIds = ['supervisor-agent-123', 'router-multi-path', 'worker-task-handler']
-
-			let state: InvocationState = { tenantId: ROOT_TENANT }
-			for (const agentId of agentIds) {
-				state = deriveChildState(state, agentId)
-			}
-
-			expect(state.parentChain).toEqual(agentIds)
-		})
-
-		it('does not mutate parent state', () => {
-			const parent: InvocationState = {
-				parentChain: ['original'],
-				tenantId: 'tnt_orig' as TenantId,
-				metadata: { key: 'value' },
-			}
-
-			const originalParentChain = [...(parent.parentChain ?? [])]
-
-			deriveChildState(parent, 'child')
-
-			// Parent state should remain unchanged
-			expect(parent.parentChain).toEqual(originalParentChain)
-			expect(parent.parentChain).toEqual(['original'])
-		})
-	})
-
-	describe('InvocationState immutability', () => {
-		it('has readonly fields', () => {
-			const state: InvocationState = {
-				tenantId: 'tnt_test' as TenantId,
-				metadata: { key: 'value' },
-				services: { db: 'postgres' },
-				parentChain: ['agent-1'],
-			}
-
-			// Type system enforces immutability, so these assertions verify the type definitions
-			expect(state.tenantId).toBe('tnt_test')
-			expect(state.metadata).toBeDefined()
-			expect(state.services).toBeDefined()
-			expect(state.parentChain).toBeDefined()
-		})
-
-		it('supports undefined optional fields (tenantId still required)', () => {
-			const minimalState: InvocationState = {
-				tenantId: ROOT_TENANT,
-				parentChain: ['agent-1'],
-			}
-
-			expect(minimalState.tenantId).toBe(ROOT_TENANT)
-			expect(minimalState.metadata).toBeUndefined()
-			expect(minimalState.services).toBeUndefined()
-			expect(minimalState.parentChain).toEqual(['agent-1'])
-		})
-
-		it('handles metadata with various types', () => {
-			const metadata = {
-				userId: 'user-123',
-				count: 42,
-				enabled: true,
-				nested: { key: 'value' },
-				array: [1, 2, 3],
-			}
-
-			const state: InvocationState = {
-				tenantId: ROOT_TENANT,
-				metadata,
-			}
-
-			expect(state.metadata?.userId).toBe('user-123')
-			expect(state.metadata?.count).toBe(42)
-			expect(state.metadata?.enabled).toBe(true)
-			expect(state.metadata?.nested).toEqual({ key: 'value' })
-			expect(state.metadata?.array).toEqual([1, 2, 3])
-		})
-	})
-})

package/src/types/provider/__tests__/cause-chain.test.ts

@@ -1,132 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import { classifyProviderError } from '../errors.js'
-
-/**
- * Every signal was read off the error handed in, so one layer of wrapping
- * hid it — and wrapping is the normal case, not an edge one: a vendor SDK
- * wraps its transport error and the runtime wraps again on the way out.
- *
- * A rate limit wrapped ONCE classified as `unknown`, which is treated as
- * non-retryable. The retry policy was dead for every failure that was not
- * the outermost throwable, which is most of them.
- */
-
-const wrap = (message: string, cause: unknown) => new Error(message, { cause })
-
-describe('status through the chain', () => {
-	// Deliberately mute: a message that says "too many requests" would let
-	// the message-text fallback reach the same verdict, and the test would
-	// pass with the status walk removed.
-	const throttled = Object.assign(new Error('upstream returned an error'), { status: 429 })
-
-	it('finds a rate limit one layer down', () => {
-		const classified = classifyProviderError(wrap('request failed', throttled))
-		expect(classified.code).toBe('rate_limit')
-		expect(classified.retryable).toBe(true)
-	})
-
-	it('finds it three layers down', () => {
-		const classified = classifyProviderError(
-			wrap('run failed', wrap('step failed', wrap('request failed', throttled))),
-		)
-		expect(classified.code).toBe('rate_limit')
-	})
-
-	it('finds a status hidden in a metadata bag under a wrapper', () => {
-		const aws = Object.assign(new Error('ThrottlingException'), {
-			$metadata: { httpStatusCode: 429 },
-		})
-		expect(classifyProviderError(wrap('send failed', aws)).code).toBe('rate_limit')
-	})
-
-	it('still prefers the outermost status when two links carry one', () => {
-		const inner = Object.assign(new Error('inner'), { status: 500 })
-		const outer = Object.assign(wrap('outer', inner), { status: 429 })
-		// The outer link is what the driver chose to expose; walking
-		// outward-in keeps the un-wrapped case behaving exactly as before.
-		expect(classifyProviderError(outer).status).toBe(429)
-	})
-})
-
-describe('errno through the chain', () => {
-	const reset = Object.assign(new Error('socket hang up'), { code: 'ECONNRESET' })
-
-	it('finds a transport failure two layers down', () => {
-		const classified = classifyProviderError(
-			wrap('provider call failed', wrap('fetch failed', reset)),
-		)
-		// The one class of failure where retrying is almost always right.
-		expect(classified.code).toBe('network')
-		expect(classified.retryable).toBe(true)
-	})
-
-	it('finds a timeout errno under a wrapper', () => {
-		const timedOut = Object.assign(new Error('headers timeout'), {
-			code: 'UND_ERR_HEADERS_TIMEOUT',
-		})
-		expect(classifyProviderError(wrap('failed', timedOut)).code).toBe('timeout')
-	})
-})
-
-describe('retry-after through the chain', () => {
-	it('reads the header off the link that carries it', () => {
-		const limited = Object.assign(new Error('rate limited'), {
-			status: 429,
-			headers: { 'retry-after': '30' },
-		})
-		expect(classifyProviderError(wrap('failed', limited)).retryAfterMs).toBe(30_000)
-	})
-})
-
-describe('message through the chain', () => {
-	it('reads a window overflow off an inner message', () => {
-		const overflow = new Error('prompt is too long for this model')
-		// A wrapper's message is usually generic, so matching only the outer
-		// text looks at the one string least likely to say anything.
-		expect(classifyProviderError(wrap('request failed', overflow)).code).toBe(
-			'context_length_exceeded',
-		)
-	})
-
-	it('lets a status anywhere on the chain beat message text', () => {
-		const badRequest = Object.assign(new Error('bad request'), { status: 400 })
-		const classified = classifyProviderError(wrap('the operation timed out', badRequest))
-		// Status is the more reliable signal, wherever it sits; a wrapper
-		// whose prose says "timed out" must not overrule it.
-		expect(classified.code).toBe('invalid_request')
-	})
-})
-
-describe('safety', () => {
-	it('terminates on a cause cycle', () => {
-		const a: { cause?: unknown; message: string } = { message: 'a' }
-		const b = { message: 'b', cause: a }
-		a.cause = b
-
-		// Easy to build by accident when errors are re-wrapped in a retry
-		// loop; without a seen-set the walk never returns.
-		expect(classifyProviderError(a).code).toBe('unknown')
-	})
-
-	it('handles a chain that ends in a non-object', () => {
-		expect(classifyProviderError(wrap('failed', 'a string cause')).code).toBe('unknown')
-	})
-
-	it('leaves an already-classified error alone', () => {
-		const classified = classifyProviderError(Object.assign(new Error('x'), { status: 429 }))
-		expect(classifyProviderError(wrap('outer', classified))).not.toBe(classified)
-		expect(classifyProviderError(classified)).toBe(classified)
-	})
-
-	it('classifies an unwrapped error exactly as before', () => {
-		for (const [err, code] of [
-			[Object.assign(new Error('x'), { status: 401 }), 'auth'],
-			[Object.assign(new Error('x'), { status: 404 }), 'not_found'],
-			[Object.assign(new Error('x'), { status: 529 }), 'overloaded'],
-			[new Error('nothing recognisable'), 'unknown'],
-		] as const) {
-			expect(classifyProviderError(err).code).toBe(code)
-		}
-	})
-})

package/src/types/provider/__tests__/declared-retryable.test.ts

@@ -1,85 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import { ProviderError, classifyProviderError, declaredRetryable } from '../errors.js'
-
-/**
- * Retryability was derived solely from namzu's own code set, so a vendor
- * SDK that says outright "this one is safe to retry" was not listened to.
- * That set is a second-hand inference from status and wording, and it
- * necessarily lags every new failure shape a provider invents — a failure
- * nobody has characterised yet lands on `unknown`, which is treated as
- * non-retryable, even when its own author flagged it retryable.
- *
- * The classification still decides WHAT went wrong. Only the retry verdict
- * defers to a first-hand statement.
- */
-
-describe('a retryable flag declared upstream', () => {
-	it('is read off the error itself', () => {
-		const err = Object.assign(new Error('something new'), { retryable: true })
-		expect(classifyProviderError(err).retryable).toBe(true)
-	})
-
-	it('is read off a wrapped cause', () => {
-		// Wrapping is the normal case, not an edge one: vendor SDKs wrap
-		// their transport errors and the runtime wraps again on the way out.
-		const inner = Object.assign(new Error('inner'), { retryable: true })
-		const outer = new Error('request failed', { cause: inner })
-		expect(classifyProviderError(outer).retryable).toBe(true)
-	})
-
-	it('can also say a failure is NOT retryable', () => {
-		// A 503 that the provider knows is permanent for this request.
-		const err = Object.assign(new Error('permanently unavailable'), {
-			status: 503,
-			retryable: false,
-		})
-		const classified = classifyProviderError(err)
-
-		expect(classified.code).toBe('overloaded')
-		// The code still says what it is; only the verdict changed.
-		expect(classified.retryable).toBe(false)
-	})
-
-	it('does not change the classification, only the verdict', () => {
-		const err = Object.assign(new Error('bad request'), { status: 400, retryable: true })
-		const classified = classifyProviderError(err)
-
-		expect(classified.code).toBe('invalid_request')
-		expect(classified.retryable).toBe(true)
-	})
-
-	it('takes the outermost declaration when links disagree', () => {
-		// The outer layer made the more recent statement, knowing what the
-		// inner one said.
-		const inner = Object.assign(new Error('inner'), { retryable: true })
-		const outer = Object.assign(new Error('outer'), { retryable: false, cause: inner })
-		expect(declaredRetryable(outer)).toBe(false)
-	})
-
-	it('leaves the code in charge when nothing declared anything', () => {
-		expect(declaredRetryable(new Error('plain'))).toBeUndefined()
-		expect(classifyProviderError(Object.assign(new Error('x'), { status: 429 })).retryable).toBe(
-			true,
-		)
-		expect(classifyProviderError(Object.assign(new Error('x'), { status: 401 })).retryable).toBe(
-			false,
-		)
-	})
-
-	it('ignores a non-boolean flag rather than coercing it', () => {
-		// `retryable: 'yes'` is a foreign object's field, not a contract.
-		// Coercing it would let any truthy value silently enable retries.
-		expect(declaredRetryable({ retryable: 'yes' })).toBeUndefined()
-		expect(declaredRetryable({ retryable: 1 })).toBeUndefined()
-	})
-
-	it('is honoured when a ProviderError is constructed directly', () => {
-		const err = new ProviderError({
-			code: 'invalid_request',
-			message: 'x',
-			retryable: true,
-		})
-		expect(err.retryable).toBe(true)
-	})
-})

package/src/types/provider/__tests__/overflow-classification.test.ts

@@ -1,113 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import { classifyProviderError } from '../errors.js'
-
-/**
- * Overflow is the one 4xx the runtime can act on: it sheds history and
- * retries. Everything else in the 400 family is surfaced. So the rescue is
- * gated on the code being EXACTLY `context_length_exceeded`, and anything
- * that misses that gate dies holding the remedy.
- *
- * Detection was a substring search over five phrases. The structural code —
- * the one field a provider has for saying what went wrong — was extracted
- * from the cause chain and then fed only to the two transport-errno sets,
- * so a provider that said `context_length_exceeded` in so many words was
- * answered with a phrase search that did not match.
- */
-
-const overflowReaches = (err: unknown) =>
-	classifyProviderError(err).code === 'context_length_exceeded'
-
-describe('the structural code', () => {
-	it('is believed over the status that carries it', () => {
-		// A 400 is a category; the code is the diagnosis.
-		expect(
-			overflowReaches(
-				Object.assign(new Error('Bad request'), { status: 400, code: 'context_length_exceeded' }),
-			),
-		).toBe(true)
-	})
-
-	it('is read from a gateway body discriminator too', () => {
-		expect(
-			overflowReaches(
-				Object.assign(new Error('Bad request'), { status: 400, type: 'context_length_exceeded' }),
-			),
-		).toBe(true)
-	})
-
-	it('is read from a nested error envelope', () => {
-		expect(
-			overflowReaches(
-				Object.assign(new Error('Bad request'), {
-					status: 400,
-					error: { type: 'context_window_exceeded' },
-				}),
-			),
-		).toBe(true)
-	})
-
-	it('is found under a wrapper', () => {
-		const inner = Object.assign(new Error('Bad request'), { code: 'max_tokens_exceeded' })
-		expect(overflowReaches(new Error('request failed', { cause: inner }))).toBe(true)
-	})
-
-	it('classifies a rate limit from the code alone', () => {
-		const classified = classifyProviderError(
-			Object.assign(new Error('Bad request'), { status: 400, code: 'rate_limit_exceeded' }),
-		)
-		expect(classified.code).toBe('rate_limit')
-		expect(classified.retryable).toBe(true)
-	})
-
-	it('leaves a code it does not recognise to the other signals', () => {
-		const classified = classifyProviderError(
-			Object.assign(new Error('nope'), { status: 404, code: 'some_vendor_specific_thing' }),
-		)
-		expect(classified.code).toBe('not_found')
-	})
-})
-
-describe('wordings that used to miss', () => {
-	it.each([
-		'Input is too long for requested model.',
-		'This request exceeds the maximum length for this model',
-		'The input is too large for the context window',
-		'payload too large for the selected model',
-	])('%s', (message) => {
-		expect(overflowReaches(Object.assign(new Error(message), { status: 400 }))).toBe(true)
-	})
-
-	it('still recognises the wordings that already worked', () => {
-		for (const message of [
-			'prompt is too long',
-			'maximum context length exceeded',
-			'too many tokens in request',
-		]) {
-			expect(overflowReaches(Object.assign(new Error(message), { status: 400 }))).toBe(true)
-		}
-	})
-
-	it('does not fire on an ordinary bad request', () => {
-		const classified = classifyProviderError(
-			Object.assign(new Error('The model id is not valid'), { status: 400 }),
-		)
-		// Overreaching here would send a run into compaction it cannot be
-		// rescued by, and hide the real error behind a retry.
-		expect(classified.code).toBe('invalid_request')
-	})
-})
-
-describe('an already-classified error', () => {
-	it('is not re-examined, which is why a driver must not guess', () => {
-		// The classifier short-circuits on a typed error. That is correct —
-		// a driver knows its own vendor best — but it means a driver that
-		// pre-files a name whose meaning depends on the body makes the body
-		// unreadable.
-		const preFiled = classifyProviderError(
-			Object.assign(new Error('Input is too long for requested model.'), { status: 400 }),
-		)
-		expect(preFiled.code).toBe('context_length_exceeded')
-		expect(classifyProviderError(preFiled)).toBe(preFiled)
-	})
-})

package/src/types/run/__tests__/step.test.ts

@@ -1,123 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import type { StepResult, StopConditionState } from '../step.js'
-import { anyOf, hasToolCall, stepCountIs } from '../step.js'
-
-/**
- * The only halt before this was `GuardCoordinator`, which consumes
- * `{aborted, totalTokens, totalCost, currentIteration, startTime}` and never
- * sees messages, tool calls or results. So a terminal `submit_answer` tool
- * could not end a run — the model had to be prompt-begged to stop, with
- * `maxIterations: 200` or the token budget as the only backstop, which meant
- * a finished task still burned its whole envelope.
- */
-
-function step(n: number, toolNames: string[] = []): StepResult {
-	return {
-		stepNumber: n,
-		model: 'm',
-		messageId: `msg_${n}` as StepResult['messageId'],
-		content: null,
-		toolCalls: toolNames.map((name, i) => ({
-			id: `c${n}_${i}`,
-			type: 'function' as const,
-			function: { name, arguments: '{}' },
-		})),
-		toolResults: [],
-		finishReason: 'tool_calls',
-		usage: {
-			promptTokens: 0,
-			completionTokens: 0,
-			totalTokens: 0,
-			cachedTokens: 0,
-			cacheWriteTokens: 0,
-		},
-		costDelta: { inputCostPer1M: 0, outputCostPer1M: 0, totalCost: 0, cacheDiscount: 0 },
-		startedAt: 0,
-		durationMs: 0,
-		toolExecutionMs: 0,
-	}
-}
-
-function stateOf(steps: StepResult[]): StopConditionState {
-	const latestStep = steps[steps.length - 1]
-	if (!latestStep) throw new Error('need at least one step')
-	return {
-		steps,
-		latestStep,
-		totalUsage: {
-			promptTokens: 0,
-			completionTokens: 0,
-			totalTokens: 0,
-			cachedTokens: 0,
-			cacheWriteTokens: 0,
-		},
-		totalCost: { inputCostPer1M: 0, outputCostPer1M: 0, totalCost: 0, cacheDiscount: 0 },
-	}
-}
-
-describe('stepCountIs', () => {
-	it('is false before the count and true at it', async () => {
-		const condition = stepCountIs(3)
-		expect(await condition(stateOf([step(1), step(2)]))).toBe(false)
-		expect(await condition(stateOf([step(1), step(2), step(3)]))).toBe(true)
-	})
-
-	it('stays true past the count — it is a floor, not an equality', async () => {
-		expect(await stepCountIs(2)(stateOf([step(1), step(2), step(3)]))).toBe(true)
-	})
-})
-
-describe('hasToolCall', () => {
-	it('fires when the latest step called the named tool', async () => {
-		expect(await hasToolCall('submit_answer')(stateOf([step(1, ['submit_answer'])]))).toBe(true)
-	})
-
-	it('does not fire on an earlier step — only the latest one is examined', async () => {
-		const state = stateOf([step(1, ['submit_answer']), step(2, ['read'])])
-		expect(await hasToolCall('submit_answer')(state)).toBe(false)
-	})
-
-	it('accepts several names', async () => {
-		const condition = hasToolCall('submit_answer', 'give_up')
-		expect(await condition(stateOf([step(1, ['give_up'])]))).toBe(true)
-		expect(await condition(stateOf([step(1, ['read'])]))).toBe(false)
-	})
-
-	it('is false for a step with no tool calls at all', async () => {
-		expect(await hasToolCall('x')(stateOf([step(1)]))).toBe(false)
-	})
-})
-
-describe('anyOf', () => {
-	it('fires when any condition does', async () => {
-		const condition = anyOf(stepCountIs(99), hasToolCall('submit_answer'))
-		expect(await condition(stateOf([step(1, ['submit_answer'])]))).toBe(true)
-	})
-
-	it('is false when none fire', async () => {
-		const condition = anyOf(stepCountIs(99), hasToolCall('submit_answer'))
-		expect(await condition(stateOf([step(1, ['read'])]))).toBe(false)
-	})
-
-	it('short-circuits — a later condition is not consulted once one fires', async () => {
-		let consulted = false
-		const condition = anyOf(
-			() => true,
-			() => {
-				consulted = true
-				return false
-			},
-		)
-		expect(await condition(stateOf([step(1)]))).toBe(true)
-		expect(consulted).toBe(false)
-	})
-
-	it('awaits an async condition', async () => {
-		const condition = anyOf(async () => {
-			await Promise.resolve()
-			return true
-		})
-		expect(await condition(stateOf([step(1)]))).toBe(true)
-	})
-})