@namzu/sdk 2.0.0 → 3.1.0

package/src/runtime/query/__tests__/memory-promotion.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { MockLLMProvider, registerMock } from '../../../provider/index.js'
+import { ToolRegistry } from '../../../registry/index.js'
+import type { RunMemoryCandidate } from '../../../types/run/memory-promotion.js'
+import { memoryCandidateFor } from '../../../types/run/memory-promotion.js'
+import {
+	generateProjectId,
+	generateSessionId,
+	generateTenantId,
+	generateThreadId,
+} from '../../../utils/id.js'
+import { drainQuery } from '../index.js'
+
+/**
+ * namzu could STORE a memory and could not FORM one. `MemoryStore` and
+ * its disk implementation have been here all along, and the only path
+ * into them was the model calling `save_memory` — so a run that worked
+ * out a durable fact and never thought to write it down lost it at
+ * settle, along with everything the compaction pass had already
+ * extracted and structured on the way.
+ */
+
+registerMock()
+
+function run(opts: {
+	promoteMemory?: (candidate: RunMemoryCandidate) => void | Promise<void>
+	failing?: boolean
+	compaction?: boolean
+}) {
+	return drainQuery({
+		provider: new MockLLMProvider({
+			turns: opts.failing ? [{ error: { message: 'provider is down' } }] : [{ text: 'done' }],
+		}),
+		tools: new ToolRegistry(),
+		agentId: 'a',
+		agentName: 'A',
+		messages: [{ role: 'user', content: 'ship the invoice job' }],
+		workingDirectory: process.cwd(),
+		runConfig: { model: 'mock', tokenBudget: 100_000, timeoutMs: 30_000, maxIterations: 2 },
+		projectId: generateProjectId(),
+		sessionId: generateSessionId(),
+		threadId: generateThreadId(),
+		tenantId: generateTenantId(),
+		...(opts.compaction === false ? {} : { compactionConfig: { strategy: 'structured' } }),
+		...(opts.promoteMemory ? { promoteMemory: opts.promoteMemory } : {}),
+	} as never)
+}
+
+describe('what a finished run leaves behind', () => {
+	it('offers the extracted state when the run settles', async () => {
+		const promote = vi.fn()
+		await run({ promoteMemory: promote })
+
+		expect(promote).toHaveBeenCalledTimes(1)
+		const candidate = promote.mock.calls[0]?.[0] as RunMemoryCandidate
+		expect(candidate.runId).toMatch(/^run_/)
+		expect(candidate.task).toContain('invoice')
+	})
+
+	it('offers it after a FAILED run too', async () => {
+		// A run that fell over still discovered things, and the approach that
+		// failed is exactly what a later run should not pay for twice.
+		const promote = vi.fn()
+		await run({ promoteMemory: promote, failing: true }).catch(() => {})
+
+		expect(promote).toHaveBeenCalledTimes(1)
+	})
+
+	it('does not retract an answer when the host throws', async () => {
+		// A memory that failed to form must not fail a run that already
+		// produced its answer.
+		const settled = await run({
+			promoteMemory: () => {
+				throw new Error('the memory store is unreachable')
+			},
+		})
+
+		expect(settled.status).toBe('completed')
+		expect(settled.result).toBe('done')
+	})
+
+	it('awaits an async host before the run returns', async () => {
+		// Fire-and-forget would race a one-shot process exiting, and the
+		// write would be lost precisely on the runs that are shortest.
+		// Asserted as an ORDER, not a flag: a flag checked after the run
+		// passes whenever the run happens to be slower than the write, which
+		// makes the test a race rather than a check.
+		const order: string[] = []
+		await run({
+			promoteMemory: async () => {
+				await new Promise((resolve) => setTimeout(resolve, 50))
+				order.push('promoted')
+			},
+		})
+		order.push('returned')
+
+		expect(order).toEqual(['promoted', 'returned'])
+	})
+
+	it('is not consulted when no host asked for it', async () => {
+		const settled = await run({})
+
+		expect(settled.status).toBe('completed')
+	})
+
+	it('is not consulted when nothing extracted the state', async () => {
+		const promote = vi.fn()
+		await run({ promoteMemory: promote, compaction: false })
+
+		expect(promote).not.toHaveBeenCalled()
+	})
+})
+
+describe('whether there is anything to offer', () => {
+	// Tested apart from the run because inside the `try` the decision and
+	// the catch that swallows its failure look identical from outside: drop
+	// the guard and the candidate throws, the catch logs, and the run-level
+	// assertion still holds for the wrong reason.
+
+	it('is nothing at all without an extractor', () => {
+		// Inventing an empty candidate would ask a host to store a record of
+		// nothing.
+		expect(memoryCandidateFor('run_1' as never, undefined)).toBeUndefined()
+	})
+
+	it('projects the state rather than handing it over', () => {
+		const state = {
+			task: 'ship it',
+			decisions: ['use the queue'],
+			discoveries: [],
+			userRequirements: ['never bill twice'],
+			failures: [],
+			environment: [],
+			files: new Map([['src/a.ts', {}]]),
+			evicted: { decisions: 2 },
+		}
+		const candidate = memoryCandidateFor('run_1' as never, { getState: () => state })
+
+		expect(candidate?.files).toEqual(['src/a.ts'])
+		expect(candidate?.userRequirements).toEqual(['never bill twice'])
+		// Copied, so a host holding the candidate cannot edit the run's state.
+		expect(candidate?.decisions).not.toBe(state.decisions)
+		// Carried rather than hidden: a host deciding whether this is worth
+		// storing should know it is looking at a truncated record.
+		expect(candidate?.evicted).toEqual({ decisions: 2 })
+	})
+})

