@namzu/sdk 2.0.0 → 3.0.0

package/src/runtime/query/__tests__/answer-review.test.ts

@@ -0,0 +1,172 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { MockLLMProvider, registerMock } from '../../../provider/index.js'
+import { ToolRegistry } from '../../../registry/index.js'
+import type { AnswerReview } from '../../../types/run/answer-review.js'
+import {
+	generateProjectId,
+	generateSessionId,
+	generateTenantId,
+	generateThreadId,
+} from '../../../utils/id.js'
+import { drainQuery } from '../index.js'
+
+/**
+ * The halt predicate is only consulted after tools have run, so there was
+ * no seam at the point the model stops calling them: the run finalized
+ * with whatever it had produced. Verify-then-fix — run the build, feed the
+ * failure back, let it try again — meant starting a whole new run and
+ * re-supplying the context the first one had already assembled.
+ */
+
+registerMock()
+
+function scriptedRun(
+	replies: readonly string[],
+	reviewAnswer: (answer: string) => AnswerReview | Promise<AnswerReview>,
+	maxAnswerReviews?: number,
+) {
+	let turn = 0
+	const provider = new MockLLMProvider({
+		responses: replies.map((content) => ({ content })),
+	} as never)
+	// The mock cycles its scripted replies; the counter is what lets a test
+	// assert how many turns the loop actually took.
+	const original = provider.chatStream.bind(provider)
+	provider.chatStream = ((params: never) => {
+		turn++
+		return original(params)
+	}) as typeof provider.chatStream
+
+	return {
+		turns: () => turn,
+		run: () =>
+			drainQuery({
+				provider,
+				tools: new ToolRegistry(),
+				agentId: 'a',
+				agentName: 'A',
+				messages: [{ role: 'user', content: 'go' }],
+				workingDirectory: process.cwd(),
+				runConfig: { model: 'mock', tokenBudget: 100_000, timeoutMs: 30_000, maxIterations: 10 },
+				projectId: generateProjectId(),
+				sessionId: generateSessionId(),
+				threadId: generateThreadId(),
+				tenantId: generateTenantId(),
+				reviewAnswer: (answer: string) => reviewAnswer(answer),
+				...(maxAnswerReviews !== undefined ? { maxAnswerReviews } : {}),
+			} as never),
+	}
+}
+
+describe('judging the answer a run is about to settle with', () => {
+	it('accepts and settles without an extra turn', async () => {
+		const review = vi.fn(() => ({ accept: true }) as AnswerReview)
+		const scripted = scriptedRun(['the answer'], review)
+
+		await scripted.run()
+
+		expect(review).toHaveBeenCalledTimes(1)
+		expect(scripted.turns()).toBe(1)
+	})
+
+	it('hands a rejected answer back and runs another turn', async () => {
+		// The whole point: the model gets another go WITH the context it
+		// already has, instead of the host starting a fresh run.
+		let calls = 0
+		const scripted = scriptedRun(['first', 'second'], () => {
+			calls++
+			return calls === 1 ? { accept: false, feedback: 'the build fails' } : { accept: true }
+		})
+
+		await scripted.run()
+		expect(scripted.turns()).toBe(2)
+	})
+
+	it('sends the feedback as the next user turn', async () => {
+		let seen: string | undefined
+		let calls = 0
+		const provider = new MockLLMProvider({ responses: [{ content: 'x' }] } as never)
+		const original = provider.chatStream.bind(provider)
+		provider.chatStream = ((params: { messages: { role: string; content: string }[] }) => {
+			const last = params.messages[params.messages.length - 1]
+			if (calls > 0) seen = last?.content
+			calls++
+			return original(params as never)
+		}) as typeof provider.chatStream
+
+		await drainQuery({
+			provider,
+			tools: new ToolRegistry(),
+			agentId: 'a',
+			agentName: 'A',
+			messages: [{ role: 'user', content: 'go' }],
+			workingDirectory: process.cwd(),
+			runConfig: { model: 'mock', tokenBudget: 100_000, timeoutMs: 30_000, maxIterations: 4 },
+			projectId: generateProjectId(),
+			sessionId: generateSessionId(),
+			threadId: generateThreadId(),
+			tenantId: generateTenantId(),
+			reviewAnswer: () =>
+				calls === 1 ? { accept: false, feedback: 'FIX: tests red' } : { accept: true },
+		} as never)
+
+		// Prose, and in the slot the model reads — a code would have to be
+		// explained to it anyway.
+		expect(seen).toBe('FIX: tests red')
+	})
+
+	it('stops with a reason that names the reviewer, not a budget', async () => {
+		// A reviewer that never accepts would otherwise burn the whole token
+		// budget and end on `max_iterations`, sending the reader to look for
+		// a loop instead of at the reviewer.
+		const scripted = scriptedRun(['a'], () => ({ accept: false, feedback: 'no' }), 2)
+		const run = await scripted.run()
+
+		expect(run.stopReason).toBe('answer_rejected')
+	})
+
+	it('spends only the attempts it was given', async () => {
+		const review = vi.fn(() => ({ accept: false, feedback: 'no' }) as AnswerReview)
+		const scripted = scriptedRun(['a'], review, 2)
+		await scripted.run()
+
+		// Two rejections, then the third call is the one that exceeds the
+		// limit and stops the run.
+		expect(review).toHaveBeenCalledTimes(3)
+	})
+
+	it('accepts when the reviewer throws, and does not loop', async () => {
+		// The opposite of what the safety gates do, deliberately. Those are
+		// asked "is this dangerous", where failing closed costs one refused
+		// operation. This is asked "is this good enough", where failing
+		// closed means handing the answer back forever.
+		const scripted = scriptedRun(['a'], () => {
+			throw new Error('reviewer exploded')
+		})
+
+		const run = await scripted.run()
+		expect(run.stopReason).not.toBe('answer_rejected')
+		expect(scripted.turns()).toBe(1)
+	})
+
+	it('is not consulted at all when no reviewer was supplied', async () => {
+		const provider = new MockLLMProvider({ responses: [{ content: 'done' }] } as never)
+		const run = await drainQuery({
+			provider,
+			tools: new ToolRegistry(),
+			agentId: 'a',
+			agentName: 'A',
+			messages: [{ role: 'user', content: 'go' }],
+			workingDirectory: process.cwd(),
+			runConfig: { model: 'mock', tokenBudget: 100_000, timeoutMs: 30_000, maxIterations: 4 },
+			projectId: generateProjectId(),
+			sessionId: generateSessionId(),
+			threadId: generateThreadId(),
+			tenantId: generateTenantId(),
+		} as never)
+
+		// The default path must be byte-identical for every existing caller.
+		expect(run.stopReason).not.toBe('answer_rejected')
+	})
+})

