@namzu/sdk 2.0.0 → 3.0.0

package/src/runtime/query/__tests__/content-budget.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from 'vitest'
+
+import { describeDroppedContent, measureContentBytes } from '../tool-output-budget.js'
+
+/**
+ * The output budget takes `output: string` only, so the rich channel was
+ * never bounded — an image block of any size passed untouched on the turn
+ * that produced it, and that is the single largest payload a tool result
+ * can carry.
+ *
+ * Worse than uncontrolled cost: when the TEXT half truncated, the rich
+ * half was dropped with it, silently. Dropping is correct — the preview is
+ * no longer the tool's own payload, so an image alongside it would be
+ * illustrating something the model can no longer read — but the model saw
+ * a preview and had no way to know an image had ever existed, so it
+ * reasoned as though the tool returned text only.
+ */
+
+describe('naming what a truncated result took with it', () => {
+	it('says what kind of block went, and how many', () => {
+		const text = describeDroppedContent([
+			{ type: 'text', text: 'summary' },
+			{ type: 'image', data: 'aGk=' },
+			{ type: 'image', data: 'aGk=' },
+		])
+
+		expect(text).toContain('2 image blocks')
+		// A fact the agent can act on — ask for a smaller region, re-run
+		// against a file — where silence looks like a text-only tool.
+		expect(text).toContain('omitted')
+	})
+
+	it('uses the singular for one block', () => {
+		expect(describeDroppedContent([{ type: 'image', data: 'x' }])).toContain('1 image')
+	})
+
+	it('says nothing when there was only text to lose', () => {
+		// The ordinary case must add no noise.
+		expect(describeDroppedContent([{ type: 'text', text: 'a' }])).toBeUndefined()
+	})
+
+	it('says nothing for a result with no rich channel at all', () => {
+		expect(describeDroppedContent(undefined)).toBeUndefined()
+		expect(describeDroppedContent('just a string')).toBeUndefined()
+	})
+
+	it('names an unfamiliar block kind rather than skipping it', () => {
+		// An unknown block is still something the model cannot see.
+		expect(describeDroppedContent([{ type: 'chart', data: 'x' }])).toContain('chart')
+	})
+
+	it('counts a block with no type at all', () => {
+		expect(describeDroppedContent([{ data: 'x' }])).toContain('content')
+	})
+})
+
+describe('measuring the rich channel', () => {
+	it('measures the payload, not the block count', () => {
+		// One block is the whole cost: a single screenshot is the largest
+		// thing a tool result can carry.
+		expect(measureContentBytes([{ type: 'image', data: 'x'.repeat(500) }])).toBe(500)
+	})
+
+	it('adds every block together', () => {
+		expect(
+			measureContentBytes([
+				{ type: 'text', text: 'ab' },
+				{ type: 'image', data: 'xyz' },
+			]),
+		).toBe(5)
+	})
+
+	it('is zero for a result with no rich channel', () => {
+		expect(measureContentBytes(undefined)).toBe(0)
+		expect(measureContentBytes([])).toBe(0)
+	})
+
+	it('ignores a block whose payload is not a string', () => {
+		// A malformed block contributes no measurable size rather than
+		// throwing inside a budget check.
+		expect(measureContentBytes([{ type: 'image', data: { buffer: [] } }])).toBe(0)
+	})
+})

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

@@ -1,5 +1,6 @@
 import { describe, expect, it, vi } from 'vitest'
 import { DefaultPathBuilder, type PathBuilder } from '../../../session/workspace/path-builder.js'
+import { posix } from '../../../test-support/paths.js'
 import type { RunId, SessionId, TenantId } from '../../../types/ids/index.js'
 import type { LLMProvider } from '../../../types/provider/index.js'
 import type { AgentRunConfig } from '../../../types/run/index.js'
@@ -74,7 +75,7 @@ describe('RunContextFactory.build', () => {
 		const ctx = RunContextFactory.build(cfg)
 
 		// Layout lives under projects/{pid}/sessions/{sid} — no `.namzu/threads/`.
-		expect(ctx.outputDir).toContain('/.namzu/projects/prj_test/sessions/ses_test')
+		expect(posix(ctx.outputDir)).toContain('/.namzu/projects/prj_test/sessions/ses_test')
 		expect(ctx.outputDir).not.toContain('threads')
 	})
 