package/src/runtime/query/__tests__/orphan-task-turn-end.test.ts

@@ -4,44 +4,16 @@ 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 { TaskGateway, TaskHandle } from '../../../types/agent/gateway.js'
 import type { SessionId, TaskId, TenantId } from '../../../types/ids/index.js'
 import { createUserMessage } from '../../../types/message/index.js'
-import type { LLMProvider, StreamChunk } from '../../../types/provider/index.js'
 import type { RunEvent } from '../../../types/run/index.js'
 import type { ProjectId, ThreadId } from '../../../types/session/ids.js'
 import { drainQuery } from '../index.js'
 
-const ZERO_USAGE = {
-	promptTokens: 0,
-	completionTokens: 0,
-	totalTokens: 0,
-	cachedTokens: 0,
-	cacheWriteTokens: 0,
-}
-
 /** Ends its turn with plain text on the first (and only) call. */
-class SingleTurnProvider implements LLMProvider {
-	readonly id = 'single-turn'
-	readonly name = 'Single Turn Provider'
-	calls = 0
-
-	async *chatStream(): AsyncIterable<StreamChunk> {
-		this.calls += 1
-		yield {
-			id: `msg_${this.calls}`,
-			delta: { content: 'Final answer.' },
-		}
-		yield {
-			id: `msg_${this.calls}`,
-			delta: {},
-			finishReason: 'stop',
-			usage: ZERO_USAGE,
-		}
-	}
-}
-
 /**
  * Gateway that permanently reports one running task. Every dispatch
  * tool is blocking, so a running task at end-of-turn is an orphan —
@@ -84,7 +56,8 @@ describe('end of turn with running agent tasks', () => {
 	// hang detector here: with the busy-wait present this test times
 	// out instead of completing.
 	it('ends the run promptly instead of busy-waiting on orphan tasks', async () => {
-		const provider = new SingleTurnProvider()
+		// One text turn, no tools — the mock's default script shape.
+		const provider = new MockLLMProvider({ turns: [{ text: 'Final answer.' }] })
 		const workingDirectory = await mkdtemp(join(tmpdir(), 'namzu-orphan-task-'))
 		workdirs.push(workingDirectory)
 		const events: RunEvent[] = []
@@ -121,7 +94,8 @@ describe('end of turn with running agent tasks', () => {
 		expect(run.stopReason).toBe('end_turn')
 		expect(run.result).toBe('Final answer.')
 		// One turn only — no futile re-invocation loop on the orphan.
-		expect(provider.calls).toBe(1)
+		// Exactly one model call: the run must NOT busy-wait on the orphan.
+		expect(provider.requests).toHaveLength(1)
 		expect(events.some((event) => event.type === 'run_failed')).toBe(false)
 	}, 10_000)
 })

package/src/runtime/query/__tests__/overflow-relief.test.ts

@@ -0,0 +1,139 @@
+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 { SessionId, TenantId } from '../../../types/ids/index.js'
+import { createUserMessage } from '../../../types/message/index.js'
+import type { ChatCompletionParams, StreamChunk } from '../../../types/provider/index.js'
+import type { ProjectId, ThreadId } from '../../../types/session/ids.js'
+import { drainQuery } from '../index.js'
+
+/**
+ * `context_length_exceeded` is the one provider failure the kernel can act
+ * on. It is correctly non-retryable — resending the identical prompt
+ * cannot help — and the kernel classified it precisely and then let the
+ * run die, while holding a compaction subsystem that could have made room.
+ *
+ * The threshold path guesses when to compact and can guess low, so this is
+ * not a hypothetical: a run carrying images, or a language the
+ * chars-per-token ratio does not fit, reaches the real window while still
+ * reading as comfortable.
+ */
+
+const dirs: string[] = []
+
+afterEach(async () => {
+	await Promise.all(dirs.map((d) => rm(d, { recursive: true, force: true })))
+	dirs.length = 0
+})
+
+/** Overflows until the prompt shrinks, then answers. */
+class OverflowingProvider extends MockLLMProvider {
+	seen: number[] = []
+	constructor(private readonly limitChars: number) {
+		super({ turns: [{ text: 'answered after relief' }] })
+	}
+
+	override async *chatStream(params: ChatCompletionParams): AsyncIterable<StreamChunk> {
+		const size = params.messages.reduce(
+			(n, m) => n + (typeof m.content === 'string' ? m.content.length : 0),
+			0,
+		)
+		this.seen.push(size)
+		if (size > this.limitChars) {
+			throw Object.assign(new Error('prompt is too long for this model: context_length_exceeded'), {
+				status: 400,
+			})
+		}
+		yield* super.chatStream(params)
+	}
+}
+
+async function run(provider: MockLLMProvider, compaction: boolean) {
+	const workingDirectory = await mkdtemp(join(tmpdir(), 'namzu-overflow-'))
+	dirs.push(workingDirectory)
+
+	// A history big enough that shedding it changes the prompt size.
+	const messages = Array.from({ length: 12 }, (_, i) =>
+		createUserMessage(`turn ${i}: ${'context '.repeat(400)}`),
+	)
+
+	return drainQuery({
+		provider,
+		tools: new ToolRegistry(),
+		runConfig: {
+			model: 'mock-model',
+			timeoutMs: 20_000,
+			tokenBudget: 500_000,
+			maxIterations: 6,
+			maxResponseTokens: 256,
+		},
+		agentId: 'agent_o',
+		agentName: 'Overflow',
+		messages,
+		workingDirectory,
+		sessionId: 'ses_o' as SessionId,
+		threadId: 'thd_o' as ThreadId,
+		projectId: 'prj_o' as ProjectId,
+		tenantId: 'tnt_o' as TenantId,
+		retry: false,
+		...(compaction
+			? {
+					compactionConfig: {
+						strategy: 'structured' as const,
+						triggerThreshold: 0.7,
+						resetThreshold: 0.4,
+						keepRecentMessages: 2,
+						clearToolResults: true,
+						keepRecentToolResults: 3,
+						minToolResultCharsToClear: 1_000,
+						maxToolResults: 30,
+						maxListSize: 25,
+						keepFirstEntries: 3,
+						llmVerification: false,
+						llmVerificationMaxTokens: 2048,
+						richStateThreshold: 15,
+						convoTextBudget: 12_000,
+						maxSentencesPerTurn: 5,
+						maxCharsPerNote: 500,
+						maxCharsPerRequirement: 300,
+						maxCharsPerTask: 400,
+					} as never,
+				}
+			: {}),
+	})
+}
+
+describe('a context overflow is relieved rather than fatal', () => {
+	it('compacts and completes instead of dying', async () => {
+		const provider = new OverflowingProvider(20_000)
+		const result = await run(provider, true)
+
+		// Two attempts: the one that overflowed, and the one after relief.
+		expect(provider.seen.length).toBeGreaterThanOrEqual(2)
+		expect(provider.seen[1]).toBeLessThan(provider.seen[0] as number)
+		expect(result.result).toBe('answered after relief')
+		expect(result.stopReason).toBe('end_turn')
+	})
+
+	it('still fails when there is no compaction configured to shed with', async () => {
+		// Relief must not be claimed when nothing can be shed — retrying
+		// would send the identical prompt and arrive at the identical error.
+		const provider = new OverflowingProvider(20_000)
+		const result = await run(provider, false)
+
+		expect(result.status).toBe('failed')
+		expect(provider.seen).toHaveLength(1)
+	})
+
+	it('does not interfere with a run that never overflows', async () => {
+		const provider = new OverflowingProvider(10_000_000)
+		const result = await run(provider, true)
+
+		expect(provider.seen).toHaveLength(1)
+		expect(result.result).toBe('answered after relief')
+	})
+})

