@namzu/sdk 14.0.7 → 15.1.0

package/src/runtime/query/__tests__/structured-output.test.ts

@@ -1,268 +0,0 @@
-import { describe, expect, it, vi } from 'vitest'
-import { z } from 'zod'
-
-import { MockLLMProvider } from '../../../provider/mock.js'
-import { ActivityStore } from '../../../store/activity/memory.js'
-import {
-	STRUCTURED_OUTPUT_TOOL_NAME,
-	createStructuredOutputTool,
-} from '../../../tools/builtins/structuredOutput.js'
-import type { RunId } from '../../../types/ids/index.js'
-import type { Message } from '../../../types/message/index.js'
-import type { LLMProvider } from '../../../types/provider/index.js'
-import type { RunEvent } from '../../../types/run/index.js'
-import type { StructuredOutputConfig } from '../../../types/structured-output/index.js'
-import type { ToolRegistryContract } from '../../../types/tool/index.js'
-import type { Logger } from '../../../utils/logger.js'
-import { ToolExecutor } from '../executor.js'
-import { IterationOrchestrator } from '../iteration/index.js'
-
-/**
- * Both leaf pieces shipped and neither was reachable.
- * `createStructuredOutputTool` is excluded from `getBuiltinTools()`, and
- * `StructuredOutputConfig` was referenced by exactly one non-test line —
- * the barrel re-export. A host needing `{verdict, findings}` from an agent
- * that also uses tools had to register the tool by hand and hope: nothing
- * forced the call, nothing stopped the loop when it came, and a schema
- * mismatch surfaced as a ZodError AFTER the run had paid for itself.
- */
-
-const RUN_ID = 'run_so' as RunId
-
-const SCHEMA = z.object({
-	verdict: z.enum(['pass', 'fail']),
-	notes: z.string(),
-})
-
-function makeLogger(): Logger {
-	const stub = { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() }
-	return { ...stub, child: vi.fn(() => ({ ...stub, child: vi.fn() })) } as unknown as Logger
-}
-
-function harness(opts: {
-	provider: LLMProvider
-	structuredOutput?: StructuredOutputConfig
-	maxIterations?: number
-}) {
-	const messages: Message[] = []
-	let iteration = 0
-	let stopReason: string | undefined
-	let structured: unknown
-	const log = makeLogger()
-
-	const outputTool = createStructuredOutputTool(SCHEMA)
-	const registry = new Map<string, unknown>([[STRUCTURED_OUTPUT_TOOL_NAME, outputTool]])
-
-	const tools = {
-		get: vi.fn(
-			(name: string) =>
-				registry.get(name) ?? {
-					name,
-					isConcurrencySafe: () => true,
-					isReadOnly: () => true,
-					isDestructive: () => false,
-				},
-		),
-		execute: vi.fn(async (name: string, input: unknown) => {
-			if (name === STRUCTURED_OUTPUT_TOOL_NAME) {
-				const parsed = SCHEMA.safeParse(input)
-				if (!parsed.success) {
-					return { success: false, output: '', error: parsed.error.message }
-				}
-				return { success: true, output: JSON.stringify(parsed.data), data: parsed.data }
-			}
-			return { success: true, output: `${name} ok` }
-		}),
-		has: vi.fn((name: string) => registry.has(name)),
-		listNames: vi.fn(() => [...registry.keys()]),
-		getAvailability: vi.fn(() => 'active'),
-		toLLMTools: vi.fn(() => []),
-		register: vi.fn(),
-		unregister: vi.fn(),
-	} as unknown as ToolRegistryContract
-
-	const activityStore = new ActivityStore(RUN_ID, {
-		enabled: false,
-		trackToolCalls: false,
-		trackLlmTurns: false,
-	})
-
-	const maxIterations = opts.maxIterations ?? 8
-
-	const runMgr = {
-		id: RUN_ID,
-		messages,
-		tokenUsage: {
-			promptTokens: 0,
-			completionTokens: 0,
-			totalTokens: 0,
-			cachedTokens: 0,
-			cacheWriteTokens: 0,
-		},
-		costInfo: { inputCostPer1M: 0, outputCostPer1M: 0, totalCost: 0, cacheDiscount: 0 },
-		get currentIteration() {
-			return iteration
-		},
-		incrementIteration: () => ++iteration,
-		pushMessage: (m: Message) => {
-			messages.push(m)
-		},
-		recordTurnUsage: vi.fn(),
-		accumulateUsage: vi.fn(),
-		clearLastPromptTokens: vi.fn(),
-		lastPromptTokens: undefined,
-		setStopReason: (r: string) => {
-			stopReason = r
-		},
-		setStructuredOutput: (v: unknown) => {
-			structured = v
-		},
-		markCancelled: vi.fn(),
-	}
-
-	const orchestrator = new IterationOrchestrator({
-		provider: opts.provider,
-		runConfig: { model: 'mock', maxIterations },
-		tools,
-		runMgr,
-		toolExecutor: new ToolExecutor(
-			{
-				tools,
-				runId: RUN_ID,
-				workingDirectory: '/tmp',
-				permissionMode: 'auto',
-				env: {},
-				abortSignal: new AbortController().signal,
-			},
-			activityStore,
-			async () => {},
-			log,
-		),
-		activityStore,
-		abortController: new AbortController(),
-		log,
-		emitEvent: async () => {},
-		drainPending: function* (): Generator<RunEvent> {},
-		checkpointMgr: { create: async () => ({ id: 'cp_1' }) },
-		resumeHandler: async () => ({ action: 'approve_tools' }),
-		planManager: { active: undefined },
-		guard: {
-			beforeIteration: () => ({
-				shouldStop: iteration >= maxIterations,
-				forceFinalize: false,
-				isCancelled: false,
-				stopReason: 'max_iterations',
-			}),
-		},
-		...(opts.structuredOutput ? { structuredOutput: opts.structuredOutput } : {}),
-	} as never)
-
-	return {
-		orchestrator,
-		messages,
-		stopReason: () => stopReason,
-		structured: () => structured,
-		iterations: () => iteration,
-	}
-}
-
-async function drain(o: IterationOrchestrator) {
-	const gen = o.runLoop()
-	let next = await gen.next()
-	while (!next.done) next = await gen.next()
-}
-
-describe('structured final output', () => {
-	it('lands the validated value on the run and ends there', async () => {
-		const provider = new MockLLMProvider({
-			turns: [
-				{ toolCalls: [{ name: 'read' }] },
-				{
-					toolCalls: [
-						{
-							name: STRUCTURED_OUTPUT_TOOL_NAME,
-							args: { verdict: 'pass', notes: 'looks fine' },
-						},
-					],
-				},
-				// Would keep going if the run did not end on the output.
-				{ text: 'should never be reached' },
-			],
-		})
-		const h = harness({ provider, structuredOutput: { schema: SCHEMA } })
-
-		await drain(h.orchestrator)
-
-		expect(h.structured()).toEqual({ verdict: 'pass', notes: 'looks fine' })
-		expect(h.stopReason()).toBe('end_turn')
-		expect(h.iterations()).toBe(2)
-	})
-
-	it('re-prompts when the model answers in prose instead', async () => {
-		const provider = new MockLLMProvider({
-			turns: [
-				{ text: 'The verdict is pass.' },
-				{
-					toolCalls: [
-						{ name: STRUCTURED_OUTPUT_TOOL_NAME, args: { verdict: 'pass', notes: 'ok' } },
-					],
-				},
-			],
-		})
-		const h = harness({ provider, structuredOutput: { schema: SCHEMA } })
-
-		await drain(h.orchestrator)
-
-		// The re-prompt reached the model...
-		expect(h.messages.some((m) => String(m.content).includes('structured_output'))).toBe(true)
-		// ...and the second turn satisfied it.
-		expect(h.structured()).toEqual({ verdict: 'pass', notes: 'ok' })
-		expect(h.stopReason()).toBe('end_turn')
-	})
-
-	it('gives up loudly rather than looping when the model never complies', async () => {
-		const provider = new MockLLMProvider({ turns: [{ text: 'still prose' }] })
-		const h = harness({
-			provider,
-			structuredOutput: { schema: SCHEMA, maxRetries: 2 },
-			maxIterations: 20,
-		})
-
-		await drain(h.orchestrator)
-
-		expect(h.stopReason()).toBe('structured_output_failed')
-		expect(h.structured()).toBeUndefined()
-		// Bounded by maxRetries, nowhere near maxIterations.
-		expect(h.iterations()).toBeLessThanOrEqual(4)
-	})
-
-	it('a schema-invalid call does not satisfy the demand', async () => {
-		const provider = new MockLLMProvider({
-			turns: [
-				// `verdict` is not in the enum → the tool returns an error result.
-				{ toolCalls: [{ name: STRUCTURED_OUTPUT_TOOL_NAME, args: { verdict: 'maybe' } }] },
-				{
-					toolCalls: [
-						{ name: STRUCTURED_OUTPUT_TOOL_NAME, args: { verdict: 'fail', notes: 'second try' } },
-					],
-				},
-			],
-		})
-		const h = harness({ provider, structuredOutput: { schema: SCHEMA } })
-
-		await drain(h.orchestrator)
-
-		expect(h.structured()).toEqual({ verdict: 'fail', notes: 'second try' })
-	})
-
-	it('is inert when no structured output was requested', async () => {
-		const provider = new MockLLMProvider({ turns: [{ text: 'plain answer' }] })
-		const h = harness({ provider })
-
-		await drain(h.orchestrator)
-
-		expect(h.structured()).toBeUndefined()
-		expect(h.stopReason()).toBe('end_turn')
-		expect(h.iterations()).toBe(1)
-	})
-})