package/src/runtime/query/__tests__/capability-negotiation.test.ts

@@ -8,68 +8,26 @@ import {
 	PERMISSIVE_PROVIDER_CAPABILITIES,
 	resolveProviderCapabilities,
 } from '../../../provider/capabilities.js'
+import { MockLLMProvider } from '../../../provider/mock.js'
 import { ToolRegistry } from '../../../registry/tool/execute.js'
 import type { SessionId, TenantId } from '../../../types/ids/index.js'
 import { createUserMessage } from '../../../types/message/index.js'
-import type {
-	ChatCompletionParams,
-	LLMProvider,
-	ProviderCapabilities,
-	StreamChunk,
-} from '../../../types/provider/index.js'
+import type { LLMProvider, ProviderCapabilities } from '../../../types/provider/index.js'
 import type { RunEvent } from '../../../types/run/index.js'
 import type { ProjectId, ThreadId } from '../../../types/session/ids.js'
 import { drainQuery } from '../index.js'
 
-const ZERO_USAGE = {
-	promptTokens: 0,
-	completionTokens: 0,
-	totalTokens: 0,
-	cachedTokens: 0,
-	cacheWriteTokens: 0,
-}
-
-class CapturingProvider implements LLMProvider {
-	readonly id = 'capturing'
-	readonly name = 'Capturing Provider'
-	readonly capabilities?: ProviderCapabilities
-	lastParams?: ChatCompletionParams
-
-	constructor(capabilities?: ProviderCapabilities) {
-		this.capabilities = capabilities
-	}
-
-	async *chatStream(params: ChatCompletionParams): AsyncIterable<StreamChunk> {
-		this.lastParams = params
-		yield { id: 'msg_1', delta: { content: 'done' } }
-		yield { id: 'msg_1', delta: {}, finishReason: 'stop', usage: ZERO_USAGE }
-	}
-}
-
-class ClosingSummaryProvider implements LLMProvider {
-	readonly id = 'closing-summary'
-	readonly name = 'Closing Summary Provider'
-	readonly calls: ChatCompletionParams[] = []
-
-	async *chatStream(params: ChatCompletionParams): AsyncIterable<StreamChunk> {
-		this.calls.push(params)
-		if (this.calls.length === 1) {
-			yield {
-				id: 'msg_empty',
-				delta: {},
-				finishReason: 'stop',
-				usage: ZERO_USAGE,
-			}
-			return
-		}
-		yield { id: 'msg_summary', delta: { content: 'closing summary' } }
-		yield {
-			id: 'msg_summary',
-			delta: {},
-			finishReason: 'stop',
-			usage: ZERO_USAGE,
-		}
-	}
+/**
+ * The scriptable mock captures every request and now accepts a capability
+ * override, which is the whole reason this suite had a bespoke class: a
+ * fixed registry-level declaration cannot express "a driver with no
+ * vision".
+ */
+function capturingProvider(capabilities?: ProviderCapabilities): MockLLMProvider {
+	return new MockLLMProvider({
+		turns: [{ text: 'done' }],
+		...(capabilities ? { capabilities } : {}),
+	})
 }
 
 const NO_TOOLS_CAPABILITIES: ProviderCapabilities = {
@@ -95,25 +53,6 @@ function registerEchoTool(tools: ToolRegistry): void {
 	})
 }
 
