@namzu/sdk 3.0.0 → 3.2.0

package/src/runtime/query/iteration/phases/context-reducer-dispatch.test.ts

@@ -0,0 +1,238 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { WorkingStateManager } from '../../../../compaction/manager.js'
+import type { ContextReducer } from '../../../../compaction/reducer.js'
+import { CompactionConfigSchema } from '../../../../config/runtime.js'
+import type { CompactionConfig } from '../../../../config/runtime.js'
+import type { Message } from '../../../../types/message/index.js'
+import { runCompactionCheck } from './compaction.js'
+import type { IterationContext } from './context.js'
+
+/**
+ * `strategy` had three values and two behaviours.
+ *
+ * The runtime asked only `strategy !== 'disabled'`, so `'sliding-window'` —
+ * the name a host picks precisely to AVOID paying for summarization — ran the
+ * full structured pass, model call included. These tests are about the
+ * dispatch rather than the algorithms: that choosing a strategy selects one,
+ * that a host-supplied reducer outranks the enum, and that the structured
+ * pass does not also run when something else owns reduction.
+ */
+
+const sys = (content: string): Message => ({ role: 'system', content, timestamp: 1 })
+const user = (content: string): Message => ({ role: 'user', content, timestamp: 1 })
+
+function longHistory(): Message[] {
+	// Long enough to be over any threshold once the window is small.
+	return [sys('prompt'), ...Array.from({ length: 40 }, (_, i) => user(`turn ${i} `.repeat(200)))]
+}
+
+interface Harness {
+	readonly ctx: IterationContext
+	readonly messages: Message[]
+	readonly providerCalls: () => number
+	readonly warnings: string[]
+}
+
+function harness(
+	over: Partial<IterationContext> & { compaction?: Partial<CompactionConfig> },
+): Harness {
+	const messages = longHistory()
+	const config: CompactionConfig = {
+		...CompactionConfigSchema.parse({}),
+		// A tiny window puts the run over the trigger immediately.
+		contextWindowTokens: 1_000,
+		keepRecentMessages: 4,
+		...over.compaction,
+	}
+	const warnings: string[] = []
+	let providerCalls = 0
+
+	const ctx = {
+		compactionConfig: config,
+		workingStateManager: new WorkingStateManager(config),
+		runConfig: { model: 'mock-model' },
+		runMgr: {
+			id: 'run_dispatch',
+			messages,
+			accumulateUsage: vi.fn(),
+			clearLastPromptTokens: vi.fn(),
+		},
+		provider: {
+			// The structured path's only observable side effect that a reducer
+			// path must not have: it pays for a summary.
+			chat: async () => {
+				providerCalls++
+				return { content: 'summary', usage: { promptTokens: 1, completionTokens: 1 } }
+			},
+		},
+		log: {
+			debug: vi.fn(),
+			info: vi.fn(),
+			warn: (message: string) => warnings.push(message),
+			error: vi.fn(),
+		},
+		...over,
+	} as unknown as IterationContext
+
+	return { ctx, messages, providerCalls: () => providerCalls, warnings }
+}
+
+describe('choosing a strategy selects one', () => {
+	it("'sliding-window' trims and summarizes nothing", async () => {
+		const h = harness({ compaction: { strategy: 'sliding-window', llmVerification: true } })
+
+		await runCompactionCheck(h.ctx)
+
+		expect(h.messages.length).toBeLessThan(41)
+		// The whole reason a host names this strategy.
+		expect(h.providerCalls()).toBe(0)
+		// Every survivor is verbatim — no `[COMPACTED CONTEXT]` block appears.
+		expect(h.messages.some((m) => String(m.content).includes('COMPACTED CONTEXT'))).toBe(false)
+	})
+
+	it("'structured' still summarizes", async () => {
+		const h = harness({ compaction: { strategy: 'structured', llmVerification: false } })
+
+		await runCompactionCheck(h.ctx)
+
+		expect(h.messages.some((m) => String(m.content).includes('COMPACTED CONTEXT'))).toBe(true)
+	})
+
+	it("'disabled' leaves the history alone", async () => {
+		const h = harness({ compaction: { strategy: 'disabled' } })
+
+		await runCompactionCheck(h.ctx)
+
+		expect(h.messages.length).toBe(41)
+	})
+})
+
+describe('a host reducer outranks the enum', () => {
+	it('runs instead of the structured pass', async () => {
+		// Deliberately NOT a tiny slice: leave more than the structured pass
+		// needs to act, so "the reducer ran" and "only the reducer ran" are
+		// different observations.
+		const reduce: ContextReducer = ({ messages }) => messages.slice(0, 20)
+		const h = harness({ contextReducer: reduce, compaction: { strategy: 'structured' } })
+
+		await runCompactionCheck(h.ctx)
+
+		expect(h.messages.length).toBe(20)
+		expect(h.messages.some((m) => String(m.content).includes('COMPACTED CONTEXT'))).toBe(false)
+	})
+
+	it('is told whether the provider already rejected the prompt', async () => {
+		const seen: string[] = []
+		const reduce: ContextReducer = ({ messages, reason }) => {
+			seen.push(reason)
+			return messages.slice(0, 5)
+		}
+		const h = harness({ contextReducer: reduce })
+
+		await runCompactionCheck(h.ctx)
+		await runCompactionCheck(h.ctx, { force: true })
+
+		expect(seen).toEqual(['threshold', 'overflow'])
+	})
+
+	it('may be async, so a reducer can call a model of its own', async () => {
+		const reduce: ContextReducer = async ({ messages }) => {
+			await Promise.resolve()
+			return messages.slice(0, 3)
+		}
+		const h = harness({ contextReducer: reduce })
+
+		await runCompactionCheck(h.ctx)
+
+		expect(h.messages.length).toBe(3)
+	})
+
+	it('gets the window it has to fit, not the run token budget', async () => {
+		let saw = 0
+		const reduce: ContextReducer = ({ contextWindowTokens, messages }) => {
+			saw = contextWindowTokens
+			return messages.slice(0, 5)
+		}
+		const h = harness({ contextReducer: reduce, compaction: { contextWindowTokens: 12_345 } })
+
+		await runCompactionCheck(h.ctx)
+
+		expect(saw).toBe(12_345)
+	})
+})
+
+describe('a reducer that cannot be trusted is not obeyed', () => {
+	it('keeps the full history when the reducer throws', async () => {
+		const reduce: ContextReducer = () => {
+			throw new Error('boom')
+		}
+		const h = harness({ contextReducer: reduce })
+
+		await runCompactionCheck(h.ctx)
+
+		// Fail open: a broken reduction hook should not take down a healthy run,
+		// the same way a broken `prepareStep` does not.
+		expect(h.messages.length).toBe(41)
+		expect(h.warnings.some((w) => w.includes('threw'))).toBe(true)
+	})
+
+	it('refuses a result that orphans a tool result', async () => {
+		const h = harness({
+			contextReducer: ({ messages }) => [
+				messages[0] as Message,
+				{ role: 'tool', content: 'ok', timestamp: 1, toolCallId: 'nobody' } as Message,
+			],
+		})
+
+		await runCompactionCheck(h.ctx)
+
+		// Installing this would trade a nameable "your reducer split a tool
+		// pair" for an opaque provider rejection a call later.
+		expect(h.messages.length).toBe(41)
+		expect(h.warnings.some((w) => w.includes('split a tool pair'))).toBe(true)
+	})
+
+	it('ignores a reducer that returns the history unchanged', async () => {
+		const h = harness({ contextReducer: ({ messages }) => messages })
+
+		await runCompactionCheck(h.ctx)
+
+		expect(h.messages.length).toBe(41)
+	})
+
+	it('leaves the history alone when the reducer declines', async () => {
+		const h = harness({ contextReducer: () => undefined })
+
+		await runCompactionCheck(h.ctx)
+
+		expect(h.messages.length).toBe(41)
+	})
+})
+
+describe('the threshold still governs a reducer', () => {
+	it('does not run one below the trigger', async () => {
+		const reduce = vi.fn(() => undefined)
+		const h = harness({
+			contextReducer: reduce,
+			// A window far larger than the history.
+			compaction: { contextWindowTokens: 10_000_000 },
+		})
+
+		await runCompactionCheck(h.ctx)
+
+		expect(reduce).not.toHaveBeenCalled()
+	})
+
+	it('runs one below the trigger when the provider forced the issue', async () => {
+		const reduce = vi.fn(() => undefined)
+		const h = harness({
+			contextReducer: reduce,
+			compaction: { contextWindowTokens: 10_000_000 },
+		})
+
+		await runCompactionCheck(h.ctx, { force: true })
+
+		expect(reduce).toHaveBeenCalledOnce()
+	})
+})

