@namzu/sdk 2.0.0 → 3.1.0

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

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 {