-function registerEnforcedTool(tools: ToolRegistry, name: string): void {
-	tools.register({
-		name,
-		description: `${name} tool`,
-		inputSchema: z.object({
-			new_string: z.string().optional(),
-			newStr: z.string().optional(),
-		}),
-		modelInputSchema: {
-			type: 'object',
-			properties: { new_string: { type: 'string' } },
-			required: ['new_string'],
-			additionalProperties: false,
-		},
-		enforceModelInput: true,
-		execute: async () => ({ success: true, output: 'ok' }),
-	})
-}
-
 function baseParams(provider: LLMProvider, tools: ToolRegistry, workingDirectory: string) {
 	return {
 		provider,
@@ -137,7 +76,7 @@ function baseParams(provider: LLMProvider, tools: ToolRegistry, workingDirectory
 
 describe('resolveProviderCapabilities', () => {
 	it('resolves an undeclared provider to the permissive default', () => {
-		expect(resolveProviderCapabilities(new CapturingProvider())).toEqual(
+		expect(resolveProviderCapabilities(capturingProvider())).toEqual(
 			PERMISSIVE_PROVIDER_CAPABILITIES,
 		)
 	})
@@ -170,7 +109,7 @@ describe('query() capability negotiation', () => {
 	}
 
 	it('strips tool surfaces and emits a capability_warning for a no-tools provider', async () => {
-		const provider = new CapturingProvider(NO_TOOLS_CAPABILITIES)
+		const provider = capturingProvider(NO_TOOLS_CAPABILITIES)
 		const tools = new ToolRegistry()
 		registerEchoTool(tools)
 		const events: RunEvent[] = []
@@ -188,9 +127,9 @@ describe('query() capability negotiation', () => {
 		expect(run.status).toBe('completed')
 
 		// The model was never told about tools: no tools param on the wire…
-		expect(provider.lastParams?.tools).toBeUndefined()
+		expect(provider.requests.at(-1)?.tools).toBeUndefined()
 		// …and no tool section in the system prompt.
-		const systemPrompt = (provider.lastParams?.messages ?? [])
+		const systemPrompt = (provider.requests.at(-1)?.messages ?? [])
 			.filter((m) => m.role === 'system')
 			.map((m) => m.content)
 			.join('\n')
@@ -203,12 +142,12 @@ describe('query() capability negotiation', () => {
 				e.type === 'capability_warning',
 		)
 		expect(warning?.capability).toBe('tools')
-		expect(warning?.providerId).toBe('capturing')
+		expect(warning?.providerId).toBe(provider.id)
 		expect(warning?.message).toContain('stripped')
 	})
 
 	it('keeps tool surfaces intact for an undeclared (permissive-default) provider', async () => {
-		const provider = new CapturingProvider()
+		const provider = capturingProvider()
 		const tools = new ToolRegistry()
 		registerEchoTool(tools)
 
@@ -218,54 +157,11 @@ describe('query() capability negotiation', () => {
 		})
 
 		expect(run.status).toBe('completed')
-		expect(provider.lastParams?.tools?.map((t) => t.function.name)).toContain('echo')
-	})
-
-	it('propagates enforcement names from the exact allowed and cache-stable tool schemas', async () => {
-		const provider = new CapturingProvider()
-		const tools = new ToolRegistry()
-		registerEnforcedTool(tools, 'edit')
-		registerEnforcedTool(tools, 'cached_edit')
-		registerEnforcedTool(tools, 'excluded_edit')
-		tools.suspendAll()
-		tools.activate(['edit'])
-
-		const run = await drainQuery({
-			...baseParams(provider, tools, await mkWorkdir()),
-			allowedTools: ['edit', 'cached_edit'],
-			messages: [createUserMessage('hello')],
-		})
-
-		expect(run.status).toBe('completed')
-		expect(provider.lastParams?.tools?.map((tool) => tool.function.name)).toEqual([
-			'edit',
-			'cached_edit',
-		])
-		expect(provider.lastParams?.enforceToolInputSchema).toEqual(['edit', 'cached_edit'])
-		expect(JSON.stringify(provider.lastParams?.tools)).not.toContain('newStr')
-	})
-
-	it('keeps the same enforcement hint on the closing-summary provider call', async () => {
-		const provider = new ClosingSummaryProvider()
-		const tools = new ToolRegistry()
-		registerEnforcedTool(tools, 'edit')
-
-		const run = await drainQuery({
-			...baseParams(provider, tools, await mkWorkdir()),
-			messages: [createUserMessage('hello')],
-		})
-
-		expect(run.status).toBe('completed')
-		expect(provider.calls).toHaveLength(2)
-		for (const call of provider.calls) {
-			expect(call.tools?.map((tool) => tool.function.name)).toEqual(['edit'])
-			expect(call.enforceToolInputSchema).toEqual(['edit'])
-		}
-		expect(provider.calls[1]?.toolChoice).toBe('none')
+		expect(provider.requests.at(-1)?.tools?.map((t) => t.function.name)).toContain('echo')
 	})
 
 	it('emits a vision capability_warning when attachments hit a no-vision provider', async () => {
-		const provider = new CapturingProvider(NO_VISION_CAPABILITIES)
+		const provider = capturingProvider(NO_VISION_CAPABILITIES)
 		const events: RunEvent[] = []
 
 		const run = await drainQuery(
@@ -288,11 +184,11 @@ describe('query() capability negotiation', () => {
 				e.type === 'capability_warning',
 		)
 		expect(warning?.capability).toBe('vision')
-		expect(warning?.providerId).toBe('capturing')
+		expect(warning?.providerId).toBe(provider.id)
 	})
 
 	it('does not warn when no attachments are present on a no-vision provider', async () => {
-		const provider = new CapturingProvider(NO_VISION_CAPABILITIES)
+		const provider = capturingProvider(NO_VISION_CAPABILITIES)
 		const events: RunEvent[] = []
 
 		await drainQuery(
@@ -309,7 +205,7 @@ describe('query() capability negotiation', () => {
 	})
 
 	it('strictCapabilities: true throws on a tools mismatch instead of degrading', async () => {
-		const provider = new CapturingProvider(NO_TOOLS_CAPABILITIES)
+		const provider = capturingProvider(NO_TOOLS_CAPABILITIES)
 		const tools = new ToolRegistry()
 		registerEchoTool(tools)
 
@@ -323,7 +219,7 @@ describe('query() capability negotiation', () => {
 	})
 
 	it('strictCapabilities: true throws on a vision mismatch instead of degrading', async () => {
-		const provider = new CapturingProvider(NO_VISION_CAPABILITIES)
+		const provider = capturingProvider(NO_VISION_CAPABILITIES)
 
 		await expect(
 			drainQuery({

package/src/runtime/query/__tests__/checkpoint-store.test.ts

@@ -5,11 +5,11 @@ import { afterEach, describe, expect, it } from 'vitest'
 import { z } from 'zod'
 
 import type { RunPersistence } from '../../../manager/run/persistence.js'
+import { MockLLMProvider } from '../../../provider/mock.js'
 import { ToolRegistry } from '../../../registry/tool/execute.js'
 import type { CheckpointId, IterationCheckpoint } from '../../../types/hitl/index.js'
 import type { RunId, SessionId, TenantId } from '../../../types/ids/index.js'
 import { createUserMessage } from '../../../types/message/index.js'
-import type { LLMProvider, StreamChunk } from '../../../types/provider/index.js'
 import type { CheckpointRunScope, CheckpointStore } from '../../../types/run/checkpoint-store.js'
 import type { RunEvent } from '../../../types/run/index.js'
 import type { ProjectId, ThreadId } from '../../../types/session/ids.js'
@@ -18,14 +18,6 @@ import { drainQuery } from '../index.js'
 import { runIterationCheckpoint } from '../iteration/phases/checkpoint.js'
 import type { IterationContext } from '../iteration/phases/context.js'
 
-const ZERO_USAGE = {
-	promptTokens: 0,
-	completionTokens: 0,
-	totalTokens: 0,
-	cachedTokens: 0,
-	cacheWriteTokens: 0,
-}
-
 const ZERO_COST = {
 	inputCostPer1M: 0,
 	outputCostPer1M: 0,
@@ -83,6 +75,14 @@ class InMemoryCheckpointStore implements CheckpointStore {
 	}
 }
 
+const ZERO_USAGE = {
+	promptTokens: 0,
+	completionTokens: 0,
+	totalTokens: 0,
+	cachedTokens: 0,
+	cacheWriteTokens: 0,
+}
+
 function makeRunMgrStub(): RunPersistence {
 	return {
 		id: SCOPE.runId,
@@ -226,46 +226,6 @@ describe('iteration checkpoint cadence (checkpointEvery)', () => {
 
 // ─── query()-level injection ─────────────────────────────────────────────────
 
-class OneToolCallProvider implements LLMProvider {
-	readonly id = 'one-tool-call'
-	readonly name = 'One Tool Call Provider'
-	calls = 0
-
-	async *chatStream(): AsyncIterable<StreamChunk> {
-		this.calls += 1
-
-		if (this.calls === 1) {
-			yield {
-				id: 'msg_1',
-				delta: {
-					toolCalls: [
-						{
-							index: 0,
-							id: 'toolu_echo_1',
-							type: 'function',
-							function: { name: 'echo', arguments: '{"text":"hi"}' },
-						},
-					],
-				},
-			}
-			yield {
-				id: 'msg_1',
-				delta: { toolCallEnd: { index: 0, id: 'toolu_echo_1' } },
-			}
-			yield {
-				id: 'msg_1',
-				delta: {},
-				finishReason: 'tool_calls',
-				usage: ZERO_USAGE,
-			}
-			return
-		}
-
-		yield { id: 'msg_2', delta: { content: 'done' } }
-		yield { id: 'msg_2', delta: {}, finishReason: 'stop', usage: ZERO_USAGE }
-	}
-}
-
 describe('query() with an injected checkpointStore', () => {
 	let workdirs: string[] = []
 
@@ -275,7 +235,10 @@ describe('query() with an injected checkpointStore', () => {
 	})
 
 	it('persists iteration checkpoints into the injected store, keyed by run scope', async () => {
-		const provider = new OneToolCallProvider()
+		// One tool call, then a closing text turn.
+		const provider = new MockLLMProvider({
+			turns: [{ toolCalls: [{ name: 'echo', args: { text: 'hi' } }] }, { text: 'done' }],
+		})
 		const store = new InMemoryCheckpointStore()
 		const tools = new ToolRegistry()
 		tools.register({

package/src/runtime/query/__tests__/checkpoint.test.ts

@@ -95,19 +95,13 @@ describe('CheckpointManager.listEntries', () => {
 
 	it('does not include full checkpoint payload fields', async () => {
 		const mgr = new CheckpointManager(
-			makeStoreStub([
-				makeCheckpoint({
-					toolResultHashes: { call_x: 'hash' },
-					branchStack: [{ agentId: 'a', decision: 'd', confidence: 1, timestamp: 0 }],
-				}),
-			]),
+			makeStoreStub([makeCheckpoint({ toolResultHashes: { call_x: 'hash' } })]),
 			TEST_SCOPE,
 		)
 		const [entry] = await mgr.listEntries()
 		expect(entry).not.toHaveProperty('tokenUsage')
 		expect(entry).not.toHaveProperty('costInfo')
 		expect(entry).not.toHaveProperty('toolResultHashes')
-		expect(entry).not.toHaveProperty('branchStack')
 		expect(entry).not.toHaveProperty('guardState')
 		expect(entry).not.toHaveProperty('messages')
 	})
@@ -169,10 +163,8 @@ describe('projectEmergencyToCheckpoint', () => {
 		expect(cp.guardState.elapsedMs).toBe(0)
 	})
 
-	it('leaves optional fields (toolResultHashes, branchStack, activeNode) unset', () => {
+	it('leaves the optional tool-result hashes unset', () => {
 		const cp = projectEmergencyToCheckpoint(makeEmergencyDump())
 		expect(cp.toolResultHashes).toBeUndefined()
-		expect(cp.branchStack).toBeUndefined()
-		expect(cp.activeNode).toBeUndefined()
 	})
 })

package/src/runtime/query/__tests__/citations.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it } from 'vitest'
+
+import { MockLLMProvider, registerMock } from '../../../provider/index.js'
+import { ToolRegistry } from '../../../registry/index.js'
+import type { Citation } from '../../../types/message/index.js'
+import type { ChatCompletionParams } from '../../../types/provider/index.js'
+import {
+	generateProjectId,
+	generateSessionId,
+	generateTenantId,
+	generateThreadId,
+} from '../../../utils/id.js'
+import { drainQuery } from '../index.js'
+
+/**
+ * Sending a document buys the provider's native handling of it — page
+ * structure, OCR, and the ability to say WHICH passage an answer rests
+ * on. namzu could send the document and could not receive the third, so
+ * an answer about a contract arrived as prose and checking it meant
+ * reading the contract again by hand.
+ */
+
+registerMock()
+
+const PDF = {
+	type: 'document' as const,
+	data: 'JVBERi0xLjQK',
+	mediaType: 'application/pdf',
+	name: 'contract.pdf',
+	citations: true,
+}
+
+const CITED: Citation = {
+	citedText: 'Either party may terminate on thirty days notice.',
+	documentIndex: 0,
+	documentTitle: 'contract.pdf',
+	location: { kind: 'page', start: 4, end: 4 },
+}
+
+function run(opts: { citations?: Citation[] } = {}) {
+	const provider = new MockLLMProvider({
+		turns: [
+			{
+				text: 'Either side can walk away with a month of warning.',
+				...(opts.citations ? { citations: opts.citations } : {}),
+			},
+		],
+	})
+
+	const settled = drainQuery({
+		provider,
+		tools: new ToolRegistry(),
+		agentId: 'a',
+		agentName: 'A',
+		messages: [{ role: 'user', content: 'can we terminate early?', attachments: [PDF] }],
+		workingDirectory: process.cwd(),
+		runConfig: { model: 'mock', tokenBudget: 100_000, timeoutMs: 30_000, maxIterations: 2 },
+		projectId: generateProjectId(),
+		sessionId: generateSessionId(),
+		threadId: generateThreadId(),
+		tenantId: generateTenantId(),
+	} as never)
+
+	return { settled, requests: provider.requests as ChatCompletionParams[] }
+}
+
+const assistantOf = (messages: readonly { role: string }[]) =>
+	messages.find((m) => m.role === 'assistant') as { citations?: readonly Citation[] } | undefined
+
+describe('a passage the model cited', () => {
+	it('lands on the assistant turn, not in its text', async () => {
+		const { settled } = run({ citations: [CITED] })
+		const settledRun = await settled
+
+		// The text is what a human reads; the citation is what a checker
+		// follows. Splicing markers into the prose would trade one for the
+		// other.
+		expect(settledRun.result).not.toContain('page 4')
+		expect(assistantOf(settledRun.messages)?.citations).toEqual([CITED])
+	})
+
+	it('is absent, not empty, when the model cited nothing', async () => {
+		const { settled } = run()
+
+		expect(assistantOf((await settled).messages)?.citations).toBeUndefined()
+	})
+
+	it('keeps every citation the model made, in order', async () => {
+		const second: Citation = {
+			citedText: 'Notice must be in writing.',
+			documentIndex: 0,
+			location: { kind: 'page', start: 5, end: 5 },
+		}
+		const { settled } = run({ citations: [CITED, second] })
+
+		// Evidence, so it is collected verbatim: reordering or de-duplicating
+		// would edit the record the reader checks against.
+		expect(assistantOf((await settled).messages)?.citations).toEqual([CITED, second])
+	})
+
+	it('carries the request opt-in through to the driver', async () => {
+		const { settled, requests } = run()
+		await settled
+
+		const sent = requests[0]?.messages.find((m) => m.role === 'user') as {
+			attachments?: { citations?: boolean }[]
+		}
+		// A driver cannot ask for citations the request never enabled.
+		expect(sent?.attachments?.[0]?.citations).toBe(true)
+	})
+})