package/src/runtime/query/__tests__/structured-run-failure.test.ts

@@ -1,144 +0,0 @@
-import { describe, expect, it, vi } from 'vitest'
-
-import { mapRunToA2AEvent } from '../../../bridge/a2a/mapper.js'
-import { NamzuError } from '../../../types/errors/index.js'
-import type { RunId } from '../../../types/ids/index.js'
-import { ProviderError } from '../../../types/provider/errors.js'
-import type { RunEvent } from '../../../types/run/index.js'
-import { ResultAssembler } from '../result.js'
-
-/**
- * `run_failed` carried a bare string, and the run boundary flattened the
- * throwable into it — discarding `code`, `status`, `retryAfterMs`,
- * `retryable`, `details` and the whole cause chain.
- *
- * This was never "the taxonomy is unbuilt". The classifier at the provider
- * boundary already walks the cause chain over status, errno and
- * `Retry-After`, so a fully-populated error genuinely arrived here and was
- * thrown away one line later — and `toPlatformError`, the projection
- * written for exactly this, had no callers outside its own test. The fix is
- * widening the event, not retrofitting hundreds of throw sites.
- */
-
-const RID = 'run_1' as RunId
-
-function makeLogger() {
-	const self = { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() }
-	;(self as unknown as { child: () => unknown }).child = () => self
-	return self as never
-}
-
-async function failWith(err: unknown): Promise<RunEvent[]> {
-	const emitted: RunEvent[] = []
-	const pending: RunEvent[] = []
-
-	const assembler = new ResultAssembler({
-		runMgr: {
-			id: RID,
-			currentIteration: 1,
-			stopReason: undefined,
-			markFailed: () => {},
-			getRun: () => ({ id: RID }),
-		} as never,
-		planManager: { isActive: false, failPlan: () => {} } as never,
-		activityStore: { enabled: false } as never,
-		log: makeLogger(),
-		emitEvent: async (event: RunEvent) => {
-			emitted.push(event)
-			pending.push(event)
-		},
-		drainPending: function* () {
-			while (pending.length > 0) {
-				const next = pending.shift()
-				if (next) yield next
-			}
-		},
-	} as never)
-
-	const span = {
-		setAttributes: () => {},
-		setStatus: () => {},
-		recordException: () => {},
-		end: () => {},
-	} as never
-
-	for await (const _event of assembler.handleError(err, span)) {
-		// drain
-	}
-	return emitted
-}
-
-const failureOf = (events: RunEvent[]) =>
-	events.find((e): e is Extract<RunEvent, { type: 'run_failed' }> => e.type === 'run_failed')
-		?.failure
-
-describe('what run_failed carries', () => {
-	it('keeps the flattened message, for consumers that only render a string', async () => {
-		const events = await failWith(new Error('boom'))
-		const failed = events.find((e) => e.type === 'run_failed')
-		expect(failed && 'error' in failed && failed.error).toContain('boom')
-	})
-
-	it('keeps a provider classification instead of flattening it away', async () => {
-		const failure = failureOf(
-			await failWith(
-				new ProviderError({
-					code: 'rate_limit',
-					message: 'slow down',
-					providerId: 'test',
-					status: 429,
-					retryAfterMs: 3_000,
-				}),
-			),
-		)
-
-		// "rate limited, retryable, wait 3s" and "your key is wrong" are the
-		// same sentence to a host that only receives a string.
-		expect(failure?.retryable).toBe(true)
-		expect(failure?.details).toMatchObject({
-			providerCode: 'rate_limit',
-			status: 429,
-			retryAfterMs: 3_000,
-		})
-	})
-
-	it('keeps a namzu error code', async () => {
-		const failure = failureOf(
-			await failWith(new NamzuError({ code: 'invalid_config', message: 'bad argument' })),
-		)
-		expect(failure?.code).toBe('invalid_config')
-		expect(failure?.retryable).toBe(false)
-	})
-
-	it('normalizes something that was never an Error at all', async () => {
-		// A thrown string still has to produce the declared shape, or the
-		// host is back to an `instanceof` ladder.
-		const failure = failureOf(await failWith('just a string'))
-		expect(failure?.code).toBeTruthy()
-		expect(failure?.message).toContain('just a string')
-	})
-})
-
-describe('what the bridges do with it', () => {
-	it('sends the classification to a remote peer as metadata', () => {
-		const event = mapRunToA2AEvent(
-			{
-				type: 'run_failed',
-				runId: RID,
-				error: 'slow down',
-				failure: { code: 'provider_error', message: 'slow down', retryable: true },
-			},
-			'ctx-1',
-		)
-
-		// As metadata, not folded into the text: a peer deciding whether to
-		// retry needs the flag, not prose it would have to pattern-match.
-		expect(event?.metadata).toMatchObject({ code: 'provider_error', retryable: true })
-	})
-
-	it('still maps a failure that carries no classification', () => {
-		const event = mapRunToA2AEvent({ type: 'run_failed', runId: RID, error: 'boom' }, 'ctx-1')
-		expect(event).not.toBeNull()
-		expect(event?.metadata).toBeUndefined()
-	})
-})

