@namzu/sdk 2.0.0 → 3.0.0

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

@@ -0,0 +1,288 @@
+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/checkpoint.ts

@@ -1,10 +1,14 @@
+import type { WorkingStateSnapshot } from '../../compaction/wire.js'
 import type { RunPersistence } from '../../manager/run/persistence.js'
+import type { SerializedSpanContext } from '../../telemetry/attributes.js'
+import { NamzuError } from '../../types/errors/index.js'
 import type {
-	ActiveNodeInfo,
-	BranchStackEntry,
 	CheckpointId,
 	CheckpointSummary,
+	HITLDecisionRequest,
+	HITLResumeDecision,
 	IterationCheckpoint,
+	PendingDecision,
 } from '../../types/hitl/index.js'
 import type { AssistantMessage } from '../../types/message/index.js'
 import type { CheckpointRunScope, CheckpointStore } from '../../types/run/checkpoint-store.js'
@@ -34,9 +38,9 @@ export function toCheckpointListEntry(cp: IterationCheckpoint): CheckpointListEn
  * shape so `replay({ fromCheckpoint: 'emergency' })` can consume it through
  * the same restore path as any other checkpoint.
  *
- * The projection is lossy: `costInfo`, `guardState.elapsedMs`,
- * `toolResultHashes`, `branchStack`, and `activeNode` are not captured at
- * emergency-save time and default to zero/empty values. The synthetic
+ * The projection is lossy: `costInfo`, `guardState.elapsedMs` and
+ * `toolResultHashes` are not captured at emergency-save time and default
+ * to zero/empty values. The synthetic
  * checkpoint id is derived deterministically from the emergency save id so
  * re-projecting the same dump yields the same {@link CheckpointId}.
  *
@@ -59,9 +63,90 @@ export function projectEmergencyToCheckpoint(dump: EmergencySaveData): Iteration
 	}
 }
 
