@namzu/sdk 2.0.0 → 3.0.0

package/src/provider/index.ts

@@ -27,3 +27,11 @@ export {
 	resolveProviderCapabilities,
 } from './capabilities.js'
 export type { ResolvedProviderCapabilities } from './capabilities.js'
+export {
+	ProviderError,
+	classifyProviderError,
+	isAbortError,
+	isProviderError,
+} from '../types/provider/errors.js'
+export { DEFAULT_PROVIDER_RETRY, withProviderRetry } from './retry.js'
+export type { ProviderRetryConfig, WithProviderRetryOptions } from './retry.js'

package/src/provider/mock-register.ts

@@ -2,10 +2,13 @@ import type { ProviderCapabilities } from '../types/provider/index.js'
 import { MockLLMProvider } from './mock.js'
 import { ProviderRegistry } from './registry.js'
 
+// The mock can script tool calls, so declaring otherwise made
+// capability negotiation strip the tool surface before a request was even
+// built — which is why no consumer could test a tool through the loop.
 export const MOCK_CAPABILITIES: ProviderCapabilities = {
-	supportsTools: false,
+	supportsTools: true,
 	supportsStreaming: true,
-	supportsFunctionCalling: false,
+	supportsFunctionCalling: true,
 }
 
 /**

package/src/provider/mock.ts

@@ -2,34 +2,66 @@ import { FALLBACK_MOCK_MODEL } from '../constants/provider/index.js'
 import type { TokenUsage } from '../types/common/index.js'
 import type {
 	ChatCompletionParams,
-	ChatCompletionResponse,
 	LLMProvider,
-	MockProviderConfig,
+	MockScript,
+	MockTurn,
+	ProviderCapabilities,
 	StreamChunk,
 } from '../types/provider/index.js'
 
+const EMPTY_USAGE: TokenUsage = {
+	promptTokens: 0,
+	completionTokens: 0,
+	totalTokens: 0,
+	cachedTokens: 0,
+	cacheWriteTokens: 0,
+}
+
+/**
+ * A model you script.
+ *
+ * The previous mock could only emit text: it never yielded
+ * `delta.toolCalls`, and `MOCK_CAPABILITIES.supportsTools` was `false`, so
+ * capability negotiation stripped the tool surface before a request was
+ * even built. A consumer writing a custom tool therefore had no supported
+ * way to test that the agent loop calls it — and namzu's own maintainers
+ * hand-rolled eight `implements LLMProvider` fakes across seven test files
+ * to work around exactly that, each re-implementing the delta bucketing
+ * and `toolCallEnd` framing that `streamProviderTurn` exists to hide.
+ *
+ * Scripted turns are emitted with the same frame sequence a real driver
+ * produces — per-tool `index`, id and name first, then argument fragments,
+ * then the block-close signal — so a test exercises the real consumer path
+ * rather than a shortcut through it.
+ */
 export class MockLLMProvider implements LLMProvider {
 	readonly id = 'mock'
 	readonly name = 'Mock LLM Provider'
+	readonly capabilities: ProviderCapabilities | undefined
 
 	private readonly model: string
-	private readonly responseText: string
 	private readonly responseDelayMs: number
+	private readonly turns: readonly MockTurn[]
+	private readonly nextTurn?: (params: ChatCompletionParams, turnIndex: number) => MockTurn
+	private readonly onRequest?: (params: ChatCompletionParams) => void
+	private turnIndex = 0
+
+	/** Every request this provider has received, in order. */
+	readonly requests: ChatCompletionParams[] = []
 
-	constructor(config: MockProviderConfig) {
+	constructor(config: MockScript = {}) {
+		this.capabilities = config.capabilities
 		this.model = config.model ?? FALLBACK_MOCK_MODEL
-		this.responseText = config.responseText ?? 'Mock provider response'
 		this.responseDelayMs = config.responseDelayMs ?? 0
+		this.onRequest = config.onRequest
+		this.nextTurn = config.nextTurn
+		this.turns = config.turns ?? [{ text: config.responseText ?? 'Mock provider response' }] // Back-compat: the old single-string config becomes a one-turn script.
 	}
 
-	private buildUsage(): TokenUsage {
-		return {
-			promptTokens: 0,
-			completionTokens: 0,
-			totalTokens: 0,
-			cachedTokens: 0,
-			cacheWriteTokens: 0,
-		}
+	/** Reset the script pointer and captured requests between cases. */
+	reset(): void {
+		this.turnIndex = 0
+		this.requests.length = 0
 	}
 
 	private async delay(): Promise<void> {
@@ -37,39 +69,90 @@ export class MockLLMProvider implements LLMProvider {
 		await new Promise((resolve) => setTimeout(resolve, this.responseDelayMs))
 	}
 
-	private normalizeResponse(params: ChatCompletionParams, message: string): ChatCompletionResponse {
-		return {
-			id: `mock-${Date.now()}-${Math.floor(Math.random() * 1_000_000)}`,
-			model: params.model ?? this.model,
-			message: {
-				role: 'assistant',
-				content: message,
-			},
-			finishReason: 'stop',
-			usage: this.buildUsage(),
-		}
+	/**
+	 * The turn to play. A script shorter than the run repeats its last
+	 * entry, so a test that only cares about the first two turns does not
+	 * have to pad the rest — and a loop bug shows up as repetition rather
+	 * than an exhausted-script crash.
+	 */
+	private resolveTurn(params: ChatCompletionParams): MockTurn {
+		const index = this.turnIndex++
+		if (this.nextTurn) return this.nextTurn(params, index)
+		return this.turns[Math.min(index, this.turns.length - 1)] ?? { text: '' }
 	}
 
 	async *chatStream(params: ChatCompletionParams): AsyncIterable<StreamChunk> {
 		await this.delay()
-		const response = this.normalizeResponse(params, this.responseText)
-		const content = response.message.content ?? ''
-		const chunkSize = 8
+		this.requests.push(params)
+		this.onRequest?.(params)
+
+		const turn = this.resolveTurn(params)
+		const id = `mock-${this.turnIndex}`
+
+		if (turn.error !== undefined) {
+			// Surfaced as a thrown error, the way a driver reports a request
+			// that never produced a stream.
+			throw Object.assign(new Error(turn.error.message), {
+				...(turn.error.status !== undefined ? { status: turn.error.status } : {}),
+			})
+		}
+
+		// Before the text, as the wire does: a citation names the passage an
+		// upcoming sentence rests on.
+		for (const citation of turn.citations ?? []) {
+			yield { id, delta: { citation } }
+		}
 
-		for (let i = 0; i < content.length; i += chunkSize) {
+		const text = turn.text ?? ''
+		const chunkSize = turn.chunkSize ?? 8
+		let emitted = 0
+
+		for (let i = 0; i < text.length; i += chunkSize) {
+			if (turn.throwAfterChunks !== undefined && emitted >= turn.throwAfterChunks) {
+				throw new Error(turn.throwMessage ?? 'mock stream failure')
+			}
+			yield { id, delta: { content: text.slice(i, i + chunkSize) } }
+			emitted++
+		}
+
+		const toolCalls = turn.toolCalls ?? []
+
+		for (const [index, call] of toolCalls.entries()) {
+			const callId = call.id ?? `call_${this.turnIndex}_${index}`
 			yield {
-				id: response.id,
+				id,
 				delta: {
-					content: content.slice(i, i + chunkSize),
+					toolCalls: [
+						{ index, id: callId, type: 'function', function: { name: call.name, arguments: '' } },
+					],
 				},
 			}
+
+			// Arguments arrive as JSON fragments, which is what forces the
+			// consumer's partial-JSON buffering to be exercised.
+			const args = call.rawArguments ?? JSON.stringify(call.args ?? {})
+			const step = call.argChunkSize ?? Math.max(1, Math.ceil(args.length / 3))
+			for (let i = 0; i < args.length; i += step) {
+				yield {
+					id,
+					delta: { toolCalls: [{ index, function: { arguments: args.slice(i, i + step) } }] },
+				}
+			}
+
+			if (call.throwAfterArguments !== undefined) {
+				throw new Error(call.throwAfterArguments)
+			}
+
+			if (call.truncateArguments !== true) {
+				yield { id, delta: { toolCallEnd: { index, id: callId } } }
+			}
 		}
 
 		yield {
-			id: response.id,
+			id,
 			delta: {},
-			finishReason: 'stop',
-			usage: response.usage,
+			finishReason: turn.finishReason ?? (toolCalls.length > 0 ? 'tool_calls' : 'stop'),
+			usage: { ...EMPTY_USAGE, ...turn.usage },
 		}
 	}
 
@@ -82,7 +165,7 @@ export class MockLLMProvider implements LLMProvider {
 				maxOutputTokens: 8_000,
 				inputPrice: 0,
 				outputPrice: 0,
-				supportsToolUse: false,
+				supportsToolUse: true,
 				supportsStreaming: true,
 			},
 		]

package/src/provider/retry.ts

@@ -0,0 +1,199 @@
+import { classifyProviderError, isAbortError } from '../types/provider/errors.js'
+import type { ChatCompletionParams, LLMProvider, StreamChunk } from '../types/provider/index.js'
+import type { Logger } from '../utils/logger.js'
+import { isProviderRequestError } from './errors.js'
+
+export interface ProviderRetryConfig {
+	/** Retry attempts AFTER the initial try. `0` disables retrying. */
+	readonly maxRetries: number
+	/** First backoff, doubled each attempt. */
+	readonly initialDelayMs: number
+	/** Ceiling for a single backoff, before jitter. */
+	readonly maxDelayMs: number
+	/**
+	 * Cap on a server-directed `Retry-After`. A provider asking for 15
+	 * minutes should not silently park an interactive run for 15 minutes;
+	 * past this we surface the error and let the caller decide.
+	 */
+	readonly maxRetryAfterMs: number
+}
+
+export const DEFAULT_PROVIDER_RETRY: ProviderRetryConfig = {
+	maxRetries: 3,
+	initialDelayMs: 500,
+	maxDelayMs: 16_000,
+	maxRetryAfterMs: 60_000,
+}
+
+/**
+ * Full jitter (AWS's formulation): sleep a uniform random amount in
+ * `[0, backoff]` rather than `backoff` exactly. Equal-jitter and no-jitter
+ * both keep a fleet of clients that failed together retrying together;
+ * full jitter is what actually spreads a thundering herd.
+ */
+function backoffWithJitter(attempt: number, config: ProviderRetryConfig, random: () => number) {
+	const exponential = Math.min(config.initialDelayMs * 2 ** attempt, config.maxDelayMs)
+	return Math.round(random() * exponential)
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+	if (ms <= 0) return Promise.resolve()
+	return new Promise<void>((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(signal.reason)
+			return
+		}
+		const timer = setTimeout(() => {
+			signal?.removeEventListener('abort', onAbort)
+			resolve()
+		}, ms)
+		const onAbort = () => {
+			clearTimeout(timer)
+			reject(signal?.reason)
+		}
+		signal?.addEventListener('abort', onAbort, { once: true })
+	})
+}
+
+export interface WithProviderRetryOptions {
+	readonly config?: Partial<ProviderRetryConfig>
+	readonly log?: Logger
+	/** Seam for deterministic tests. */
+	readonly random?: () => number
+	readonly sleepFn?: (ms: number, signal?: AbortSignal) => Promise<void>
+}
+
+/**
+ * Wrap a provider so transient failures are retried with exponential
+ * backoff and full jitter.
+ *
+ * **Retry only before the first content chunk.** Once a delta has been
+ * yielded the consumer has already emitted `text_delta` events and
+ * appended to its buffer, so restarting the request would duplicate
+ * output. A mid-stream failure is therefore surfaced, not retried — the
+ * existing stream-error path in `streamProviderTurn` handles it (and can
+ * still salvage a truncated tool call). This is the whole reason the
+ * retry lives in a decorator rather than inside the loop: the loop cannot
+ * un-emit.
+ *
+ * Aborts propagate untouched so a Stop still settles the run as
+ * `cancelled` rather than being mistaken for a transport failure.
+ */
+export function withProviderRetry(
+	provider: LLMProvider,
+	options: WithProviderRetryOptions = {},
+): LLMProvider {
+	const config: ProviderRetryConfig = { ...DEFAULT_PROVIDER_RETRY, ...options.config }
+	const random = options.random ?? Math.random
+	const doSleep = options.sleepFn ?? sleep
+	const log = options.log
+
+	if (config.maxRetries <= 0) return provider
+
+	async function* chatStream(params: ChatCompletionParams): AsyncIterable<StreamChunk> {
+		for (let attempt = 0; ; attempt++) {
+			let produced = false
+			try {
+				for await (const chunk of provider.chatStream(params)) {
+					// An error-only chunk is a failure report, not output: it
+					// leaves `produced` false so a driver that surfaces errors
+					// in-band is still retryable on its first chunk.
+					const isErrorOnly =
+						chunk.error !== undefined && !chunk.delta.content && !chunk.delta.toolCalls?.length
+
+					if (!isErrorOnly) produced = true
+
+					if (isErrorOnly && !produced && attempt < config.maxRetries) {
+						throw new Error(chunk.error)
+					}
+					yield chunk
+				}
+				return
+			} catch (err) {
+				if (isAbortError(err) || params.signal?.aborted) throw err
+				// A driver that already classified its own failure has said
+				// everything this layer would: re-wrapping it would replace a
+				// first-hand statement with a guess, and the run boundary reads
+				// that classification to choose between a pause and a failure.
+				if (isProviderRequestError(err)) throw err
+
+				const classified = classifyProviderError(err, provider.id)
+				const exhausted = attempt >= config.maxRetries
+
+				if (produced || !classified.retryable || exhausted) {
+					log?.warn('Provider call failed', {
+						provider: provider.id,
+						code: classified.code,
+						status: classified.status,
+						attempt: attempt + 1,
+						retryable: classified.retryable,
+						reason: produced
+							? 'stream already produced output — cannot retry without duplicating it'
+							: exhausted
+								? 'retries exhausted'
+								: 'not retryable',
+					})
+					throw classified
+				}
+
+				const serverDirected = classified.retryAfterMs
+				const delay =
+					serverDirected !== undefined && serverDirected <= config.maxRetryAfterMs
+						? serverDirected
+						: backoffWithJitter(attempt, config, random)
+
+				log?.warn('Provider call failed — retrying', {
+					provider: provider.id,
+					code: classified.code,
+					status: classified.status,
+					attempt: attempt + 1,
+					maxRetries: config.maxRetries,
+					delayMs: delay,
+					serverDirected: serverDirected !== undefined,
+				})
+
+				// Tell the consumer BEFORE sleeping. With the default policy a
+				// run can sit silent for the better part of a minute between
+				// `iteration_started` and the next event, and a server-directed
+				// delay may take it to the full cap — a host with no signal
+				// cannot tell a backoff from a hang, and its watchdog cancels a
+				// run that was about to succeed. This is the only channel open
+				// while the decorator sleeps: the consumer is blocked inside
+				// this iterator, so a callback could not reach it until the
+				// backoff was already over.
+				yield {
+					id: '',
+					delta: {},
+					retry: {
+						attempt: attempt + 1,
+						maxRetries: config.maxRetries,
+						delayMs: delay,
+						code: classified.code,
+						...(classified.status !== undefined ? { status: classified.status } : {}),
+						serverDirected: serverDirected !== undefined,
+					},
+				}
+
+				await doSleep(delay, params.signal)
+			}
+		}
+	}
+
+	// Preserve identity and every optional capability of the wrapped driver;
+	// the decorator must be transparent to capability negotiation.
+	return {
+		get id() {
+			return provider.id
+		},
+		get name() {
+			return provider.name
+		},
+		get capabilities() {
+			return provider.capabilities
+		},
+		chatStream,
+		...(provider.listModels ? { listModels: () => provider.listModels?.() } : {}),
+		...(provider.healthCheck ? { healthCheck: () => provider.healthCheck?.() } : {}),
+		...(provider.doctorCheck ? { doctorCheck: () => provider.doctorCheck?.() } : {}),
+	} as LLMProvider
+}

package/src/public-runtime.ts

@@ -68,11 +68,28 @@ export { extractFinalResponse } from './utils/conversation.js'
 
 export { resolveTaskModel } from './router/task-router.js'
 export { drainQuery, query } from './runtime/query/index.js'
+export { createMockBidiProvider, startBidiRun } from './runtime/bidi/index.js'
 export { ContextCache } from './runtime/query/context-cache.js'
 export {
 	CheckpointManager,
+	findPendingCheckpoint,
+	isExpiredPark,
+	listExpiredParks,
 	projectEmergencyToCheckpoint,
 } from './runtime/query/checkpoint.js'
+// Projecting what the SDK records onto the session-layer statuses. Both
+// were declared and consumed with nothing in the repo producing them, so a
+// host implementing either had to invent the mapping.
+export { deriveRunStatus } from './types/run/derive-status.js'
+// Scoped approval memory: the mechanism that lets an approver choose how
+// wide their yes is, instead of choosing between 'this one call' and
+// 'everything for the session'.
+export { ToolGrantSet, toolGrantKeys } from './runtime/query/tool-grants.js'
+export type { ToolGrantKeys } from './runtime/query/tool-grants.js'
+export { toWireRunStatus } from './contracts/run-status.js'
+// Durable run state: the snapshot a different process picks a run up from.
+export { captureRunState, loadRunState } from './runtime/query/run-state.js'
+export type { RunStateScope } from './runtime/query/run-state.js'
 export { prepareReplayState } from './runtime/query/replay/prepare.js'
 export { listCheckpoints } from './runtime/query/replay/list.js'
 export { DecisionParser, FallbackResolver } from './runtime/decision/index.js'
@@ -164,30 +181,46 @@ export { LocalTaskGateway } from './gateway/local.js'
 // ─── providers, sandbox, vault ───────────────────────────────────────────
 
 export {
-	bodySaysContextOverflow,
-	classifyProviderHttpStatus,
+	classifyProviderError,
+	DEFAULT_PROVIDER_RETRY,
 	DuplicateProviderError,
-	isCallerAbortError,
-	isProviderRequestError,
+	isAbortError,
+	isProviderError,
 	LazyProviderLoadError,
 	LazyProviderSyncCreateError,
 	MOCK_CAPABILITIES,
 	MockLLMProvider,
 	parseRetryAfterMs,
 	PERMISSIVE_PROVIDER_CAPABILITIES,
-	providerHttpError,
-	providerVendorError,
+	ProviderError,
 	ProviderRegistry,
 	ProviderRequestError,
 	registerMock,
 	resolveProviderCapabilities,
 	UnknownProviderError,
+	withProviderRetry,
 } from './provider/index.js'
+export type { ProviderRetryConfig, WithProviderRetryOptions } from './provider/index.js'
 
 export {
+	assertIsolation,
+	describeIsolation,
+	isolationOf,
 	LocalSandboxProvider,
+	missingIsolation,
 	SandboxProviderFactory,
 } from './sandbox/index.js'
+export type { LocalSandboxProviderOptions } from './sandbox/index.js'
+
+// The classified provider-failure surface: a driver states what went wrong
+// first-hand, and the run boundary reads it to choose between a pause and a
+// failure.
+export {
+	isCallerAbortError,
+	isProviderRequestError,
+	providerHttpError,
+	providerVendorError,
+} from './provider/errors.js'
 
 export { InMemoryCredentialVault } from './vault/index.js'
 
@@ -203,7 +236,7 @@ export {
 	DefaultKnowledgeBase,
 	DefaultRetriever,
 	InMemoryVectorStore,
-	OpenRouterEmbeddingProvider,
+	HttpEmbeddingProvider,
 	TextChunker,
 } from './rag/index.js'
 
@@ -413,6 +446,9 @@ export {
 	createAssistantMessage,
 	createSystemMessage,
 	createToolMessage,
+	hasNonTextBlocks,
+	toToolResultBlocks,
+	toolResultToText,
 	createUserMessage,
 } from './types/message/index.js'
 export { isTerminalPlanStatus } from './types/plan/index.js'
@@ -426,10 +462,16 @@ export {
 	PluginMCPServerConfigSchema,
 } from './types/plugin/index.js'
 export { EmergencySaveConfigSchema } from './types/run/emergency.js'
+export { toMemoryCandidate } from './types/run/memory-promotion.js'
 export { MutationNotApplicableError } from './types/run/replay.js'
 export {
 	assertSandboxEnvironment,
 	assertSandboxStatus,
+	// A VALUE, not a type: the control list is iterated at runtime by
+	// anything reporting which controls a host enforces. `export type *`
+	// carried it far enough to type-check and left the import to fail on
+	// the first line of the built binary.
+	SANDBOX_ISOLATION_CONTROLS,
 } from './types/sandbox/index.js'
 // `SandboxConfigSchema` is already re-exported above from `./config/runtime.js`
 // (the project-wide config barrel surfaces it first). types/sandbox also exports
@@ -443,6 +485,9 @@ export { assertTaskStatus, isTerminalTaskStatus } from './types/task/index.js'
 
 export {
 	buildVerifiedSummary,
+	DEFAULT_ASSUMED_CONTEXT_WINDOW,
+	lookupContextWindow,
+	resolveContextWindow,
 	createConversationManager,
 	extractFromAssistantMessage,
 	extractFromToolCall,
@@ -450,6 +495,7 @@ export {
 	extractFromUserMessage,
 	findDanglingMessages,
 	findSafeTrimIndex,
+	findRetainedIndices,
 	NullManager,
 	removeDanglingMessages,
 	serializeState,
@@ -457,3 +503,61 @@ export {
 	StructuredCompactionManager,
 	WorkingStateManager,
 } from './compaction/index.js'
+
+// ─── loop control ────────────────────────────────────────────────────────
+
+export { anyOf, hasToolCall, stepCountIs } from './types/run/step.js'
+
+// ─── evaluation harness ──────────────────────────────────────────────────
+
+export {
+	completionScorer,
+	containsScorer,
+	customScorer,
+	evalRunFromQuery,
+	evalRunFromRun,
+	formatReport,
+	judgeScorer,
+	runExperiment,
+	stepBudgetScorer,
+	trajectoryScorer,
+} from './eval/index.js'
+
+// ─── metrics ─────────────────────────────────────────────────────────────
+//
+// Exported so a host can record its own measurements onto the same series
+// the runtime uses, rather than defining a parallel set under different
+// names that never aggregate.
+
+export {
+	recordModelDuration,
+	recordRunDuration,
+	recordTokenUsage,
+	recordToolCall,
+	resetRuntimeMetrics,
+} from './telemetry/metrics.js'
+export type { TokenUsageSample } from './telemetry/metrics.js'
+
+// ─── guardrails ──────────────────────────────────────────────────────────
+
+export {
+	promptInjectionGuardrail,
+	secretRedactionGuardrail,
+} from './runtime/query/guardrail-presets.js'
+
+// Error taxonomy. `toPlatformError` is the load-bearing one: it normalizes
+// ANYTHING thrown into the declared `PlatformError` shape, so a host writes
+// one handler instead of an `instanceof` ladder per call site.
+export { NamzuError, isNamzuError, toPlatformError } from './types/errors/index.js'
+// The remediation layer above it: classification says what KIND of failure
+// it is, the catalog says what a person should do about it. Separate on
+// purpose — the first is structural and belongs at the boundary, the second
+// is editorial and belongs in a list a human appends to.
+export {
+	DEFAULT_ERROR_RULES,
+	explainError,
+	factsOf,
+	readHint,
+	withHint,
+} from './types/errors/catalog.js'
+export type { ErrorCatalogRule, ErrorExplanation, ErrorFacts } from './types/errors/catalog.js'

package/src/public-types.ts

@@ -16,10 +16,12 @@
 export type * from './types/ids/index.js'
 export type * from './types/message/index.js'
 export type * from './types/common/index.js'
+export type * from './types/bidi/index.js'
 export type * from './types/tool/index.js'
 export type * from './types/toolset/index.js'
 export type * from './types/permission/index.js'
 export type * from './types/run/index.js'
+export type * from './types/errors/index.js'
 export type * from './types/provider/index.js'
 export type * from './types/agent/index.js'
 export type * from './types/decision/index.js'
@@ -97,7 +99,7 @@ export type { ContextCacheConfig, PromptCacheInput } from './runtime/query/conte
 
 export type { LimitCheckResult, LimitCheckerState, RunReporter } from './run/index.js'
 
-export type { ConcurrencyMode, DefineAgentOptions, Disposable } from './agents/index.js'
+export type { DefineAgentOptions, Disposable } from './agents/index.js'
 
 export type {
 	ActivityEvent,
@@ -164,3 +166,5 @@ export type {
 	ToolResultSlot,
 	WorkingState,
 } from './compaction/index.js'
+export type * from './eval/index.js'
+export type * from './types/guardrail/index.js'