@namzu/sdk 14.0.6 → 15.0.0

package/src/runtime/query/__tests__/trace-parenting.test.ts

@@ -1,128 +0,0 @@
-import { mkdtemp, rm } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { type Context, type Span, type Tracer, trace } from '@opentelemetry/api'
-import { afterEach, describe, expect, it } from 'vitest'
-
-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 { ProjectId, ThreadId } from '../../../types/session/ids.js'
-import { drainQuery } from '../index.js'
-
-/**
- * Every run started its OWN root trace, including a spawned sub-agent's.
- * A supervisor delegating to three children produced four disconnected
- * traces rather than one tree — the same defect that made a 20-turn run
- * appear as 21 roots before iterations were parented, except across the
- * spawn boundary, where the delegation structure is the thing you most
- * want to see.
- *
- * Captures what is handed to `startSpan` rather than pulling in an
- * exporter, matching the approach in `telemetry/__tests__` — the question
- * here is whether the parent is PASSED, and that is answerable at the call.
- */
-
-const dirs: string[] = []
-
-function fakeSpan(id: string): Span {
-	const self: Span = {
-		spanContext: () => ({ traceId: `trace-${id}`, spanId: id, traceFlags: 1 }),
-		setAttribute: () => self,
-		setAttributes: () => self,
-		addEvent: () => self,
-		setStatus: () => self,
-		updateName: () => self,
-		end: () => {},
-		isRecording: () => true,
-		recordException: () => {},
-		addLink: () => self,
-		addLinks: () => self,
-	} as unknown as Span
-	return self
-}
-
-/** Records the context each span was started with. */
-function recordingTracer(): { tracer: Tracer; started: { name: string; parent?: Span }[] } {
-	const started: { name: string; parent?: Span }[] = []
-	const tracer = {
-		startSpan: (name: string, _opts?: unknown, ctx?: Context) => {
-			const parent = ctx ? trace.getSpan(ctx) : undefined
-			started.push({ name, ...(parent ? { parent } : {}) })
-			return fakeSpan(`span-${started.length}`)
-		},
-		startActiveSpan: (() => {
-			throw new Error('startActiveSpan does not hold context across yield; not used here')
-		}) as never,
-	} as unknown as Tracer
-	return { tracer, started }
-}
-
-afterEach(async () => {
-	trace.disable()
-	await Promise.all(dirs.map((d) => rm(d, { recursive: true, force: true })))
-	dirs.length = 0
-})
-
-async function runOnce(parentSpan?: Span) {
-	const { tracer, started } = recordingTracer()
-	trace.setGlobalTracerProvider({ getTracer: () => tracer } as never)
-
-	const workingDirectory = await mkdtemp(join(tmpdir(), 'namzu-trace-'))
-	dirs.push(workingDirectory)
-
-	await drainQuery({
-		provider: new MockLLMProvider({ turns: [{ text: 'done' }] }),
-		tools: new ToolRegistry(),
-		runConfig: {
-			model: 'mock-model',
-			timeoutMs: 10_000,
-			tokenBudget: 100_000,
-			maxIterations: 3,
-			maxResponseTokens: 256,
-		},
-		agentId: 'agent_t',
-		agentName: 'Traced',
-		messages: [createUserMessage('go')],
-		workingDirectory,
-		sessionId: 'ses_t' as SessionId,
-		threadId: 'thd_t' as ThreadId,
-		projectId: 'prj_t' as ProjectId,
-		tenantId: 'tnt_t' as TenantId,
-		...(parentSpan ? { parentSpan } : {}),
-	})
-
-	return started
-}
-
-describe('a delegated run joins the trace it belongs to', () => {
-	it('parents its root span to the supplied span', async () => {
-		const caller = fakeSpan('delegating-tool')
-		const started = await runOnce(caller)
-
-		// The run span is the first thing the run starts.
-		const runSpan = started[0]
-		expect(runSpan).toBeDefined()
-		expect(runSpan?.parent).toBe(caller)
-	})
-
-	it('a top-level run still starts its own root', async () => {
-		// Absent a parent, a run IS the root. Forcing one would be wrong.
-		const started = await runOnce()
-
-		expect(started[0]).toBeDefined()
-		expect(started[0]?.parent).toBeUndefined()
-	})
-
-	it('iterations still parent to the run, not to the caller', async () => {
-		// The cross-run fix must not disturb the within-run hierarchy.
-		const caller = fakeSpan('delegating-tool')
-		const started = await runOnce(caller)
-
-		expect(started.length).toBeGreaterThan(1)
-		const iteration = started[1]
-		expect(iteration?.parent).toBeDefined()
-		expect(iteration?.parent).not.toBe(caller)
-	})
-})

