@namzu/sdk 2.0.0 → 3.0.0

package/src/run/reporter.ts

@@ -78,6 +78,12 @@ export function createRunReporter(parentLogger?: Logger): RunReporter {
 				log.error('Run failed', {
 					runId: event.runId,
 					error: event.error,
+					// A greppable id and a sentence saying what to change,
+					// where before there was only whatever prose the vendor
+					// SDK happened to write.
+					code: event.failure?.code,
+					reason: event.explanation?.id,
+					hint: event.explanation?.hint,
 				})
 				break
 
@@ -225,6 +231,45 @@ export function createRunReporter(parentLogger?: Logger): RunReporter {
 				})
 				break
 
+			case 'reasoning_started':
+			case 'reasoning_delta':
+				// High-frequency and content-bearing; the completed block
+				// below carries everything a log needs.
+				break
+
+			case 'reasoning_completed':
+				log.debug('Reasoning block completed', {
+					runId: event.runId,
+					iteration: event.iteration,
+					blockIndex: event.blockIndex,
+					signed: event.signed,
+					chars: event.text?.length ?? 0,
+				})
+				break
+
+			case 'guardrail_triggered':
+				log.warn('Guardrail triggered', {
+					runId: event.runId,
+					stage: event.stage,
+					action: event.action,
+					guardrail: event.guardrail,
+					reason: event.reason,
+				})
+				break
+
+			case 'compaction_completed':
+				log.info('Context compacted', {
+					runId: event.runId,
+					iteration: event.iteration,
+					messagesDropped: event.messagesBefore - event.messagesAfter,
+					tokensBefore: event.tokensBefore,
+					tokensAfter: event.tokensAfter,
+					measuredBy: event.measuredBy,
+					contextWindowTokens: event.contextWindowTokens,
+					windowSource: event.windowSource,
+				})
+				break
+
 			case 'capability_warning':
 				log.warn('Provider capability mismatch', {
 					runId: event.runId,
@@ -234,6 +279,45 @@ export function createRunReporter(parentLogger?: Logger): RunReporter {
 				})
 				break
 
+			case 'tool_progress':
+				// Debug, not info: a long tool can emit many of these and they
+				// are a live-view signal, not a run milestone.
+				log.debug(`Tool progress: ${event.toolName}`, {
+					runId: event.runId,
+					tool: event.toolName,
+					message: event.message,
+				})
+				break
+
+			case 'user_question_asked':
+				log.info('Question asked — the run is parked on an answer', {
+					runId: event.runId,
+					checkpointId: event.checkpointId,
+					questionId: event.questionId,
+				})
+				break
+
+			case 'user_question_answered':
+				log.info(event.answered ? 'Question answered' : 'Question closed unanswered', {
+					runId: event.runId,
+					checkpointId: event.checkpointId,
+				})
+				break
+
+			case 'provider_retry':
+				// `warn`, not debug: this is the run going quiet for a
+				// measurable stretch, and the delay it names is still ahead.
+				log.warn(`Model call failed — retrying in ${event.delayMs}ms`, {
+					runId: event.runId,
+					iteration: event.iteration,
+					attempt: event.attempt,
+					maxRetries: event.maxRetries,
+					code: event.code,
+					status: event.status,
+					serverDirected: event.serverDirected,
+				})
+				break
+
 			default: {
 				const _exhaustive: never = event
 				throw new Error(`Unhandled run event type: ${(_exhaustive as RunEvent).type}`)

package/src/runtime/bidi/__tests__/session.test.ts

@@ -0,0 +1,232 @@
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+
+import { ToolRegistry } from '../../../registry/index.js'
+import { defineTool } from '../../../tools/defineTool.js'
+import type { BidiRunEvent } from '../../../types/bidi/index.js'
+import { createMockBidiProvider } from '../mock.js'
+import { startBidiRun } from '../session.js'
+
+/**
+ * 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. A duplex
+ * session has none of those boundaries — input keeps arriving while
+ * output is still being produced — so the two properties that matter
+ * here do not exist in the turn-based path at all: a tool must not stall
+ * the stream, and an interruption must invalidate work in flight.
+ */
+
+function slowTool(name: string, gate: Promise<void>) {
+	return defineTool({
+		name,
+		description: `${name} tool`,
+		inputSchema: z.object({}),
+		category: 'custom',
+		permissions: [],
+		readOnly: true,
+		destructive: false,
+		concurrencySafe: true,
+		execute: async () => {
+			await gate
+			return { success: true, output: `${name} finished` }
+		},
+	})
+}
+
+function open(gate?: Promise<void>) {
+	const tools = new ToolRegistry()
+	tools.register(slowTool('lookup', gate ?? Promise.resolve()))
+	const provider = createMockBidiProvider()
+	return { tools, provider }
+}
+
+const collect = async (run: { events(): AsyncIterable<BidiRunEvent> }, until: number) => {
+	const seen: BidiRunEvent[] = []
+	for await (const event of run.events()) {
+		seen.push(event)
+		if (seen.length >= until) break
+	}
+	return seen
+}
+
+describe('a session with no turn boundary', () => {
+	it('carries the model text through', async () => {
+		const { tools, provider } = open()
+		const run = await startBidiRun({
+			provider,
+			tools,
+			connect: { model: 'mock' },
+			workingDirectory: process.cwd(),
+		})
+
+		provider.session()?.push({ type: 'text', text: 'hello there' })
+		const seen = await collect(run, 1)
+
+		expect(seen[0]).toMatchObject({ type: 'text', text: 'hello there' })
+		await run.close()
+	})
+
+	it('answers a tool call on the same session', async () => {
+		const { tools, provider } = open()
+		const run = await startBidiRun({
+			provider,
+			tools,
+			connect: { model: 'mock' },
+			workingDirectory: process.cwd(),
+		})
+
+		provider.session()?.push({ type: 'tool_call', id: 't1', name: 'lookup', arguments: '{}' })
+		const seen = await collect(run, 2)
+
+		expect(seen.map((e) => e.type)).toEqual(['tool_started', 'tool_completed'])
+		expect(provider.session()?.sent).toContainEqual({
+			toolResult: 't1',
+			output: 'lookup finished',
+			isError: false,
+		})
+		await run.close()
+	})
+
+	it('keeps delivering model output while a tool is still running', async () => {
+		// The property the turn-based loop never needs: awaiting a tool
+		// inline would stall the very stream an interruption arrives on.
+		let release: (() => void) | undefined
+		const gate = new Promise<void>((resolve) => {
+			release = resolve
+		})
+		const { tools, provider } = open(gate)
+		const run = await startBidiRun({
+			provider,
+			tools,
+			connect: { model: 'mock' },
+			workingDirectory: process.cwd(),
+		})
+
+		provider.session()?.push({ type: 'tool_call', id: 't1', name: 'lookup', arguments: '{}' })
+		provider.session()?.push({ type: 'text', text: 'still talking' })
+
+		const seen = await collect(run, 2)
+		expect(seen.map((e) => e.type)).toEqual(['tool_started', 'text'])
+
+		release?.()
+		await run.close()
+	})
+
+	it('abandons a tool answer when the human speaks over the model', async () => {
+		// Delivering it would put a stale answer into a conversation that
+		// has moved on.
+		let release: (() => void) | undefined
+		const gate = new Promise<void>((resolve) => {
+			release = resolve
+		})
+		const { tools, provider } = open(gate)
+		const run = await startBidiRun({
+			provider,
+			tools,
+			connect: { model: 'mock' },
+			workingDirectory: process.cwd(),
+		})
+
+		provider.session()?.push({ type: 'tool_call', id: 't1', name: 'lookup', arguments: '{}' })
+		provider.session()?.push({ type: 'interrupted' })
+		release?.()
+
+		const seen = await collect(run, 3)
+		expect(seen.map((e) => e.type)).toEqual(['tool_started', 'interrupted', 'tool_abandoned'])
+		// Nothing was sent back for it.
+		expect(provider.session()?.sent).toEqual([])
+		await run.close()
+	})
+
+	it('answers a tool that finished before the interruption', async () => {
+		const { tools, provider } = open()
+		const run = await startBidiRun({
+			provider,
+			tools,
+			connect: { model: 'mock' },
+			workingDirectory: process.cwd(),
+		})
+
+		provider.session()?.push({ type: 'tool_call', id: 't1', name: 'lookup', arguments: '{}' })
+		const seen = await collect(run, 2)
+		provider.session()?.push({ type: 'interrupted' })
+
+		expect(seen.map((e) => e.type)).toEqual(['tool_started', 'tool_completed'])
+		expect(provider.session()?.sent).toHaveLength(1)
+		await run.close()
+	})
+
+	it('reports a tool failure rather than dropping it', async () => {
+		const tools = new ToolRegistry()
+		tools.register(
+			defineTool({
+				name: 'lookup',
+				description: 'lookup',
+				inputSchema: z.object({}),
+				category: 'custom',
+				permissions: [],
+				readOnly: true,
+				destructive: false,
+				concurrencySafe: true,
+				execute: async () => ({ success: false, output: '', error: 'the lookup failed' }),
+			}),
+		)
+		const provider = createMockBidiProvider()
+		const run = await startBidiRun({
+			provider,
+			tools,
+			connect: { model: 'mock' },
+			workingDirectory: process.cwd(),
+		})
+
+		provider.session()?.push({ type: 'tool_call', id: 't1', name: 'lookup', arguments: '{}' })
+		const seen = await collect(run, 2)
+
+		expect(seen[1]).toMatchObject({ type: 'tool_completed', isError: true })
+		expect(provider.session()?.sent).toContainEqual({
+			toolResult: 't1',
+			output: 'the lookup failed',
+			isError: true,
+		})
+		await run.close()
+	})
+
+	it('stops reading a driver that keeps talking after it hung up', async () => {
+		// A driver that says it closed and then carries on is misbehaving,
+		// and a loop that kept forwarding would hand a consumer output from
+		// a session it was told had ended.
+		const { tools, provider } = open()
+		const run = await startBidiRun({
+			provider,
+			tools,
+			connect: { model: 'mock' },
+			workingDirectory: process.cwd(),
+		})
+
+		provider.session()?.push({ type: 'closed' })
+		provider.session()?.push({ type: 'text', text: 'still here' })
+
+		const seen: BidiRunEvent[] = []
+		for await (const event of run.events()) seen.push(event)
+
+		expect(seen.map((e) => e.type)).toEqual(['closed'])
+	})
+
+	it('ends the event stream when the far side closes', async () => {
+		const { tools, provider } = open()
+		const run = await startBidiRun({
+			provider,
+			tools,
+			connect: { model: 'mock' },
+			workingDirectory: process.cwd(),
+		})
+
+		provider.session()?.push({ type: 'closed', reason: 'the far side hung up' })
+
+		const seen: BidiRunEvent[] = []
+		for await (const event of run.events()) seen.push(event)
+
+		expect(seen).toEqual([{ type: 'closed', runId: run.runId, reason: 'the far side hung up' }])
+	})
+})

package/src/runtime/bidi/index.ts

@@ -0,0 +1,4 @@
+export { createMockBidiProvider } from './mock.js'
+export type { MockBidiScript, MockBidiSession } from './mock.js'
+export { startBidiRun } from './session.js'
+export type { BidiRun, BidiRunParams } from './session.js'

package/src/runtime/bidi/mock.ts

@@ -0,0 +1,90 @@
+import type { BidiEvent, BidiInput, BidiProvider, BidiSession } from '../../types/bidi/index.js'
+
+/**
+ * A duplex driver you script.
+ *
+ * The loop it exercises has no real service behind it yet, and that is
+ * the ordinary situation for a driver contract in this codebase rather
+ * than a reason not to have one: the turn-based path is developed and
+ * regression-tested against a scripted model too. What this makes
+ * testable is the part that is genuinely namzu's — running tools without
+ * stalling the stream, and abandoning their answers when the human speaks
+ * over the model.
+ */
+
+export interface MockBidiScript {
+	/** Events the far side emits, in order, as the test releases them. */
+	readonly events?: readonly BidiEvent[]
+	/** Emit everything immediately instead of waiting to be stepped. */
+	readonly auto?: boolean
+}
+
+export interface MockBidiSession extends BidiSession {
+	/** Release the next scripted event. */
+	step(): void
+	/** Emit an event the script did not contain. */
+	push(event: BidiEvent): void
+	/** Everything the loop sent back, in order. */
+	readonly sent: ReadonlyArray<BidiInput | { toolResult: string; output: string; isError: boolean }>
+}
+
+export function createMockBidiProvider(script: MockBidiScript = {}): BidiProvider & {
+	session(): MockBidiSession | undefined
+} {
+	let current: MockBidiSession | undefined
+
+	return {
+		id: 'mock-bidi',
+		session: () => current,
+		connect: async () => {
+			const pending = [...(script.events ?? [])]
+			const queue: BidiEvent[] = []
+			let wake: (() => void) | undefined
+			let done = false
+			const sent: Array<BidiInput | { toolResult: string; output: string; isError: boolean }> = []
+
+			const emit = (event: BidiEvent) => {
+				queue.push(event)
+				if (event.type === 'closed') done = true
+				wake?.()
+			}
+
+			if (script.auto) for (const event of pending.splice(0)) emit(event)
+
+			const session: MockBidiSession = {
+				sent,
+				step: () => {
+					const next = pending.shift()
+					if (next) emit(next)
+				},
+				push: emit,
+				send: async (input) => {
+					sent.push(input)
+				},
+				sendToolResult: async (id, output, isError) => {
+					sent.push({ toolResult: id, output, isError: isError ?? false })
+				},
+				events: async function* () {
+					while (true) {
+						while (queue.length > 0) {
+							const next = queue.shift()
+							if (next) yield next
+						}
+						if (done) return
+						await new Promise<void>((resolve) => {
+							wake = resolve
+						})
+						wake = undefined
+					}
+				},
+				close: async () => {
+					done = true
+					wake?.()
+				},
+			}
+
+			current = session
+			return session
+		},
+	}
+}

package/src/runtime/bidi/session.ts

@@ -0,0 +1,205 @@
+import type {
+	BidiConnectParams,
+	BidiProvider,
+	BidiRunEvent,
+	BidiSession,
+} from '../../types/bidi/index.js'
+import type { RunId } from '../../types/ids/index.js'
+import type { ToolContext, ToolRegistryContract } from '../../types/tool/index.js'
+import { toErrorMessage } from '../../utils/error.js'
+import { generateRunId } from '../../utils/id.js'
+import { type Logger, getRootLogger } from '../../utils/logger.js'
+
+/**
+ * Run tools for a duplex session.
+ *
+ * The turn-based loop can execute a batch of calls because it knows when
+ * the batch is complete: the model stopped talking. Here nothing stops.
+ * Two consequences shape everything below.
+ *
+ * **A tool must not block the stream.** The model keeps producing while a
+ * tool runs, and the human keeps talking. Awaiting a tool inline would
+ * stall the events that the interruption arrives on — so the loop would
+ * only notice it was interrupted after finishing work the interruption
+ * made pointless.
+ *
+ * **An interruption invalidates work in flight.** When the human speaks
+ * over the model, a tool the model asked for is answering a question
+ * nobody is asking. Sending its result anyway would put a stale answer
+ * into a conversation that has moved on, so a call that was running when
+ * the interruption arrived is abandoned rather than delivered.
+ */
+
+export interface BidiRunParams {
+	readonly provider: BidiProvider
+	readonly tools: ToolRegistryContract
+	readonly connect: BidiConnectParams
+	readonly workingDirectory: string
+	readonly env?: Record<string, string>
+	readonly signal?: AbortSignal
+	readonly log?: Logger
+	/** Overrides the generated id, so a host can correlate its own. */
+	readonly runId?: RunId
+}
+
+export interface BidiRun {
+	readonly runId: RunId
+	/** What the loop reports, in order. Ends when the session closes. */
+	events(): AsyncIterable<BidiRunEvent>
+	/** Push input from the human. */
+	send(input: Parameters<BidiSession['send']>[0]): Promise<void>
+	close(): Promise<void>
+}
+
+export async function startBidiRun(params: BidiRunParams): Promise<BidiRun> {
+	const runId = params.runId ?? generateRunId()
+	const log = (params.log ?? getRootLogger()).child({ component: 'BidiRun', runId })
+	const session = await params.provider.connect({
+		...params.connect,
+		...(params.signal ? { signal: params.signal } : {}),
+	})
+
+	// One generation of work. Bumped by every interruption, so a tool that
+	// started under an older generation knows its answer is stale without
+	// needing a handle on the call that cancelled it.
+	let generation = 0
+	const inflight = new Set<Promise<void>>()
+
+	const queue: BidiRunEvent[] = []
+	let wake: (() => void) | undefined
+	const emit = (event: BidiRunEvent) => {
+		queue.push(event)
+		wake?.()
+	}
+
+	const executeCall = async (call: { id: string; name: string; arguments: string }) => {
+		const startedUnder = generation
+		emit({ type: 'tool_started', runId, toolUseId: call.id, toolName: call.name })
+
+		let output: string
+		let isError = false
+		try {
+			let input: unknown
+			try {
+				input = JSON.parse(call.arguments || '{}')
+			} catch {
+				input = {}
+			}
+			const context: ToolContext = {
+				runId,
+				workingDirectory: params.workingDirectory,
+				abortSignal: params.signal ?? new AbortController().signal,
+				env: params.env ?? {},
+				log: (level, message) => log[level](message),
+				toolUseId: call.id,
+			}
+			const result = await params.tools.execute(call.name, input, context)
+			output = result.success ? result.output : (result.error ?? 'the tool failed')
+			isError = !result.success
+		} catch (err) {
+			output = toErrorMessage(err)
+			isError = true
+		}
+
+		if (startedUnder !== generation) {
+			// The human spoke over the model while this ran. Delivering the
+			// answer now would put it in a conversation that has moved on.
+			emit({ type: 'tool_abandoned', runId, toolUseId: call.id, toolName: call.name })
+			return
+		}
+
+		emit({
+			type: 'tool_completed',
+			runId,
+			toolUseId: call.id,
+			toolName: call.name,
+			output,
+			isError,
+		})
+		await session.sendToolResult(call.id, output, isError)
+	}
+
+	let closed = false
+	const pump = (async () => {
+		try {
+			for await (const event of session.events()) {
+				switch (event.type) {
+					case 'text':
+						emit({ type: 'text', runId, text: event.text })
+						break
+					case 'audio':
+						emit({ type: 'audio', runId, data: event.data, mediaType: event.mediaType })
+						break
+					case 'tool_call': {
+						// Started, not awaited: awaiting here would stall the very
+						// stream an interruption arrives on.
+						const running = executeCall(event).catch((err: unknown) => {
+							emit({ type: 'error', runId, message: toErrorMessage(err) })
+						})
+						inflight.add(running)
+						void running.finally(() => inflight.delete(running))
+						break
+					}
+					case 'turn_complete':
+						emit({ type: 'turn_complete', runId })
+						break
+					case 'interrupted':
+						generation++
+						emit({ type: 'interrupted', runId })
+						break
+					case 'error':
+						emit({ type: 'error', runId, message: event.message })
+						break
+					case 'closed':
+						emit({
+							type: 'closed',
+							runId,
+							...(event.reason !== undefined ? { reason: event.reason } : {}),
+						})
+						closed = true
+						break
+					default: {
+						const _exhaustive: never = event
+						throw new Error(`Unknown BidiEvent: ${JSON.stringify(_exhaustive)}`)
+					}
+				}
+				if (closed) break
+			}
+		} catch (err) {
+			emit({ type: 'error', runId, message: toErrorMessage(err) })
+		} finally {
+			closed = true
+			// Let a consumer parked on the queue notice the end.
+			wake?.()
+		}
+	})()
+
+	async function* events(): AsyncIterable<BidiRunEvent> {
+		while (true) {
+			while (queue.length > 0) {
+				const next = queue.shift()
+				if (next) yield next
+			}
+			if (closed) return
+			await new Promise<void>((resolve) => {
+				wake = resolve
+			})
+			wake = undefined
+		}
+	}
+
+	return {
+		runId,
+		events,
+		send: (input) => session.send(input),
+		close: async () => {
+			await session.close()
+			closed = true
+			wake?.()
+			// Tools still running are awaited, so a close cannot leave one
+			// writing into a session nobody is reading.
+			await Promise.allSettled([...inflight])
+			await pump.catch(() => undefined)
+		},
+	}
+}

package/src/runtime/decision/parser.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest'
+import { getRootLogger } from '../../utils/logger.js'
+import { DecisionParser } from './parser.js'
+
+function makeParser(): DecisionParser {
+	return new DecisionParser(
+		{
+			validAgentIds: ['agent-a'],
+			minConfidence: 0,
+			maxRetries: 1,
+			fallbackAgentId: 'agent-a',
+		},
+		getRootLogger(),
+	)
+}
+
+describe('DecisionParser', () => {
+	it('extracts JSON from a fenced code block', () => {
+		const parser = makeParser()
+		const raw = '```json\n{"agentId":"agent-a","confidence":0.9}\n```'
+
+		const result = parser.parse(raw)
+
+		expect(result.ok).toBe(true)
+	})
+
+	// `codeBlockMatch` used `\s*\n?` on both sides of a lazy `[\s\S]*?`
+	// capture — whitespace and the capture overlap, so an unterminated
+	// fence forces the engine to explore every way of splitting the same
+	// run of blank lines between them. The trailing non-whitespace `x`
+	// keeps `.trim()` from stripping the blank-line run before the regex
+	// ever runs. A ~1KB unterminated fence (well within a single routing
+	// completion) used to take multiple seconds; this pins it to
+	// comfortably sub-second.
+	it('does not exhibit super-linear backtracking on an unterminated fence with many blank lines', () => {
+		const parser = makeParser()
+		const raw = `\`\`\`json${'\n'.repeat(1000)}x`
+
+		const start = Date.now()
+		const result = parser.parse(raw)
+		const elapsed = Date.now() - start
+
+		expect(elapsed).toBeLessThan(500)
+		expect(result.ok).toBe(false)
+	})
+})

package/src/runtime/decision/parser.ts

@@ -113,7 +113,14 @@ export class DecisionParser {
 			return trimmed
 		}
 
-		const codeBlockMatch = trimmed.match(/```(?:json)?\s*\n?([\s\S]*?)\n?\s*```/)
+		// `\s*` directly abutting a lazy `[\s\S]*?` (and again on the closing
+		// side) lets the engine split the same run of whitespace between the
+		// two constructs in many equivalent ways, so an unterminated fence
+		// with a long run of blank lines makes matching super-linear. The
+		// trailing `.trim()` below already strips leading/trailing
+		// whitespace, so the fence markers only need to bound the capture,
+		// not pre-trim it.
+		const codeBlockMatch = trimmed.match(/```(?:json)?\n?([\s\S]*?)```/)
 		if (codeBlockMatch?.[1]) {
 			return codeBlockMatch[1].trim()
 		}