@namzu/sdk 1.4.0 → 3.0.0

package/src/types/agent/reactive.ts

@@ -1,10 +1,17 @@
 import type { CompactionConfig } from '../../config/runtime.js'
+import type { QueryParams } from '../../runtime/query/index.js'
 import type { AdvisoryConfig } from '../advisory/index.js'
+import type { InputGuardrailSpec, OutputGuardrailSpec } from '../guardrail/index.js'
+import type { ResumeHandler } from '../hitl/index.js'
 import type { AgentPersona } from '../persona/index.js'
 import type { LLMProvider } from '../provider/index.js'
+import type { CheckpointStore } from '../run/checkpoint-store.js'
+import type { PrepareStepChain, StepResult, StopCondition } from '../run/index.js'
 import type { SandboxProvider } from '../sandbox/index.js'
 import type { Skill } from '../skills/index.js'
+import type { StructuredOutputConfig } from '../structured-output/index.js'
 import type { ToolRegistryContract } from '../tool/index.js'
+import type { RepairToolCall } from '../tool/repair.js'
 import type { VerificationGateConfig } from '../verification/index.js'
 import type { BaseAgentConfig, BaseAgentResult } from './base.js'
 import type { WorkingMemoryProvider } from './working-memory.js'
@@ -59,6 +66,49 @@ export interface ReactiveAgentConfig extends BaseAgentConfig {
 	 * sharing the supervisor's output dir passes the same provider.
 	 */
 	workingMemoryProvider?: WorkingMemoryProvider
+
+	/**
+	 * Loop-control and resilience seams, forwarded verbatim to `query()`.
+	 *
+	 * These existed on `QueryParams` and stopped there. `ReactiveAgent` is
+	 * the entry point most consumers actually use — it is what
+	 * `AgentManager` spawns and what the estate's own applications call —
+	 * and it forwarded none of them. So a per-tool deadline, a provider
+	 * retry policy, a guardrail, a stop condition: all of it was reachable
+	 * only by dropping down to `query()` and rebuilding the run wiring by
+	 * hand. Features that a consumer cannot reach are features that do not
+	 * exist for them.
+	 *
+	 * Every field is optional and absent means exactly what it meant
+	 * before, so no existing agent changes behavior.
+	 */
+	resumeHandler?: ResumeHandler
+	retry?: QueryParams['retry']
+	emergencySave?: boolean
+	toolTimeoutMs?: number
+	maxToolConcurrency?: number
+	maxToolOutputChars?: number
+	/**
+	 * Cap on the RICH channel of a single tool result, in base64 characters.
+	 * `0` or absent disables it. Separate from {@link maxToolOutputChars}:
+	 * that one bounds characters the model reads, this one bounds the image
+	 * payload beside them, which no text budget ever touched.
+	 */
+	maxToolContentBytes?: number
+	repairToolCall?: RepairToolCall
+	stopWhen?: StopCondition
+	onStepFinish?: (step: StepResult) => void
+	prepareStep?: PrepareStepChain
+	structuredOutput?: StructuredOutputConfig
+	inputGuardrails?: readonly InputGuardrailSpec[]
+	outputGuardrails?: readonly OutputGuardrailSpec[]
+	checkpointStore?: CheckpointStore
+
+	/**
+	 * Span this run should hang off, when it is a delegated one. Absent for
+	 * a top-level run, which correctly starts its own root trace.
+	 */
+	parentSpan?: import('@opentelemetry/api').Span
 }
 
 export interface ReactiveAgentResult extends BaseAgentResult {

package/src/types/agent/router.ts

@@ -1,3 +1,4 @@
+import type { TokenUsage } from '../common/index.js'
 import type { LLMProvider } from '../provider/index.js'
 import type { BaseAgentConfig, BaseAgentResult } from './base.js'
 import type { Agent } from './core.js'
@@ -9,6 +10,16 @@ export interface RoutingDecision {
 	confidence: number
 	reasoning?: string
 	routingSource: RoutingDecisionSource
+	/**
+	 * Tokens the routing call itself spent, summed over any retries.
+	 *
+	 * Routing runs before the delegate's run exists, so it has no
+	 * `RunPersistence` to accumulate into. Reporting it here lets the
+	 * router fold it into the result it returns, instead of the caller
+	 * seeing only the delegate's usage and under-reporting every routed
+	 * run by one model call.
+	 */
+	usage?: TokenUsage
 }
 
 export interface RouteDefinition {

package/src/types/agent/supervisor.ts

@@ -38,8 +38,8 @@ export interface SupervisorAgentConfig extends BaseAgentConfig {
 	 * Optional human-in-the-loop hook for tool review and run-pause
 	 * decisions. When omitted, the supervisor delegates to drainQuery's
 	 * built-in `autoApproveHandler`, which approves every tool call
-	 * without prompting — matching Anthropic's "Act without asking"
-	 * cowork mode.
+	 * without prompting — the unattended mode, where the run is expected
+	 * to finish without a human at the keyboard.
 	 *
 	 * Hosts that want "Ask before acting" behaviour pass a custom
 	 * handler that surfaces the `tool_review_requested` RunEvent to

package/src/types/agent/task.ts

@@ -90,6 +90,18 @@ export interface AgentTask {
 	result?: BaseAgentResult
 	progress?: AgentTaskProgress
 
+	/**
+	 * Tokens reserved from the shared pool when this child was spawned.
+	 *
+	 * A RESERVATION, not a spend: it is subtracted up front so siblings
+	 * cannot each be promised the same headroom, and the unused part is
+	 * returned when the child settles. Without the return, a pool shrank
+	 * by the full allocation every spawn regardless of what the child
+	 * actually used, so a long session ran out of budget while almost none
+	 * of it had been spent.
+	 */
+	budgetReservation?: number
+
 	pendingMessages: Message[]
 	createdAt: number
 	completedAt?: number
@@ -149,4 +161,18 @@ export interface AgentManagerConfig {
 	evictionMs: number
 
 	maxBudgetFraction: number
+
+	/**
+	 * Wall-clock deadline given to a spawned child when the caller supplies
+	 * no `budgetAllocation.timeoutMs`.
+	 *
+	 * This exists because the fallback used to be
+	 * `context.budgetTracker.remaining` — a TOKEN count read as
+	 * milliseconds. The unit error hid for so long because a typical
+	 * six-figure token budget lands in a plausible-looking range of
+	 * milliseconds; it only bites at the edges, where an unlimited budget
+	 * (`0`) became a zero-millisecond deadline and a small budget became a
+	 * child that died in under a second.
+	 */
+	childTimeoutMs: number
 }

package/src/types/bidi/index.ts

@@ -0,0 +1,119 @@
+import type { RunId } from '../ids/index.js'
+import type { LLMToolSchema } from '../tool/index.js'
+
+/**
+ * A conversation with no turn boundary.
+ *
+ * Every other seam in this kernel is turn-based by construction: a run
+ * has iterations, an iteration sends a complete message list and reads a
+ * stream back, and a checkpoint is taken between two of them. That shape
+ * is load-bearing everywhere it appears and it cannot describe a duplex
+ * session, where input keeps arriving while output is still being
+ * produced and "the turn" is not a thing either side can point at.
+ *
+ * So this is a second contract rather than a widening of the first. The
+ * alternative — bending `chatStream` until it accepts a live input
+ * channel — would put a half-duplex assumption inside every consumer of
+ * the turn-based path in exchange for a duplex path that still would not
+ * fit.
+ *
+ * What is here: the driver contract, the session loop that runs tools
+ * against it, and a scripted driver so both are exercised. What is NOT
+ * here, and deliberately: audio capture and playback, which belong to
+ * whatever owns the microphone, and checkpoint/resume, which has no
+ * meaning yet for a session whose state lives on the far side of a
+ * socket.
+ */
+
+export type BidiInput =
+	| { readonly type: 'text'; readonly text: string }
+	| { readonly type: 'audio'; readonly data: string; readonly mediaType: string }
+
+/**
+ * What the far side reports.
+ *
+ * `interrupted` is the event that makes this contract different from the
+ * turn-based one. In a duplex session the human can speak over the model,
+ * and everything the model was in the middle of — text it was emitting, a
+ * tool it just asked for — is now answering a question nobody is asking.
+ * A driver that cannot detect that never emits it and the loop behaves as
+ * if the model always finished what it started.
+ */
+export type BidiEvent =
+	| { readonly type: 'text'; readonly text: string }
+	| { readonly type: 'audio'; readonly data: string; readonly mediaType: string }
+	| {
+			readonly type: 'tool_call'
+			readonly id: string
+			readonly name: string
+			/** JSON, as the model produced it. */
+			readonly arguments: string
+	  }
+	/** The model finished a stretch of output and is waiting. */
+	| { readonly type: 'turn_complete' }
+	/** The human spoke over the model; anything in flight is now stale. */
+	| { readonly type: 'interrupted' }
+	| { readonly type: 'error'; readonly message: string }
+	| { readonly type: 'closed'; readonly reason?: string }
+
+export interface BidiConnectParams {
+	readonly model: string
+	readonly system?: string
+	readonly tools?: readonly LLMToolSchema[]
+	readonly signal?: AbortSignal
+}
+
+export interface BidiSession {
+	/** Push input from the human. Never waits for the model to be idle. */
+	send(input: BidiInput): Promise<void>
+	/**
+	 * Answer a `tool_call`.
+	 *
+	 * Separate from {@link send} because it is not input from the human:
+	 * a driver has to attach it to the call it answers, and a session that
+	 * received it as ordinary input would have to guess.
+	 */
+	sendToolResult(id: string, output: string, isError?: boolean): Promise<void>
+	events(): AsyncIterable<BidiEvent>
+	close(): Promise<void>
+}
+
+export interface BidiProvider {
+	readonly id: string
+	connect(params: BidiConnectParams): Promise<BidiSession>
+}
+
+/** What the loop reports back to whoever is driving it. */
+export type BidiRunEvent =
+	| { readonly type: 'text'; readonly runId: RunId; readonly text: string }
+	| {
+			readonly type: 'audio'
+			readonly runId: RunId
+			readonly data: string
+			readonly mediaType: string
+	  }
+	| {
+			readonly type: 'tool_started'
+			readonly runId: RunId
+			readonly toolUseId: string
+			readonly toolName: string
+	  }
+	| {
+			readonly type: 'tool_completed'
+			readonly runId: RunId
+			readonly toolUseId: string
+			readonly toolName: string
+			readonly output: string
+			readonly isError: boolean
+	  }
+	/** A tool's answer was thrown away because the human interrupted. */
+	| {
+			readonly type: 'tool_abandoned'
+			readonly runId: RunId
+			readonly toolUseId: string
+			readonly toolName: string
+	  }
+	| { readonly type: 'turn_complete'; readonly runId: RunId }
+	| { readonly type: 'interrupted'; readonly runId: RunId }
+	| { readonly type: 'error'; readonly runId: RunId; readonly message: string }
+	| { readonly type: 'closed'; readonly runId: RunId; readonly reason?: string }

package/src/types/common/__tests__/numeric-correctness.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, it } from 'vitest'
+
+import { toolsHash } from '../../../connector/mcp/policy.js'
+import type { MCPToolDefinition } from '../../../types/connector/index.js'
+import { mergeTokenUsage } from '../index.js'
+
+/**
+ * Arithmetic defects, each pinned by the exact counterexample that proves it.
+ * A test here is only worth having if it fails against the old formula, so
+ * every one names the number the old code produced.
+ */
+
+describe('mergeTokenUsage — totalTokens is derived, not independent', () => {
+	it('does not lose the completion tokens Anthropic reports in a later frame', () => {
+		// A driver reports the input on `message_start` and the output on
+		// `message_delta`. The driver derives each frame's own total as
+		// input+output, so the two frames carry 1200 and 350 — and a max of
+		// those returns the larger COMPONENT, not the sum.
+		const messageStart = {
+			promptTokens: 1200,
+			completionTokens: 0,
+			totalTokens: 1200,
+			cachedTokens: 0,
+			cacheWriteTokens: 0,
+		}
+		const messageDelta = {
+			promptTokens: 0,
+			completionTokens: 350,
+			totalTokens: 350,
+			cachedTokens: 0,
+			cacheWriteTokens: 0,
+		}
+
+		const merged = mergeTokenUsage(messageStart, messageDelta)
+
+		expect(merged.promptTokens).toBe(1200)
+		expect(merged.completionTokens).toBe(350)
+		// Old formula: Math.max(1200, 350) = 1200. Every completion token was
+		// invisible to the budget hard stop, which reads only totalTokens.
+		expect(merged.totalTokens).toBe(1550)
+	})
+
+	it('holds for the minimal case too', () => {
+		const a = {
+			promptTokens: 1,
+			completionTokens: 0,
+			totalTokens: 1,
+			cachedTokens: 0,
+			cacheWriteTokens: 0,
+		}
+		const b = {
+			promptTokens: 0,
+			completionTokens: 1,
+			totalTokens: 1,
+			cachedTokens: 0,
+			cacheWriteTokens: 0,
+		}
+		expect(mergeTokenUsage(a, b).totalTokens).toBe(2)
+	})
+
+	it('never under-reports a provider total that exceeds prompt + completion', () => {
+		// Some providers count tokens the two components do not cover. The
+		// merge must be monotone: it may never return less than what was
+		// reported.
+		const reported = {
+			promptTokens: 10,
+			completionTokens: 5,
+			totalTokens: 99,
+			cachedTokens: 0,
+			cacheWriteTokens: 0,
+		}
+		const empty = {
+			promptTokens: 0,
+			completionTokens: 0,
+			totalTokens: 0,
+			cachedTokens: 0,
+			cacheWriteTokens: 0,
+		}
+		expect(mergeTokenUsage(reported, empty).totalTokens).toBe(99)
+	})
+
+	it('is idempotent, so re-merging a frame cannot inflate the total', () => {
+		const usage = {
+			promptTokens: 1200,
+			completionTokens: 350,
+			totalTokens: 1550,
+			cachedTokens: 0,
+			cacheWriteTokens: 0,
+		}
+		expect(mergeTokenUsage(usage, usage).totalTokens).toBe(1550)
+		expect(mergeTokenUsage(mergeTokenUsage(usage, usage), usage).totalTokens).toBe(1550)
+	})
+})
+
+describe('toolsHash — the fingerprint covers what the HITL gate reads', () => {
+	const tool = (annotations?: Record<string, unknown>): MCPToolDefinition =>
+		({
+			name: 'delete_rows',
+			description: 'Delete rows',
+			inputSchema: { type: 'object', properties: {} },
+			...(annotations ? { annotations } : {}),
+		}) as MCPToolDefinition
+
+	it('notices a server flipping destructive to read-only', () => {
+		// `annotations` becomes `isDestructive` / `isReadOnly` on the tool
+		// definition, and those drive whether a human reviews the call. A
+		// fingerprint that ignores them cannot see the exact rug-pull it was
+		// built to catch: same name, same schema, no longer reviewed.
+		const before = toolsHash([tool({ destructiveHint: true, readOnlyHint: false })])
+		const after = toolsHash([tool({ destructiveHint: false, readOnlyHint: true })])
+		expect(after).not.toBe(before)
+	})
+
+	it('notices annotations appearing where there were none', () => {
+		expect(toolsHash([tool()])).not.toBe(toolsHash([tool({ readOnlyHint: true })]))
+	})
+
+	it('is still stable for an unchanged tool', () => {
+		expect(toolsHash([tool({ destructiveHint: true })])).toBe(
+			toolsHash([tool({ destructiveHint: true })]),
+		)
+	})
+})

package/src/types/common/index.ts

@@ -25,17 +25,29 @@ export function accumulateTokenUsage(current: TokenUsage, addition: TokenUsage):
 /**
  * Merge two usage snapshots seen WITHIN a single streamed turn. Provider usage
  * frames over one stream are cumulative/monotonic (input set once early, output
- * grows), but a late frame can OMIT a field (report 0) — e.g. Anthropic's
+ * grows), but a late frame can OMIT a field (report 0) — e.g. a
  * `message_delta` may carry only output tokens. A naive last-write-wins
  * (`usage = chunk.usage`) then drops the earlier prompt/cache counts and
  * under-reports the turn. Taking the per-field high-water mark preserves every
  * field. DISTINCT from {@link accumulateTokenUsage}, which SUMS across turns.
  */
 export function mergeTokenUsage(current: TokenUsage, next: TokenUsage): TokenUsage {
+	const promptTokens = Math.max(current.promptTokens, next.promptTokens)
+	const completionTokens = Math.max(current.completionTokens, next.completionTokens)
+
 	return {
-		promptTokens: Math.max(current.promptTokens, next.promptTokens),
-		completionTokens: Math.max(current.completionTokens, next.completionTokens),
-		totalTokens: Math.max(current.totalTokens, next.totalTokens),
+		promptTokens,
+		completionTokens,
+		// `totalTokens` is DERIVED (`input + output`), not independent, so the
+		// per-field high-water mark is wrong for it: a provider reports the
+		// input on `message_start` and the output on `message_delta`, and each
+		// frame's own total covers only the component that frame carried.
+		// Maxing those two totals returns the larger COMPONENT, not the sum —
+		// 1200 and 350 merge to 1200 instead of 1550, and every completion
+		// token vanishes from the run's budget. Take the max of what was
+		// reported and what the merged components imply, so the result is
+		// monotone and can never under-report.
+		totalTokens: Math.max(current.totalTokens, next.totalTokens, promptTokens + completionTokens),
 		cachedTokens: Math.max(current.cachedTokens, next.cachedTokens),
 		cacheWriteTokens: Math.max(current.cacheWriteTokens, next.cacheWriteTokens),
 	}

package/src/types/computer-use/index.ts

@@ -59,7 +59,7 @@ export type MouseButton = 'left' | 'right' | 'middle'
 export type ScrollDirection = 'up' | 'down' | 'left' | 'right'
 
 // ---------------------------------------------------------------------------
-// Action — discriminated union; mirrors Anthropic's computer_20250124 shape
+// Action — discriminated union over what a pointer-and-keyboard host can do
 // ---------------------------------------------------------------------------
 
 export type ComputerUseAction =

package/src/types/connector/mcp.ts

@@ -85,6 +85,15 @@ export interface MCPToolDefinition {
 	name: string
 	description?: string
 	inputSchema: MCPJsonSchema
+	/**
+	 * The shape the tool returns, as the server declares it.
+	 *
+	 * Servers publish this on a tool listing regardless of negotiated
+	 * protocol revision, and it had no slot here — so a declared return
+	 * shape never reached the model at all, which was left inferring one
+	 * from prose or from whatever the first call happened to return.
+	 */
+	outputSchema?: MCPJsonSchema
 	annotations?: MCPToolAnnotations
 }
 
@@ -96,6 +105,18 @@ export type MCPContentBlock =
 export interface MCPToolResult {
 	content: MCPContentBlock[]
 	isError?: boolean
+	/**
+	 * A machine-readable payload alongside (or instead of) the content
+	 * blocks.
+	 *
+	 * A server may return this and omit the compatibility text block. The
+	 * field survived the wire cast and was read by nothing, so that call
+	 * produced an empty tool result for a request that succeeded — with no
+	 * diagnostic anywhere, since `isError` was false and the content array
+	 * was legitimately empty.
+	 */
+	structuredContent?: unknown
+	_meta?: Record<string, unknown>
 }
 
 export interface MCPResource {
@@ -158,6 +179,14 @@ export interface MCPClientConfig {
 	transport: MCPTransportUnion
 	capabilities?: MCPClientCapabilities
 	clientInfo?: { name: string; version: string }
+	/**
+	 * Deadline for a single JSON-RPC round trip. Defaults to
+	 * `DEFAULT_MCP_REQUEST_TIMEOUT_MS`.
+	 *
+	 * Without one, a wedged stdio server left every caller pending
+	 * forever — no error, no failure, just a run that stopped.
+	 */
+	requestTimeoutMs?: number
 }
 
 export interface MCPClientState {

package/src/types/errors/__tests__/catalog.test.ts

@@ -0,0 +1,130 @@
+import { describe, expect, it } from 'vitest'
+
+import { ProviderError } from '../../provider/errors.js'
+import { DEFAULT_ERROR_RULES, explainError, factsOf, readHint, withHint } from '../catalog.js'
+import { NamzuError } from '../index.js'
+
+/**
+ * A failure surfaced as whatever prose the vendor SDK happened to write:
+ * no stable id to grep in logs, no instruction on what to change, and no
+ * growth point — a newly-observed failure shape could only be given
+ * curated copy by editing the classifier itself.
+ *
+ * Classification and remediation are separate jobs. The first is
+ * structural and belongs at the boundary; the second is editorial and
+ * belongs in a list a human appends to. `DoctorCheckResult` already
+ * carried `message` and `remediation` as separate fields — `namzu doctor`
+ * was simply the only surface that got either.
+ */
+
+const providerError = (code: string, status?: number) =>
+	new ProviderError({
+		code: code as never,
+		message: 'the vendor wrote this',
+		providerId: 'test',
+		...(status !== undefined ? { status } : {}),
+	})
+
+describe('explaining a failure', () => {
+	it('gives a stale key an id and something to do about it', () => {
+		const explanation = explainError(providerError('auth', 401))
+
+		expect(explanation?.id).toBe('provider.auth')
+		expect(explanation?.hint).toMatch(/API key/)
+		// Not the vendor's sentence: the point is copy an operator can act
+		// on, keyed by an id they can grep for.
+		expect(explanation?.message).not.toContain('the vendor wrote this')
+	})
+
+	it('separates a permission failure from an authentication one', () => {
+		// The provider codes collapse 401 and 403, but the two call for
+		// different actions and the status still tells them apart.
+		expect(explainError(providerError('auth', 403))?.id).toBe('provider.permission')
+		expect(explainError(providerError('auth', 401))?.id).toBe('provider.auth')
+	})
+
+	it('recognises the failures an operator hits first', () => {
+		expect(explainError(providerError('rate_limit', 429))?.id).toBe('provider.rate_limit')
+		expect(explainError(providerError('context_length_exceeded'))?.id).toBe(
+			'provider.context_overflow',
+		)
+		expect(explainError(providerError('overloaded', 529))?.id).toBe('provider.unavailable')
+		expect(explainError(providerError('network'))?.id).toBe('provider.network')
+		expect(explainError(providerError('not_found', 404))?.id).toBe('provider.model_not_found')
+	})
+
+	it('says nothing rather than inventing advice', () => {
+		// A generic fallback would send the reader somewhere specific and
+		// wrong, which is worse than admitting the failure is unfamiliar.
+		expect(explainError(new Error('something nobody has characterised'))).toBeNull()
+	})
+
+	it('matches on structure, not on vendor prose', () => {
+		// Vendor copy changes without warning and differs per SDK version,
+		// so a rule keyed to it silently stops matching.
+		const reworded = providerError('rate_limit', 429)
+		Object.defineProperty(reworded, 'message', { value: 'completely different wording' })
+		expect(explainError(reworded)?.id).toBe('provider.rate_limit')
+	})
+
+	it('takes the first matching rule, so a rule can be as specific as it likes', () => {
+		const ids = DEFAULT_ERROR_RULES.map((rule) => rule.id)
+		expect(ids.indexOf('provider.permission')).toBeLessThan(ids.indexOf('provider.auth'))
+	})
+})
+
+describe('a hint attached where the failure was raised', () => {
+	it('wins over a rule matched on a status code', () => {
+		// Code that raised the failure knows more about it than a generic
+		// rule ever will — a container that has not been built, a daemon
+		// that is not running.
+		const err = withHint(providerError('rate_limit', 429), 'the sandbox worker is not running')
+		const explanation = explainError(err)
+
+		expect(explanation?.id).toBe('hint.from_throw_site')
+		expect(explanation?.hint).toBe('the sandbox worker is not running')
+	})
+
+	it('survives being read back off a plain throwable', () => {
+		expect(readHint(withHint(new Error('boom'), 'check the socket path'))).toBe(
+			'check the socket path',
+		)
+	})
+
+	it('does not change the message or the type', () => {
+		// Baking remediation into the message is what made it impossible to
+		// separate again — a surface could not render one without the other.
+		const original = new NamzuError({ code: 'storage_error', message: 'write failed' })
+		const hinted = withHint(original, 'the run directory is not writable')
+
+		expect(hinted).toBe(original)
+		expect(hinted.message).toBe('write failed')
+		expect(hinted instanceof NamzuError).toBe(true)
+	})
+
+	it('is not enumerable, so it cannot leak into a serialized error', () => {
+		const err = withHint(new Error('boom'), 'a hint')
+		expect(Object.keys(err)).not.toContain('hint')
+	})
+
+	it('ignores an empty or non-string hint', () => {
+		expect(readHint(withHint(new Error('boom'), ''))).toBeUndefined()
+		expect(readHint({ hint: 42 })).toBeUndefined()
+		expect(readHint(null)).toBeUndefined()
+	})
+})
+
+describe('the facts a rule matches on', () => {
+	it('reads a provider classification', () => {
+		const facts = factsOf(providerError('rate_limit', 429))
+		expect(facts).toMatchObject({ code: 'rate_limit', status: 429 })
+	})
+
+	it('reads a namzu code', () => {
+		expect(factsOf(new NamzuError({ code: 'tool_error', message: 'x' })).code).toBe('tool_error')
+	})
+
+	it('still produces facts for something that was never an Error', () => {
+		expect(factsOf('just a string').message).toBe('just a string')
+	})
+})