package/src/runtime/query/__tests__/wiring-seams.test.ts

@@ -1,288 +0,0 @@
-import { mkdtemp, rm } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { afterEach, describe, expect, it, vi } from 'vitest'
-import { z } from 'zod'
-
-import { MockLLMProvider } from '../../../provider/mock.js'
-import { ToolRegistry } from '../../../registry/tool/execute.js'
-import { DiskCheckpointStore } from '../../../store/run/checkpoint-disk.js'
-import type { HITLResumeDecision, ResumeHandler } from '../../../types/hitl/index.js'
-import type { RunId, SessionId, TenantId } from '../../../types/ids/index.js'
-import { createUserMessage } from '../../../types/message/index.js'
-import type { PluginHookResult } from '../../../types/plugin/index.js'
-import type { ProjectId, ThreadId } from '../../../types/session/ids.js'
-import type { ToolDefinition } from '../../../types/tool/index.js'
-import type { RepairToolCall } from '../../../types/tool/repair.js'
-import { findPendingCheckpoint } from '../checkpoint.js'
-import { drainQuery } from '../index.js'
-
-/**
- * Four defects that every unit test in this repo missed for the same
- * reason: the tests construct the internal class directly, so they prove
- * the helper works and prove nothing about whether `query()` ever reaches
- * it.
- *
- * Each test here goes through the public entry point and would have caught
- * its defect. That is the only property that makes them worth having.
- */
-
-const dirs: string[] = []
-
-afterEach(async () => {
-	await Promise.all(dirs.map((d) => rm(d, { recursive: true, force: true })))
-	dirs.length = 0
-})
-
-async function workdir(): Promise<string> {
-	const dir = await mkdtemp(join(tmpdir(), 'namzu-seam-'))
-	dirs.push(dir)
-	return dir
-}
-
-function countingTool(name: string, calls: string[]): ToolDefinition {
-	return {
-		name,
-		description: `${name} tool`,
-		inputSchema: z.object({ id: z.number() }),
-		isDestructive: () => true,
-		execute: (input: unknown) => {
-			calls.push(`${name}:${(input as { id: number }).id}`)
-			return Promise.resolve({ success: true, output: 'ok' })
-		},
-	} as unknown as ToolDefinition
-}
-
-function baseParams(opts: {
-	dir: string
-	tools: ToolRegistry
-	provider: MockLLMProvider
-	resumeHandler?: ResumeHandler
-}) {
-	return {
-		provider: opts.provider,
-		tools: opts.tools,
-		...(opts.resumeHandler ? { resumeHandler: opts.resumeHandler } : {}),
-		runConfig: {
-			model: 'mock-model',
-			timeoutMs: 10_000,
-			tokenBudget: 100_000,
-			maxIterations: 4,
-			maxResponseTokens: 256,
-		},
-		agentId: 'agent_seam',
-		agentName: 'Seam',
-		workingDirectory: opts.dir,
-		sessionId: 'ses_seam' as SessionId,
-		threadId: 'thd_seam' as ThreadId,
-		projectId: 'prj_seam' as ProjectId,
-		tenantId: 'tnt_seam' as TenantId,
-	}
-}
-
-describe('query() actually reaches repairToolCall', () => {
-	it('repairs a malformed call issued through the real entry point', async () => {
-		// The bug: `repairToolCall` was spread into `ToolingBootstrap.init`,
-		// whose config type has no such field and whose `init` enumerates
-		// what it forwards. Object spread bypasses excess-property checking,
-		// so `query({ repairToolCall })` type-checked and did nothing.
-		const dir = await workdir()
-		const calls: string[] = []
-		const tools = new ToolRegistry()
-		tools.register(countingTool('delete_row', calls))
-
-		const repair = vi.fn<RepairToolCall>(() => ({ arguments: '{"id":42}' }))
-		const provider = new MockLLMProvider({
-			turns: [{ toolCalls: [{ name: 'delete_row', rawArguments: '{"id": 4' }] }, { text: 'done' }],
-		})
-
-		await drainQuery({
-			...baseParams({ dir, tools, provider }),
-			messages: [createUserMessage('delete row 42')],
-			repairToolCall: repair,
-		})
-
-		expect(repair).toHaveBeenCalled()
-		expect(calls).toEqual(['delete_row:42'])
-	})
-})
-
-describe('a post_tool_use retry works on a tool that did not opt into retries', () => {
-	it('honors the hook once, then stops', async () => {
-		// The bug: `post.retry` was read inside a loop bounded by the tool's
-		// `maxRetries`, which defaults to 0 — so the loop body never ran and
-		// the hook's answer was silently discarded. `retry` had also been
-		// removed from the unsupported-action throw, so plugin authors got
-		// silence instead of an error.
-		const dir = await workdir()
-		const calls: string[] = []
-		const tools = new ToolRegistry()
-		tools.register(countingTool('flaky', calls))
-
-		let asked = 0
-		const pluginManager = {
-			executeHooks: (event: string) => {
-				if (event !== 'post_tool_use') return Promise.resolve([] as PluginHookResult[])
-				asked++
-				// Ask for exactly one retry, then let it settle.
-				return Promise.resolve(
-					asked === 1
-						? ([{ action: 'retry' }] as PluginHookResult[])
-						: ([{ action: 'continue' }] as PluginHookResult[]),
-				)
-			},
-		}
-
-		const provider = new MockLLMProvider({
-			turns: [{ toolCalls: [{ name: 'flaky', args: { id: 1 } }] }, { text: 'done' }],
-		})
-
-		await drainQuery({
-			...baseParams({ dir, tools, provider }),
-			messages: [createUserMessage('go')],
-			pluginManager: pluginManager as never,
-		})
-
-		// Ran twice: the original call plus the hook-requested retry.
-		expect(calls).toEqual(['flaky:1', 'flaky:1'])
-	})
-
-	it('a hook that always asks for a retry cannot spin the executor', async () => {
-		const dir = await workdir()
-		const calls: string[] = []
-		const tools = new ToolRegistry()
-		tools.register(countingTool('flaky', calls))
-
-		const pluginManager = {
-			executeHooks: (event: string) =>
-				Promise.resolve(
-					event === 'post_tool_use'
-						? ([{ action: 'retry' }] as PluginHookResult[])
-						: ([] as PluginHookResult[]),
-				),
-		}
-
-		const provider = new MockLLMProvider({
-			turns: [{ toolCalls: [{ name: 'flaky', args: { id: 1 } }] }, { text: 'done' }],
-		})
-
-		await drainQuery({
-			...baseParams({ dir, tools, provider }),
-			messages: [createUserMessage('go')],
-			pluginManager: pluginManager as never,
-		})
-
-		// Bounded by HOOK_RETRY_BUDGET, not unbounded.
-		expect(calls).toHaveLength(2)
-	})
-})
-
-describe('a cross-process resume clears the park it acted on', () => {
-	it('stops reporting pending once the approved batch has run', async () => {
-		// The bug: `applyPendingResume` executed the batch and returned. The
-		// checkpoint kept `pending` with no `resolvedAt`, so an approval
-		// queue built on `findPendingCheckpoint` re-served a destructive call
-		// that had already run — the exact failure recording the park exists
-		// to prevent.
-		const dir = await workdir()
-		const calls: string[] = []
-		const tools = new ToolRegistry()
-		tools.register(countingTool('delete_row', calls))
-		const store = new DiskCheckpointStore({ baseDir: join(dir, 'runs') })
-		const scope = {
-			tenantId: 'tnt_seam' as TenantId,
-			projectId: 'prj_seam' as ProjectId,
-			sessionId: 'ses_seam' as SessionId,
-			runId: 'run_seam' as RunId,
-		}
-
-		const pauseOnReview: ResumeHandler = (request) =>
-			Promise.resolve(
-				request.type === 'tool_review'
-					? ({ action: 'pause', reason: 'ask a human' } as HITLResumeDecision)
-					: ({ action: 'continue' } as HITLResumeDecision),
-			)
-
-		const parked = await drainQuery({
-			...baseParams({
-				dir,
-				tools,
-				provider: new MockLLMProvider({
-					turns: [{ toolCalls: [{ name: 'delete_row', args: { id: 9 } }] }],
-				}),
-				resumeHandler: pauseOnReview,
-			}),
-			checkpointStore: store,
-			runId: scope.runId,
-			messages: [createUserMessage('delete row 9')],
-		})
-
-		const pending = await findPendingCheckpoint(store, { ...scope, runId: parked.id })
-		expect(pending).not.toBeNull()
-
-		await drainQuery({
-			...baseParams({
-				dir,
-				tools,
-				provider: new MockLLMProvider({ turns: [{ text: 'gone' }] }),
-				resumeHandler: pauseOnReview,
-			}),
-			checkpointStore: store,
-			runId: scope.runId,
-			messages: [],
-			resumeFromCheckpoint: pending?.id,
-			pendingDecision: { action: 'approve_tools' },
-		})
-
-		expect(calls).toEqual(['delete_row:9'])
-		// The queue must not offer this decision again.
-		expect(await findPendingCheckpoint(store, { ...scope, runId: parked.id })).toBeNull()
-	})
-})
-
-describe('configuring an output guardrail does not rewrite the run outcome', () => {
-	it('leaves a cancelled run cancelled', async () => {
-		// The bug: the guardrail branch called `markCompleted()` purely to
-		// materialize the produced text, so merely ADDING a safety check
-		// turned a cancelled run into a completed one.
-		const dir = await workdir()
-		const tools = new ToolRegistry()
-		const controller = new AbortController()
-
-		const provider = new MockLLMProvider({
-			turns: [{ toolCalls: [{ name: 'noop', args: {} }] }, { text: 'never' }],
-		})
-
-		const cancelOnReview: ResumeHandler = () => {
-			controller.abort()
-			return Promise.resolve({ action: 'abort', reason: 'user stopped' } as HITLResumeDecision)
-		}
-
-		const result = await drainQuery({
-			...baseParams({ dir, tools, provider, resumeHandler: cancelOnReview }),
-			messages: [createUserMessage('go')],
-			signal: controller.signal,
-			outputGuardrails: [() => ({ action: 'pass' })],
-		})
-
-		expect(result.status).toBe('cancelled')
-		expect(result.stopReason).toBe('cancelled')
-	})
-
-	it('still settles a normal run as completed', async () => {
-		const dir = await workdir()
-		const tools = new ToolRegistry()
-		const result = await drainQuery({
-			...baseParams({
-				dir,
-				tools,
-				provider: new MockLLMProvider({ turns: [{ text: 'all good' }] }),
-			}),
-			messages: [createUserMessage('go')],
-			outputGuardrails: [() => ({ action: 'pass' })],
-		})
-
-		expect(result.status).toBe('completed')
-		expect(result.result).toBe('all good')
-	})
-})

