@namzu/sdk 14.0.7 → 15.0.0

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

@@ -1,285 +0,0 @@
-import { mkdtemp, rm } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-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 { 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'
-import { CheckpointManager } from '../checkpoint.js'
-import { drainQuery } from '../index.js'
-import { runIterationCheckpoint } from '../iteration/phases/checkpoint.js'
-import type { IterationContext } from '../iteration/phases/context.js'
-
-const ZERO_COST = {
-	inputCostPer1M: 0,
-	outputCostPer1M: 0,
-	totalCost: 0,
-	cacheDiscount: 0,
-}
-
-const SCOPE: CheckpointRunScope = {
-	tenantId: 'tnt_cp_store' as TenantId,
-	projectId: 'prj_cp_store' as ProjectId,
-	sessionId: 'ses_cp_store' as SessionId,
-	runId: 'run_cp_store' as RunId,
-}
-
-/**
- * In-memory {@link CheckpointStore} used both as the conformance fixture for
- * `CheckpointManager` and as the injected store in the query()-level test.
- * Keys rows by the full scope so the tests can assert the kernel passes the
- * five-layer attribution through, not just the checkpoint payload.
- */
-class InMemoryCheckpointStore implements CheckpointStore {
-	readonly rows = new Map<string, IterationCheckpoint>()
-	readonly seenScopes: CheckpointRunScope[] = []
-
-	private key(scope: CheckpointRunScope, checkpointId: CheckpointId): string {
-		return [scope.tenantId, scope.projectId, scope.sessionId, scope.runId, checkpointId].join('/')
-	}
-
-	private runPrefix(scope: CheckpointRunScope): string {
-		return `${[scope.tenantId, scope.projectId, scope.sessionId, scope.runId].join('/')}/`
-	}
-
-	async writeCheckpoint(scope: CheckpointRunScope, checkpoint: IterationCheckpoint): Promise<void> {
-		this.seenScopes.push(scope)
-		this.rows.set(this.key(scope, checkpoint.id), checkpoint)
-	}
-
-	async readCheckpoint(
-		scope: CheckpointRunScope,
-		checkpointId: CheckpointId,
-	): Promise<IterationCheckpoint | null> {
-		return this.rows.get(this.key(scope, checkpointId)) ?? null
-	}
-
-	async listCheckpoints(scope: CheckpointRunScope): Promise<IterationCheckpoint[]> {
-		const prefix = this.runPrefix(scope)
-		return [...this.rows.entries()]
-			.filter(([key]) => key.startsWith(prefix))
-			.map(([, cp]) => cp)
-			.sort((a, b) => a.createdAt - b.createdAt)
-	}
-
-	async deleteCheckpoint(scope: CheckpointRunScope, checkpointId: CheckpointId): Promise<void> {
-		this.rows.delete(this.key(scope, checkpointId))
-	}
-}
-
-const ZERO_USAGE = {
-	promptTokens: 0,
-	completionTokens: 0,
-	totalTokens: 0,
-	cachedTokens: 0,
-	cacheWriteTokens: 0,
-}
-
-function makeRunMgrStub(): RunPersistence {
-	return {
-		id: SCOPE.runId,
-		messages: [{ role: 'user', content: 'hello' }],
-		tokenUsage: { ...ZERO_USAGE },
-		costInfo: { ...ZERO_COST },
-		currentIteration: 1,
-		getSession: () => ({ startedAt: Date.now() }),
-	} as unknown as RunPersistence
-}
-
-describe('CheckpointManager against an injected CheckpointStore', () => {
-	it('round-trips create → restore → list → prune through the interface', async () => {
-		const store = new InMemoryCheckpointStore()
-		const mgr = new CheckpointManager(store, SCOPE)
-		const runMgr = makeRunMgrStub()
-
-		const first = await mgr.create(runMgr, 1)
-		const second = await mgr.create(runMgr, 2)
-		// Deterministic ordering for prune (createdAt can tie at ms resolution).
-		const storedFirst = store.rows.get(
-			[SCOPE.tenantId, SCOPE.projectId, SCOPE.sessionId, SCOPE.runId, first.id].join('/'),
-		)
-		const storedSecond = store.rows.get(
-			[SCOPE.tenantId, SCOPE.projectId, SCOPE.sessionId, SCOPE.runId, second.id].join('/'),
-		)
-		if (storedFirst) storedFirst.createdAt = 1_000
-		if (storedSecond) storedSecond.createdAt = 2_000
-
-		// restore reads back through the interface
-		const restored = await mgr.restore(first.id)
-		expect(restored.id).toBe(first.id)
-		expect(restored.iteration).toBe(1)
-
-		// list sees both, oldest first
-		const listed = await mgr.list()
-		expect(listed.map((cp) => cp.id)).toEqual([first.id, second.id])
-
-		// prune deletes oldest-first through deleteCheckpoint
-		await mgr.prune(1)
-		const remaining = await mgr.list()
-		expect(remaining.map((cp) => cp.id)).toEqual([second.id])
-
-		// every write carried the full five-layer scope
-		expect(store.seenScopes.every((s) => s.tenantId === SCOPE.tenantId)).toBe(true)
-		expect(store.seenScopes.every((s) => s.sessionId === SCOPE.sessionId)).toBe(true)
-	})
-
-	it('restore throws a descriptive error for a missing checkpoint', async () => {
-		const mgr = new CheckpointManager(new InMemoryCheckpointStore(), SCOPE)
-		await expect(mgr.restore('cp_missing' as CheckpointId)).rejects.toThrow(
-			'Checkpoint not found: cp_missing',
-		)
-	})
-})
-
-// ─── cadence + prune via the iteration-checkpoint phase ──────────────────────
-
-function makePhaseContext(
-	store: InMemoryCheckpointStore,
-	runConfig: { checkpointEvery?: number; pruneKeepLast?: number },
-): { ctx: IterationContext; events: RunEvent[] } {
-	const events: RunEvent[] = []
-	const ctx = {
-		runConfig: {
-			model: 'mock-model',
-			timeoutMs: 5_000,
-			tokenBudget: 100_000,
-			...runConfig,
-		},
-		runMgr: makeRunMgrStub(),
-		checkpointMgr: new CheckpointManager(store, SCOPE),
-		emitEvent: async (event: RunEvent) => {
-			events.push(event)
-		},
-		drainPending: function* (): Generator<RunEvent> {},
-		resumeHandler: async () => ({ action: 'continue' as const }),
-	} as unknown as IterationContext
-	return { ctx, events }
-}
-
-async function drivePhase(ctx: IterationContext, iterationNum: number): Promise<void> {
-	const gen = runIterationCheckpoint(ctx, iterationNum)
-	let result = await gen.next()
-	while (!result.done) {
-		result = await gen.next()
-	}
-}
-
-describe('iteration checkpoint cadence (checkpointEvery)', () => {
-	it('defaults to a checkpoint on every iteration', async () => {
-		const store = new InMemoryCheckpointStore()
-		const { ctx, events } = makePhaseContext(store, {})
-
-		await drivePhase(ctx, 1)
-		await drivePhase(ctx, 2)
-		await drivePhase(ctx, 3)
-
-		expect(store.rows.size).toBe(3)
-		expect(events.filter((e) => e.type === 'checkpoint_created')).toHaveLength(3)
-	})
-
-	it('checkpointEvery: 2 checkpoints iterations 1, 3, 5 and skips the rest', async () => {
-		const store = new InMemoryCheckpointStore()
-		const { ctx, events } = makePhaseContext(store, { checkpointEvery: 2 })
-
-		for (const iteration of [1, 2, 3, 4, 5]) {
-			await drivePhase(ctx, iteration)
-		}
-
-		const created = events.filter(
-			(e): e is Extract<RunEvent, { type: 'checkpoint_created' }> =>
-				e.type === 'checkpoint_created',
-		)
-		expect(created.map((e) => e.iteration)).toEqual([1, 3, 5])
-		expect(store.rows.size).toBe(3)
-	})
-
-	it('pruneKeepLast keeps only the newest N checkpoints after each create', async () => {
-		const store = new InMemoryCheckpointStore()
-		const { ctx } = makePhaseContext(store, { pruneKeepLast: 2 })
-
-		// Make createdAt strictly increasing so prune order is deterministic.
-		let tick = 0
-		const originalWrite = store.writeCheckpoint.bind(store)
-		store.writeCheckpoint = async (scope, checkpoint) => {
-			tick += 1
-			await originalWrite(scope, { ...checkpoint, createdAt: tick })
-		}
-
-		await drivePhase(ctx, 1)
-		await drivePhase(ctx, 2)
-		await drivePhase(ctx, 3)
-		await drivePhase(ctx, 4)
-
-		const remaining = await store.listCheckpoints(SCOPE)
-		expect(remaining).toHaveLength(2)
-		expect(remaining.map((cp) => cp.iteration)).toEqual([3, 4])
-	})
-})
-
-// ─── query()-level injection ─────────────────────────────────────────────────
-
-describe('query() with an injected checkpointStore', () => {
-	let workdirs: string[] = []
-
-	afterEach(async () => {
-		await Promise.all(workdirs.map((dir) => rm(dir, { recursive: true, force: true })))
-		workdirs = []
-	})
-
-	it('persists iteration checkpoints into the injected store, keyed by run scope', async () => {
-		// 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({
-			name: 'echo',
-			description: 'echo the text back',
-			inputSchema: z.object({ text: z.string() }),
-			execute: async () => ({ success: true, output: 'hi' }),
-		})
-
-		const workingDirectory = await mkdtemp(join(tmpdir(), 'namzu-checkpoint-store-'))
-		workdirs.push(workingDirectory)
-
-		const run = await drainQuery({
-			provider,
-			tools,
-			checkpointStore: store,
-			runConfig: {
-				model: 'mock-model',
-				timeoutMs: 5_000,
-				tokenBudget: 100_000,
-				maxIterations: 3,
-				maxResponseTokens: 256,
-			},
-			agentId: 'agent_test',
-			agentName: 'Test Agent',
-			messages: [createUserMessage('use the echo tool')],
-			workingDirectory,
-			sessionId: 'ses_cp_inject' as SessionId,
-			threadId: 'thd_cp_inject' as ThreadId,
-			projectId: 'prj_cp_inject' as ProjectId,
-			tenantId: 'tnt_cp_inject' as TenantId,
-		})
-
-		expect(run.status).toBe('completed')
-		// The tool-call iteration produced at least one checkpoint, and it
-		// landed in the injected store — not on disk.
-		expect(store.rows.size).toBeGreaterThan(0)
-		const scope = store.seenScopes[0]
-		expect(scope?.tenantId).toBe('tnt_cp_inject')
-		expect(scope?.projectId).toBe('prj_cp_inject')
-		expect(scope?.sessionId).toBe('ses_cp_inject')
-		expect(scope?.runId).toBe(run.id)
-	})
-})

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

