@namzu/sdk 7.0.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/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,

package/src/runtime/query/iteration/__tests__/settle-grace.test.ts

@@ -0,0 +1,265 @@
+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 { CompletionInbox } from '../../../../gateway/completion-inbox.js'
+import { ToolRegistry } from '../../../../registry/tool/execute.js'
+import { DELEGATION_TIMEOUT_MS } from '../../../../tools/coordinator/index.js'
+import type { 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 { ProjectId, ThreadId } from '../../../../types/session/ids.js'
+import { GuardCoordinator } from '../../guard.js'
+import { drainQuery } from '../../index.js'
+import { settleGraceMs } from '../index.js'
+
+/**
+ * How long a finishing run waits for a worker it launched.
+ *
+ * This used to be a constant — 120 seconds, unrelated to the run holding it.
+ * Measured before the change: a run configured `timeoutMs: 20_000` was held
+ * open for 120,267 ms, because the hold sits INSIDE an iteration and the guard
+ * only checks between them, so nothing could interrupt it. The same constant
+ * abandoned workers observed at 4m21s, 5m58s and 8m04s on runs that had hours
+ * left.
+ */
+
+describe('the grace is a share of what the run has left', () => {
+	it('takes half, so the turn that reads the result still has time to happen', () => {
+		// The fraction is the whole argument. Spending everything remaining
+		// would deliver a notification into a run with no turn left to act on
+		// it — the failure this mechanism exists to prevent, in a new costume.
+		expect(settleGraceMs(60_000)).toBe(30_000)
+	})
+
+	it('holds for nothing when the run has nothing left', () => {
+		// A decision, not a rounding artefact: with no time left there is no
+		// turn in which to read a notification, so waiting can only delay a
+		// stop that is already due. Nothing is lost — `waitForArrival` returns
+		// before it looks at its timer when a completion is already in hand.
+		expect(settleGraceMs(0)).toBe(0)
+	})
+
+	it('cannot outlive the deadline it was derived from', () => {
+		// Bounded by construction, which is why the guard's inability to
+		// interrupt a hold needs no new interrupt seam.
+		for (const remaining of [1, 250, 30_000, 600_000, 3_600_000]) {
+			expect(settleGraceMs(remaining)).toBeLessThan(remaining)
+		}
+	})
+
+	it('stops at the longest this subsystem ever waits for a worker', () => {
+		// Only reachable for a host whose run timeout exceeds two hours.
+		expect(settleGraceMs(10 * 60 * 60 * 1000)).toBe(DELEGATION_TIMEOUT_MS)
+	})
+})
+
+describe('the guard reports time to the finalize point, not to the deadline', () => {
+	it('stops short of the closing reserve', () => {
+		// 90% of the budget, not 100%. The last tenth is what the guard keeps
+		// so a run can produce a closing answer; a wait sized against the
+		// deadline spends it on waiting instead.
+		const guard = new GuardCoordinator({ tokenBudget: 1_000, timeoutMs: 60_000 })
+
+		const remaining = guard.remainingBeforeFinalizeMs()
+
+		expect(remaining).toBeLessThanOrEqual(54_000)
+		expect(remaining).toBeGreaterThan(50_000)
+	})
+
+	it('subtracts the time a previous process already spent', () => {
+		// A run resumed from a checkpoint gets the remainder of ITS budget, not
+		// a fresh clock — otherwise N resumes buy N x timeoutMs, and a hold
+		// sized from the fresh clock would outlive the real deadline.
+		const guard = new GuardCoordinator({ tokenBudget: 1_000, timeoutMs: 60_000 })
+		guard.restoreElapsed(50_000)
+
+		expect(guard.remainingBeforeFinalizeMs()).toBeLessThanOrEqual(4_000)
+		expect(guard.remainingBeforeFinalizeMs()).toBeGreaterThan(1_000)
+	})
+
+	it('reports nothing once the run is already past the finalize point', () => {
+		// 95% elapsed: the guard is about to ask for a closing summary, and a
+		// hold opened here would be taken out of the answer's time.
+		const guard = new GuardCoordinator({ tokenBudget: 1_000, timeoutMs: 60_000 })
+		guard.restoreElapsed(57_000)
+
+		expect(guard.remainingBeforeFinalizeMs()).toBe(0)
+	})
+
+	it('never reports a negative remainder', () => {
+		const guard = new GuardCoordinator({ tokenBudget: 1_000, timeoutMs: 1_000 })
+		guard.restoreElapsed(500_000)
+
+		expect(guard.remainingBeforeFinalizeMs()).toBe(0)
+	})
+})
+
+describe('the hold cannot reach into the run closing reserve', () => {
+	it('ends before the finalize point however late it starts', () => {
+		// The failure the finalize-relative input exists for. Against the
+		// DEADLINE, a hold beginning at elapsed fraction e ends at
+		// 0.5 + 0.5e — so one starting just under the 0.9 threshold ends at
+		// 95% of the budget, with half the closing reserve gone. Against the
+		// finalize point it cannot cross 90% at all.
+		const timeoutMs = 60_000
+		const finalizeAt = timeoutMs * 0.9
+
+		for (const elapsed of [0, 30_000, 50_000, 53_000, 53_900]) {
+			const remainingBeforeFinalize = Math.max(0, finalizeAt - elapsed)
+			const endsAt = elapsed + settleGraceMs(remainingBeforeFinalize)
+
+			expect(
+				endsAt,
+				`a hold starting at ${elapsed}ms crossed the finalize point`,
+			).toBeLessThanOrEqual(finalizeAt)
+		}
+	})
+})
+
+const ZERO_USAGE = {
+	promptTokens: 0,
+	completionTokens: 0,
+	totalTokens: 0,
+	cachedTokens: 0,
+	cacheWriteTokens: 0,
+}
+
+/** Answers straight away. The hold is the only thing that can delay this run. */
+class AnswersImmediately implements LLMProvider {
+	readonly id = 'answers'
+	readonly name = 'Answers Immediately'
+	async *chatStream(): AsyncIterable<StreamChunk> {
+		yield { id: 'm1', delta: { content: 'Done.' } }
+		yield { id: 'm1', delta: {}, finishReason: 'stop', usage: ZERO_USAGE }
+	}
+}
+
+const workdirs: string[] = []
+afterEach(async () => {
+	await Promise.all(workdirs.map((dir) => rm(dir, { recursive: true, force: true })))
+	workdirs.length = 0
+})
+
+/**
+ * The loop, not the helper.
+ *
+ * `settleGraceMs` has its own tests above and every one of them passes with
+ * the loop still calling a constant. Only a real run can say which number the
+ * hold actually used.
+ */
+describe('the hold a run pays is the one its own budget allows', () => {
+	async function runHoldingFor(timeoutMs: number): Promise<number> {
+		const workingDirectory = await mkdtemp(join(tmpdir(), 'namzu-grace-'))
+		workdirs.push(workingDirectory)
+
+		const inbox = new CompletionInbox()
+		// `getTask` because the inbox asks the gateway about a task whose
+		// completion may have been announced before the launch was recorded.
+		// A double that omits a method the interface requires is not a smaller
+		// gateway, it is a broken one.
+		inbox.attach({ onTaskCompleted: () => () => {}, getTask: () => undefined } as never)
+		// Outstanding and never settling: the worst case the bound exists for.
+		// `expect` records the launch as well, so the inbox owns this task.
+		inbox.expect('tsk_never' as TaskId)
+
+		const startedAt = Date.now()
+		await drainQuery({
+			provider: new AnswersImmediately(),
+			tools: new ToolRegistry(),
+			completionInbox: inbox,
+			agentId: 'agent_test',
+			agentName: 'Test Agent',
+			messages: [createUserMessage('go')],
+			workingDirectory,
+			runConfig: {
+				model: 'mock-model',
+				timeoutMs,
+				tokenBudget: 100_000,
+				maxIterations: 2,
+				maxResponseTokens: 256,
+			},
+			sessionId: 'ses_grace' as SessionId,
+			threadId: 'thd_grace' as ThreadId,
+			projectId: 'prj_grace' as ProjectId,
+			tenantId: 'tnt_grace' as TenantId,
+		} as never)
+		return Date.now() - startedAt
+	}
+
+	it('a two-second run does not wait two minutes for a worker', async () => {
+		const elapsed = await runHoldingFor(2_000)
+
+		// Half of two seconds, plus whatever the turn itself costs. The number
+		// this replaced would have parked here for 120 s regardless.
+		expect(elapsed, 'the hold outlived the run budget that bounds it').toBeLessThan(5_000)
+	}, 200_000)
+
+	it('a run with no time left does not hold at all', async () => {
+		// The guard stops this run at the top of its first iteration, so no
+		// hold is even reached — which is the point: the last tenth of a run
+		// already never holds, so no artificial minimum has to defend it.
+		const elapsed = await runHoldingFor(1)
+
+		expect(elapsed).toBeLessThan(2_000)
+	}, 200_000)
+
+	it('still delivers a completion that arrives inside the grace', async () => {
+		// The bound must not become an excuse to drop what was nearly ready.
+		const workingDirectory = await mkdtemp(join(tmpdir(), 'namzu-grace-hit-'))
+		workdirs.push(workingDirectory)
+
+		const inbox = new CompletionInbox()
+		let announce: ((h: TaskHandle) => void) | undefined
+		inbox.attach({
+			onTaskCompleted: (cb: (h: TaskHandle) => void) => {
+				announce = cb
+				return () => {
+					announce = undefined
+				}
+			},
+			getTask: () => undefined,
+		} as never)
+		inbox.expect('tsk_soon' as TaskId)
+		const timer = setTimeout(() => {
+			announce?.({
+				taskId: 'tsk_soon' as TaskId,
+				agentId: 'reviewer',
+				state: 'completed',
+				createdAt: 0,
+				completedAt: 1,
+				result: { status: 'completed', result: 'ARRIVED INSIDE THE GRACE' },
+			} as TaskHandle)
+		}, 150)
+		timer.unref?.()
+
+		const run = await drainQuery({
+			provider: new AnswersImmediately(),
+			tools: new ToolRegistry(),
+			completionInbox: inbox,
+			agentId: 'agent_test',
+			agentName: 'Test Agent',
+			messages: [createUserMessage('go')],
+			workingDirectory,
+			runConfig: {
+				model: 'mock-model',
+				timeoutMs: 30_000,
+				tokenBudget: 100_000,
+				maxIterations: 3,
+				maxResponseTokens: 256,
+			},
+			sessionId: 'ses_grace' as SessionId,
+			threadId: 'thd_grace' as ThreadId,
+			projectId: 'prj_grace' as ProjectId,
+			tenantId: 'tnt_grace' as TenantId,
+		} as never)
+
+		const userText = (run.messages as { role: string; content: unknown }[])
+			.filter((m) => m.role === 'user')
+			.map((m) => (typeof m.content === 'string' ? m.content : ''))
+
+		expect(userText.some((m) => m.includes('ARRIVED INSIDE THE GRACE'))).toBe(true)
+	}, 200_000)
+})