@namzu/sdk 6.2.0 → 7.0.0

package/src/gateway/local.ts

@@ -39,6 +39,8 @@ export class LocalTaskGateway implements TaskGateway {
 	private settledHandles: Map<TaskId, TaskHandle> = new Map()
 
 	private siblingFailurePolicy: SiblingFailurePolicy = 'continue'
+	/** See {@link onTaskProgress}. */
+	private readonly progressListeners = new Set<(taskId: TaskId) => void>()
 
 	constructor(
 		agentManager: AgentManagerContract,
@@ -86,7 +88,15 @@ export class LocalTaskGateway implements TaskGateway {
 			// allocated `maxBudgetFraction` of the SAME number — N x 50% of a
 			// budget that only had 100% in it.
 			this.taskContext,
-			this.listener,
+			// The host's listener still sees everything it always did; this
+			// only tees off the fact that SOMETHING happened, which is what an
+			// idle bound measures. The event itself is not forwarded — a
+			// progress signal that carried the child's output would be a
+			// second, undocumented way to read a worker's work.
+			(event) => {
+				this.listener?.(event)
+				for (const notify of this.progressListeners) notify(task.taskId)
+			},
 		)
 
 		this.trackedTaskIds.add(task.taskId)
@@ -208,6 +218,21 @@ export class LocalTaskGateway implements TaskGateway {
 		return handles
 	}
 
+	/**
+	 * Every event a child emits, reduced to "this one is still alive".
+	 *
+	 * Deliberately just the id. A caller that wanted the event itself has
+	 * the run listener; what an idle clock needs is the fact, and passing
+	 * the payload here would make this a second way to read a worker's
+	 * output — one nobody documented and nothing frames as untrusted.
+	 */
+	onTaskProgress(callback: (taskId: TaskId) => void): () => void {
+		this.progressListeners.add(callback)
+		return () => {
+			this.progressListeners.delete(callback)
+		}
+	}
+
 	onTaskCompleted(callback: (handle: TaskHandle) => void): () => void {
 		this.completionListeners.add(callback)
 		return () => {

package/src/manager/agent/lifecycle.ts

@@ -296,6 +296,12 @@ export class AgentManager {
 				parentSpan: options.configOverrides?.parentSpan,
 				maxIterations: options.configOverrides?.maxIterations,
 				maxResponseTokens: options.configOverrides?.maxResponseTokens,
+				// A delegate spawned without a configBuilder lands here, and this
+				// list is the only thing it inherits. Omitting these meant a child
+				// silently ran at the default depth and effort its parent had
+				// deliberately moved off.
+				thinking: options.configOverrides?.thinking,
+				effort: options.configOverrides?.effort,
 				env: options.configOverrides?.env,
 				sessionId: spawnRecord.childSessionId,
 				threadId: context.threadId,

package/src/provider/thinking-support.ts

@@ -1,4 +1,4 @@
-import type { ThinkingConfig } from '../types/provider/index.js'
+import type { ReasoningEffort, ThinkingConfig } from '../types/provider/index.js'
 
 /**
  * Refuse a thinking request a driver does not implement.
@@ -27,8 +27,25 @@ import type { ThinkingConfig } from '../types/provider/index.js'
  */
 export function assertThinkingUnsupported(
 	driverName: string,
-	params: { thinking?: ThinkingConfig },
+	params: { thinking?: ThinkingConfig; effort?: ReasoningEffort },
 ): void {
+	// `effort` is refused on exactly the same reasoning, and it is the worse
+	// silence of the two. A dropped `thinking` at least leaves an empty
+	// reasoning list a caller could notice; a dropped `effort` leaves a
+	// perfectly ordinary answer, so a run someone believes they paid for at
+	// `max` is indistinguishable from one at the model's default — including
+	// on the bill.
+	//
+	// Checked before thinking because it is the cheaper mistake to make: a
+	// caller reaching for effort on a driver without it has usually pointed a
+	// working config at a new provider, and naming the field they set beats
+	// naming the neighbouring one.
+	if (params.effort !== undefined) {
+		throw new Error(
+			`${driverName} does not implement effort. Silently ignoring it would return an ordinary completion, so a run requested at "${params.effort}" would be indistinguishable from one at the model's default — including in what it cost. Drop \`effort\`, or use a driver that implements it.`,
+		)
+	}
+
 	const type = params.thinking?.type
 	if (type !== 'enabled' && type !== 'adaptive') return
 	throw new Error(

package/src/public-runtime.ts

@@ -369,9 +369,18 @@ export {
 	FileLockManager,
 } from './bus/index.js'
 
+// `describeRule` travels with `evaluateRule` deliberately. `evaluateRule`
+// answers WHETHER a rule matched; on its own it leaves a caller holding a
+// decision with no words for it, and the only way to say anything about the
+// refusal is to switch on the rule's TYPE — which names the kind of rule and
+// nothing about what it said. That is precisely the defect the gate itself
+// carried until its reason stopped being `Matched rule: <type>`, and shipping
+// the verdict without the sentence would have left the same hole one layer up
+// for anyone driving the rules directly instead of through the gate.
 export {
 	defaultSandboxedGateConfig,
 	defaultSandboxedShellGateConfig,
+	describeRule,
 	evaluateRule,
 	VerificationGate,
 } from './verification/index.js'

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/iteration/index.ts

@@ -317,6 +317,7 @@ export class IterationOrchestrator {
 						maxTokens: step.maxResponseTokens ?? runConfig.maxResponseTokens,
 						cacheControl: { type: 'auto' },
 						...(runConfig.thinking ? { thinking: runConfig.thinking } : {}),
+						...(runConfig.effort ? { effort: runConfig.effort } : {}),
 						// Thread the run abort into the model call so a Stop tears the
 						// in-flight turn down (provider passes it to fetch; the consumer
 						// also races it). Inert when never aborted.
@@ -1154,6 +1155,10 @@ export class IterationOrchestrator {
 					maxTokens: this.ctx.runConfig.maxResponseTokens,
 					cacheControl: { type: 'auto' },
 					...(this.ctx.runConfig.thinking ? { thinking: this.ctx.runConfig.thinking } : {}),
+					// This turn is a hand-maintained duplicate of the one above, which
+					// is exactly the shape a field goes missing from — so it is tested
+					// separately rather than assumed to have been kept in step.
+					...(this.ctx.runConfig.effort ? { effort: this.ctx.runConfig.effort } : {}),
 					// Cancellable too: a Stop during the closing summary must not
 					// stream to completion.
 					signal: this.ctx.abortController.signal,

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

@@ -2,6 +2,10 @@ 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'
+import { MockLLMProvider } from '../../provider/mock.js'
+import { ToolRegistry } from '../../registry/tool/execute.js'
+import { drainQuery } from '../../runtime/query/index.js'
+import { createUserMessage } from '../../types/message/index.js'
 
 /**
  * There was no span around the model call at all.
@@ -72,12 +76,25 @@ afterEach(async () => {
 	workdirs = []
 })
 
+/**
+ * These four are imported at module scope on purpose, and must stay there.
+ *
+ * They used to be `await import(...)` inside this function, which meant the
+ * query runtime's module graph — 75 imports deep — was loaded on the clock of
+ * whichever test called it first. Measured: that test took 1349ms on an idle
+ * machine while its eight siblings took 13-16ms, and under CPU load it hit
+ * vitest's 5000ms default and went red. Nothing about it was racy and nothing
+ * about it was slow; a load cost was simply billed to the wrong clock.
+ *
+ * At module scope the same work happens during collection, which carries no
+ * per-test deadline, so the wall time is unchanged and the deadline is not.
+ *
+ * Safe because `vi.mock` is hoisted above every import in this file, so a
+ * static import still receives the mocked `runtime-accessors`. That is a
+ * property of the transform rather than of import order — verified by running,
+ * not assumed, since no other file in this package had done it this way.
+ */
 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)
 

package/src/telemetry/__tests__/span-closure.test.ts

@@ -1,5 +1,17 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { z } from 'zod'
+// Imported at module scope on purpose, and must stay there.
+//
+// This was `await import(...)` repeated inside all five test bodies. That
+// billed the tool-registry module graph to whichever test happened to run
+// first, out of that test's own 5000ms deadline — and because every body
+// re-entered the same pending import, a stall did not fail one test, it took
+// the whole file down. At module scope the load happens during collection,
+// which has no per-test deadline.
+//
+// `vi.mock` is hoisted above every import here, so the static form still
+// receives the mocked `runtime-accessors`.
+import { ToolRegistry } from '../../registry/tool/execute.js'
 
 /**
  * A span that never ends is a trace that never closes, and the export is
@@ -73,7 +85,6 @@ afterEach(() => {
 
 describe('a tool span closes however the call leaves', () => {
 	it('closes on the ordinary path', async () => {
-		const { ToolRegistry } = await import('../../registry/tool/execute.js')
 		const tools = new ToolRegistry()
 		tools.register({
 			name: 'echo',
@@ -89,7 +100,6 @@ describe('a tool span closes however the call leaves', () => {
 	})
 
 	it('closes when the tool throws', async () => {
-		const { ToolRegistry } = await import('../../registry/tool/execute.js')
 		const tools = new ToolRegistry()
 		tools.register({
 			name: 'boom',
@@ -106,7 +116,6 @@ describe('a tool span closes however the call leaves', () => {
 	})
 
 	it('closes when input validation refuses the call', async () => {
-		const { ToolRegistry } = await import('../../registry/tool/execute.js')
 		const tools = new ToolRegistry()
 		tools.register({
 			name: 'strict',
@@ -121,7 +130,6 @@ describe('a tool span closes however the call leaves', () => {
 	})
 
 	it('closes when the tool is not active', async () => {
-		const { ToolRegistry } = await import('../../registry/tool/execute.js')
 		const tools = new ToolRegistry()
 		tools.register(
 			{
@@ -139,7 +147,6 @@ describe('a tool span closes however the call leaves', () => {
 	})
 
 	it('closes when the registry does not hold the name at all', async () => {
-		const { ToolRegistry } = await import('../../registry/tool/execute.js')
 		const tools = new ToolRegistry()
 
 		// `getOrThrow` sat OUTSIDE the try that owned the finally, so this