@namzu/sdk 6.2.0 → 8.0.0

package/src/runtime/query/__tests__/context-size-on-the-wire.test.ts

@@ -0,0 +1,122 @@
+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 { createUserMessage } from '../../../types/message/index.js'
+import type { RunEvent } from '../../../types/run/index.js'
+import { drainQuery } from '../index.js'
+
+/**
+ * Cumulative spend and current context size are different quantities, and a
+ * host divided the first by a context window and shipped it.
+ *
+ * That indicator climbed toward full on any long run no matter how much room
+ * the conversation actually had — most wrong exactly when someone needed it —
+ * because `usage` is summed over every turn and never falls, while the context
+ * is what is being sent right now and falls whenever a compaction sheds.
+ *
+ * The host had no better option: the correct numerator needs internals it
+ * cannot see, and the correct denominator was a two-branch guess on a model
+ * name. So both numbers are on the event, named so that reaching for the wrong
+ * one is a visible mistake rather than a plausible guess.
+ */
+
+let workdirs: string[] = []
+
+afterEach(async () => {
+	await Promise.all(workdirs.map((d) => rm(d, { recursive: true, force: true })))
+	workdirs = []
+})
+
+type UsageEvent = Extract<RunEvent, { type: 'token_usage_updated' }>
+
+async function run(
+	compaction: Record<string, unknown> | undefined,
+	turns: unknown[],
+): Promise<UsageEvent[]> {
+	const seen: UsageEvent[] = []
+	const dir = await mkdtemp(join(tmpdir(), 'namzu-ctxsize-'))
+	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 },
+			...(compaction ? { compactionConfig: compaction } : {}),
+			agentId: 'agent_ctx',
+			agentName: 'Context Agent',
+			workingDirectory: dir,
+			sessionId: 'ses_ctx',
+			threadId: 'thd_ctx',
+			projectId: 'prj_ctx',
+			tenantId: 'tnt_ctx',
+			messages: [createUserMessage('go')],
+		} as never,
+		(event: RunEvent) => {
+			if (event.type === 'token_usage_updated') seen.push(event)
+		},
+	)
+
+	return seen
+}
+
+const COMPACTION = {
+	strategy: 'sliding-window',
+	triggerThreshold: 0.9,
+	contextWindowTokens: 50_000,
+	keepRecentMessages: 4,
+}
+
+describe('a run reports how much room its context has', () => {
+	it('carries the context size and the window together', async () => {
+		const events = await run(COMPACTION, [{ text: 'done' }])
+
+		expect(events.length).toBeGreaterThan(0)
+		const event = events[0] as UsageEvent
+		expect(event.contextTokens).toBeGreaterThan(0)
+		expect(event.contextWindowTokens).toBe(50_000)
+	})
+
+	it('says whether each number was measured or guessed', async () => {
+		// A fraction is only as honest as the weaker of its two terms, so a
+		// surface rendering these owes a reader the distinction. It cannot
+		// pass it on if it never receives it.
+		const event = (await run(COMPACTION, [{ text: 'done' }]))[0] as UsageEvent
+
+		expect(['provider', 'estimate']).toContain(event.contextMeasuredBy)
+		// The window was stated in config here, so its provenance is not a guess.
+		expect(event.windowSource).toBe('config')
+	})
+
+	it('keeps the context size distinct from cumulative spend', async () => {
+		// The whole defect in one assertion, and this driver demonstrates it
+		// more sharply than a real one would: it reports no usage at all, so
+		// cumulative spend stays at zero while the context genuinely fills.
+		//
+		// A surface dividing spend by a window would show 0% here, for a
+		// conversation that is really there. The same surface on a long run
+		// shows 100% for a conversation that was compacted down to nothing.
+		// Both directions, same category error — which is why the two numbers
+		// are reported separately rather than left to be inferred from each
+		// other.
+		const events = await run(COMPACTION, [{ text: 'one' }, { text: 'two' }])
+		const last = events[events.length - 1] as UsageEvent
+
+		expect(last.contextTokens).toBeGreaterThan(0)
+		expect(last.contextTokens).not.toBe(last.usage.totalTokens)
+	})
+
+	it('reports nothing rather than a guess when no window is configured', async () => {
+		// Without a compaction config nothing resolves a window, and inventing
+		// one would be the guess this replaces. Absent is a fact a surface can
+		// act on; a fabricated default is not.
+		const event = (await run(undefined, [{ text: 'done' }]))[0] as UsageEvent
+
+		expect(event.contextTokens).toBeUndefined()
+		expect(event.contextWindowTokens).toBeUndefined()
+		expect(event.windowSource).toBeUndefined()
+	})
+})

