@namzu/sdk 2.0.0 → 3.0.0

package/src/tools/posix-path.ts

@@ -0,0 +1,73 @@
+/**
+ * Path arithmetic in the SANDBOX's coordinate system.
+ *
+ * A sandbox is a POSIX filesystem whatever the host runs, so resolving its
+ * paths with the host's path module rewrites them whenever the two
+ * disagree: on a Windows host, `resolve('/workspace')` becomes
+ * `C:\workspace` and a container path stops being a container path. The
+ * tool then hands the model a string its own sandbox cannot open — which
+ * is the same class of failure as reporting host-relative paths from a
+ * sandboxed search, just one layer lower.
+ *
+ * These are deliberately small: join, relativise, and refuse an escape.
+ * Nothing here touches the host filesystem.
+ */
+
+function normalizeSegments(path: string): string[] {
+	const out: string[] = []
+	for (const segment of path.split('/')) {
+		if (segment === '' || segment === '.') continue
+		if (segment === '..') {
+			// Popping past the root is how a climb-out starts; the caller
+			// decides what to do about it via `resolveWithinPosix`.
+			if (out.length > 0 && out[out.length - 1] !== '..') out.pop()
+			else out.push('..')
+			continue
+		}
+		out.push(segment)
+	}
+	return out
+}
+
+/** Join, normalising `.` and `..`. Absolute in, absolute out. */
+export function joinPosix(base: string, ...parts: string[]): string {
+	const absolute = base.startsWith('/')
+	const segments = normalizeSegments([base, ...parts].join('/'))
+	return (absolute ? '/' : '') + segments.join('/')
+}
+
+/** `to` expressed relative to `from`, or `to` itself when unrelated. */
+export function relativePosix(from: string, to: string): string {
+	const fromSegments = normalizeSegments(from)
+	const toSegments = normalizeSegments(to)
+
+	let shared = 0
+	while (
+		shared < fromSegments.length &&
+		shared < toSegments.length &&
+		fromSegments[shared] === toSegments[shared]
+	) {
+		shared++
+	}
+
+	const up = fromSegments.slice(shared).map(() => '..')
+	return [...up, ...toSegments.slice(shared)].join('/')
+}
+
+/**
+ * Resolve `candidate` against `root`, refusing anything that lands
+ * outside. The sandbox-side twin of the host containment check.
+ */
+export function resolveWithinPosix(root: string, candidate: string | undefined): string {
+	if (candidate === undefined || candidate === '') return joinPosix(root)
+
+	// An absolute candidate is taken as sandbox-absolute, not appended.
+	const resolved = candidate.startsWith('/') ? joinPosix(candidate) : joinPosix(root, candidate)
+	const rel = relativePosix(root, resolved)
+	if (rel.startsWith('..')) {
+		throw new Error(
+			`Path escapes the working directory: ${candidate}. Tools may only reach inside ${root}.`,
+		)
+	}
+	return resolved
+}

package/src/types/advisory/config.ts

@@ -1,3 +1,4 @@
+import type { ModelPricing } from '../../utils/cost.js'
 import type { AgentPersona } from '../persona/index.js'
 import type { LLMProvider } from '../provider/index.js'
 import type { AdvisoryTrigger } from './trigger.js'
@@ -14,14 +15,31 @@ export interface AdvisorDefinition {
 	readonly useCompactedContext?: boolean
 	readonly maxResponseTokens?: number
 	readonly temperature?: number
+	/**
+	 * What this advisor's model costs. Absent means cost is not measured,
+	 * which is fine until a cost cap is set — see {@link AdvisoryBudget}.
+	 */
+	readonly pricing?: ModelPricing
 }
 