package/src/runtime/query/iteration/__tests__/cancel-settles-turn.test.ts

@@ -1,177 +0,0 @@
-import { type Attributes, type Meter, metrics } from '@opentelemetry/api'
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-
-import { resetRuntimeMetrics } from '../../../../telemetry/metrics.js'
-import type { RunId } from '../../../../types/ids/index.js'
-import type { ChatCompletionParams, StreamChunk } from '../../../../types/provider/index.js'
-import type { LLMProvider } from '../../../../types/provider/interface.js'
-import type { RunEvent } from '../../../../types/run/index.js'
-import type { Logger } from '../../../../utils/logger.js'
-import { streamProviderTurn } from '../stream-turn.js'
-
-/**
- * Cancel re-threw from inside the chunk loop, so everything past it was
- * unreachable: the usage merged so far was discarded wholesale, the span
- * opened for the call was never ended, and the message the turn announced
- * never got a terminator.
- *
- * The load-bearing consequence is silent cost under-reporting — a cancelled
- * turn is not a free turn; the tokens were spent. The stream-ERROR path a
- * few lines away already settled all of this, so cancel was the one exit
- * that skipped it, which is the opposite of what its frequency deserves.
- */
-
-const RUN_ID = 'run_cancel' as RunId
-
-interface Written {
-	instrument: string
-	value: number
-	attributes: Attributes
-}
-
-function captureMetrics(written: Written[]) {
-	const instrument = (name: string) => ({
-		add: (value: number, attributes: Attributes = {}) =>
-			written.push({ instrument: name, value, attributes }),
-		record: (value: number, attributes: Attributes = {}) =>
-			written.push({ instrument: name, value, attributes }),
-	})
-	const meter = {
-		createCounter: (n: string) => instrument(n),
-		createHistogram: (n: string) => instrument(n),
-		createUpDownCounter: (n: string) => instrument(n),
-		createObservableGauge: (n: string) => instrument(n),
-		createObservableCounter: (n: string) => instrument(n),
-		createObservableUpDownCounter: (n: string) => instrument(n),
-		addBatchObservableCallback: () => {},
-		removeBatchObservableCallback: () => {},
-	} as unknown as Meter
-	metrics.setGlobalMeterProvider({ getMeter: () => meter })
-}
-
-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
-}
-
-/** Streams a little, then blocks until the caller aborts. */
-function stallingProvider(controller: AbortController): LLMProvider {
-	return {
-		id: 'stalling',
-		name: 'stalling',
-		capabilities: { supportsTools: true, supportsStreaming: true, supportsFunctionCalling: true },
-		async *chatStream(): AsyncIterable<StreamChunk> {
-			yield { id: 'm1', delta: { content: 'partial answer' } }
-			yield {
-				id: 'm1',
-				delta: {},
-				usage: {
-					promptTokens: 1_200,
-					completionTokens: 340,
-					totalTokens: 1_540,
-					cachedTokens: 500,
-					cacheWriteTokens: 40,
-				},
-			}
-			controller.abort()
-			// The runtime checks the signal between chunks.
-			yield { id: 'm1', delta: { content: 'never seen' } }
-		},
-		async listModels() {
-			return []
-		},
-		async healthCheck() {
-			return true
-		},
-	}
-}
-
-async function runCancelled(): Promise<{ events: RunEvent[]; written: Written[] }> {
-	const written: Written[] = []
-	captureMetrics(written)
-
-	const controller = new AbortController()
-	const events: RunEvent[] = []
-	const params = {
-		model: 'cancel-model',
-		messages: [{ role: 'user' as const, content: 'hi' }],
-		signal: controller.signal,
-	} as ChatCompletionParams
-
-	const iterator = streamProviderTurn(
-		stallingProvider(controller),
-		params,
-		async (e: RunEvent) => {
-			events.push(e)
-		},
-		function* () {},
-		RUN_ID,
-		1,
-		false,
-		makeLogger(),
-	)
-
-	await expect(
-		(async () => {
-			for (;;) {
-				const next = await iterator.next()
-				if (next.done) return next.value
-				events.push(next.value)
-			}
-		})(),
-	).rejects.toThrow()
-
-	return { events, written }
-}
-
-beforeEach(() => {
-	resetRuntimeMetrics()
-})
-
-afterEach(() => {
-	metrics.disable()
-	resetRuntimeMetrics()
-})
-
-describe('a turn cancelled mid-stream', () => {
-	it('records the tokens it already spent', async () => {
-		const { written } = await runCancelled()
-		const tokens = written.filter((w) => w.instrument === 'gen_ai.client.token.usage')
-
-		// A cancelled turn is not a free turn. Discarding the accumulated
-		// usage under-reports the cost of every cancellation.
-		expect(tokens.length).toBeGreaterThan(0)
-		expect(tokens.reduce((sum, w) => sum + w.value, 0)).toBe(1_200 + 340 + 500 + 40)
-	})
-
-	it('records how long the call ran before it was stopped', async () => {
-		const { written } = await runCancelled()
-		expect(written.some((w) => w.instrument === 'gen_ai.client.operation.duration')).toBe(true)
-	})
-
-	it('closes the message it announced', async () => {
-		const { events } = await runCancelled()
-		const completed = events.find((e) => e.type === 'message_completed') as
-			| { stopReason?: string; content?: string }
-			| undefined
-
-		// A host consuming the message lifecycle saw a message begin and
-		// never end.
-		expect(completed).toBeDefined()
-		expect(completed?.stopReason).toBe('cancelled')
-	})
-
-	it('keeps the text the model had already produced', async () => {
-		const { events } = await runCancelled()
-		const completed = events.find((e) => e.type === 'message_completed') as
-			| { content?: string }
-			| undefined
-		expect(completed?.content).toBe('partial answer')
-	})
-
-	it('still propagates the cancellation', async () => {
-		// Settling the bookkeeping must not swallow the reason the turn
-		// ended — the run loop needs the throw to settle as cancelled.
-		await expect(runCancelled()).resolves.toBeDefined()
-	})
-})