package/src/runtime/query/__tests__/context.test.ts

@@ -100,4 +100,28 @@ describe('RunContextFactory.build', () => {
 		const runDir = builder.runDir('prj_x' as ProjectId, 'ses_y' as SessionId, 'run_z' as RunId)
 		expect(posix(runDir)).toBe('/base/.namzu/projects/prj_x/sessions/ses_y/runs/run_z')
 	})
+
+	it("carries the caller's stop reason across into the run", () => {
+		// This is the frame that was losing it. The host aborts with a
+		// sentence, the run re-aborts with nothing, and every layer below —
+		// the tool executor, the tool itself, the result the model reads —
+		// can only report that something stopped. The words do not survive
+		// the hop unless this site forwards them.
+		const host = new AbortController()
+		const ctx = RunContextFactory.build(buildConfig({ signal: host.signal }))
+
+		host.abort(new Error('nightly window closed'))
+
+		expect(ctx.abortController.signal.aborted).toBe(true)
+		expect((ctx.abortController.signal.reason as Error)?.message).toBe('nightly window closed')
+	})
+
+	it('still aborts when the caller gave no reason', () => {
+		const host = new AbortController()
+		const ctx = RunContextFactory.build(buildConfig({ signal: host.signal }))
+
+		host.abort()
+
+		expect(ctx.abortController.signal.aborted).toBe(true)
+	})
 })

package/src/runtime/query/__tests__/effort-reaches-the-wire.test.ts

@@ -0,0 +1,135 @@
+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 { createUserMessage } from '../../../types/message/index.js'
+import type { AgentRunConfig } from '../../../types/run/index.js'
+import { drainQuery } from '../index.js'
+
+/**
+ * `effort` was declared on the provider params, exported, and read by a driver
+ * that wrote it straight to the wire — and nothing in the kernel ever set it.
+ * No caller could reach it, and the symptom (every request going out at the
+ * model's default) reads as "this model ignores effort" rather than "nobody
+ * plumbed it through".
+ *
+ * These drive a real run and read what the provider was actually handed, which
+ * is the only thing that distinguishes a wired field from a declared one. A
+ * test asserting the field exists on the config type would have passed against
+ * the broken version.
+ */
+
+let workdirs: string[] = []
+
+afterEach(async () => {
+	await Promise.all(workdirs.map((d) => rm(d, { recursive: true, force: true })))
+	workdirs = []
+})
+
+async function run(overrides: Partial<AgentRunConfig>, turns: unknown[]): Promise<MockLLMProvider> {
+	const provider = new MockLLMProvider({ turns: turns as never })
+	const dir = await mkdtemp(join(tmpdir(), 'namzu-effort-'))
+	workdirs.push(dir)
+
+	await drainQuery({
+		provider,
+		tools: new ToolRegistry(),
+		runConfig: {
+			model: 'mock-model',
+			timeoutMs: 30_000,
+			tokenBudget: 100_000,
+			maxIterations: 2,
+			...overrides,
+		},
+		agentId: 'agent_effort',
+		agentName: 'Effort Agent',
+		workingDirectory: dir,
+		sessionId: 'ses_effort',
+		threadId: 'thd_effort',
+		projectId: 'prj_effort',
+		tenantId: 'tnt_effort',
+		messages: [createUserMessage('go')],
+	} as never)
+
+	return provider
+}
+
+describe('an effort level set on the run reaches the provider', () => {
+	it('arrives on the request', async () => {
+		const provider = await run({ effort: 'max' }, [{ text: 'done' }])
+
+		expect(provider.requests.length).toBeGreaterThan(0)
+		expect(provider.requests[0]?.effort).toBe('max')
+	})
+
+	it('is absent when nobody asked for one', async () => {
+		// Not `undefined`-valued but genuinely absent: a present key carrying
+		// undefined is the kind of thing that survives a spread into a request
+		// body and reaches a wire that did not expect the field.
+		const provider = await run({}, [{ text: 'done' }])
+
+		expect(provider.requests[0] && 'effort' in provider.requests[0]).toBe(false)
+	})
+
+	it('rides every turn of the run, not only the first', async () => {
+		// The value is run-level because the provider documents that changing
+		// it between requests invalidates the cached prefix. A run that
+		// forwarded it once and then stopped would pay that cost silently.
+		const provider = await run({ effort: 'low' }, [{ text: 'one' }, { text: 'two' }])
+
+		for (const request of provider.requests) {
+			expect(request.effort).toBe('low')
+		}
+	})
+
+	it('travels alongside thinking rather than inside it', async () => {
+		const provider = await run({ effort: 'high', thinking: { type: 'adaptive' } }, [
+			{ text: 'done' },
+		])
+
+		expect(provider.requests[0]?.effort).toBe('high')
+		expect(provider.requests[0]?.thinking?.type).toBe('adaptive')
+	})
+})
+
+describe('the front door forwards it too, not only the kernel', () => {
+	/**
+	 * These exist because everything above passed while a real run put NOTHING
+	 * on the wire.
+	 *
+	 * `drainQuery` takes the run config a caller hands it, so testing through
+	 * it proves the loop forwards the field and nothing about whether a caller
+	 * can set it. Every ergonomic entry point — this one, `ReactiveAgent`,
+	 * `SupervisorAgent`, and the manager's bare-config branch — builds its
+	 * `AgentRunConfig` by HAND-LISTING fields, so a field nobody remembered to
+	 * add is dropped in silence, with no cast to blame and no error to see.
+	 * `thinking` had been in that state since it shipped.
+	 *
+	 * It was found by watching an actual HTTP body, which is the only place the
+	 * gap is visible. So the regression test drives the front door.
+	 */
+	it('reaches the provider through runAgent', async () => {
+		const { runAgent } = await import('../../../agents/runAgent.js')
+		const provider = new MockLLMProvider({ turns: [{ text: 'done' }] as never })
+		const dir = await mkdtemp(join(tmpdir(), 'namzu-effort-door-'))
+		workdirs.push(dir)
+
+		await runAgent({
+			provider,
+			model: 'mock-model',
+			prompt: 'go',
+			workingDirectory: dir,
+			effort: 'xhigh',
+			thinking: { type: 'adaptive' },
+			timeoutMs: 30_000,
+			tokenBudget: 100_000,
+			maxIterations: 2,
+		})
+
+		expect(provider.requests.length).toBeGreaterThan(0)
+		expect(provider.requests[0]?.effort, 'the front door dropped effort').toBe('xhigh')
+		expect(provider.requests[0]?.thinking?.type, 'the front door dropped thinking').toBe('adaptive')
+	})
+})