package/src/runtime/query/iteration/phases/context.ts

@@ -1,6 +1,7 @@
 import type { AdvisoryContext } from '../../../../advisory/context.js'
 import type { AgentBus } from '../../../../bus/index.js'
 import type { WorkingStateManager } from '../../../../compaction/manager.js'
+import type { ContextReducer } from '../../../../compaction/reducer.js'
 import type { CompactionConfig } from '../../../../config/runtime.js'
 import type { PlanManager } from '../../../../manager/plan/lifecycle.js'
 import type { RunPersistence } from '../../../../manager/run/persistence.js'
@@ -14,6 +15,7 @@ import type {
 } from '../../../../types/hitl/index.js'
 import type { TaskId } from '../../../../types/ids/index.js'
 import type { LLMProvider } from '../../../../types/provider/index.js'
+import type { TaskRouterConfig } from '../../../../types/router/index.js'
 import type { ReviewAnswer } from '../../../../types/run/answer-review.js'
 import type {
 	AgentRunConfig,
@@ -104,10 +106,19 @@ export interface IterationContext {
 	 */
 	readonly toolGrants?: ToolGrantSet
 
+	/** Per-task model overrides. Consulted for the compaction summary call. */
+	readonly taskRouter?: TaskRouterConfig
+
 	readonly compactionConfig?: CompactionConfig
 
 	readonly workingStateManager?: WorkingStateManager
 
+	/**
+	 * Host-supplied context reduction. Outranks `compactionConfig.strategy`
+	 * and replaces the structured pass for this run.
+	 */
+	readonly contextReducer?: ContextReducer
+
 	readonly workingMemoryProvider?: WorkingMemoryProvider
 
 	readonly advisoryCtx?: AdvisoryContext

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

@@ -0,0 +1,93 @@
+import type { PendingDecision } from '../../types/hitl/index.js'
+import type { CheckpointStore } from '../../types/run/checkpoint-store.js'
+import type { Run } from '../../types/run/entity.js'
+import type { RunState } from '../../types/run/state.js'
+import { type QueryParams, drainQuery } from './index.js'
+import { type RunStateScope, loadRunState } from './run-state.js'
+
+/**
+ * What a resume attempt found.
+ *
+ * Three outcomes rather than a nullable `Run`, because the two failures
+ * mean opposite things to a caller. "No checkpoint" is a dead end — there
+ * is nothing to continue and starting fresh would be a different run
+ * wearing the same id. "Awaiting decision" is the run working as designed:
+ * it parked on a question, and continuing means answering it first.
+ */
+export type ResumeOutcome =
+	| { readonly resumed: false; readonly reason: 'no-checkpoint' }
+	| {
+			readonly resumed: false
+			readonly reason: 'awaiting-decision'
+			/** What to put in front of a human. */
+			readonly pending: PendingDecision
+			readonly state: RunState
+	  }
+	| { readonly resumed: true; readonly run: Run; readonly state: RunState }
+
+/**
+ * The half of a run that cannot be serialized, plus where to look.
+ *
+ * `messages` is deliberately absent. On resume the history comes from the
+ * checkpoint and any passed messages would be discarded, so accepting them
+ * would invite a caller to hand over a transcript that is silently ignored.
+ */
+export interface ResumeRunParams
+	extends Omit<QueryParams, 'messages' | 'runId' | 'resumeFromCheckpoint'> {
+	/** Identifies the run inside the checkpoint store. */
+	readonly scope: RunStateScope
+	/** Required to find the checkpoint; also threaded into the resumed run. */
+	readonly checkpointStore: CheckpointStore
+	/**
+	 * Resume a specific checkpoint instead of the one the store would pick.
+	 * Absent means the parked checkpoint if there is one, else the newest.
+	 */
+	readonly checkpointId?: RunState['checkpointId']
+}
+
+/**
+ * Continue a run that a different process started.
+ *
+ * Everything this needs already existed — `CheckpointManager` writes the
+ * history, budgets, working state, trace context and any park;
+ * `loadRunState` reads them back; `query` accepts `runId` +
+ * `resumeFromCheckpoint` and restores all of it. What was missing was the
+ * few lines that join them, so every host wrote their own — and in this
+ * repo nothing outside the SDK ever did, which means the whole path shipped
+ * untravelled.
+ *
+ * The division of labour is the one the mechanism already implies: the
+ * CALLER brings what cannot be serialized — the provider client, the tool
+ * registry, the sandbox, the working directory — and the STORE brings the
+ * state. A snapshot deliberately holds no socket, no client and no open
+ * file, so it could never have carried the first half.
+ *
+ * Refusing beats guessing at both failure points. A missing checkpoint does
+ * not silently become a fresh run under a recycled id, and a park is not
+ * resumed past without the answer it is waiting for.
+ */
+export async function resumeRun(params: ResumeRunParams): Promise<ResumeOutcome> {
+	const { scope, checkpointStore, checkpointId, pendingDecision, ...rest } = params
+
+	const state = await loadRunState(checkpointStore, scope, checkpointId)
+	if (!state?.checkpointId) return { resumed: false, reason: 'no-checkpoint' }
+
+	// A park is outstanding until it is answered. `resolvedAt` is what marks
+	// an answered one, so a checkpoint that carries a resolved decision is an
+	// ordinary resume, not a question waiting on anybody.
+	const outstanding = state.pending && !state.pending.resolvedAt ? state.pending : undefined
+	if (outstanding && !pendingDecision) {
+		return { resumed: false, reason: 'awaiting-decision', pending: outstanding, state }
+	}
+
+	const run = await drainQuery({
+		...rest,
+		messages: [],
+		runId: state.runId,
+		resumeFromCheckpoint: state.checkpointId,
+		checkpointStore,
+		...(pendingDecision ? { pendingDecision } : {}),
+	} as QueryParams)
+
+	return { resumed: true, run, state }
+}

package/src/telemetry/__tests__/model-call-span.test.ts

@@ -0,0 +1,189 @@
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+/**
+ * There was no span around the model call at all.
+ *
+ * `chatSpanName` shipped in the telemetry attributes with zero call sites,
+ * so a run's traces carried no LLM latency whatsoever — and the one thing
+ * anybody opens a trace to find, which turn was slow and why, was the one
+ * thing missing from it. The token counts landed on the iteration span
+ * instead of the operation that produced them.
+ */
+
+interface Recorded {
+	name: string
+	attributes: Record<string, unknown>
+	ended: boolean
+	status?: number
+}
+
+const spans: Recorded[] = []
+
+vi.mock('../runtime-accessors.js', () => ({
+	getTracer: () => ({
+		startSpan: (name: string) => {
+			const rec: Recorded = { name, attributes: {}, ended: false }
+			spans.push(rec)
+			return {
+				setAttributes: (a: Record<string, unknown>) => Object.assign(rec.attributes, a),
+				setAttribute: (k: string, v: unknown) => {
+					rec.attributes[k] = v
+				},
+				setStatus: (s: { code: number }) => {
+					rec.status = s.code
+				},
+				recordException: () => undefined,
+				addEvent: () => undefined,
+				end: () => {
+					rec.ended = true
+				},
+				spanContext: () => ({ traceId: 't', spanId: 's', traceFlags: 1 }),
+				isRecording: () => true,
+				updateName: () => undefined,
+			}
+		},
+		startActiveSpan: (_n: string, _o: unknown, _c: unknown, fn: (s: unknown) => unknown) =>
+			fn({
+				setAttributes: () => undefined,
+				setStatus: () => undefined,
+				recordException: () => undefined,
+				end: () => undefined,
+				spanContext: () => ({ traceId: 't', spanId: 's', traceFlags: 1 }),
+				isRecording: () => true,
+			}),
+	}),
+	getMeter: () => ({
+		createCounter: () => ({ add: () => undefined }),
+		createHistogram: () => ({ record: () => undefined }),
+	}),
+}))
+
+let workdirs: string[] = []
+
+beforeEach(() => {
+	spans.length = 0
+})
+
+afterEach(async () => {
+	await Promise.all(workdirs.map((d) => rm(d, { recursive: true, force: true })))
+	workdirs = []
+})
+
+async function runOnce(turns: { text?: string }[]): Promise<void> {
+	const { MockLLMProvider } = await import('../../provider/mock.js')
+	const { ToolRegistry } = await import('../../registry/tool/execute.js')
+	const { drainQuery } = await import('../../runtime/query/index.js')
+	const { createUserMessage } = await import('../../types/message/index.js')
+
+	const dir = await mkdtemp(join(tmpdir(), 'namzu-chatspan-'))
+	workdirs.push(dir)
+
+	await drainQuery({
+		provider: new MockLLMProvider({ turns: turns as never }),
+		tools: new ToolRegistry(),
+		runConfig: {
+			model: 'mock-model',
+			timeoutMs: 30_000,
+			tokenBudget: 100_000,
+			maxIterations: 3,
+			maxResponseTokens: 256,
+			temperature: 0.3,
+		},
+		agentId: 'agent_cs',
+		agentName: 'Chat Span Agent',
+		workingDirectory: dir,
+		sessionId: 'ses_cs',
+		threadId: 'thd_cs',
+		projectId: 'prj_cs',
+		tenantId: 'tnt_cs',
+		messages: [createUserMessage('go')],
+	} as never)
+}
+
+const chatSpans = () => spans.filter((s) => s.name.startsWith('chat '))
+
+describe('the model call has a span of its own', () => {
+	it('opens one named for the model', async () => {
+		await runOnce([{ text: 'done' }])
+
+		// One per model call. A run makes at least one, and a forced-final
+		// turn makes another — both are model calls and both deserve a span.
+		expect(chatSpans().length).toBeGreaterThanOrEqual(1)
+		for (const s of chatSpans()) expect(s.name).toBe('chat mock-model')
+	})
+
+	it('closes it', async () => {
+		await runOnce([{ text: 'done' }])
+
+		for (const s of chatSpans()) expect(s.ended).toBe(true)
+	})
+
+	it('carries the request parameters that were actually used', async () => {
+		await runOnce([{ text: 'done' }])
+
+		const attrs = chatSpans()[0]?.attributes ?? {}
+		expect(attrs['gen_ai.operation.name']).toBe('chat')
+		expect(attrs['gen_ai.request.model']).toBe('mock-model')
+		expect(attrs['gen_ai.request.temperature']).toBe(0.3)
+		expect(attrs['gen_ai.request.max_tokens']).toBe(256)
+	})
+
+	it('carries the usage on the call that produced it', async () => {
+		await runOnce([{ text: 'done' }])
+
+		const attrs = chatSpans()[0]?.attributes ?? {}
+		// These previously landed only on the iteration span — one level up
+		// from the operation that spent the tokens.
+		expect(attrs).toHaveProperty('gen_ai.usage.input_tokens')
+		expect(attrs).toHaveProperty('gen_ai.usage.output_tokens')
+	})
+
+	it('records what the response said it was, not only what was asked for', async () => {
+		await runOnce([{ text: 'done' }])
+
+		const attrs = chatSpans()[0]?.attributes ?? {}
+		// A provider may answer on a different model than the alias asked
+		// for, and the response id is how a trace is matched to a provider's
+		// own logs. Both constants existed and neither was ever set.
+		expect(attrs['gen_ai.response.model']).toBe('mock-model')
+		expect(attrs['gen_ai.response.id']).toBeDefined()
+	})
+
+	it('records the finish reason as an array, per the convention', async () => {
+		await runOnce([{ text: 'done' }])
+
+		// One call can finish several ways when a provider returns more than
+		// one choice, which is why the convention makes it a list.
+		expect(Array.isArray(chatSpans()[0]?.attributes['gen_ai.response.finish_reasons'])).toBe(true)
+	})
+
+	it('reports cache tokens, which had constants and no producer', async () => {
+		await runOnce([{ text: 'done' }])
+
+		const attrs = chatSpans()[0]?.attributes ?? {}
+		expect(attrs).toHaveProperty('namzu.cache.read_tokens')
+		expect(attrs).toHaveProperty('namzu.cache.write_tokens')
+	})
+
+	it('opens one per turn, not one per run', async () => {
+		await runOnce([{ text: 'first' }, { text: 'second' }])
+
+		// A run with several turns is exactly the case a trace is opened for.
+		expect(chatSpans().length).toBeGreaterThanOrEqual(1)
+	})
+
+	it('nests under the iteration span rather than emitting as a root', async () => {
+		await runOnce([{ text: 'done' }])
+
+		// The iteration span is created first; the chat span is parented to it
+		// explicitly because this body is an async generator and the ambient
+		// context at resume time belongs to the consumer.
+		const iterationIndex = spans.findIndex((s) => s.name.includes('iteration'))
+		const chatIndex = spans.findIndex((s) => s.name.startsWith('chat '))
+		expect(iterationIndex).toBeGreaterThanOrEqual(0)
+		expect(chatIndex).toBeGreaterThan(iterationIndex)
+	})
+})