+/**
+ * Bounds on what a run may spend on advice.
+ *
+ * Every cap here is enforced. Per-SESSION caps used to be declared beside
+ * these and were not: the advisory stack is built once per run, so there was
+ * no accumulator that outlived one, and the field could only ever read as a
+ * promise. A host that wants a session bound holds it where sessions live.
+ */
 export interface AdvisoryBudget {
+	/** Advisory calls allowed in one run. Checked before each call. */
 	readonly maxCallsPerRun?: number
-	readonly maxCallsPerSession?: number
-	readonly maxCostPerCall?: number
+	/**
+	 * Total advisory spend allowed in one run, in the same units as
+	 * {@link ModelPricing}. Requires every advisor to carry `pricing`;
+	 * a run configured otherwise is refused rather than left uncapped.
+	 */
 	readonly maxCostPerRun?: number
-	readonly maxCostPerSession?: number
+	/** Response-token ceiling applied to each call, clamping the advisor's own. */
 	readonly maxTokensPerCall?: number
 }
 

package/src/types/advisory/result.ts

@@ -8,17 +8,22 @@ export interface AdvisoryRequest {
 	readonly includeContext?: boolean
 }
 
+/**
+ * What an advisor answered.
+ *
+ * Three more fields — a plan, a model suggestion, per-category tool guidance —
+ * were declared here with neither a producer nor a reader, so they described
+ * a shape the runtime never built and nothing ever branched on. The two that
+ * remain are produced by the parser and consumed: decisions land in working
+ * state and survive compaction, warnings are rendered back to the executing
+ * agent.
+ */
 export interface AdvisoryResult {
 	readonly advice: string
-	readonly plan?: Array<{ step: string; status?: string }>
+	/** Carried into working state, so they outlive the context they were given in. */
 	readonly decisions?: string[]
+	/** Rendered back to the executing agent under their own heading. */
 	readonly warnings?: string[]
-	readonly modelSuggestion?: string
-	readonly toolGuidance?: Array<{
-		readonly category: string
-		readonly recommendation: 'prefer' | 'avoid' | 'required'
-		readonly reason?: string
-	}>
 }
 
 export interface AdvisoryCallRecord {

package/src/types/agent/base.ts

@@ -23,6 +23,23 @@ export interface BaseAgentConfig {
 	permissionMode?: PermissionMode
 	env?: Record<string, string>
 
+	/**
+	 * Deduplicate a retried invocation instead of running it twice.
+	 *
+	 * The failure this exists for: a caller sends a request, the
+	 * connection drops, the caller retries. Without a key the retry is a
+	 * second full run — a second set of model calls, and a second set of
+	 * whatever the tools did. A duplicate arriving while the first is
+	 * still running awaits it and receives its result, error included.
+	 *
+	 * In-flight only. A retry that arrives after the first has settled
+	 * runs again, because keeping the answer would turn deduplication
+	 * into caching and staleness is the host's judgement, not the SDK's.
+	 * Instance-scoped, like the invocation lock: deduplicating across
+	 * processes needs somewhere durable to record the key.
+	 */
+	idempotencyKey?: string
+
 	/**
 	 * Long-lived goal scope for the run. Required at runtime — agents reject
 	 * configs missing this (`'X requires sessionId, projectId, and tenantId
@@ -58,6 +75,9 @@ export interface BaseAgentConfig {
 
 	/** Shared invocation state passed through agent hierarchies */
 	invocationState?: InvocationState
+
+	/** Span a delegated run hangs off. Absent for a top-level run. */
+	parentSpan?: import('@opentelemetry/api').Span
 }
 
 export type RuntimeToolOverrides = Record<string, ToolAvailability | 'disabled'>
@@ -68,8 +88,8 @@ export interface AgentRuntimeContext {
 	/**
 	 * Optional working/scratch directory the runtime exposes to the
 	 * agent — sibling to `outputDirectory`, invisible to the
-	 * output collector. Mirrors the Anthropic Cowork pattern
-	 * where `/home/claude` is scratch and `/mnt/user-data/outputs` is
+	 * output collector. Follows the same separation as the container layout
+	 * where the scratch bind is invisible and `/mnt/user-data/outputs` is
 	 * user-visible.
 	 */
 	scratchDirectory?: string

package/src/types/agent/factory.ts

@@ -15,8 +15,8 @@ export interface AgentDefinition {
 
 export interface AgentFactoryOptions {
 	/**
-	 * API key for providers that authenticate via key (OpenAI, Anthropic,
-	 * OpenRouter). Optional because BYO-provider flows (Bedrock IAM, custom
+	 * API key for providers that authenticate via a key. Optional because
+	 * BYO-provider flows (ambient cloud credentials, a custom
 	 * `ProviderRegistry.create(...)`) resolve credentials outside this object.
 	 * `configBuilder` implementations should treat an absent `apiKey` as the
 	 * BYO signal and use the provider passed via the agent config instead.
@@ -33,14 +33,20 @@ export interface AgentFactoryOptions {
 
 	systemPrompt?: string
 
-	provider?: 'openrouter' | 'bedrock'
+	/**
+	 * Which registered provider to build. Any type registered with
+	 * `ProviderRegistry` is valid — this was a closed two-member union
+	 * naming two specific services, which the registry has never been
+	 * limited to and which no caller could extend.
+	 */
+	provider?: string
 
-	bedrockConfig?: {
-		region?: string
-		accessKeyId?: string
-		secretAccessKey?: string
-		sessionToken?: string
-	}
+	/**
+	 * Extra construction config for the chosen provider, passed through
+	 * untouched. Replaces a field that existed for exactly one service and
+	 * had no construction site anywhere.
+	 */
+	providerConfig?: Record<string, unknown>
 
 	agentDefinitions?: AgentDefinition[]
 

package/src/types/agent/gateway.ts

@@ -11,7 +11,27 @@ export interface TaskHandle {
 	readonly completedAt?: number
 }
 
+/**
+ * What a failed child means for the siblings still running.
+ *
+ * `'continue'` — the default, and deliberately so. Partial results are
+ * usually worth having, and tearing down healthy siblings on any failure
+ * would let one flaky child waste four good ones.
+ *
+ * `'cancel-siblings'` — stop the rest. For a fan-out whose parts only mean
+ * something together: if one leg of a comparison dies, the others are
+ * spending budget on an answer nobody can use.
+ */
+export type SiblingFailurePolicy = 'continue' | 'cancel-siblings'
+
 export interface CreateTaskOptions {
+	/**
+	 * Span the spawned run should hang off — normally the executing tool's
+	 * own span, so the delegation shows up inside the turn that asked for
+	 * it rather than as a disconnected root trace.
+	 */
+	readonly parentSpan?: import('@opentelemetry/api').Span
+
 	agentId: string
 
 	prompt: string

package/src/types/agent/manager.ts

@@ -18,8 +18,27 @@ export interface AgentManagerContract {
 	cancel(taskId: TaskId): void
 	cancelAll(parentRunId: RunId): void
 
+	/**
+	 * Queue a message for a running task.
+	 *
+	 * **The runtime does not deliver it.** These three methods maintain a
+	 * per-task queue that nothing in the iteration loop reads: the consumer
+	 * that once drained it was removed, and the mid-run delivery handshake
+	 * that would replace it is a host concern, not a kernel one. A caller
+	 * who assumes `continueTask` reaches the agent is queuing into a buffer
+	 * only {@link drainMessages} empties.
+	 *
+	 * Kept, and documented rather than deleted, because `drainMessages` is
+	 * the only way a host can pick these up at all — removing it would take
+	 * away the escape hatch and leave the trap. Two delivery routes that DO
+	 * work today: reject/modify feedback rides inside a tool result, and
+	 * `prepareStep`'s `system` string is appended to the next model call
+	 * from a hook that sees live history.
+	 */
 	continueTask(taskId: TaskId, message: string): Promise<void>
+	/** See {@link continueTask} — queued, not delivered. */
 	queueMessage(taskId: TaskId, message: Message): void
+	/** Empty the queue {@link continueTask} fills. The host must call this. */
 	drainMessages(taskId: TaskId): Message[]
 
 	waitForCompletion(taskId: TaskId): Promise<void>

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 })]),
+		)
+	})
+})