@roj-ai/sdk 0.0.2

package/src/core/llm/snapshot-middleware.ts

@@ -0,0 +1,185 @@
+/**
+ * Snapshot-caching LLM middleware for e2e tests.
+ *
+ * Works at the InferenceRequest/InferenceResponse boundary (not HTTP). On a
+ * request hit, returns the cached response without calling the downstream
+ * provider. On a miss, forwards the request, records the response, writes
+ * one snapshot file per request hash.
+ *
+ * Unlike the lower-level `snapshot-fetch` (which writes one file per testName
+ * and overwrites on each call), this middleware keys by request hash — so a
+ * single multi-turn test records N independent snapshots.
+ *
+ * Usage:
+ *   startStandaloneServer({
+ *     presets: [myPreset],
+ *     llmMiddleware: [createSnapshotLLMMiddleware({ snapshotsDir: '...' })],
+ *   })
+ */
+
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { Err, Ok } from '~/lib/utils/result.js'
+import type { LLMMiddleware } from './middleware.js'
+import type { InferenceRequest, InferenceResponse } from './provider.js'
+
+export interface SnapshotLLMMiddlewareOptions {
+	/** Directory where per-request snapshot files are stored. */
+	snapshotsDir: string
+	/**
+	 * - `auto` (default) — replay if snapshot exists, otherwise record.
+	 * - `replay` — fail on miss. Use in CI to catch accidental live calls.
+	 * - `record` — always call next and (over)write the snapshot.
+	 */
+	mode?: 'auto' | 'replay' | 'record'
+	/**
+	 * Transform the request before hashing. Returns a request used only for
+	 * key computation — the original is still sent downstream on cache miss.
+	 *
+	 * Use this to strip run-local data (session IDs, timestamps, random
+	 * workspace paths) that would otherwise prevent snapshots from matching
+	 * across runs. See `stripUuids` for a common default.
+	 */
+	normalize?: (request: InferenceRequest) => InferenceRequest
+}
+
+/**
+ * Replace all UUIDs in a string with a `__UUID__` placeholder.
+ */
+export function stripUuids(text: string): string {
+	return text.replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/g, '__UUID__')
+}
+
+/**
+ * Replace dynamically assigned TCP ports (e.g. `port 46140`, `:46140`) with
+ * a `__PORT__` placeholder. Dev services in roj pick free ports at runtime,
+ * which otherwise bust the snapshot key on every run.
+ */
+export function stripEphemeralPorts(text: string): string {
+	return text
+		.replace(/port\s+(\d{4,5})\b/gi, 'port __PORT__')
+		.replace(/:(1[0-9]{4}|[2-6][0-9]{4})\b/g, ':__PORT__')
+}
+
+/**
+ * Compose multiple text stripping functions.
+ */
+export function composeStrippers(...fns: Array<(text: string) => string>): (text: string) => string {
+	return (text) => fns.reduce((acc, fn) => fn(acc), text)
+}
+
+/**
+ * Build a `normalize` hook that applies a text-level stripper to the system
+ * prompt and all string-form message content / text parts.
+ */
+export function normalizeWith(stripper: (text: string) => string): (request: InferenceRequest) => InferenceRequest {
+	return (request) => ({
+		...request,
+		systemPrompt: stripper(request.systemPrompt),
+		messages: request.messages.map((m) => {
+			if (typeof m.content === 'string') {
+				return { ...m, content: stripper(m.content) }
+			}
+			if (Array.isArray(m.content)) {
+				return {
+					...m,
+					content: m.content.map((part) =>
+						part.type === 'text' ? { ...part, text: stripper(part.text) } : part,
+					),
+				}
+			}
+			return m
+		}) as InferenceRequest['messages'],
+	})
+}
+
+/**
+ * A `normalize` implementation that strips UUIDs from the request text.
+ * Use `normalizeStripRuntime` if dev service ports also leak into prompts.
+ */
+export const normalizeStripUuids = normalizeWith(stripUuids)
+
+/**
+ * `normalize` implementation for typical e2e runs: strips UUIDs and
+ * dynamically-assigned ports. Covers the usual suspects; add your own with
+ * `normalizeWith(composeStrippers(...))` for more.
+ */
+export const normalizeStripRuntime = normalizeWith(composeStrippers(stripUuids, stripEphemeralPorts))
+
+interface SnapshotEntry {
+	request: unknown
+	response: InferenceResponse
+}
+
+function stableStringify(value: unknown): string {
+	return JSON.stringify(value, (_key, val) => {
+		if (val && typeof val === 'object' && !Array.isArray(val)) {
+			return Object.fromEntries(Object.entries(val as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b)))
+		}
+		return val
+	})
+}
+
+/**
+ * Build a stable digest of the request. Strips:
+ *   - tool `input`/`execute` functions + Zod schemas (reduced to name/description)
+ *   - conversation-metadata fields on messages (`timestamp`, `isError`,
+ *     `toolName`, `sourceMessageIds`) — not forwarded to the LLM, so they
+ *     shouldn't bust the snapshot key either.
+ */
+function stripMessageMetadata(message: unknown): unknown {
+	if (!message || typeof message !== 'object') return message
+	const { timestamp: _t, isError: _e, toolName: _n, sourceMessageIds: _s, ...rest } = message as Record<string, unknown>
+	return rest
+}
+
+function buildDigest(request: InferenceRequest): Record<string, unknown> {
+	return {
+		model: String(request.model),
+		systemPrompt: request.systemPrompt,
+		messages: request.messages.map(stripMessageMetadata),
+		tools: request.tools?.map((t) => ({ name: t.name, description: t.description })),
+		maxTokens: request.maxTokens,
+		temperature: request.temperature,
+		stopSequences: request.stopSequences,
+		openrouter: request.openrouter,
+		anthropic: request.anthropic,
+	}
+}
+
+function hashDigest(digest: unknown): string {
+	return createHash('sha256').update(stableStringify(digest)).digest('hex').slice(0, 16)
+}
+
+export function createSnapshotLLMMiddleware(options: SnapshotLLMMiddlewareOptions): LLMMiddleware {
+	const mode = options.mode ?? 'auto'
+	mkdirSync(options.snapshotsDir, { recursive: true })
+
+	return async (request, context, next) => {
+		const forHashing = options.normalize ? options.normalize(request) : request
+		const digest = buildDigest(forHashing)
+		const hash = hashDigest(digest)
+		const filePath = join(options.snapshotsDir, `${hash}.json`)
+		const hasSnapshot = existsSync(filePath)
+
+		if (mode !== 'record' && hasSnapshot) {
+			const entry = JSON.parse(readFileSync(filePath, 'utf-8')) as SnapshotEntry
+			return Ok(entry.response)
+		}
+
+		if (mode === 'replay') {
+			return Err({
+				type: 'invalid_request',
+				message: `Snapshot not found (replay mode): ${hash}. Set mode to 'auto' or 'record' and provide API keys to record.`,
+			})
+		}
+
+		const result = await next(request, context)
+		if (result.ok) {
+			const entry: SnapshotEntry = { request: digest, response: result.value }
+			writeFileSync(filePath, JSON.stringify(entry, null, '\t'))
+		}
+		return result
+	}
+}

