@namzu/sdk 2.0.0 → 3.0.0

package/src/runtime/query/__tests__/durable-run-state.test.ts

@@ -0,0 +1,194 @@
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import { DiskCheckpointStore } from '../../../store/run/checkpoint-disk.js'
+import type {
+	CheckpointId,
+	HITLDecisionRequest,
+	IterationCheckpoint,
+} from '../../../types/hitl/index.js'
+import type { RunId, SessionId, TenantId } from '../../../types/ids/index.js'
+import type { CheckpointRunScope } from '../../../types/run/checkpoint-store.js'
+import { RUN_STATE_VERSION, RunStateVersionError, parseRunState } from '../../../types/run/state.js'
+import type { ProjectId, ThreadId } from '../../../types/session/ids.js'
+import { ZERO_COST } from '../../../utils/cost.js'
+import { CheckpointManager, findPendingCheckpoint } from '../checkpoint.js'
+import { type RunStateScope, loadRunState } from '../run-state.js'
+
+/**
+ * A parked approval used to exist only as a suspended `await` inside one
+ * process. Nothing on disk said a human owed the run an answer, so an
+ * approval queue could not be rebuilt and a serverless host could not park
+ * a run at all — the container that held the promise had to stay alive.
+ */
+
+const RUN_ID = 'run_durable' as RunId
+let baseDir: string
+let store: DiskCheckpointStore
+let scope: RunStateScope
+
+beforeEach(async () => {
+	baseDir = await mkdtemp(join(tmpdir(), 'namzu-durable-'))
+	store = new DiskCheckpointStore({ baseDir })
+	scope = {
+		tenantId: 'tnt_d' as TenantId,
+		projectId: 'prj_d' as ProjectId,
+		sessionId: 'ses_d' as SessionId,
+		threadId: 'thd_d' as ThreadId,
+		runId: RUN_ID,
+	}
+})
+
+afterEach(async () => {
+	await rm(baseDir, { recursive: true, force: true })
+})
+
+function checkpoint(id: string, iteration: number): IterationCheckpoint {
+	return {
+		id: id as CheckpointId,
+		runId: RUN_ID,
+		iteration,
+		messages: [{ role: 'user', content: `turn ${iteration}` }],
+		tokenUsage: {
+			promptTokens: 10 * iteration,
+			completionTokens: iteration,
+			totalTokens: 11 * iteration,
+			cachedTokens: 0,
+			cacheWriteTokens: 0,
+		},
+		costInfo: { ...ZERO_COST },
+		guardState: { iterationCount: iteration, elapsedMs: 1_000 * iteration },
+		createdAt: 1_700_000_000_000 + iteration,
+	}
+}
+
+const reviewRequest = (checkpointId: string): HITLDecisionRequest => ({
+	type: 'tool_review',
+	runId: RUN_ID,
+	checkpointId: checkpointId as CheckpointId,
+	toolCalls: [{ id: 'call_1', name: 'delete_row', input: { id: 42 }, isDestructive: true }],
+})
+
+describe('recording a park', () => {
+	it('makes the outstanding decision readable from the store alone', async () => {
+		const mgr = new CheckpointManager(store, scope as CheckpointRunScope)
+		const cp = checkpoint('cp_1', 1)
+		await store.writeCheckpoint(scope, cp)
+
+		expect(await findPendingCheckpoint(store, scope)).toBeNull()
+
+		await mgr.park(cp, reviewRequest('cp_1'))
+
+		// A DIFFERENT reader — a fresh store over the same directory, i.e.
+		// what a second process has.
+		const fresh = new DiskCheckpointStore({ baseDir })
+		const found = await findPendingCheckpoint(fresh, scope)
+		expect(found?.id).toBe('cp_1')
+		expect(found?.pending?.request.type).toBe('tool_review')
+		expect(found?.pending?.parkedAt).toBeGreaterThan(0)
+	})
+
+	it('stops being outstanding once answered, and keeps the answer as evidence', async () => {
+		const mgr = new CheckpointManager(store, scope as CheckpointRunScope)
+		const cp = checkpoint('cp_1', 1)
+		await store.writeCheckpoint(scope, cp)
+		await mgr.park(cp, reviewRequest('cp_1'))
+
+		await mgr.unpark('cp_1' as CheckpointId, { action: 'approve_tools' })
+
+		expect(await findPendingCheckpoint(store, scope)).toBeNull()
+		const stored = await store.readCheckpoint(scope, 'cp_1' as CheckpointId)
+		// Not erased — a gate that cannot say what was approved is not an
+		// audit trail.
+		expect(stored?.pending?.decision).toEqual({ action: 'approve_tools' })
+		expect(stored?.pending?.resolvedAt).toBeGreaterThan(0)
+	})
+
+	it('returns the newest outstanding park when several checkpoints exist', async () => {
+		const mgr = new CheckpointManager(store, scope as CheckpointRunScope)
+		for (const [id, n] of [
+			['cp_1', 1],
+			['cp_2', 2],
+			['cp_3', 3],
+		] as const) {
+			await store.writeCheckpoint(scope, checkpoint(id, n))
+		}
+		await mgr.park(checkpoint('cp_1', 1), reviewRequest('cp_1'))
+		await mgr.unpark('cp_1' as CheckpointId, { action: 'approve_tools' })
+		await mgr.park(checkpoint('cp_3', 3), reviewRequest('cp_3'))
+
+		expect((await findPendingCheckpoint(store, scope))?.id).toBe('cp_3')
+	})
+
+	it('unparking something that was never parked is a no-op, not a crash', async () => {
+		const mgr = new CheckpointManager(store, scope as CheckpointRunScope)
+		await store.writeCheckpoint(scope, checkpoint('cp_1', 1))
+		expect(await mgr.unpark('cp_1' as CheckpointId, { action: 'approve_tools' })).toBeNull()
+		expect(await mgr.unpark('cp_gone' as CheckpointId, { action: 'approve_tools' })).toBeNull()
+	})
+})
+
+describe('loadRunState', () => {
+	it('rebuilds a snapshot with no live run object', async () => {
+		await store.writeCheckpoint(scope, checkpoint('cp_1', 1))
+		await store.writeCheckpoint(scope, checkpoint('cp_2', 2))
+
+		const state = await loadRunState(store, scope)
+
+		expect(state).not.toBeNull()
+		expect(state?.runId).toBe(RUN_ID)
+		expect(state?.currentIteration).toBe(2)
+		// Budgets are properties of the RUN, not of the process hosting it.
+		expect(state?.elapsedMs).toBe(2_000)
+		expect(state?.tokenUsage.totalTokens).toBe(22)
+		expect(state?.checkpointId).toBe('cp_2')
+	})
+
+	it('prefers the outstanding park over the newest checkpoint', async () => {
+		// "What is this run waiting on" is the question a resuming process
+		// is actually asking.
+		const mgr = new CheckpointManager(store, scope as CheckpointRunScope)
+		await store.writeCheckpoint(scope, checkpoint('cp_1', 1))
+		await store.writeCheckpoint(scope, checkpoint('cp_2', 2))
+		await mgr.park(checkpoint('cp_1', 1), reviewRequest('cp_1'))
+
+		const state = await loadRunState(store, scope)
+		expect(state?.checkpointId).toBe('cp_1')
+		expect(state?.pending?.request.type).toBe('tool_review')
+	})
+
+	it('returns null for a run that never checkpointed', async () => {
+		// Rather than synthesizing a snapshot that would restart from zero
+		// while claiming to be a continuation.
+		expect(await loadRunState(store, scope)).toBeNull()
+	})
+
+	it('survives a JSON round trip', async () => {
+		await store.writeCheckpoint(scope, checkpoint('cp_1', 1))
+		const state = await loadRunState(store, scope)
+		const revived = parseRunState(JSON.stringify(state))
+		expect(revived).toEqual(state)
+	})
+})
+
+describe('parseRunState', () => {
+	it('refuses a snapshot from an incompatible version', () => {
+		// A silent partial restore produces a run that looks healthy and has
+		// lost its budgets.
+		expect(() => parseRunState(JSON.stringify({ version: 99, runId: RUN_ID }))).toThrow(
+			RunStateVersionError,
+		)
+	})
+
+	it('refuses a snapshot with no version at all', () => {
+		expect(() => parseRunState('{"runId":"run_x"}')).toThrow(RunStateVersionError)
+		expect(() => parseRunState('null')).toThrow(RunStateVersionError)
+	})
+
+	it('accepts an object as well as a string', () => {
+		const state = { version: RUN_STATE_VERSION, runId: RUN_ID }
+		expect(parseRunState(state).runId).toBe(RUN_ID)
+	})
+})