package/src/runtime/query/__tests__/tool-timeout.test.ts

@@ -177,6 +177,44 @@ describe('ToolExecutor — per-tool deadline', () => {
 		expect(batch.results[0]?.output).toContain('was cancelled')
 	})
 
+	it('says WHICH stop it was, when the caller named one', async () => {
+		// The reason was on this signal all along — it is forwarded into the
+		// per-tool controller a few lines above the message — and the message
+		// threw it away. So a deadline, a budget and an operator pressing stop
+		// all reached the model as the same four words, and they want
+		// different next moves: one is worth waiting out, one is worth
+		// narrowing the input for, and one is worth stopping over.
+		const controller = new AbortController()
+		const h = harness({
+			toolTimeoutMs: 60_000,
+			abortSignal: controller.signal,
+			run: never,
+		})
+		const pending = h.exec.executeBatch(response('hang'))
+		controller.abort(new Error('deployment window closed'))
+		const batch = await pending
+
+		expect(batch.results[0]?.output).toContain('deployment window closed')
+	})
+
+	it('does not invent a reason when the caller gave none', async () => {
+		// `abort()` with no argument fills `reason` with a DOMException named
+		// AbortError. Rendering it would turn an honest silence into something
+		// that reads like an explanation, which is the worse failure.
+		const controller = new AbortController()
+		const h = harness({
+			toolTimeoutMs: 60_000,
+			abortSignal: controller.signal,
+			run: never,
+		})
+		const pending = h.exec.executeBatch(response('hang'))
+		controller.abort()
+		const batch = await pending
+
+		expect(batch.results[0]?.output).toContain('was cancelled.')
+		expect(batch.results[0]?.output).not.toContain('AbortError')
+	})
+
 	it('exposes a sane default deadline', () => {
 		// Documented so a change is a deliberate decision, not a drift.
 		expect(DEFAULT_TOOL_TIMEOUT_MS).toBe(120_000)

package/src/runtime/query/context.ts

@@ -134,7 +134,22 @@ export class RunContextFactory {
 	static build(config: RunContextConfig): RunContext {
 		const abortController = new AbortController()
 		if (config.signal) {
-			config.signal.addEventListener('abort', () => abortController.abort(), { once: true })
+			// Forward the caller's REASON, not just the fact of the abort.
+			//
+			// This used to be a bare `abort()`. Every word a host attached to
+			// its stop — a deadline name, a budget, an operator's message —
+			// died one frame above the executor, so the most a tool result
+			// could say was "was cancelled". A run that ends for a nameable
+			// reason is a run someone can debug; this is the frame where the
+			// name was being thrown away.
+			//
+			// `createChildAbortController` already does exactly this, but it
+			// takes an AbortController and what arrives here is a bare
+			// AbortSignal, so the reason is forwarded by hand rather than by
+			// reaching for a helper that does not fit.
+			config.signal.addEventListener('abort', () => abortController.abort(config.signal?.reason), {
+				once: true,
+			})
 		}
 
 		const cwd = config.workingDirectory ?? process.cwd()

package/src/runtime/query/executor.ts

@@ -33,6 +33,7 @@ import type {
 	ToolCallRepair,
 	ToolCallRepairReason,
 } from '../../types/tool/repair.js'
+import { abortReasonText } from '../../utils/abort.js'
 import { toErrorMessage } from '../../utils/error.js'
 import type { Logger } from '../../utils/logger.js'
 import { compressShellOutput } from '../../utils/shell-compress.js'
@@ -859,10 +860,19 @@ export class ToolExecutor {
 			}
 
 			if (outcome === 'aborted') {
+				// Say WHY, when the caller said why. The reason has been
+				// available on this signal all along — it is forwarded into
+				// `controller` a few lines above — and the message threw it
+				// away, so a deadline, a budget and an operator pressing stop
+				// were all reported to the model with the same four words.
+				// Those want different next moves.
+				const why = abortReasonText(controller.signal.reason)
 				return {
 					success: false,
 					output: '',
-					error: `Tool "${toolName}" was cancelled.`,
+					error: why
+						? `Tool "${toolName}" was cancelled: ${why}`
+						: `Tool "${toolName}" was cancelled.`,
 				}
 			}
 

package/src/runtime/query/guard.ts

@@ -55,6 +55,38 @@ export class GuardCoordinator {
 		this.startTime = Date.now() - Math.max(0, elapsedMs)
 	}
 
+	/**
+	 * Wall-clock left before this run is asked to start finishing.
+	 *
+	 * NOT the time left before the deadline, and the difference is the whole
+	 * point. The checks above run BETWEEN iterations, so anything that waits
+	 * inside one cannot be stopped by them, and a caller sizing such a wait
+	 * needs a number the run actually owns: a fixed two-minute hold measured
+	 * against a run configured for twenty seconds kept it open for 120,267 ms.
+	 *
+	 * Measuring to the DEADLINE was the first attempt and it was wrong. The
+	 * binding constraint is `budgetWarningThreshold`, the point at which this
+	 * guard stops asking for more work and asks for a closing summary — that
+	 * last slice exists so the run can produce an answer, and a wait sized
+	 * against the deadline eats into it. Half of the time-to-deadline, started
+	 * just under the threshold, ends at 95% of the budget: half the closing
+	 * reserve spent waiting for a result the closing answer was supposed to
+	 * use.
+	 *
+	 * Zero once the threshold has passed, which is also how a caller gets the
+	 * re-evaluation it needs: `forceFinalize` is sampled at the top of an
+	 * iteration and this is read when the wait is about to start, so a long
+	 * iteration that crossed the line in between is told to wait for nothing.
+	 *
+	 * Reads through the same `startTime` the limit checks use, so a run
+	 * resumed from a checkpoint (see `restoreElapsed`) reports the time left
+	 * on the RUN rather than on the process now hosting it.
+	 */
+	remainingBeforeFinalizeMs(): number {
+		const finalizeAt = this.limitConfig.timeoutMs * this.limitConfig.budgetWarningThreshold
+		return Math.max(0, finalizeAt - (Date.now() - this.startTime))
+	}
+
 	beforeIteration(runMgr: RunPersistence, abortSignal: AbortSignal): GuardCheckResult {
 		const limitState = {
 			aborted: abortSignal.aborted,