package/src/runtime/query/__tests__/terminal-tool.test.ts

@@ -1,148 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { z } from 'zod'
-
-import { MockLLMProvider, registerMock } from '../../../provider/index.js'
-import { ToolRegistry } from '../../../registry/index.js'
-import { defineTool } from '../../../tools/defineTool.js'
-import type { MockTurn } from '../../../types/provider/index.js'
-import {
-	generateProjectId,
-	generateSessionId,
-	generateTenantId,
-	generateThreadId,
-} from '../../../utils/id.js'
-import { drainQuery } from '../index.js'
-
-/**
- * Every delegation path is blocking and returns the worker's final text as
- * the dispatching call's result — after which the loop went round again,
- * costing one more model call at the parent's FULL context size whose only
- * job was to restate what the worker already said. The relay is also
- * lossy: the parent paraphrases through its own compacted view, so what
- * the caller receives is not what the worker produced.
- */
-
-registerMock()
-
-const WORKER_ANSWER = 'the specialist says: ship it on Tuesday'
-
-function tool(name: string, terminal: boolean) {
-	return defineTool({
-		name,
-		description: `${name} tool`,
-		inputSchema: z.object({}),
-		category: 'custom',
-		permissions: [],
-		readOnly: true,
-		destructive: false,
-		concurrencySafe: true,
-		terminal,
-		execute: async () => ({ success: true, output: WORKER_ANSWER }),
-	})
-}
-
-const call = (id: string, name: string) => ({ id, name, args: {} })
-
-async function run(opts: {
-	terminal: boolean
-	turns: MockTurn[]
-	failing?: boolean
-	extraTool?: boolean
-}) {
-	const tools = new ToolRegistry()
-	tools.register(
-		opts.failing
-			? defineTool({
-					name: 'delegate',
-					description: 'delegate tool',
-					inputSchema: z.object({}),
-					category: 'custom',
-					permissions: [],
-					readOnly: true,
-					destructive: false,
-					concurrencySafe: true,
-					terminal: opts.terminal,
-					execute: async () => ({ success: false, output: '', error: 'the worker died' }),
-				})
-			: tool('delegate', opts.terminal),
-	)
-	if (opts.extraTool) tools.register(tool('take_note', false))
-
-	const provider = new MockLLMProvider({ turns: opts.turns })
-	const result = await drainQuery({
-		provider,
-		tools,
-		agentId: 'a',
-		agentName: 'A',
-		messages: [{ role: 'user', content: 'route this' }],
-		workingDirectory: process.cwd(),
-		runConfig: { model: 'mock', tokenBudget: 100_000, timeoutMs: 30_000, maxIterations: 6 },
-		projectId: generateProjectId(),
-		sessionId: generateSessionId(),
-		threadId: generateThreadId(),
-		tenantId: generateTenantId(),
-	} as never)
-
-	return { result, turns: provider.requests.length }
-}
-
-const delegateThenSummarize: MockTurn[] = [
-	{ toolCalls: [call('c1', 'delegate')], finishReason: 'tool_calls' },
-	{ text: 'the specialist suggested something about Tuesday' },
-]
-
-describe('a tool whose output is the answer', () => {
-	it('costs a relay turn when not declared terminal', async () => {
-		// The premise. Two model calls: one to delegate, one whose entire
-		// job is to restate what came back.
-		const { result, turns } = await run({ terminal: false, turns: delegateThenSummarize })
-
-		expect(turns).toBe(2)
-		expect(result.result).not.toBe(WORKER_ANSWER)
-	})
-
-	it('settles the run with the tool output when declared terminal', async () => {
-		const { result, turns } = await run({ terminal: true, turns: delegateThenSummarize })
-
-		// One model call, and the caller receives the worker's words rather
-		// than the parent's paraphrase of them.
-		expect(turns).toBe(1)
-		expect(result.result).toBe(WORKER_ANSWER)
-		expect(result.stopReason).toBe('end_turn')
-	})
-
-	it('keeps looping when the terminal call shared its turn', async () => {
-		// The model asked for other work in the same turn and meant to see
-		// those results; ending the run would discard answers it requested.
-		const { result, turns } = await run({
-			terminal: true,
-			extraTool: true,
-			turns: [
-				{
-					toolCalls: [call('c1', 'delegate'), call('c2', 'take_note')],
-					finishReason: 'tool_calls',
-				},
-				{ text: 'both came back' },
-			],
-		})
-
-		expect(turns).toBe(2)
-		expect(result.result).toBe('both came back')
-	})
-
-	it('returns a failed terminal call to the model instead of settling on it', async () => {
-		// An error is not an answer, and the model is the one that should
-		// read it.
-		const { result, turns } = await run({
-			terminal: true,
-			failing: true,
-			turns: [
-				{ toolCalls: [call('c1', 'delegate')], finishReason: 'tool_calls' },
-				{ text: 'the delegate failed, here is what I can do instead' },
-			],
-		})
-
-		expect(turns).toBe(2)
-		expect(result.result).toBe('the delegate failed, here is what I can do instead')
-	})
-})