package/src/core/llm/state.ts

@@ -0,0 +1,92 @@
+import z4 from 'zod/v4'
+import { agentIdSchema } from '~/core/agents'
+import type { LLMMessage } from '~/core/agents/state'
+import { createEventsFactory } from '~/core/events/types'
+import { toolCallIdSchema } from '~/core/tools/schema'
+import { messageIdSchema } from '~/plugins/mailbox/schema'
+import { llmCallIdSchema } from './schema'
+
+// ============================================================================
+// Supporting types for LLM events
+// ============================================================================
+
+/**
+ * LLM response content - can be text and/or tool calls.
+ */
+export type LLMResponse = {
+	content: string | null
+	toolCalls: LLMToolCall[]
+}
+
+/**
+ * A single tool call from the LLM.
+ */
+export type LLMToolCall = {
+	id: string // ToolCallId
+	name: string
+	input: unknown
+}
+
+/**
+ * Metrics from an LLM inference call.
+ */
+export type LLMMetrics = {
+	promptTokens: number
+	completionTokens: number
+	totalTokens: number
+	latencyMs: number
+	model: string
+	provider?: string
+	cost?: number
+	/** Tokens served from prompt cache (cache read) */
+	cachedTokens?: number
+	/** Tokens written to prompt cache */
+	cacheWriteTokens?: number
+}
+
+// ============================================================================
+// LLM events
+// ============================================================================
+
+export const llmEvents = createEventsFactory({
+	events: {
+		inference_started: z4.object({
+			agentId: agentIdSchema,
+			messages: z4.array(z4.custom<LLMMessage>()),
+			consumedMessageIds: z4.array(messageIdSchema),
+		}),
+		inference_completed: z4.object({
+			agentId: agentIdSchema,
+			consumedMessageIds: z4.array(messageIdSchema),
+			response: z4.object({
+				content: z4.string().nullable(),
+				toolCalls: z4.array(z4.object({
+					id: toolCallIdSchema,
+					name: z4.string(),
+					input: z4.unknown(),
+				})),
+			}),
+			metrics: z4.object({
+				promptTokens: z4.number(),
+				completionTokens: z4.number(),
+				totalTokens: z4.number(),
+				latencyMs: z4.number(),
+				model: z4.string(),
+				provider: z4.string().optional(),
+				cost: z4.number().optional(),
+				cachedTokens: z4.number().optional(),
+				cacheWriteTokens: z4.number().optional(),
+			}),
+			llmCallId: llmCallIdSchema.optional(),
+		}),
+		inference_failed: z4.object({
+			agentId: agentIdSchema,
+			error: z4.string(),
+			llmCallId: llmCallIdSchema.optional(),
+		}),
+	},
+})
+
+export type InferenceStartedEvent = (typeof llmEvents)['Events']['inference_started']
+export type InferenceCompletedEvent = (typeof llmEvents)['Events']['inference_completed']
+export type InferenceFailedEvent = (typeof llmEvents)['Events']['inference_failed']