@@ -1,170 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import type { CheckpointId, IterationCheckpoint } from '../../../types/hitl/index.js'
-import type { EmergencySaveId, RunId, SessionId, TenantId } from '../../../types/ids/index.js'
-import type { CheckpointRunScope, CheckpointStore } from '../../../types/run/checkpoint-store.js'
-import type { EmergencySaveData } from '../../../types/run/emergency.js'
-import type { ProjectId } from '../../../types/session/ids.js'
-import { CheckpointManager, projectEmergencyToCheckpoint } from '../checkpoint.js'
-
-const TEST_SCOPE: CheckpointRunScope = {
-	tenantId: 'tnt_test' as TenantId,
-	projectId: 'prj_test' as ProjectId,
-	sessionId: 'ses_test' as SessionId,
-	runId: 'run_test' as RunId,
-}
-
-function makeCheckpoint(overrides: Partial<IterationCheckpoint> = {}): IterationCheckpoint {
-	return {
-		id: 'cp_test_a' as CheckpointId,
-		runId: 'run_test' as RunId,
-		iteration: 1,
-		messages: [{ role: 'user', content: 'hello' }],
-		tokenUsage: {
-			promptTokens: 0,
-			completionTokens: 0,
-			totalTokens: 0,
-			cachedTokens: 0,
-			cacheWriteTokens: 0,
-		},
-		costInfo: {
-			inputCostPer1M: 0,
-			outputCostPer1M: 0,
-			totalCost: 0,
-			cacheDiscount: 0,
-		},
-		guardState: { iterationCount: 1, elapsedMs: 100 },
-		createdAt: Date.now(),
-		...overrides,
-	}
-}
-
-function makeStoreStub(checkpoints: IterationCheckpoint[]): CheckpointStore {
-	return {
-		listCheckpoints: async () => checkpoints,
-	} as unknown as CheckpointStore
-}
-
-describe('CheckpointManager.listEntries', () => {
-	it('projects stored checkpoints to CheckpointListEntry', async () => {
-		const store = makeStoreStub([
-			makeCheckpoint({
-				id: 'cp_a' as CheckpointId,
-				iteration: 1,
-				createdAt: 1000,
-				messages: [
-					{ role: 'user', content: 'hi' },
-					{ role: 'assistant', content: 'hello' },
-				],
-			}),
-			makeCheckpoint({
-				id: 'cp_b' as CheckpointId,
-				iteration: 2,
-				createdAt: 2000,
-				messages: [
-					{ role: 'user', content: 'hi' },
-					{ role: 'assistant', content: 'hello' },
-					{ role: 'user', content: 'more' },
-				],
-			}),
-		])
-
-		const mgr = new CheckpointManager(store, TEST_SCOPE)
-		const entries = await mgr.listEntries()
-
-		expect(entries).toHaveLength(2)
-		expect(entries[0]).toEqual({
-			id: 'cp_a',
-			runId: 'run_test',
-			iteration: 1,
-			createdAt: 1000,
-			messageCount: 2,
-		})
-		expect(entries[1]).toEqual({
-			id: 'cp_b',
-			runId: 'run_test',
-			iteration: 2,
-			createdAt: 2000,
-			messageCount: 3,
-		})
-	})
-
-	it('returns empty array when no checkpoints exist', async () => {
-		const mgr = new CheckpointManager(makeStoreStub([]), TEST_SCOPE)
-		expect(await mgr.listEntries()).toEqual([])
-	})
-
-	it('does not include full checkpoint payload fields', async () => {
-		const mgr = new CheckpointManager(
-			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('guardState')
-		expect(entry).not.toHaveProperty('messages')
-	})
-})
-
-function makeEmergencyDump(overrides: Partial<EmergencySaveData> = {}): EmergencySaveData {
-	return {
-		id: 'esave_dump_a' as EmergencySaveId,
-		runId: 'run_victim' as RunId,
-		messages: [
-			{ role: 'user', content: 'before the crash' },
-			{ role: 'assistant', content: 'working' },
-		],
-		tokenUsage: {
-			promptTokens: 10,
-			completionTokens: 5,
-			totalTokens: 15,
-			cachedTokens: 0,
-			cacheWriteTokens: 0,
-		},
-		currentIteration: 7,
-		startedAt: 1_000,
-		savedAt: 2_500,
-		processSignal: 'SIGTERM',
-		...overrides,
-	}
-}
-
-describe('projectEmergencyToCheckpoint', () => {
-	it('produces an IterationCheckpoint with all required fields', () => {
-		const dump = makeEmergencyDump()
-		const cp = projectEmergencyToCheckpoint(dump)
-
-		expect(cp.runId).toBe('run_victim')
-		expect(cp.iteration).toBe(7)
-		expect(cp.messages).toBe(dump.messages)
-		expect(cp.tokenUsage).toBe(dump.tokenUsage)
-		expect(cp.createdAt).toBe(2_500)
-		expect(cp.guardState).toEqual({ iterationCount: 7, elapsedMs: 1_500 })
-		expect(cp.costInfo).toEqual({
-			inputCostPer1M: 0,
-			outputCostPer1M: 0,
-			totalCost: 0,
-			cacheDiscount: 0,
-		})
-	})
-
-	it('derives a deterministic CheckpointId from the emergency save id', () => {
-		const dump = makeEmergencyDump({ id: 'esave_xyz123' as EmergencySaveId })
-		const cp1 = projectEmergencyToCheckpoint(dump)
-		const cp2 = projectEmergencyToCheckpoint(dump)
-
-		expect(cp1.id).toBe('cp_emergency_xyz123')
-		expect(cp1.id).toBe(cp2.id)
-	})
-
-	it('clamps guardState.elapsedMs to 0 when savedAt precedes startedAt', () => {
-		const cp = projectEmergencyToCheckpoint(makeEmergencyDump({ startedAt: 2_000, savedAt: 1_000 }))
-		expect(cp.guardState.elapsedMs).toBe(0)
-	})
-
-	it('leaves the optional tool-result hashes unset', () => {
-		const cp = projectEmergencyToCheckpoint(makeEmergencyDump())
-		expect(cp.toolResultHashes).toBeUndefined()
-	})
-})

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

@@ -1,111 +0,0 @@
-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)
-	})
-})