+/**
+ * The newest checkpoint of a run that is still awaiting a human decision,
+ * or `null` when the run is not parked.
+ *
+ * Standalone (not a `CheckpointManager` method) so a host can ask the
+ * question without constructing a run: an approval-queue worker in a
+ * different process has a store and a scope, and nothing else.
+ */
+export async function findPendingCheckpoint(
+	store: CheckpointStore,
+	scope: CheckpointRunScope,
+	options?: { readonly now?: number },
+): Promise<IterationCheckpoint | null> {
+	const all = await store.listCheckpoints(scope)
+	const now = options?.now ?? Date.now()
+	// `listCheckpoints` is contractually ascending by `createdAt`; the
+	// newest outstanding park is the one a human should be answering.
+	for (let i = all.length - 1; i >= 0; i--) {
+		const cp = all[i] as IterationCheckpoint
+		if (!cp.pending || cp.pending.resolvedAt !== undefined) continue
+		// An expired park is not outstanding. Serving it re-presents an
+		// approval whose window has closed, and every queue reader would
+		// keep re-presenting it forever — a redeployed worker leaves a park
+		// nobody will ever answer and nothing in-process can time out.
+		if (isExpiredPark(cp.pending, now)) continue
+		return cp
+	}
+	return null
+}
+
+/** Whether a park's absolute deadline has passed. No deadline never expires. */
+export function isExpiredPark(pending: PendingDecision, now = Date.now()): boolean {
+	return pending.deadlineAt !== undefined && now >= pending.deadlineAt
+}
+
+/**
+ * Every outstanding park in a run, expired ones included, so a host can
+ * sweep them.
+ *
+ * The out-of-process timer stays a host concern — consistent with the same
+ * decision made for retention — but a host cannot sweep what it cannot
+ * enumerate, and this is the read that makes a sweep a few lines rather
+ * than a re-implementation of the store contract.
+ */
+export async function listExpiredParks(
+	store: CheckpointStore,
+	scope: CheckpointRunScope,
+	options?: { readonly now?: number },
+): Promise<IterationCheckpoint[]> {
+	const all = await store.listCheckpoints(scope)
+	const now = options?.now ?? Date.now()
+	return all.filter(
+		(cp) => cp.pending && cp.pending.resolvedAt === undefined && isExpiredPark(cp.pending, now),
+	)
+}
+
 export class CheckpointManager {
 	private store: CheckpointStore
 	private scope: CheckpointRunScope
+	/**
+	 * Compaction's state source, when the run has one.
+	 *
+	 * Every checkpoint snapshots it, so a resumed run can carry forward the
+	 * state its earlier summary was built from. Without that the next
+	 * compaction supersedes that summary with one covering only post-resume
+	 * activity, and the record of everything before the resume is gone.
+	 */
+	private workingStateSource?: () => WorkingStateSnapshot | undefined
+
+	/**
+	 * The most recent checkpoint this manager wrote, if any.
+	 *
+	 * A run that fails on a transient error needs to name the state a host
+	 * should resume from. Re-listing the store to find it would be a disk
+	 * read on the failure path, at the moment the run is least able to
+	 * afford one; the id is already in hand.
+	 */
+	private lastCreatedId?: CheckpointId
+
+	/** See {@link setTraceSource}. */
+	private traceSource?: () => SerializedSpanContext | undefined
+
+	/** See {@link setParkTtl}. */
+	private parkTtlMs?: number
 
 	/**
 	 * @param store scope-keyed checkpoint persistence. The default query
@@ -75,13 +160,26 @@ export class CheckpointManager {
 		this.scope = scope
 	}
 
+	/** Wire compaction's state in, so every checkpoint carries a snapshot. */
+	setWorkingStateSource(source: () => WorkingStateSnapshot | undefined): void {
+		this.workingStateSource = source
+	}
+
+	/**
+	 * The run's root span, so every checkpoint records the trace it was
+	 * taken inside and a resume can join it rather than starting a second,
+	 * unlinked one.
+	 */
+	setTraceSource(source: () => SerializedSpanContext | undefined): void {
+		this.traceSource = source
+	}
+
 	async create(
 		runMgr: RunPersistence,
 		iteration: number,
 		extra?: {
 			toolResults?: Array<{ toolCallId: string; toolName: string; input: unknown; output: string }>
-			branchStack?: BranchStackEntry[]
-			activeNode?: ActiveNodeInfo
+			workingState?: WorkingStateSnapshot
 		},
 	): Promise<IterationCheckpoint> {
 		const checkpoint: IterationCheckpoint = {
@@ -97,18 +195,152 @@ export class CheckpointManager {
 			},
 			createdAt: Date.now(),
 			toolResultHashes: extra?.toolResults ? buildToolResultHashes(extra.toolResults) : undefined,
-			branchStack: extra?.branchStack,
-			activeNode: extra?.activeNode,
+			workingState: extra?.workingState ?? this.workingStateSource?.(),
+			traceContext: this.traceSource?.(),
 		}
 
 		await this.store.writeCheckpoint(this.scope, checkpoint)
+		this.lastCreatedId = checkpoint.id
 		return checkpoint
 	}
 
+	/** See {@link lastCreatedId}. */
+	get lastCheckpointId(): CheckpointId | undefined {
+		return this.lastCreatedId
+	}
+
+	/**
+	 * The trace a checkpoint was taken inside, for parenting a resumed run.
+	 *
+	 * Read separately and BEFORE the run's root span, because a span's
+	 * parent can only be set at creation and the root is minted before the
+	 * restore branch runs.
+	 *
+	 * Never throws. Telemetry continuity is worth a disk read; it is not
+	 * worth failing a resume over, and the restore path immediately after
+	 * will report a genuinely unreadable checkpoint far better than a
+	 * tracing helper could.
+	 */
+	async readTraceContext(checkpointId: CheckpointId): Promise<SerializedSpanContext | undefined> {
+		try {
+			const checkpoint = await this.store.readCheckpoint(this.scope, checkpointId)
+			return checkpoint?.traceContext
+		} catch {
+			return undefined
+		}
+	}
+
+	/**
+	 * Record that the run parked at `checkpoint` awaiting a human, and
+	 * return the updated checkpoint.
+	 *
+	 * A park used to exist only as a suspended `await`: the checkpoint
+	 * written just before it was indistinguishable from any mid-run
+	 * checkpoint, so a host could not tell from durable state that a
+	 * decision was outstanding — and a process boundary lost the request
+	 * entirely. Writing the request down is what lets an approval queue be
+	 * rebuilt, and what lets a resumed run apply the answer to the exact
+	 * tool calls the human saw.
+	 *
+	 * Called after `create` rather than as an argument to it because the
+	 * request carries the checkpoint's own id.
+	 */
+	async park(
+		checkpoint: IterationCheckpoint,
+		request: HITLDecisionRequest,
+		options?: { readonly ttlMs?: number },
+	): Promise<IterationCheckpoint> {
+		const parkedAt = Date.now()
+		const ttl = options?.ttlMs ?? this.parkTtlMs
+		const parked: IterationCheckpoint = {
+			...checkpoint,
+			pending: {
+				request,
+				parkedAt,
+				// Absolute, so it survives the process that set it. A
+				// duration plus an in-process timer cannot: the worker gets
+				// redeployed and the park becomes immortal.
+				...(ttl !== undefined && ttl > 0 ? { deadlineAt: parkedAt + ttl } : {}),
+			},
+		}
+		await this.store.writeCheckpoint(this.scope, parked)
+		return parked
+	}
+
+	/** Default time-to-live applied to every park this manager records. */
+	setParkTtl(ttlMs: number | undefined): void {
+		this.parkTtlMs = ttlMs
+	}
+
+	/**
+	 * Mark an expired park as no longer outstanding.
+	 *
+	 * Recorded rather than deleted: the checkpoint showing what was asked
+	 * and that nobody answered in time is the evidence an approval gate is
+	 * worth having, and the same reasoning already keeps a resolved
+	 * decision on the record.
+	 */
+	async expire(checkpointId: CheckpointId): Promise<IterationCheckpoint | null> {
+		const checkpoint = await this.store.readCheckpoint(this.scope, checkpointId)
+		if (!checkpoint?.pending || checkpoint.pending.resolvedAt !== undefined) return null
+
+		const expired: IterationCheckpoint = {
+			...checkpoint,
+			pending: {
+				...checkpoint.pending,
+				resolvedAt: Date.now(),
+				// The park ended by running out of time, not by a decision.
+				// An `abort` here would read as somebody having refused it.
+				decision: { action: 'pause', reason: 'The approval request expired without an answer.' },
+			},
+		}
+		await this.store.writeCheckpoint(this.scope, expired)
+		return expired
+	}
+
+	/**
+	 * Record the answer, so an outstanding park stops looking outstanding.
+	 *
+	 * The decision is kept rather than erased: a checkpoint that shows both
+	 * what was asked and what was answered is the evidence trail an
+	 * approval gate is worth having. A no-op when the checkpoint is gone
+	 * (pruned) or was never parked.
+	 */
+	async unpark(
+		checkpointId: CheckpointId,
+		decision: HITLResumeDecision,
+	): Promise<IterationCheckpoint | null> {
+		const checkpoint = await this.store.readCheckpoint(this.scope, checkpointId)
+		if (!checkpoint?.pending) return null
+
+		const resolved: IterationCheckpoint = {
+			...checkpoint,
+			pending: { ...checkpoint.pending, resolvedAt: Date.now(), decision },
+		}
+		await this.store.writeCheckpoint(this.scope, resolved)
+		return resolved
+	}
+
+	/**
+	 * The run's outstanding park, if it has one — the newest checkpoint
+	 * whose `pending` has no `resolvedAt`.
+	 *
+	 * This is the read a host's approval queue is built from, and it works
+	 * across a process boundary because it consults the store rather than
+	 * in-memory state.
+	 */
+	async findPending(): Promise<IterationCheckpoint | null> {
+		return findPendingCheckpoint(this.store, this.scope)
+	}
+
 	async restore(checkpointId: CheckpointId): Promise<IterationCheckpoint> {
 		const checkpoint = await this.store.readCheckpoint(this.scope, checkpointId)
 		if (!checkpoint) {
-			throw new Error(`Checkpoint not found: ${checkpointId}`)
+			throw new NamzuError({
+				code: 'not_found',
+				message: `Checkpoint not found: ${checkpointId}`,
+				details: { checkpointId, runId: this.scope.runId },
+			})
 		}
 		return checkpoint
 	}

package/src/runtime/query/events.ts

@@ -21,7 +21,7 @@ export type EmitEvent = (event: RunEvent) => Promise<void>
  * (100 deltas/s sustained) before pressure kicks in. Tune via
  * empirical evidence; not a hard guarantee, just a safety net.
  *
- * Codex D2 (ses_001-tool-stream-events).
+ * See ses_001-tool-stream-events.
  */
 const PENDING_EVENT_SOFT_CAP = 1000
 
@@ -70,7 +70,7 @@ export class EventTranslator {
 		// They live only on the in-memory bus for live UI rendering.
 		// Replay (`runtime/query/replay/prepare.ts`) reads checkpoints
 		// not transcripts, so this preserves replay fidelity while
-		// eliminating the durable bloat codex flagged.
+		// eliminating the durable bloat review flagged.
 		if (!isEphemeralEvent(event)) {
 			await this.runMgr.getRunStore().appendEvent(event)
 		}