package/src/runtime/query/__tests__/partial-batch-resume.test.ts

@@ -0,0 +1,264 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { ActivityStore } from '../../../store/activity/memory.js'
+import { RunDiskStore } from '../../../store/run/disk.js'
+import type { CheckpointId, IterationCheckpoint } from '../../../types/hitl/index.js'
+import type { RunId } from '../../../types/ids/index.js'
+import {
+	type Message,
+	createAssistantMessage,
+	createUserMessage,
+} from '../../../types/message/index.js'
+import type { ToolRegistryContract } from '../../../types/tool/index.js'
+import type { Logger } from '../../../utils/logger.js'
+import { ToolExecutor } from '../executor.js'
+import { planCrashResume, unansweredToolCalls } from '../resume-pending.js'
+
+/**
+ * A batch's results reach the history only when the WHOLE batch settles,
+ * so a hard kill part-way through loses every result that had already come
+ * back — and the resumed run re-executes those calls. For a `write_file`
+ * that is waste; for a payment or an email it is a second one.
+ *
+ * Nothing new had to be recorded to fix it. The executor already awaits a
+ * `tool_completed` per tool, inline, carrying the id, the name, the result
+ * and the error flag, and the transcript already persists it. The record
+ * was durable all along and simply never read back.
+ */
+
+function makeLogger(): Logger {
+	const self = { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() } as unknown as Logger
+	;(self as { child: (ctx: unknown) => Logger }).child = vi.fn(() => self)
+	return self
+}
+
+const call = (id: string, name: string) => ({
+	id,
+	type: 'function' as const,
+	function: { name, arguments: '{}' },
+})
+
+function checkpointWith(messages: Message[]): IterationCheckpoint {
+	return { id: 'cp_1' as CheckpointId, messages } as IterationCheckpoint
+}
+
+const parkedBatch = (): Message[] => [
+	createUserMessage('charge the customer and email them'),
+	{
+		...createAssistantMessage(''),
+		toolCalls: [call('t1', 'charge_card'), call('t2', 'send_email')],
+	} as Message,
+]
+
+describe('reading completed calls back out of the transcript', () => {
+	let dir: string
+	let store: RunDiskStore
+
+	beforeEach(async () => {
+		dir = await mkdtemp(join(tmpdir(), 'namzu-resume-'))
+		store = new RunDiskStore({ baseDir: dir })
+		await store.initRun('run_1')
+	})
+
+	afterEach(async () => {
+		await rm(dir, { recursive: true, force: true })
+	})
+
+	const append = async (lines: unknown[]) => {
+		await writeFile(
+			join(dir, 'run_1', 'transcript.jsonl'),
+			`${lines.map((l) => JSON.stringify(l)).join('\n')}\n`,
+			'utf-8',
+		)
+	}
+
+	it('recovers the calls that finished', async () => {
+		await append([
+			{ type: 'tool_executing', toolUseId: 't1', toolName: 'charge_card' },
+			{
+				type: 'tool_completed',
+				toolUseId: 't1',
+				toolName: 'charge_card',
+				result: 'charged',
+				isError: false,
+			},
+		])
+
+		const completed = await store.readCompletedTools()
+		expect(completed.get('t1')).toEqual({
+			toolUseId: 't1',
+			toolName: 'charge_card',
+			result: 'charged',
+			isError: false,
+		})
+		// The one that never finished must NOT be invented — it still has to
+		// run, and claiming otherwise would drop the work silently.
+		expect(completed.has('t2')).toBe(false)
+	})
+
+	it('keeps the last result when a tool was retried', async () => {
+		await append([
+			{
+				type: 'tool_completed',
+				toolUseId: 't1',
+				toolName: 'fetch',
+				result: 'timeout',
+				isError: true,
+			},
+			{ type: 'tool_completed', toolUseId: 't1', toolName: 'fetch', result: 'ok', isError: false },
+		])
+
+		expect((await store.readCompletedTools()).get('t1')?.result).toBe('ok')
+	})
+
+	it('survives the torn last line a killed process leaves behind', async () => {
+		// This is the ordinary shape of a file that was being appended to
+		// when the process died — which is the exact case being recovered.
+		await writeFile(
+			join(dir, 'run_1', 'transcript.jsonl'),
+			`${JSON.stringify({ type: 'tool_completed', toolUseId: 't1', toolName: 'a', result: 'r', isError: false })}\n{"type":"tool_com`,
+			'utf-8',
+		)
+
+		const completed = await store.readCompletedTools()
+		expect(completed.size).toBe(1)
+	})
+
+	it('returns nothing when the run never wrote a transcript', async () => {
+		expect((await store.readCompletedTools()).size).toBe(0)
+	})
+
+	it('ignores an event missing the fields that identify a call', async () => {
+		await append([{ type: 'tool_completed', result: 'orphan', isError: false }])
+		expect((await store.readCompletedTools()).size).toBe(0)
+	})
+})
+
+describe('planning the resume of a part-executed batch', () => {
+	it('takes over when some calls already ran', () => {
+		const messages = parkedBatch()
+		const plan = planCrashResume(checkpointWith(messages), new Map([['t1', {}]]), makeLogger())
+
+		expect(plan).not.toBeNull()
+		// The assistant turn is kept, not stripped: the results about to be
+		// produced have to answer the `tool_use` blocks that are in it.
+		expect(plan?.response.message.toolCalls).toHaveLength(2)
+		expect(plan?.denials.size).toBe(0)
+	})
+
+	it('leaves an untouched batch to the ordinary repair', () => {
+		// A tool-review park records the checkpoint BEFORE any execution, so
+		// nothing completed and re-deciding costs only a round trip. Taking
+		// it over here would execute calls a human had not answered yet.
+		expect(planCrashResume(checkpointWith(parkedBatch()), new Map(), makeLogger())).toBeNull()
+	})
+
+	it('says which calls are about to run for the first time', () => {
+		const log = makeLogger()
+		planCrashResume(checkpointWith(parkedBatch()), new Map([['t1', {}]]), log)
+
+		const warned = (log.warn as unknown as { mock: { calls: unknown[][] } }).mock.calls[0]
+		expect(warned?.[1]).toMatchObject({ completed: 1, total: 2, remaining: ['send_email'] })
+	})
+
+	it('does nothing when the turn is fully answered', () => {
+		const messages: Message[] = [
+			...parkedBatch(),
+			{ role: 'tool', content: 'charged', toolCallId: 't1' } as Message,
+			{ role: 'tool', content: 'sent', toolCallId: 't2' } as Message,
+		]
+		expect(
+			planCrashResume(checkpointWith(messages), new Map([['t1', {}]]), makeLogger()),
+		).toBeNull()
+	})
+})
+
+describe('executing a batch that carries recovered results', () => {
+	const response = {
+		message: {
+			role: 'assistant',
+			content: null,
+			toolCalls: [call('t1', 'charge_card'), call('t2', 'send_email')],
+		},
+		finishReason: 'tool_calls',
+		usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+	} as never
+
+	async function runBatch(prior?: ReadonlyMap<string, { result: string; isError: boolean }>) {
+		const execute = vi.fn(async () => ({ success: true, output: 'freshly executed' }))
+		const tools = {
+			register: vi.fn(),
+			unregister: vi.fn(),
+			execute,
+			get: vi.fn(() => ({ isConcurrencySafe: () => true })),
+			has: vi.fn(() => true),
+			listNames: vi.fn(() => []),
+			getAvailability: vi.fn(),
+		} as unknown as ToolRegistryContract
+
+		const executor = new ToolExecutor(
+			{
+				tools,
+				runId: 'run_1' as RunId,
+				workingDirectory: tmpdir(),
+				permissionMode: 'auto',
+				env: {},
+				abortSignal: new AbortController().signal,
+			},
+			new ActivityStore('run_1' as RunId, {
+				enabled: false,
+				trackToolCalls: false,
+				trackLlmTurns: false,
+			}),
+			async () => {},
+			makeLogger(),
+		)
+
+		const batch = await executor.executeBatch(response, undefined, prior)
+		return { batch, execute }
+	}
+
+	it('does not run a tool that already ran', async () => {
+		const { batch, execute } = await runBatch(
+			new Map([['t1', { result: 'charged $40', isError: false }]]),
+		)
+
+		// The whole point: charging the card twice is the failure.
+		expect(execute).toHaveBeenCalledTimes(1)
+		expect(batch.results.find((r) => r.toolCallId === 't1')?.output).toBe('charged $40')
+	})
+
+	it('still runs the calls that never completed', async () => {
+		const { batch } = await runBatch(new Map([['t1', { result: 'charged', isError: false }]]))
+		expect(batch.results.find((r) => r.toolCallId === 't2')?.output).toBe('freshly executed')
+		// Every `tool_use` block is answered, in the original order.
+		expect(batch.results.map((r) => r.toolCallId)).toEqual(['t1', 't2'])
+	})
+
+	it('preserves a recovered failure as a failure', async () => {
+		const { batch } = await runBatch(new Map([['t1', { result: 'declined', isError: true }]]))
+		expect(batch.results.find((r) => r.toolCallId === 't1')?.isError).toBe(true)
+	})
+
+	it('runs everything when nothing was recovered', async () => {
+		const { execute } = await runBatch()
+		expect(execute).toHaveBeenCalledTimes(2)
+	})
+})
+
+describe('which calls are worth asking about', () => {
+	it('is only the unanswered ones', () => {
+		const messages: Message[] = [
+			...parkedBatch(),
+			{ role: 'tool', content: 'charged', toolCallId: 't1' } as Message,
+		]
+		expect(unansweredToolCalls(messages).map((tc) => tc.id)).toEqual(['t2'])
+	})
+
+	it('is empty when the history holds no tool calls at all', () => {
+		expect(unansweredToolCalls([createUserMessage('hello')])).toEqual([])
+	})
+})

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

@@ -19,7 +19,6 @@ describe('applyLifecycleHookResults', () => {
 		['skip', { action: 'skip', reason: 'no' } as PluginHookResult],
 		['modify', { action: 'modify', input: {} } as PluginHookResult],
 		['retry', { action: 'retry' } as PluginHookResult],
-		['resume', { action: 'resume', input: 'x' } as PluginHookResult],
 	])('throws on unsupported %s action for lifecycle event', (_, result) => {
 		expect(() => applyLifecycleHookResults('iteration_start', [result])).toThrow(
 			/unsupported action/,