@@ -97,6 +98,6 @@ describe('RunContextFactory.build', () => {
 	it('DefaultPathBuilder lays out runs under sessions/{sessionId}/runs', () => {
 		const builder = new DefaultPathBuilder('/base/.namzu')
 		const runDir = builder.runDir('prj_x' as ProjectId, 'ses_y' as SessionId, 'run_z' as RunId)
-		expect(runDir).toBe('/base/.namzu/projects/prj_x/sessions/ses_y/runs/run_z')
+		expect(posix(runDir)).toBe('/base/.namzu/projects/prj_x/sessions/ses_y/runs/run_z')
 	})
 })

package/src/runtime/query/__tests__/deferred-tools.test.ts

@@ -4,96 +4,22 @@ import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
 import { z } from 'zod'
 
+import { MockLLMProvider } from '../../../provider/mock.js'
 import { ToolRegistry } from '../../../registry/tool/execute.js'
 import { SearchToolsTool } from '../../../tools/builtins/search-tools.js'
 import type { RunId, SessionId, TenantId } from '../../../types/ids/index.js'
 import { createUserMessage } from '../../../types/message/index.js'
-import type {
-	ChatCompletionParams,
-	LLMProvider,
-	StreamChunk,
-} from '../../../types/provider/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'
-	lastParams?: ChatCompletionParams
-
-	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 DeferredActivationProvider implements LLMProvider {
-	readonly id = 'deferred-activation'
-	readonly name = 'Deferred Activation Provider'
-	readonly calls: ChatCompletionParams[] = []
-
-	async *chatStream(params: ChatCompletionParams): AsyncIterable<StreamChunk> {
-		this.calls.push(params)
-		if (this.calls.length === 1) {
-			yield {
-				id: 'msg_search',
-				delta: {
-					toolCalls: [
-						{
-							index: 0,
-							id: 'toolu_search',
-							type: 'function',
-							function: { name: SearchToolsTool.name },
-						},
-					],
-				},
-			}
-			yield {
-				id: 'msg_search',
-				delta: {
-					toolCalls: [
-						{
-							index: 0,
-							id: 'toolu_search',
-							function: { arguments: '{"query":"canonical_key"}' },
-						},
-					],
-				},
-			}
-			yield {
-				id: 'msg_search',
-				delta: {},
-				finishReason: 'tool_calls',
-				usage: ZERO_USAGE,
-			}
-			return
-		}
-
-		yield { id: 'msg_done', delta: { content: 'done' } }
-		yield {
-			id: 'msg_done',
-			delta: {},
-			finishReason: 'stop',
-			usage: ZERO_USAGE,
-		}
-	}
+/**
+ * The scriptable mock captures every request it receives, which is all
+ * this suite ever needed a hand-rolled provider for. Keeping a bespoke
+ * class here would mean re-implementing the frame sequence by hand — the
+ * exact duplication the mock was rebuilt to remove.
+ */
+function capturingProvider(): MockLLMProvider {
+	return new MockLLMProvider({ turns: [{ text: 'done' }] })
 }
 
 function registerDeferredDocumentTool(tools: ToolRegistry, name = 'generate_document'): void {
@@ -119,7 +45,7 @@ describe('query deferred tool discovery', () => {
 	})
 
 	it('auto-exposes search_tools when deferred tools are registered', async () => {
-		const provider = new CapturingProvider()
+		const provider = capturingProvider()
 		const tools = new ToolRegistry()
 		registerDeferredDocumentTool(tools)
 
@@ -151,10 +77,14 @@ describe('query deferred tool discovery', () => {
 		expect(tools.getAvailability(SearchToolsTool.name)).toBe('active')
 		expect(tools.getAvailability('generate_document')).toBe('deferred')
 
-		const toolNames = provider.lastParams?.tools?.map((tool) => tool.function.name).sort() ?? []
+		const toolNames =
+			provider.requests
+				.at(-1)
+				?.tools?.map((tool) => tool.function.name)
+				.sort() ?? []
 		expect(toolNames).toEqual([SearchToolsTool.name])
 
-		const systemPrompt = (provider.lastParams?.messages ?? [])
+		const systemPrompt = (provider.requests.at(-1)?.messages ?? [])
 			.filter((message) => message.role === 'system')
 			.map((message) => message.content)
 			.join('\n')
@@ -166,7 +96,7 @@ describe('query deferred tool discovery', () => {
 	})
 
 	it('keeps search_tools executable when allowedTools names a deferred tool', async () => {
-		const provider = new CapturingProvider()
+		const provider = capturingProvider()
 		const tools = new ToolRegistry()
 		registerDeferredDocumentTool(tools)
 
@@ -197,10 +127,14 @@ describe('query deferred tool discovery', () => {
 		expect(run.status).toBe('completed')
 		expect(tools.getAvailability('generate_document')).toBe('deferred')
 
-		const toolNames = provider.lastParams?.tools?.map((tool) => tool.function.name).sort() ?? []
+		const toolNames =
+			provider.requests
+				.at(-1)
+				?.tools?.map((tool) => tool.function.name)
+				.sort() ?? []
 		expect(toolNames).toEqual([SearchToolsTool.name])
 
-		const systemPrompt = (provider.lastParams?.messages ?? [])
+		const systemPrompt = (provider.requests.at(-1)?.messages ?? [])
 			.filter((message) => message.role === 'system')
 			.map((message) => message.content)
 			.join('\n')
@@ -208,65 +142,6 @@ describe('query deferred tool discovery', () => {
 		expect(systemPrompt).toContain('- generate_document')
 	})
 
-	it('adds enforcement only after a deferred model-schema tool is activated', async () => {
-		const provider = new DeferredActivationProvider()
-		const tools = new ToolRegistry()
-		tools.register(
-			{
-				name: 'deferred_edit',
-				description: 'Mutate a document using the provided content.',
-				inputSchema: z.object({ legacyKey: z.string() }),
-				modelInputSchema: {
-					type: 'object',
-					properties: { canonical_key: { type: 'string' } },
-					required: ['canonical_key'],
-					additionalProperties: false,
-				},
-				enforceModelInput: true,
-				execute: async () => ({ success: true, output: 'edited' }),
-			},
-			'deferred',
-		)
-
-		const workingDirectory = await mkdtemp(join(tmpdir(), 'namzu-deferred-enforcement-'))
-		workdirs.push(workingDirectory)
-		const run = await drainQuery({
-			provider,
-			tools,
-			allowedTools: ['deferred_edit'],
-			runConfig: {
-				model: 'mock-model',
-				timeoutMs: 5_000,
-				tokenBudget: 100_000,
-				maxIterations: 3,
-				maxResponseTokens: 256,
-			},
-			agentId: 'agent_test',
-			agentName: 'Test Agent',
-			messages: [createUserMessage('find and load the right tool')],
-			workingDirectory,
-			sessionId: 'ses_deferred_enforcement' as SessionId,
-			threadId: 'thd_deferred_enforcement' as ThreadId,
-			projectId: 'prj_deferred_enforcement' as ProjectId,
-			tenantId: 'tnt_deferred_enforcement' as TenantId,
-		})
-
-		expect(run.status).toBe('completed')
-		expect(provider.calls).toHaveLength(2)
-		expect(provider.calls[0]?.tools?.map((tool) => tool.function.name)).toEqual([
-			SearchToolsTool.name,
-		])
-		expect(provider.calls[0]?.enforceToolInputSchema).toBeUndefined()
-		expect(provider.calls[1]?.tools?.map((tool) => tool.function.name)).toEqual([
-			'deferred_edit',
-			SearchToolsTool.name,
-		])
-		expect(provider.calls[1]?.enforceToolInputSchema).toEqual(['deferred_edit'])
-		expect(provider.calls[1]?.tools?.[0]?.function.parameters).toEqual(
-			tools.get('deferred_edit')?.modelInputSchema,
-		)
-	})
-
 	it('does not let search_tools reveal or activate deferred tools outside allowedTools', async () => {
 		const tools = new ToolRegistry()
 		registerDeferredDocumentTool(tools)

package/src/runtime/query/__tests__/delegation-resume.test.ts

@@ -0,0 +1,159 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { RunDiskStore } from '../../../store/run/disk.js'
+import type { CheckpointId, IterationCheckpoint } from '../../../types/hitl/index.js'
+import type { RunId } from '../../../types/ids/index.js'
+import { createAssistantMessage, createUserMessage } from '../../../types/message/index.js'
+import type { Message } from '../../../types/message/index.js'
+import type { Logger } from '../../../utils/logger.js'
+import { planCrashResume, recoverCompletedCalls } from '../resume-pending.js'
+
+/**
+ * A fan-out that crashes part-way through must not re-run the workers that
+ * already finished — for a worker with a side effect, a write or an
+ * outbound message, "run it again" is "do it twice".
+ *
+ * The claim under test is that this is ALREADY covered, and by a general
+ * mechanism rather than a delegation-specific one. Delegation here is
+ * blocking: the tool awaits its worker and returns that worker's output as
+ * its own `tool_result`. So a delegation is an ordinary tool call, its
+ * completion is recorded as an ordinary `tool_completed`, and the
+ * crash-resume path that answers already-executed tool calls from the
+ * transcript answers delegations too.
+ *
+ * These tests exist because that is a load-bearing consequence of an
+ * unrelated design choice, and nothing pinned it. If delegation ever stops
+ * blocking, they fail — which is exactly when somebody needs to know.
+ */
+
+const RID = 'run_1' as RunId
+
+function makeLogger(): Logger {
+	const self = { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() } as unknown as Logger
+	;(self as { child: (ctx: unknown) => Logger }).child = vi.fn(() => self)
+	return self
+}
+
+const delegation = (id: string, agent: string) => ({
+	id,
+	type: 'function' as const,
+	function: { name: 'create_task', arguments: JSON.stringify({ agent_id: agent }) },
+})
+
+/** A five-worker fan-out: one assistant turn, five delegation blocks. */
+const fanOut = (): Message[] => [
+	createUserMessage('fan out to five specialists'),
+	{
+		...createAssistantMessage(''),
+		toolCalls: [
+			delegation('w1', 'writer'),
+			delegation('w2', 'auditor'),
+			delegation('w3', 'billing'),
+			delegation('w4', 'mailer'),
+			delegation('w5', 'reporter'),
+		],
+	} as Message,
+]
+
+describe('a fan-out interrupted part-way through', () => {
+	let dir: string
+	let store: RunDiskStore
+
+	beforeEach(async () => {
+		dir = await mkdtemp(join(tmpdir(), 'namzu-fanout-'))
+		store = new RunDiskStore({ baseDir: dir })
+		await store.initRun(RID)
+	})
+
+	afterEach(async () => {
+		await rm(dir, { recursive: true, force: true })
+	})
+
+	const recordCompletions = async (ids: readonly string[]) => {
+		const lines = ids.map((id) =>
+			JSON.stringify({
+				type: 'tool_completed',
+				toolUseId: id,
+				toolName: 'create_task',
+				result: `${id} finished its work`,
+				isError: false,
+			}),
+		)
+		await writeFile(join(dir, RID, 'transcript.jsonl'), `${lines.join('\n')}\n`, 'utf-8')
+	}
+
+	it('recovers the workers that already finished', async () => {
+		await recordCompletions(['w1', 'w2', 'w3'])
+
+		const runMgr = { getRunStore: () => store } as never
+		const recovered = await recoverCompletedCalls(
+			runMgr,
+			(fanOut()[1] as { toolCalls: { id: string }[] }).toolCalls as never,
+			makeLogger(),
+		)
+
+		// Three workers are answered from the record. The billing worker in
+		// particular does not charge a second time.
+		expect([...recovered.keys()].sort()).toEqual(['w1', 'w2', 'w3'])
+		expect(recovered.get('w3')?.result).toContain('finished its work')
+	})
+
+	it('takes over the turn rather than letting the model re-decide', async () => {
+		// The ordinary repair strips the assistant turn and lets the model
+		// re-issue every delegation — which is precisely the second run.
+		const plan = planCrashResume(
+			{ id: 'cp_1' as CheckpointId, messages: fanOut() } as IterationCheckpoint,
+			new Map([['w1', {}]]),
+			makeLogger(),
+		)
+
+		expect(plan).not.toBeNull()
+		expect(plan?.response.message.toolCalls).toHaveLength(5)
+	})
+
+	it('names the workers that will actually run', async () => {
+		const log = makeLogger()
+		planCrashResume(
+			{ id: 'cp_1' as CheckpointId, messages: fanOut() } as IterationCheckpoint,
+			new Map([
+				['w1', {}],
+				['w2', {}],
+				['w3', {}],
+			]),
+			log,
+		)
+
+		const warned = (log.warn as unknown as { mock: { calls: unknown[][] } }).mock.calls[0]
+		expect(warned?.[1]).toMatchObject({ completed: 3, total: 5 })
+	})
+
+	it('leaves an untouched fan-out to the ordinary repair', async () => {
+		// Nothing dispatched yet means nothing to protect, and re-deciding
+		// costs only a round trip.
+		expect(
+			planCrashResume(
+				{ id: 'cp_1' as CheckpointId, messages: fanOut() } as IterationCheckpoint,
+				new Map(),
+				makeLogger(),
+			),
+		).toBeNull()
+	})
+
+	it('does not confuse a worker id with one from an earlier turn', async () => {
+		await recordCompletions(['from-an-older-turn'])
+
+		const runMgr = { getRunStore: () => store } as never
+		const recovered = await recoverCompletedCalls(
+			runMgr,
+			(fanOut()[1] as { toolCalls: { id: string }[] }).toolCalls as never,
+			makeLogger(),
+		)
+
+		// Scoped to the calls being resumed, so a stale id cannot answer a
+		// delegation that never ran.
+		expect(recovered.size).toBe(0)
+	})
+})

package/src/runtime/query/__tests__/document-attachments.test.ts

@@ -0,0 +1,125 @@
+import { describe, expect, it } from 'vitest'
+
+import { resolveProviderCapabilities } from '../../../provider/capabilities.js'
+import { MockLLMProvider, registerMock } from '../../../provider/index.js'
+import { ToolRegistry } from '../../../registry/index.js'
+import type { ChatCompletionParams, ProviderCapabilities } from '../../../types/provider/index.js'
+import {
+	generateProjectId,
+	generateSessionId,
+	generateTenantId,
+	generateThreadId,
+} from '../../../utils/id.js'
+import { drainQuery } from '../index.js'
+
+/**
+ * Documents existed in the type system only in the TOOL-RESULT direction,
+ * so "here is the contract, answer questions about it" was reachable only
+ * by having a tool read the file and stringify it. That loses the
+ * provider's native document handling — page structure, built-in OCR,
+ * citations — and pays the text cost instead.
+ */
+
+registerMock()
+
+const PDF = {
+	type: 'document' as const,
+	data: 'JVBERi0xLjQK',
+	mediaType: 'application/pdf',
+	name: 'contract.pdf',
+}
+const PNG = { data: 'iVBORw0KGgo=', mediaType: 'image/png' }
+
+const capabilities = (over: Partial<ProviderCapabilities>): ProviderCapabilities =>
+	({
+		supportsTools: true,
+		supportsStreaming: true,
+		supportsFunctionCalling: true,
+		supportsVision: true,
+		supportsDocuments: true,
+		...over,
+	}) as ProviderCapabilities
+
+function runWith(opts: {
+	attachments: readonly unknown[]
+	capabilities?: ProviderCapabilities
+	strict?: boolean
+}) {
+	const provider = new MockLLMProvider({
+		turns: [{ text: 'read it' }],
+		...(opts.capabilities ? { capabilities: opts.capabilities } : {}),
+	})
+
+	const settled = drainQuery({
+		provider,
+		tools: new ToolRegistry(),
+		agentId: 'a',
+		agentName: 'A',
+		messages: [{ role: 'user', content: 'answer from the file', attachments: opts.attachments }],
+		workingDirectory: process.cwd(),
+		runConfig: { model: 'mock', tokenBudget: 100_000, timeoutMs: 30_000, maxIterations: 2 },
+		projectId: generateProjectId(),
+		sessionId: generateSessionId(),
+		threadId: generateThreadId(),
+		tenantId: generateTenantId(),
+		...(opts.strict ? { strictCapabilities: true } : {}),
+	} as never)
+
+	return { settled, requests: provider.requests as ChatCompletionParams[] }
+}
+
+describe('a user message that carries a document', () => {
+	it('reaches the driver alongside the text', async () => {
+		const { settled, requests } = runWith({ attachments: [PDF] })
+		await settled
+
+		const sent = requests[0]?.messages.find((m) => m.role === 'user')
+		expect((sent as { attachments?: unknown[] })?.attachments).toEqual([PDF])
+	})
+
+	it('refuses to run against a driver that says it cannot map documents', async () => {
+		await expect(
+			runWith({
+				attachments: [PDF],
+				capabilities: capabilities({ supportsDocuments: false }),
+				strict: true,
+			}).settled,
+		).rejects.toThrow(/supportsDocuments: false/)
+	})
+
+	it('does not fire the document check for an image', async () => {
+		// The two are separate wire shapes, and a check aimed at the wrong
+		// one sends the reader to the wrong half of the driver.
+		await expect(
+			runWith({
+				attachments: [PNG],
+				capabilities: capabilities({ supportsDocuments: false }),
+				strict: true,
+			}).settled,
+		).resolves.toBeDefined()
+	})
+
+	it('does not fire the vision check for a document', async () => {
+		await expect(
+			runWith({
+				attachments: [PDF],
+				capabilities: capabilities({ supportsVision: false }),
+				strict: true,
+			}).settled,
+		).resolves.toBeDefined()
+	})
+})
+
+describe('a driver that declares nothing', () => {
+	it('is assumed to handle documents, like every other capability', () => {
+		// A driver written before the field existed must not start warning.
+		expect(resolveProviderCapabilities({ capabilities: undefined }).supportsDocuments).toBe(true)
+	})
+
+	it('keeps its own answer when it declares one', () => {
+		expect(
+			resolveProviderCapabilities({ capabilities: capabilities({ supportsDocuments: false }) })
+				.supportsDocuments,
+		).toBe(false)
+	})
+})