package/src/core/llm/tokens.ts

@@ -0,0 +1,61 @@
+/**
+ * Token estimation utilities using tokenx library.
+ * Provides ~95-98% accuracy compared to full tokenizers.
+ */
+
+import { estimateTokenCount, sliceByTokens } from 'tokenx'
+
+/**
+ * Estimate token count for a text string.
+ * Uses tokenx library for better accuracy than simple char/4 heuristic.
+ */
+export function estimateTokens(text: string): number {
+	return estimateTokenCount(text)
+}
+
+/**
+ * Message structure for token estimation.
+ */
+export interface TokenEstimationMessage {
+	role: string
+	content: string | unknown
+}
+
+/**
+ * Estimate total tokens for an array of messages.
+ * Includes ~4 tokens overhead per message for role/formatting.
+ */
+export interface TruncationResult {
+	content: string
+	originalTokens: number
+}
+
+/**
+ * Truncate text to fit within a token budget.
+ * Returns null if text is already within budget.
+ * Uses 80/20 head/tail split via sliceByTokens.
+ */
+export function truncateByTokens(text: string, maxTokens: number): TruncationResult | null {
+	const originalTokens = estimateTokenCount(text)
+	// 5% tolerance to avoid truncating near the boundary
+	if (originalTokens <= maxTokens * 1.05) return null
+
+	const headBudget = Math.floor(maxTokens * 0.8)
+	const tailBudget = maxTokens - headBudget
+	const head = sliceByTokens(text, 0, headBudget)
+	const tail = sliceByTokens(text, -tailBudget)
+
+	const content = `${head}\n\n[... truncated — ~${originalTokens} tokens total ...]\n\n${tail}`
+	return { content, originalTokens }
+}
+
+/**
+ * Estimate total tokens for an array of messages.
+ * Includes ~4 tokens overhead per message for role/formatting.
+ */
+export function estimateMessagesTokens(messages: TokenEstimationMessage[]): number {
+	return messages.reduce((sum, msg) => {
+		const content = typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content)
+		return sum + estimateTokens(content) + 4 // 4 tokens overhead per message
+	}, 0)
+}

package/src/core/multi-agent.integration.test.ts