package/src/runtime/query/__tests__/executor-plugin-hooks.test.ts

@@ -237,10 +237,16 @@ describe('ToolExecutor plugin hooks', () => {
 			toolRegistry: {} as any,
 			log: makeLogger(),
 		})
-		realManager['hookHandlers'].set('pre_tool_use', [
-			{ pluginId: 'p1' as any, handler: handlers[0] as any },
-			{ pluginId: 'p2' as any, handler: handlers[1] as any },
-		])
+		// Through the real registration path, so the entries are the ones
+		// dispatch actually receives.
+		realManager.registerHook('p1' as any, {
+			event: 'pre_tool_use',
+			handler: handlers[0] as any,
+		})
+		realManager.registerHook('p2' as any, {
+			event: 'pre_tool_use',
+			handler: handlers[1] as any,
+		})
 
 		const exec = new ToolExecutor(
 			{
@@ -277,22 +283,20 @@ describe('ToolExecutor plugin hooks', () => {
 			log: makeLogger(),
 		})
 		const seenInputs: unknown[] = []
-		realManager['hookHandlers'].set('pre_tool_use', [
-			{
-				pluginId: 'p1' as any,
-				handler: (async (ctx: any) => {
-					seenInputs.push(['hook1', ctx.toolInput])
-					return { action: 'modify', input: { patched: true } }
-				}) as any,
-			},
-			{
-				pluginId: 'p2' as any,
-				handler: (async (ctx: any) => {
-					seenInputs.push(['hook2', ctx.toolInput])
-					return { action: 'skip', reason: 'after patch' }
-				}) as any,
-			},
-		])
+		realManager.registerHook('p1' as any, {
+			event: 'pre_tool_use',
+			handler: (async (ctx: any) => {
+				seenInputs.push(['hook1', ctx.toolInput])
+				return { action: 'modify', input: { patched: true } }
+			}) as any,
+		})
+		realManager.registerHook('p2' as any, {
+			event: 'pre_tool_use',
+			handler: (async (ctx: any) => {
+				seenInputs.push(['hook2', ctx.toolInput])
+				return { action: 'skip', reason: 'after patch' }
+			}) as any,
+		})
 
 		const exec = new ToolExecutor(
 			{

package/src/runtime/query/__tests__/finish-reason-vs-tool-calls.test.ts

@@ -0,0 +1,206 @@
+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 { ToolRegistry } from '../../../registry/tool/execute.js'
+import type { 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 { ProjectId, ThreadId } from '../../../types/session/ids.js'
+import { drainQuery } from '../index.js'
+
+/**
+ * The turn ended on `finishReason === 'stop'` before it looked at whether
+ * the model had asked for tools. Endpoints on the function-calling wire shape —
+ * gateways and local servers especially — routinely report `stop` on the
+ * same response that carries a populated `tool_calls`, and three of this
+ * repo's drivers passed that value through untouched.
+ *
+ * The damage was total and silent: every requested call skipped, an
+ * assistant turn left carrying tool_use blocks nothing ever answered, and
+ * the run settling as though it had finished the work.
+ *
+ * The existing suite could not see it, because the scripted mock reports
+ * `tool_calls` whenever it emits one — which is what an honest provider
+ * does, and therefore never the case that breaks.
+ */
+
+const dirs: string[] = []
+
+afterEach(async () => {
+	await Promise.all(dirs.splice(0).map((d) => rm(d, { recursive: true, force: true })))
+})
+
+async function mkWorkdir(): Promise<string> {
+	const dir = await mkdtemp(join(tmpdir(), 'namzu-finish-'))
+	dirs.push(dir)
+	return dir
+}
+
+const USAGE = {
+	promptTokens: 1,
+	completionTokens: 1,
+	totalTokens: 2,
+	cachedTokens: 0,
+	cacheWriteTokens: 0,
+}
+
+/** Asks for a tool, then claims the turn is over. */
+function provider(reported: 'stop' | 'tool_calls'): LLMProvider {
+	let turn = 0
+	return {
+		id: 'scripted',
+		name: 'scripted',
+		capabilities: {
+			supportsTools: true,
+			supportsStreaming: true,
+			supportsFunctionCalling: true,
+		},
+		async *chatStream(): AsyncIterable<StreamChunk> {
+			turn++
+			if (turn === 1) {
+				yield {
+					id: 'c1',
+					delta: {
+						toolCalls: [
+							{
+								index: 0,
+								id: 'call_1',
+								type: 'function',
+								function: { name: 'echo', arguments: '{"text":"hi"}' },
+							},
+						],
+						toolCallEnd: { index: 0, id: 'call_1' },
+					},
+				}
+				// The lie under test.
+				yield { id: 'c1', delta: {}, finishReason: reported, usage: USAGE }
+				return
+			}
+			yield { id: 'c2', delta: { content: 'done' } }
+			yield { id: 'c2', delta: {}, finishReason: 'stop', usage: USAGE }
+		},
+		async listModels() {
+			return []
+		},
+		async healthCheck() {
+			return true
+		},
+	}
+}
+
+async function run(reported: 'stop' | 'tool_calls') {
+	const tools = new ToolRegistry()
+	let calls = 0
+	tools.register({
+		name: 'echo',
+		description: 'Echo the text back.',
+		inputSchema: z.object({ text: z.string() }),
+		execute: async () => {
+			calls++
+			return { success: true, output: 'ok' }
+		},
+	})
+
+	const result = await drainQuery({
+		provider: provider(reported),
+		tools,
+		messages: [createUserMessage('echo hi')],
+		runConfig: {
+			model: 'scripted-model',
+			timeoutMs: 5_000,
+			tokenBudget: 100_000,
+			maxIterations: 4,
+			maxResponseTokens: 256,
+		},
+		agentId: 'agent_test',
+		agentName: 'Test Agent',
+		workingDirectory: await mkWorkdir(),
+		sessionId: 'ses_finish' as SessionId,
+		threadId: 'thd_finish' as ThreadId,
+		projectId: 'prj_finish' as ProjectId,
+		tenantId: 'tnt_finish' as TenantId,
+	})
+
+	return { result, calls }
+}
+
+describe('a provider that says stop while asking for a tool', () => {
+	it('runs the tool anyway', async () => {
+		// The calls are the fact and the reason is the summary; when they
+		// disagree the calls win.
+		expect((await run('stop')).calls).toBe(1)
+	})
+
+	it('leaves no tool call unanswered', async () => {
+		const { result } = await run('stop')
+		const requested = result.messages
+			.filter((m) => m.role === 'assistant')
+			.flatMap((m) => (m as { toolCalls?: { id: string }[] }).toolCalls ?? [])
+			.map((c) => c.id)
+		const answered = result.messages
+			.filter((m) => m.role === 'tool')
+			.map((m) => (m as unknown as { toolCallId: string }).toolCallId)
+
+		// An assistant turn carrying a call nothing answered is a malformed
+		// conversation, and the next request is rejected for it.
+		expect(requested.length).toBeGreaterThan(0)
+		for (const id of requested) expect(answered).toContain(id)
+	})
+
+	it('behaves exactly as it does for an honest provider', async () => {
+		const dishonest = await run('stop')
+		const honest = await run('tool_calls')
+		expect(dishonest.calls).toBe(honest.calls)
+		expect(dishonest.result.messages.filter((m) => m.role === 'tool')).toHaveLength(
+			honest.result.messages.filter((m) => m.role === 'tool').length,
+		)
+	})
+
+	it('still ends the turn when there are no tool calls', async () => {
+		const tools = new ToolRegistry()
+		const result = await drainQuery({
+			provider: {
+				id: 'plain',
+				name: 'plain',
+				capabilities: {
+					supportsTools: true,
+					supportsStreaming: true,
+					supportsFunctionCalling: true,
+				},
+				async *chatStream(): AsyncIterable<StreamChunk> {
+					yield { id: 'c', delta: { content: 'just an answer' } }
+					yield { id: 'c', delta: {}, finishReason: 'stop', usage: USAGE }
+				},
+				async listModels() {
+					return []
+				},
+				async healthCheck() {
+					return true
+				},
+			},
+			tools,
+			messages: [createUserMessage('hi')],
+			runConfig: {
+				model: 'plain-model',
+				timeoutMs: 5_000,
+				tokenBudget: 100_000,
+				maxIterations: 4,
+				maxResponseTokens: 256,
+			},
+			agentId: 'agent_test',
+			agentName: 'Test Agent',
+			workingDirectory: await mkWorkdir(),
+			sessionId: 'ses_plain' as SessionId,
+			threadId: 'thd_plain' as ThreadId,
+			projectId: 'prj_plain' as ProjectId,
+			tenantId: 'tnt_plain' as TenantId,
+		})
+
+		// The ordinary path must not have moved.
+		expect(result.status).toBe('completed')
+		expect(result.messages.filter((m) => m.role === 'tool')).toHaveLength(0)
+	})
+})

package/src/runtime/query/__tests__/grant-cannot-overrule-the-gate.test.ts

@@ -0,0 +1,115 @@
+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'
+
+/**
+ * A grant and a gate are different authorities. A grant records that the
+ * USER said yes to a shape of call; the gate encodes what the OPERATOR
+ * forbids. The grant check used to run first and RETURN, so a remembered
+ * approval skipped the gate entirely — and because a tool-scoped grant
+ * matches any arguments, approving one harmless invocation of a tool
+ * authorised every other invocation of it, past a rule written to stop
+ * exactly that.
+ */
+
+registerMock()
+
+const ran: string[] = []
+
+function tools() {
+	const registry = new ToolRegistry()
+	registry.register(
+		defineTool({
+			name: 'shell',
+			description: 'run a command',
+			inputSchema: z.object({ command: z.string() }),
+			category: 'shell',
+			permissions: ['shell_execute'],
+			readOnly: false,
+			destructive: true,
+			concurrencySafe: false,
+			execute: async (input) => {
+				ran.push((input as { command: string }).command)
+				return { success: true, output: 'done' }
+			},
+		}),
+	)
+	return registry
+}
+
+/** Operator policy: this one command is forbidden, whoever asks. */
+const gate = {
+	enabled: true,
+	rules: [
+		{ type: 'custom_pattern', pattern: 'rm -rf', target: 'args', decision: 'deny' },
+		{ type: 'allow_by_name', toolNames: ['shell'] },
+	],
+	allowReadOnlyTools: false,
+	denyDangerousPatterns: false,
+	logDecisions: false,
+}
+
+const call = (command: string): MockTurn => ({
+	toolCalls: [{ id: 'c1', name: 'shell', args: { command } }],
+	finishReason: 'tool_calls',
+})
+
+/**
+ * One run, two tool-calling turns. The grant has to be LIVE for the
+ * second call — a `ToolGrantSet` is per-run, so approving in one run and
+ * calling in another proves nothing about whether a grant can overrule
+ * the gate.
+ */
+async function run(commands: readonly string[]) {
+	ran.length = 0
+	const turns: MockTurn[] = [...commands.map(call), { text: 'done' }]
+
+	await drainQuery({
+		provider: new MockLLMProvider({ turns }),
+		tools: tools(),
+		agentId: 'a',
+		agentName: 'A',
+		messages: [{ role: 'user', content: 'go' }],
+		workingDirectory: process.cwd(),
+		runConfig: { model: 'mock', tokenBudget: 100_000, timeoutMs: 30_000, maxIterations: 5 },
+		projectId: generateProjectId(),
+		sessionId: generateSessionId(),
+		threadId: generateThreadId(),
+		tenantId: generateTenantId(),
+		verificationGate: gate,
+		// The approver says "remember: this tool" — the scope the docs
+		// recommend for a tool that would otherwise re-prompt forever.
+		resumeHandler: async () => ({ action: 'approve_tools', remember: ['shell'] }),
+	} as never)
+
+	return ran.slice()
+}
+
+describe('a call the operator denies', () => {
+	it('does not run just because the same run approved this tool earlier', async () => {
+		// Turn one is harmless and earns a tool-wide grant. Turn two is the
+		// call the gate exists to stop, and the grant covers it by name.
+		expect(await run(['git status', 'rm -rf /'])).toEqual(['git status'])
+	})
+
+	it('still runs what the gate allows, without re-prompting', async () => {
+		// The fix must not turn every grant back into a prompt; that noise
+		// is what the grant was built to end.
+		expect(await run(['git status', 'git log'])).toEqual(['git status', 'git log'])
+	})
+
+	it('denies the same call when no grant exists at all', async () => {
+		expect(await run(['rm -rf /'])).toEqual([])
+	})
+})