@namzu/sdk 3.0.0 → 3.2.0

package/src/runtime/query/__tests__/per-step-tool-choice.test.ts

@@ -0,0 +1,180 @@
+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 { 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'
+
+/**
+ * Forcing a tool is the one step-shaping knob that can hang an agent.
+ *
+ * A forced choice that PERSISTS makes the model call a tool, read the
+ * result, and be forced again — forever. The peer SDK that puts
+ * `tool_choice` on persistent model settings carries three moving parts to
+ * undo that: a tool-use tracker, an opt-out flag, and a reset applied at
+ * two separate call sites. Its flag defaults to on precisely because
+ * turning it off hangs the agent.
+ *
+ * Putting the knob on `prepareStep` removes the failure instead of
+ * managing it: the next step is prepared from scratch, so a force cannot
+ * outlive the step that asked for it. There is no flag to get wrong.
+ */
+
+let workdirs: string[] = []
+
+afterEach(async () => {
+	await Promise.all(workdirs.map((d) => rm(d, { recursive: true, force: true })))
+	workdirs = []
+})
+
+async function mkWorkdir(): Promise<string> {
+	const dir = await mkdtemp(join(tmpdir(), 'namzu-tool-choice-'))
+	workdirs.push(dir)
+	return dir
+}
+
+function registerEcho(tools: ToolRegistry): void {
+	tools.register({
+		name: 'echo',
+		description: 'Echo the text back.',
+		inputSchema: z.object({ text: z.string().optional() }),
+		execute: async () => ({ success: true, output: 'ok' }),
+	})
+}
+
+async function baseParams(provider: MockLLMProvider, tools: ToolRegistry) {
+	return {
+		provider,
+		tools,
+		runConfig: {
+			model: 'mock-model',
+			timeoutMs: 30_000,
+			tokenBudget: 100_000,
+			maxIterations: 4,
+			maxResponseTokens: 256,
+		},
+		agentId: 'agent_tc',
+		agentName: 'Tool Choice Agent',
+		workingDirectory: await mkWorkdir(),
+		sessionId: 'ses_tc' as SessionId,
+		threadId: 'thd_tc' as ThreadId,
+		projectId: 'prj_tc' as ProjectId,
+		tenantId: 'tnt_tc' as TenantId,
+		messages: [createUserMessage('go')],
+	}
+}
+
+describe('a step can force the model to call a tool', () => {
+	it('puts the caller choice on that step request', async () => {
+		const provider = new MockLLMProvider({ turns: [{ text: 'done' }] })
+		const tools = new ToolRegistry()
+		registerEcho(tools)
+
+		await drainQuery({
+			...(await baseParams(provider, tools)),
+			prepareStep: () => ({ toolChoice: 'required' as const }),
+		})
+
+		expect(provider.requests.at(0)?.toolChoice).toBe('required')
+	})
+
+	it('carries a named function through unchanged', async () => {
+		const provider = new MockLLMProvider({ turns: [{ text: 'done' }] })
+		const tools = new ToolRegistry()
+		registerEcho(tools)
+
+		await drainQuery({
+			...(await baseParams(provider, tools)),
+			prepareStep: () => ({
+				toolChoice: { type: 'function' as const, function: { name: 'echo' } },
+			}),
+		})
+
+		expect(provider.requests.at(0)?.toolChoice).toEqual({
+			type: 'function',
+			function: { name: 'echo' },
+		})
+	})
+
+	it('leaves the request alone when no step asks', async () => {
+		const provider = new MockLLMProvider({ turns: [{ text: 'done' }] })
+		const tools = new ToolRegistry()
+		registerEcho(tools)
+
+		await drainQuery(await baseParams(provider, tools))
+
+		expect(provider.requests.at(0)?.toolChoice).toBeUndefined()
+	})
+
+	it('says nothing when there are no tools to choose between', async () => {
+		const provider = new MockLLMProvider({ turns: [{ text: 'done' }] })
+
+		await drainQuery({
+			...(await baseParams(provider, new ToolRegistry())),
+			prepareStep: () => ({ toolChoice: 'required' as const }),
+		})
+
+		// `tool_choice` alongside an absent tool list is rejected by the
+		// providers, so a forced choice with nothing registered has to drop.
+		expect(provider.requests.at(0)?.toolChoice).toBeUndefined()
+	})
+})
+
+/**
+ * NOT covered here, and deliberately not faked: the forced-final turn takes
+ * precedence over a step's choice (`forceFinalize` wins in
+ * `iteration/index.ts`), so a budget-exhausted run can still stop asking
+ * for tools and answer. Reaching that branch needs the guard to raise a
+ * budget warning, which needs real usage the mock provider does not report.
+ * The precedence is implemented and read in review; it is not pinned.
+ */
+describe('a forced choice cannot outlive the step that asked for it', () => {
+	it('applies to the named step only, leaving later steps free', async () => {
+		const provider = new MockLLMProvider({
+			turns: [
+				{ toolCalls: [{ id: 'c1', name: 'echo', rawArguments: '{}' }] },
+				{ text: 'finished' },
+			],
+		})
+		const tools = new ToolRegistry()
+		registerEcho(tools)
+
+		await drainQuery({
+			...(await baseParams(provider, tools)),
+			// Only the first step is forced. Without per-step scoping this
+			// would keep forcing and the run would never reach a text answer.
+			prepareStep: ({ stepNumber }) =>
+				stepNumber === 1 ? { toolChoice: 'required' as const } : {},
+		})
+
+		expect(provider.requests.at(0)?.toolChoice).toBe('required')
+		expect(provider.requests.at(1)?.toolChoice).toBeUndefined()
+	})
+
+	it('a run whose every step forces a tool still ends, bounded by the loop', async () => {
+		const provider = new MockLLMProvider({
+			turns: [
+				{ toolCalls: [{ id: 'c1', name: 'echo', rawArguments: '{}' }] },
+				{ toolCalls: [{ id: 'c2', name: 'echo', rawArguments: '{}' }] },
+				{ text: 'finished' },
+			],
+		})
+		const tools = new ToolRegistry()
+		registerEcho(tools)
+
+		const run = await drainQuery({
+			...(await baseParams(provider, tools)),
+			prepareStep: () => ({ toolChoice: 'required' as const }),
+		})
+
+		// The knob cannot hang a run on its own: the iteration cap is still
+		// the backstop, and it settles rather than spinning.
+		expect(['completed', 'failed']).toContain(run.status)
+	})
+})

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

@@ -0,0 +1,262 @@
+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 { 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 { ProjectId, ThreadId } from '../../../types/session/ids.js'
+import { resumeRun } from '../resume-run.js'
+import type { RunStateScope } from '../run-state.js'
+
+/**
+ * The pieces of a cross-process resume all existed and nothing joined them.
+ * `CheckpointManager` wrote the history, budgets, working state and any
+ * park; `loadRunState` read them back; `query` accepted `runId` +
+ * `resumeFromCheckpoint` and restored all of it. But `resumeFromCheckpoint`
+ * had no caller anywhere outside `packages/sdk/src`, so the whole path
+ * shipped untravelled — every host was expected to write the same wiring
+ * and none did.
+ *
+ * These cover the join, and especially its two refusals: a resume must not
+ * quietly become a fresh run under a recycled id, and it must not step past
+ * a park without the answer that park is waiting for.
+ */
+
+const SCOPE: RunStateScope = {
+	tenantId: 'tnt_resume' as TenantId,
+	projectId: 'prj_resume' as ProjectId,
+	sessionId: 'ses_resume' as SessionId,
+	runId: 'run_resume' as RunId,
+	threadId: 'thd_resume' as ThreadId,
+}
+
+const ZERO_USAGE = {
+	promptTokens: 0,
+	completionTokens: 0,
+	totalTokens: 0,
+	cachedTokens: 0,
+	cacheWriteTokens: 0,
+}
+
+const ZERO_COST = {
+	inputCostPer1M: 0,
+	outputCostPer1M: 0,
+	totalCost: 0,
+	cacheDiscount: 0,
+}
+
+class InMemoryCheckpointStore implements CheckpointStore {
+	readonly rows = new Map<string, IterationCheckpoint>()
+
+	private key(scope: CheckpointRunScope, id: CheckpointId): string {
+		return [scope.tenantId, scope.projectId, scope.sessionId, scope.runId, id].join('/')
+	}
+
+	async writeCheckpoint(scope: CheckpointRunScope, checkpoint: IterationCheckpoint): Promise<void> {
+		this.rows.set(this.key(scope, checkpoint.id), checkpoint)
+	}
+
+	async readCheckpoint(
+		scope: CheckpointRunScope,
+		id: CheckpointId,
+	): Promise<IterationCheckpoint | null> {
+		return this.rows.get(this.key(scope, id)) ?? null
+	}
+
+	async listCheckpoints(scope: CheckpointRunScope): Promise<IterationCheckpoint[]> {
+		const prefix = `${[scope.tenantId, scope.projectId, scope.sessionId, scope.runId].join('/')}/`
+		return [...this.rows.entries()]
+			.filter(([key]) => key.startsWith(prefix))
+			.map(([, cp]) => cp)
+			.sort((a, b) => a.createdAt - b.createdAt)
+	}
+
+	async deleteCheckpoint(scope: CheckpointRunScope, id: CheckpointId): Promise<void> {
+		this.rows.delete(this.key(scope, id))
+	}
+}
+
+function checkpoint(overrides: Partial<IterationCheckpoint> = {}): IterationCheckpoint {
+	return {
+		id: 'ckpt_1' as CheckpointId,
+		runId: SCOPE.runId,
+		iteration: 2,
+		messages: [createUserMessage('the work so far')],
+		tokenUsage: { ...ZERO_USAGE, promptTokens: 120, totalTokens: 120 },
+		costInfo: { ...ZERO_COST, totalCost: 0.4 },
+		guardState: { iterationCount: 2, elapsedMs: 9_000 },
+		createdAt: Date.now(),
+		...overrides,
+	} as IterationCheckpoint
+}
+
+let workdirs: string[] = []
+
+afterEach(async () => {
+	await Promise.all(workdirs.map((d) => rm(d, { recursive: true, force: true })))
+	workdirs = []
+})
+
+async function mkWorkdir(): Promise<string> {
+	const dir = await mkdtemp(join(tmpdir(), 'namzu-resume-run-'))
+	workdirs.push(dir)
+	return dir
+}
+
+async function baseParams(store: CheckpointStore) {
+	return {
+		scope: SCOPE,
+		checkpointStore: store,
+		provider: new MockLLMProvider({ turns: [{ text: 'continued' }] }),
+		tools: new ToolRegistry(),
+		runConfig: {
+			model: 'mock-model',
+			timeoutMs: 30_000,
+			tokenBudget: 100_000,
+			maxIterations: 2,
+			maxResponseTokens: 256,
+		},
+		agentId: 'agent_resume',
+		agentName: 'Resume Agent',
+		workingDirectory: await mkWorkdir(),
+		sessionId: SCOPE.sessionId,
+		threadId: SCOPE.threadId,
+		projectId: SCOPE.projectId,
+		tenantId: SCOPE.tenantId,
+		// Required by the contract, and rightly so: a resume that lands on a
+		// park has to have somewhere to ask.
+		resumeHandler: async () => ({ action: 'continue' as const }),
+	}
+}
+
+describe('a run is picked back up from its store', () => {
+	it('continues the same run id rather than starting a new one', async () => {
+		const store = new InMemoryCheckpointStore()
+		await store.writeCheckpoint(SCOPE, checkpoint())
+
+		const outcome = await resumeRun(await baseParams(store))
+
+		expect(outcome.resumed).toBe(true)
+		if (!outcome.resumed) return
+		// The whole point: a resume is the same run in a different process,
+		// so its id, budgets and trace all have to carry across.
+		expect(outcome.run.id).toBe(SCOPE.runId)
+		expect(outcome.state.checkpointId).toBe('ckpt_1')
+	})
+
+	it('carries the spent budget forward instead of granting a fresh one', async () => {
+		const store = new InMemoryCheckpointStore()
+		await store.writeCheckpoint(SCOPE, checkpoint())
+
+		const outcome = await resumeRun(await baseParams(store))
+
+		expect(outcome.resumed).toBe(true)
+		if (!outcome.resumed) return
+		// A run recalled at 120 tokens must not come back at zero — the
+		// budget belongs to the run, not to the process hosting it.
+		expect(outcome.run.tokenUsage.totalTokens).toBeGreaterThanOrEqual(120)
+	})
+
+	it('picks the newest checkpoint when the caller names none', async () => {
+		const store = new InMemoryCheckpointStore()
+		await store.writeCheckpoint(SCOPE, checkpoint({ id: 'ckpt_old' as CheckpointId, createdAt: 1 }))
+		await store.writeCheckpoint(
+			SCOPE,
+			checkpoint({ id: 'ckpt_new' as CheckpointId, createdAt: 2_000 }),
+		)
+
+		const outcome = await resumeRun(await baseParams(store))
+
+		expect(outcome.resumed).toBe(true)
+		if (!outcome.resumed) return
+		expect(outcome.state.checkpointId).toBe('ckpt_new')
+	})
+
+	it('honours an explicitly named checkpoint', async () => {
+		const store = new InMemoryCheckpointStore()
+		await store.writeCheckpoint(SCOPE, checkpoint({ id: 'ckpt_old' as CheckpointId, createdAt: 1 }))
+		await store.writeCheckpoint(
+			SCOPE,
+			checkpoint({ id: 'ckpt_new' as CheckpointId, createdAt: 2_000 }),
+		)
+
+		const outcome = await resumeRun({
+			...(await baseParams(store)),
+			checkpointId: 'ckpt_old' as CheckpointId,
+		})
+
+		expect(outcome.resumed).toBe(true)
+		if (!outcome.resumed) return
+		expect(outcome.state.checkpointId).toBe('ckpt_old')
+	})
+})
+
+describe('it refuses rather than guessing', () => {
+	it('reports no checkpoint instead of silently starting fresh', async () => {
+		const outcome = await resumeRun(await baseParams(new InMemoryCheckpointStore()))
+
+		// Starting a new run here would be the worst outcome: a different
+		// run wearing a recycled id, with the original's budget reset.
+		expect(outcome).toEqual({ resumed: false, reason: 'no-checkpoint' })
+	})
+
+	it('hands back the outstanding question instead of resuming past it', async () => {
+		const store = new InMemoryCheckpointStore()
+		await store.writeCheckpoint(
+			SCOPE,
+			checkpoint({
+				pending: {
+					request: {
+						type: 'tool_review',
+						runId: SCOPE.runId,
+						checkpointId: 'ckpt_1' as CheckpointId,
+						toolCalls: [{ id: 'call_1', name: 'write', input: {} }],
+					},
+					parkedAt: Date.now(),
+					deadlineAt: Date.now() + 60_000,
+				},
+			} as unknown as Partial<IterationCheckpoint>),
+		)
+
+		const outcome = await resumeRun(await baseParams(store))
+
+		expect(outcome.resumed).toBe(false)
+		if (outcome.resumed || outcome.reason !== 'awaiting-decision') {
+			throw new Error(`expected awaiting-decision, got ${JSON.stringify(outcome)}`)
+		}
+		// The host needs the request itself to put in front of a person.
+		expect(outcome.pending.request.type).toBe('tool_review')
+		expect(outcome.state.runId).toBe(SCOPE.runId)
+	})
+
+	it('treats an already-answered park as an ordinary resume', async () => {
+		const store = new InMemoryCheckpointStore()
+		await store.writeCheckpoint(
+			SCOPE,
+			checkpoint({
+				pending: {
+					request: {
+						type: 'tool_review',
+						runId: SCOPE.runId,
+						checkpointId: 'ckpt_1' as CheckpointId,
+						toolCalls: [{ id: 'call_1', name: 'write', input: {} }],
+					},
+					parkedAt: Date.now(),
+					deadlineAt: Date.now() + 60_000,
+					resolvedAt: Date.now(),
+				},
+			} as unknown as Partial<IterationCheckpoint>),
+		)
+
+		const outcome = await resumeRun(await baseParams(store))
+
+		// `resolvedAt` is what makes a park answered. Blocking on one that
+		// already has its answer would strand the run permanently.
+		expect(outcome.resumed).toBe(true)
+	})
+})

package/src/runtime/query/executor.ts

@@ -7,6 +7,7 @@ import { ProbeVetoError } from '../../probe/errors.js'
 import { type ProbeRegistry, probe as defaultProbeRegistry } from '../../probe/registry.js'
 import { renderToolSchema } from '../../registry/tool/schema.js'
 import type { ActivityStore } from '../../store/activity/memory.js'
+import { fingerprintContent } from '../../tools/builtins/content-fingerprint.js'
 import type { RunId, ToolUseId } from '../../types/ids/index.js'
 import type { InvocationState } from '../../types/invocation/index.js'
 import {
@@ -205,11 +206,18 @@ export class ToolExecutor {
 	private probes: ProbeRegistry
 	private parentSpan?: Span
 	private readonly readPaths: Set<string> = new Set()
+	private readonly readFingerprints: Map<string, string> = new Map()
 	private readonly fileReadTracker: FileReadTracker = {
-		recordRead: (key: string) => {
+		recordRead: (key: string, content?: string) => {
 			this.readPaths.add(key)
+			// Only when the reader had the body. A tool that records a read
+			// without one leaves the previous fingerprint alone rather than
+			// clearing it, so a later write is still checked against the last
+			// body anyone actually saw.
+			if (content !== undefined) this.readFingerprints.set(key, fingerprintContent(content))
 		},
 		hasRead: (key: string) => this.readPaths.has(key),
+		fingerprint: (key: string) => this.readFingerprints.get(key),
 	}
 
 	constructor(

package/src/runtime/query/index.ts

@@ -9,6 +9,8 @@ import {
 import { findDanglingMessages, removeDanglingMessages } from '../../compaction/dangling.js'
 import { extractFromUserMessage } from '../../compaction/extractor.js'
 import { WorkingStateManager } from '../../compaction/manager.js'
+import type { ContextReducer } from '../../compaction/reducer.js'
+import { serializeState as serializeWorkingState } from '../../compaction/serializer.js'
 import { restoreWorkingState, snapshotWorkingState } from '../../compaction/wire.js'
 import type { CompactionConfig } from '../../config/runtime.js'
 import { TOOL_OUTPUT_DIR_NAME } from '../../constants/tools/index.js'
@@ -421,6 +423,16 @@ export interface QueryParams {
 	 */
 	workingMemoryProvider?: WorkingMemoryProvider
 
+	/**
+	 * Replace context reduction for this run.
+	 *
+	 * Outranks `compactionConfig.strategy`, and the built-in structured pass
+	 * does not also run: two mechanisms editing one history in the same pass
+	 * cannot both be reasoned about. See `ContextReducer` for the invariants a
+	 * reducer is expected to keep.
+	 */
+	contextReducer?: ContextReducer
+
 	agentBus?: import('../../bus/index.js').AgentBus
 
 	verificationGate?: VerificationGateConfig
@@ -752,6 +764,31 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			params.advisory.budget,
 		)
 
+		// What the run looks like when the MODEL consults an advisor, as
+		// opposed to when a trigger does. The trigger path has always passed
+		// this; the tool path passed an empty context, so an advisor the model
+		// asked for help saw the question and nothing else.
+		//
+		// `includeToolCatalog` and `useCompactedContext` are read here and
+		// nowhere else. Both were declared on `AdvisoryConfig` /
+		// `AdvisorDefinition` and consulted by nothing, so a host who turned
+		// the catalogue off still paid for it in every advisory prompt.
+		const advisoryConfig = params.advisory
+		advisoryCtx.setCallContextProvider(() => {
+			const summary =
+				workingStateManager && advisoryConfig.advisors.some((a) => a.useCompactedContext)
+					? serializeWorkingState(workingStateManager.getState())
+					: undefined
+			return {
+				messages: ctx.runMgr.messages,
+				...(summary !== undefined ? { workingStateSummary: summary } : {}),
+				...(advisoryConfig.includeToolCatalog
+					? { toolCatalog: params.tools.toLLMTools(effectiveAllowedTools) }
+					: {}),
+				iteration: ctx.runMgr.currentIteration,
+			}
+		})
+
 		if (params.advisory.enableAgentTool) {
 			const advisoryTools = buildAdvisoryTools({ advisoryCtx })
 			const overrides = params.runtimeToolOverrides
@@ -800,6 +837,8 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		toolGrants: new ToolGrantSet(),
 		compactionConfig: params.compactionConfig,
 		workingStateManager,
+		taskRouter: params.taskRouter,
+		contextReducer: params.contextReducer,
 		workingMemoryProvider: params.workingMemoryProvider,
 		advisoryCtx,
 		agentBus: params.agentBus,