@@ -0,0 +1,340 @@
+import { describe, expect, it } from 'bun:test'
+import { AgentId } from '~/core/agents/schema.js'
+import { agentEvents } from '~/core/agents/state.js'
+import { MockLLMProvider } from '~/core/llm/mock.js'
+import { ToolCallId } from '~/core/tools/schema.js'
+import { createMultiAgentPreset, TestHarness } from '~/testing/index.js'
+
+describe('core: multi-agent flows', () => {
+	it('orchestrator spawns worker → worker processes → sends result to orchestrator → orchestrator continues', async () => {
+		let orchestratorCalls = 0
+		let orchestratorSawResult = false
+
+		let workerCalls = 0
+
+		const harness = new TestHarness({
+			presets: [createMultiAgentPreset([
+				{ name: 'worker', system: 'Worker agent.', tools: [], agents: [] },
+			], { orchestratorSystem: 'Orchestrator agent.' })],
+			mockHandler: (request) => {
+				if (request.systemPrompt.includes('Orchestrator')) {
+					orchestratorCalls++
+					if (orchestratorCalls === 1) {
+						return {
+							content: null,
+							toolCalls: [{ id: ToolCallId('tc1'), name: 'start_worker', input: { message: 'Do work' } }],
+							finishReason: 'stop',
+							metrics: MockLLMProvider.defaultMetrics(),
+						}
+					}
+					// Check if orchestrator received the worker's report
+					const userMessages = request.messages.filter(m => m.role === 'user')
+					if (userMessages.some(m => typeof m.content === 'string' && m.content.includes('Work result: done'))) {
+						orchestratorSawResult = true
+					}
+					return { content: 'All done', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+				}
+				// Worker: send result to parent on first call, finish on second
+				workerCalls++
+				if (workerCalls === 1) {
+					return {
+						content: null,
+						toolCalls: [{ id: ToolCallId('tc2'), name: 'send_message', input: { to: 'parent', message: 'Work result: done' } }],
+						finishReason: 'stop',
+						metrics: MockLLMProvider.defaultMetrics(),
+					}
+				}
+				return { content: 'Worker done', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+			},
+		})
+
+		const session = await harness.createSession('test')
+		await session.sendAndWaitForIdle('Start', { timeoutMs: 10000 })
+
+		expect(orchestratorSawResult).toBe(true)
+
+		// Both agents should be idle
+		const orchState = session.state.agents.get(session.getEntryAgentId()!)!
+		expect(orchState.status).toBe('pending')
+		const workerState = session.state.agents.get(AgentId('worker_1'))!
+		expect(workerState.status).toBe('pending')
+
+		await harness.shutdown()
+	})
+
+	it('orchestrator spawns multiple workers → all process concurrently', async () => {
+		let orchestratorCalls = 0
+		const workerCallCounts = new Map<string, number>()
+
+		const harness = new TestHarness({
+			presets: [createMultiAgentPreset([
+				{ name: 'worker', system: 'Worker agent.', tools: [], agents: [] },
+			], { orchestratorSystem: 'Orchestrator agent.' })],
+			mockHandler: (request) => {
+				if (request.systemPrompt.includes('Orchestrator')) {
+					orchestratorCalls++
+					if (orchestratorCalls === 1) {
+						return {
+							content: null,
+							toolCalls: [
+								{ id: ToolCallId('tc1'), name: 'start_worker', input: { message: 'Task A' } },
+								{ id: ToolCallId('tc2'), name: 'start_worker', input: { message: 'Task B' } },
+								{ id: ToolCallId('tc3'), name: 'start_worker', input: { message: 'Task C' } },
+							],
+							finishReason: 'stop',
+							metrics: MockLLMProvider.defaultMetrics(),
+						}
+					}
+					return { content: 'Done', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+				}
+				// Workers
+				const agentId = request.systemPrompt.includes('Worker') ? 'worker' : 'unknown'
+				workerCallCounts.set(agentId, (workerCallCounts.get(agentId) ?? 0) + 1)
+				return { content: 'Worker done', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+			},
+		})
+
+		const session = await harness.createSession('test')
+		await session.sendAndWaitForIdle('Start', { timeoutMs: 10000 })
+
+		// All three workers should exist
+		expect(session.state.agents.has(AgentId('worker_1'))).toBe(true)
+		expect(session.state.agents.has(AgentId('worker_2'))).toBe(true)
+		expect(session.state.agents.has(AgentId('worker_3'))).toBe(true)
+
+		// All workers should have been called
+		expect(workerCallCounts.get('worker')).toBeGreaterThanOrEqual(3)
+
+		// All workers should be idle
+		for (const id of [AgentId('worker_1'), AgentId('worker_2'), AgentId('worker_3')]) {
+			expect(session.state.agents.get(id)!.status).toBe('pending')
+		}
+
+		await harness.shutdown()
+	})
+
+	it('parent pauses child → child stops, parent notified', async () => {
+		let orchestratorCalls = 0
+
+		const harness = new TestHarness({
+			presets: [createMultiAgentPreset([
+				{ name: 'worker', system: 'Worker agent.', tools: [], agents: [] },
+			], { orchestratorSystem: 'Orchestrator agent.' })],
+			mockHandler: (request) => {
+				if (request.systemPrompt.includes('Orchestrator')) {
+					orchestratorCalls++
+					if (orchestratorCalls === 1) {
+						return {
+							content: null,
+							toolCalls: [{ id: ToolCallId('tc1'), name: 'start_worker', input: { message: 'Work' } }],
+							finishReason: 'stop',
+							metrics: MockLLMProvider.defaultMetrics(),
+						}
+					}
+					return { content: 'Done', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+				}
+				return { content: 'Worker done', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+			},
+		})
+
+		const session = await harness.createSession('test')
+		await session.sendAndWaitForIdle('Start')
+
+		// Pause the child
+		const pauseResult = await session.callPluginMethod('agents.pause', { agentId: 'worker_1' })
+		expect(pauseResult.ok).toBe(true)
+
+		// Child should be paused
+		expect(session.state.agents.get(AgentId('worker_1'))!.status).toBe('paused')
+
+		// agent_paused event emitted
+		const pausedEvents = await session.getEventsByType(agentEvents, 'agent_paused')
+		expect(pausedEvents.some(e => e.agentId === AgentId('worker_1'))).toBe(true)
+
+		await harness.shutdown()
+	})
+
+	it('parent resumes child → child continues', async () => {
+		let orchestratorCalls = 0
+		let workerCalls = 0
+
+		const harness = new TestHarness({
+			presets: [createMultiAgentPreset([
+				{ name: 'worker', system: 'Worker agent.', tools: [], agents: [] },
+			], { orchestratorSystem: 'Orchestrator agent.' })],
+			mockHandler: (request) => {
+				if (request.systemPrompt.includes('Orchestrator')) {
+					orchestratorCalls++
+					if (orchestratorCalls === 1) {
+						return {
+							content: null,
+							toolCalls: [{ id: ToolCallId('tc1'), name: 'start_worker', input: { message: 'Work' } }],
+							finishReason: 'stop',
+							metrics: MockLLMProvider.defaultMetrics(),
+						}
+					}
+					return { content: 'Done', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+				}
+				workerCalls++
+				return { content: 'Worker done', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+			},
+		})
+
+		const session = await harness.createSession('test')
+		await session.sendAndWaitForIdle('Start')
+
+		// Pause
+		const pauseResult = await session.callPluginMethod('agents.pause', { agentId: 'worker_1' })
+		expect(pauseResult.ok).toBe(true)
+		expect(session.state.agents.get(AgentId('worker_1'))!.status).toBe('paused')
+
+		// Resume
+		const resumeResult = await session.callPluginMethod('agents.resume', { agentId: 'worker_1' })
+		expect(resumeResult.ok).toBe(true)
+
+		await session.waitForIdle()
+
+		// Worker should have processed again after resume
+		expect(session.state.agents.get(AgentId('worker_1'))!.status).toBe('pending')
+
+		// agent_resumed event should exist
+		const resumedEvents = await session.getEventsByType(agentEvents, 'agent_resumed')
+		expect(resumedEvents.some(e => e.agentId === AgentId('worker_1'))).toBe(true)
+
+		await harness.shutdown()
+	})
+
+	it('child agent completes → parent receives completion message (if configured)', async () => {
+		let orchestratorCalls = 0
+		let orchestratorSawCompletion = false
+
+		const harness = new TestHarness({
+			presets: [createMultiAgentPreset([
+				{
+					name: 'worker',
+					system: 'Worker agent.',
+					tools: [],
+					agents: [],
+					plugins: [{ pluginName: 'mailbox', config: { sendCompletionMessage: true } }],
+				},
+			], { orchestratorSystem: 'Orchestrator agent.' })],
+			mockHandler: (request) => {
+				if (request.systemPrompt.includes('Orchestrator')) {
+					orchestratorCalls++
+					if (orchestratorCalls === 1) {
+						return {
+							content: null,
+							toolCalls: [{ id: ToolCallId('tc1'), name: 'start_worker', input: { message: 'Work' } }],
+							finishReason: 'stop',
+							metrics: MockLLMProvider.defaultMetrics(),
+						}
+					}
+					// Check if completion message arrived
+					const userMessages = request.messages.filter(m => m.role === 'user')
+					if (userMessages.some(m => typeof m.content === 'string' && m.content.includes('Task completed.'))) {
+						orchestratorSawCompletion = true
+					}
+					return { content: 'Done', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+				}
+				// Worker completes immediately
+				return { content: 'Worker done', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+			},
+		})
+
+		const session = await harness.createSession('test')
+		await session.sendAndWaitForIdle('Start', { timeoutMs: 10000 })
+
+		expect(orchestratorSawCompletion).toBe(true)
+
+		await harness.shutdown()
+	})
+
+	it('deeply nested agents: orch → A → B → B reports to A → A reports to orch', async () => {
+		let orchestratorCalls = 0
+		let workerACalls = 0
+		let workerBCalls = 0
+		let orchestratorSawFinalReport = false
+
+		const harness = new TestHarness({
+			presets: [createMultiAgentPreset([
+				{ name: 'worker_a', system: 'Worker A agent.', tools: [], agents: ['worker_b'] },
+				{ name: 'worker_b', system: 'Worker B agent.', tools: [], agents: [] },
+			], { orchestratorSystem: 'Orchestrator agent.' })],
+			mockHandler: (request) => {
+				if (request.systemPrompt.includes('Orchestrator')) {
+					orchestratorCalls++
+					if (orchestratorCalls === 1) {
+						return {
+							content: null,
+							toolCalls: [{ id: ToolCallId('tc1'), name: 'start_worker_a', input: { message: 'Coordinate' } }],
+							finishReason: 'stop',
+							metrics: MockLLMProvider.defaultMetrics(),
+						}
+					}
+					// Check for final report from A
+					const userMessages = request.messages.filter(m => m.role === 'user')
+					if (userMessages.some(m => typeof m.content === 'string' && m.content.includes('Final report from A'))) {
+						orchestratorSawFinalReport = true
+					}
+					return { content: 'All done', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+				}
+
+				if (request.systemPrompt.includes('Worker A')) {
+					workerACalls++
+					if (workerACalls === 1) {
+						// A spawns B
+						return {
+							content: null,
+							toolCalls: [{ id: ToolCallId('tc2'), name: 'start_worker_b', input: { message: 'Sub-task for B' } }],
+							finishReason: 'stop',
+							metrics: MockLLMProvider.defaultMetrics(),
+						}
+					}
+					// A received report from B, now report to orchestrator
+					const userMessages = request.messages.filter(m => m.role === 'user')
+					if (userMessages.some(m => typeof m.content === 'string' && m.content.includes('B result: success'))) {
+						// Check if we already sent the report (tool result in messages means we did)
+						const toolMessages = request.messages.filter(m => m.role === 'tool')
+						if (toolMessages.length > 0 && workerACalls > 3) {
+							return { content: 'A done', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+						}
+						return {
+							content: null,
+							toolCalls: [{ id: ToolCallId('tc4'), name: 'send_message', input: { to: 'parent', message: 'Final report from A' } }],
+							finishReason: 'stop',
+							metrics: MockLLMProvider.defaultMetrics(),
+						}
+					}
+					return { content: 'A waiting', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+				}
+
+				// Worker B
+				workerBCalls++
+				if (workerBCalls === 1) {
+					// B reports to A
+					return {
+						content: null,
+						toolCalls: [{ id: ToolCallId('tc3'), name: 'send_message', input: { to: 'parent', message: 'B result: success' } }],
+						finishReason: 'stop',
+						metrics: MockLLMProvider.defaultMetrics(),
+					}
+				}
+				return { content: 'B done', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+			},
+		})
+
+		const session = await harness.createSession('test')
+		await session.sendAndWaitForIdle('Start', { timeoutMs: 10000 })
+
+		// Verify hierarchy
+		expect(session.state.agents.has(AgentId('worker_a_1'))).toBe(true)
+		expect(session.state.agents.has(AgentId('worker_b_1'))).toBe(true)
+		expect(session.state.agents.get(AgentId('worker_a_1'))!.parentId).toBe(session.getEntryAgentId()!)
+		expect(session.state.agents.get(AgentId('worker_b_1'))!.parentId).toBe(AgentId('worker_a_1'))
+
+		// Orchestrator received final report from A
+		expect(orchestratorSawFinalReport).toBe(true)
+
+		await harness.shutdown()
+	})
+})