package/src/runtime/query/__tests__/the-other-approval-surface-names-the-agent.test.ts

@@ -1,95 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import type { PlanManager } from '../../../manager/plan/lifecycle.js'
-import { MockLLMProvider, registerMock } from '../../../provider/index.js'
-import { ToolRegistry } from '../../../registry/index.js'
-import type { HITLResumeDecision, PlanApprovalData } from '../../../types/hitl/index.js'
-import {
-	generateProjectId,
-	generateSessionId,
-	generateTenantId,
-	generateThreadId,
-} from '../../../utils/id.js'
-import { drainQuery } from '../index.js'
-
-/**
- * There are TWO approval surfaces, and the fix landed on one of them.
- *
- * `PlanStep.agentId` was added so an approver could see WHICH agent a step goes
- * to rather than only THAT it delegates. It reached `PlanApprovalRequest` — the
- * shape a host sees when it installs its own handler on `PlanManager` — and the
- * test written at the time asserted on exactly that, by constructing a
- * `PlanManager` directly.
- *
- * It did not reach `PlanApprovalData`, which is what every `resumeHandler` host
- * receives, because that type declared its own step shape and both mappers copy
- * field by field. So the busier surface kept showing `toolName: 'create_task'`
- * and nothing else — the precise behaviour the change was supposed to end.
- *
- * A live run did not catch it either: the run observes `plan_ready`, which
- * carries whole `PlanStep`s and therefore always had `agentId`. Watching the
- * event stream confirmed the field existed somewhere, which is not the same
- * question as whether the approver gets it.
- */
-
-registerMock()
-
-async function agentIdSeenByResumeHandler(): Promise<PlanApprovalData['steps']> {
-	let seen: PlanApprovalData['steps'] | undefined
-
-	await drainQuery({
-		provider: new MockLLMProvider({ responses: [{ content: 'done' }] } as never),
-		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(),
-		// The ordinary host path: a resumeHandler, not a hand-installed
-		// PlanManager handler.
-		resumeHandler: async (request: { type: string; plan?: PlanApprovalData }) => {
-			if (request.type === 'plan_approval' && request.plan) seen = request.plan.steps
-			return { action: 'approve_plan' } as HITLResumeDecision
-		},
-		onContextCreated: ({ planManager }: { planManager: PlanManager }) => {
-			planManager.startGenerating('the work')
-			planManager.addStep({
-				id: 'step_1',
-				description: 'delegated work',
-				agentId: 'shell-runner',
-				toolName: 'create_task',
-				dependsOn: [],
-				order: 1,
-			})
-			planManager.addStep({ id: 'step_2', description: 'my own work', dependsOn: [], order: 2 })
-			planManager.markReady()
-			void planManager.requestApproval()
-		},
-	} as never)
-
-	if (!seen) throw new Error('the resume handler never received a plan approval')
-	return seen
-}
-
-describe('the resumeHandler approval surface names the agent too', () => {
-	it('carries agentId through to the host', async () => {
-		const steps = await agentIdSeenByResumeHandler()
-
-		expect(steps.map((s) => s.agentId)).toEqual(['shell-runner', undefined])
-	})
-
-	it('still distinguishes the two steps by more than toolName', async () => {
-		// The defect in the shape that matters: without agentId both delegated
-		// steps reach the approver identical, and an orchestrator-owned step is
-		// told apart only by an absent toolName.
-		const steps = await agentIdSeenByResumeHandler()
-		const delegated = steps.find((s) => s.id === 'step_1')
-
-		expect(delegated?.toolName).toBe('create_task')
-		expect(delegated?.agentId).toBe('shell-runner')
-	})
-})