@namzu/sdk 6.0.0 → 6.2.0

package/src/runtime/query/iteration/index.ts

@@ -5,6 +5,7 @@ import {
 	DEFAULT_STRUCTURED_OUTPUT_RETRIES,
 	STRUCTURED_OUTPUT_REPROMPT,
 } from '../../../constants/tools/index.js'
+import { formatCompletionNotification } from '../../../gateway/completion-inbox.js'
 import { renderSkillsSection } from '../../../persona/assembler.js'
 import { collect } from '../../../provider/collect.js'
 import {
@@ -61,6 +62,16 @@ export type { ToolReviewOutcome } from './phases/index.js'
  */
 const DEFAULT_ANSWER_REVIEW_LIMIT = 3
 
+/**
+ * How long a finishing run waits for a background worker it launched.
+ *
+ * Long enough to be worth having — a delegated worker doing real work takes
+ * minutes — and bounded because a worker that never finishes must not hold
+ * the run open forever. `maxIterations` bounds how many times this can
+ * happen, and the run's own timeout bounds the whole thing regardless.
+ */
+const BACKGROUND_TASK_GRACE_MS = 120_000
+
 export class IterationOrchestrator {
 	private ctx: IterationContext
 	/** Rejections so far. See {@link DEFAULT_ANSWER_REVIEW_LIMIT}. */
@@ -207,7 +218,13 @@ export class IterationOrchestrator {
 				// supplied no hook.
 				const step = await this.prepareStep(iterationNum)
 
-				const llmTools = this.ctx.tools.toLLMTools(step.allowedTools ?? this.ctx.allowedTools)
+				const stepAllowedTools = step.allowedTools ?? this.ctx.allowedTools
+				const llmTools = this.ctx.tools.toLLMTools(stepAllowedTools)
+				// The same list the request was built from now also bounds what
+				// may run. Narrowing only the request left the restriction
+				// presentational — the model was shown fewer tools and could
+				// still call any of them by name.
+				this.ctx.toolExecutor.setStepAllowedTools(stepAllowedTools)
 				const enforceToolInputSchema = enforcedModelInputToolNames(this.ctx.tools, llmTools)
 				const stepModel = step.model ?? model
 
@@ -551,6 +568,36 @@ export class IterationOrchestrator {
 						}
 					}
 
+					// A background worker is still out there, and this turn was
+					// about to end the run.
+					//
+					// Settling here would throw away the very thing the launch
+					// existed to produce: the supervisor said "launched", the
+					// worker had not finished, and the run closed over it. So
+					// the run is held open — bounded by the deadline below and
+					// by `maxIterations` above, so a worker that never finishes
+					// cannot keep it open forever — and the completion arrives
+					// as a notification the next turn reads.
+					if (!forceFinalize && this.ctx.completionInbox?.hasPendingWork) {
+						this.ctx.log.info('Holding the run open for a background task', {
+							runId: runMgr.id,
+							iteration: iterationNum,
+						})
+						await this.ctx.completionInbox.waitForArrival(BACKGROUND_TASK_GRACE_MS)
+						const arrived = this.ctx.completionInbox.drain()
+						if (arrived.length > 0) {
+							runMgr.pushMessage(createUserMessage(formatCompletionNotification(arrived)))
+							await this.ctx.emitEvent({
+								type: 'iteration_completed',
+								runId: runMgr.id,
+								iteration: iterationNum,
+								hasToolCalls: false,
+							})
+							yield* this.ctx.drainPending()
+							continue
+						}
+					}
+
 					if (!hasContent && !forceFinalize) {
 						this.ctx.log.warn('Empty completion detected — requesting final summary', {
 							iteration: iterationNum,
@@ -674,6 +721,35 @@ export class IterationOrchestrator {
 					return
 				}
 
+				// Workers that finished with nobody listening.
+				//
+				// A completion normally reaches the supervisor as the
+				// `tool_result` of the `create_task` that launched it. Two
+				// cases have no such call: a launch made in the background on
+				// purpose, and a blocking launch whose deadline passed — the
+				// model was told "timed out, it may still be running" and the
+				// worker then finished, holding a result nothing would read.
+				//
+				// This is the channel that was removed in `dc16d58` because it
+				// double-delivered: it fired for completions the blocking tool
+				// had already handed over, so the supervisor saw each result
+				// twice. The inbox restores it with the distinction that was
+				// missing — a tool that delivers a completion claims it, and
+				// only unclaimed ones arrive here.
+				//
+				// Placed beside the advisory phase deliberately: that is the
+				// established seam for putting a user message in after tool
+				// results and before the next turn.
+				const unheard = this.ctx.completionInbox?.drain() ?? []
+				if (unheard.length > 0) {
+					this.ctx.log.info('Delivering unawaited task completions', {
+						runId: runMgr.id,
+						iteration: iterationNum,
+						tasks: unheard.map((h) => h.taskId),
+					})
+					runMgr.pushMessage(createUserMessage(formatCompletionNotification(unheard)))
+				}
+
 				await runAdvisoryPhase(this.ctx, iterationNum, response)
 
 				if (this.ctx.pluginManager) {

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

@@ -3,6 +3,7 @@ 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 { CompletionInbox } from '../../../../gateway/completion-inbox.js'
 import type { PlanManager } from '../../../../manager/plan/lifecycle.js'
 import type { RunPersistence } from '../../../../manager/run/persistence.js'
 import type { ActivityStore } from '../../../../store/activity/memory.js'
@@ -103,6 +104,15 @@ export interface IterationContext {
 
 	readonly taskGateway?: TaskGateway
 
+	/**
+	 * Completions no call is waiting for, on their way to the transcript.
+	 *
+	 * Absent means the loop behaves exactly as it did before this existed:
+	 * a blocking `create_task` still delivers its own result, and a
+	 * completion nobody awaited is simply never mentioned.
+	 */
+	readonly completionInbox?: CompletionInbox
+
 	readonly taskStore?: TaskStore
 
 	readonly launchedTasks: Map<TaskId, LaunchedTaskMeta>
@@ -199,16 +209,51 @@ export async function awaitDecisionDurably(
 		}
 	}
 
-	const recordIfSlow = (async (): Promise<void> => {
-		await sleep(delay)
-		if (settled) return
-		await record()
-	})()
+	// The wait for "is this park slow enough to be worth writing down", and
+	// the reason it is a cancellable timer rather than a slept-through one.
+	//
+	// It used to `await sleep(delay)` where `sleep` created its timer and
+	// UNREF'D it, so a pending recorder could never hold a process open after
+	// the run settled. That is a real hazard and the intent was right, but the
+	// scope was wrong: this promise is awaited *during* the run, below, on
+	// every park. An unref'd timer does not keep Node's event loop alive — so
+	// once the decision resolved and the run sat here waiting out the rest of
+	// the delay, the loop had nothing ref'd left in it and the process exited.
+	// Mid-turn. Exit code 0. Nothing written, no error, no terminal event.
+	//
+	// That shipped, and it made the headless surfaces unable to finish a turn
+	// at all: the first tool call would complete and the process would end.
+	// Every test passed because a test runner holds the loop open for the
+	// whole file, which is exactly the kind of prop that hides this.
+	//
+	// Cancelling gets both properties. The timer is ref'd, so the run cannot
+	// be killed by its own wait; and it is cleared the moment the decision
+	// arrives, so nothing dangles past the run either.
+	let parkTimer: ReturnType<typeof setTimeout> | undefined
+	// Set SYNCHRONOUSLY when the write begins, because `recorded` only turns
+	// true after it finishes — waiting on that instead would skip a write that
+	// is still in flight and let the unpark below race it.
+	let recording = false
+	const recordIfSlow = new Promise<void>((resolve) => {
+		parkTimer = setTimeout(() => {
+			if (settled) {
+				resolve()
+				return
+			}
+			recording = true
+			record().then(resolve, resolve)
+		}, delay)
+	})
 
 	try {
 		const decision = await decisionPromise
 		settled = true
-		await recordIfSlow
+		// Cancel the wait rather than sitting through it. If the timer already
+		// fired, `recordIfSlow` is the park write and is worth awaiting so the
+		// unpark below cannot race it; if it has not, there is nothing to wait
+		// for and clearing it is what lets the turn continue immediately.
+		if (parkTimer !== undefined) clearTimeout(parkTimer)
+		if (recording) await recordIfSlow
 
 		// `pause` is not an answer — it is "I am not answering now, hold
 		// this". It therefore ALWAYS gets recorded, even when it arrived too
@@ -239,15 +284,6 @@ export async function awaitDecisionDurably(
 	}
 }
 
-function sleep(ms: number): Promise<void> {
-	return new Promise((resolve) => {
-		const timer = setTimeout(resolve, ms)
-		// A pending park recorder must never be the reason a process stays
-		// alive after the run settles.
-		;(timer as { unref?: () => void }).unref?.()
-	})
-}
-
 /**
  * Await a HITL `resumeHandler` decision, but RACE it against the run's abort
  * signal. A Stop that arrives while the run is parked on a tool-review or

package/src/tools/builtins/__tests__/bash.proc-test.ts

@@ -0,0 +1,142 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+
+import type { ToolContext } from '../../../types/tool/index.js'
+import { BashTool } from '../bash.js'
+
+/**
+ * What a shell command actually tells the model, measured by running one.
+ *
+ * The only builtin that runs a shell had no test at all, and what that cost
+ * is visible in the code it shipped: the host path called `exec` with no
+ * `catch`, and `exec` REJECTS on a non-zero exit. So the two things an agent
+ * runs a shell for most — a test run and a build — both threw, and the
+ * registry turned the throw into "the tool failed" with none of the stdout,
+ * stderr or exit code that explains why. The sandbox path beside it reported
+ * all three, so the same command told the model two different amounts
+ * depending on where it happened to run.
+ *
+ * These spawn real processes, so they live in the `proc-test` suite rather
+ * than the unit one — measured, running them beside 2594 unit tests flaked
+ * four unrelated timing-sensitive tests. The assertions that need no shell
+ * stayed behind in `bash.test.ts`.
+ *
+ * Commands are written to behave identically under `cmd.exe` and `sh`,
+ * because `exec` picks the platform shell and a test that only passes on one
+ * of them is a test that fails for whoever is on the other.
+ */
+
+const dirs: string[] = []
+afterEach(() => {
+	for (const dir of dirs) {
+		// A killed child can still hold its working directory for a moment —
+		// on Windows that surfaces as EBUSY, and it failed the timeout test
+		// from the cleanup rather than the assertion, which is the most
+		// misleading way for a test to go red. Retry, then let it go: a temp
+		// directory that outlives the run is the operating system's problem,
+		// not a result worth reporting.
+		try {
+			rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 })
+		} catch {
+			// Deliberately swallowed. See above.
+		}
+	}
+	dirs.length = 0
+})
+
+function ctx(): ToolContext {
+	const workingDirectory = mkdtempSync(join(tmpdir(), 'namzu-bash-'))
+	dirs.push(workingDirectory)
+	return { workingDirectory } as ToolContext
+}
+
+async function run(
+	input: Record<string, unknown>,
+	context: ToolContext = ctx(),
+): Promise<{ success: boolean; output: string; error?: string; data?: Record<string, unknown> }> {
+	const parsed = BashTool.inputSchema.parse(input)
+	return (await BashTool.execute(parsed as never, context)) as never
+}
+
+describe('a command that succeeds', () => {
+	it('returns its stdout', async () => {
+		const result = await run({ command: 'echo hello' })
+
+		expect(result.success).toBe(true)
+		expect(result.output).toContain('hello')
+		expect(result.data?.exitCode).toBe(0)
+	})
+
+	it('runs in the working directory it was given', async () => {
+		const context = ctx()
+		writeFileSync(join(context.workingDirectory, 'marker.txt'), 'x')
+
+		const result = await run(
+			{ command: `node -e "console.log(require('fs').readdirSync('.'))"` },
+			context,
+		)
+
+		expect(result.output).toContain('marker.txt')
+	})
+
+	it('says so rather than returning an empty string', async () => {
+		const result = await run({ command: 'node -e ""' })
+
+		expect(result.output).toBe('(no output)')
+	})
+})
+
+describe('a command that fails still says what happened', () => {
+	it('reports the exit code instead of throwing', async () => {
+		// The whole defect: this used to reject out of `execute`.
+		const result = await run({ command: 'node -e "process.exit(3)"' })
+
+		expect(result.success).toBe(false)
+		expect(result.data?.exitCode).toBe(3)
+		expect(result.error).toContain('exited with code 3')
+	})
+
+	it('keeps the output a failing command produced', async () => {
+		// The reason a model runs a shell at all: a failing test prints WHY it
+		// failed, on stdout, before exiting non-zero.
+		const result = await run({
+			command: `node -e "console.log('3 tests failed'); process.exit(1)"`,
+		})
+
+		expect(result.success).toBe(false)
+		expect(result.output, 'the failure output was discarded').toContain('3 tests failed')
+	})
+
+	it('keeps stderr too', async () => {
+		const result = await run({
+			command: `node -e "console.error('compiler said no'); process.exit(2)"`,
+		})
+
+		expect(result.output).toContain('compiler said no')
+		expect(result.data?.exitCode).toBe(2)
+	})
+
+	it('reports a missing command as a failure, not as success', async () => {
+		const result = await run({ command: 'definitely-not-a-real-command-xyz' })
+
+		expect(result.success).toBe(false)
+		expect(result.error).toBeTruthy()
+	})
+})
+
+describe('a command that runs out of time', () => {
+	it('says it timed out rather than that it exited', async () => {
+		// "Ran out of time" and "exited 1" are different diagnoses and lead to
+		// different next moves, so the message has to distinguish them.
+		const result = await run({
+			command: `node -e "setTimeout(() => {}, 10000)"`,
+			timeout: 300,
+		})
+
+		expect(result.success).toBe(false)
+		expect(result.data?.timedOut).toBe(true)
+		expect(result.error).toContain('timed out')
+	}, 20_000)
+})

package/src/tools/builtins/__tests__/bash.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest'
+
+import { BashTool } from '../bash.js'
+
+/**
+ * What `bash` promises before it runs anything.
+ *
+ * These need no shell, so they stay in the unit suite. The ones that actually
+ * execute a command live in `bash.proc-test.ts` — spawning real processes
+ * beside 2594 unit tests flaked four unrelated timing-sensitive ones, so the
+ * process suite is separate and has its own CI step.
+ */
+
+describe('the two clocks agree', () => {
+	it('declares a deadline of its own', () => {
+		// The executor reads a tool's `timeoutMs` before falling back to its
+		// generic default. With none declared, `bash` inherited that default —
+		// the same two minutes as its OWN default — so the two agreed by
+		// coincidence and diverged the moment a model asked for longer because
+		// it knew a build was slow. It got two minutes, from a clock it had not
+		// been told about, reported as an abandoned tool rather than as a
+		// command that ran out of time.
+		expect(BashTool.timeoutMs).toBeDefined()
+	})
+
+	it('puts that deadline above the longest the model may request', () => {
+		// So this tool's own clock is the one that fires, and the executor's is
+		// a backstop rather than a second clock racing it.
+		const accepted = BashTool.inputSchema.safeParse({ command: 'true', timeout: 10 * 60 * 1000 })
+
+		expect(accepted.success).toBe(true)
+		expect(BashTool.timeoutMs as number).toBeGreaterThan(10 * 60 * 1000)
+	})
+
+	it('refuses an over-long request rather than silently shortening it', () => {
+		// Refuse, do not degrade. A number the model was not told had changed
+		// is how it learns to distrust its own arguments.
+		const overCeiling = BashTool.inputSchema.safeParse({
+			command: 'true',
+			timeout: 60 * 60 * 1000,
+		})
+
+		expect(overCeiling.success, 'the ceiling is not enforced').toBe(false)
+	})
+
+	it('refuses a nonsensical deadline', () => {
+		expect(BashTool.inputSchema.safeParse({ command: 'true', timeout: 0 }).success).toBe(false)
+		expect(BashTool.inputSchema.safeParse({ command: 'true', timeout: -1 }).success).toBe(false)
+	})
+
+	it('applies its default when none is given', () => {
+		const parsed = BashTool.inputSchema.parse({ command: 'true' })
+
+		expect(parsed.timeout).toBeGreaterThan(0)
+	})
+})
+
+describe('the input is closed before a shell ever sees it', () => {
+	it('refuses an empty command', () => {
+		expect(BashTool.inputSchema.safeParse({ command: '' }).success).toBe(false)
+	})
+
+	it('accepts a numeric timeout sent as a string', () => {
+		// Providers do this, and the coercion is deliberate.
+		const parsed = BashTool.inputSchema.parse({ command: 'true', timeout: '5000' })
+
+		expect(parsed.timeout).toBe(5000)
+	})
+})
+
+describe('the danger flag reads the command', () => {
+	it('marks a destructive command destructive', () => {
+		expect(BashTool.isDestructive?.({ command: 'rm -rf /', timeout: 1000 } as never)).toBe(true)
+	})
+
+	it('leaves an ordinary command alone', () => {
+		expect(BashTool.isDestructive?.({ command: 'ls -la', timeout: 1000 } as never)).toBe(false)
+	})
+})

package/src/tools/builtins/bash.ts

@@ -22,6 +22,25 @@ const DEFAULT_BASH_MAX_BUFFER_BYTES = readPositiveIntEnv(
 	100 * 1024 * 1024,
 )
 
+/**
+ * The longest deadline this tool will accept from the model.
+ *
+ * There are two clocks on a bash call and until now only one of them was
+ * declared. This tool enforces `input.timeout` itself; the EXECUTOR enforces
+ * a separate per-tool deadline, and with none declared here it fell back to
+ * its own generic default — also two minutes. The two agreed by coincidence,
+ * so a model that asked for five minutes because it knew the build was slow
+ * got two, from a clock it had not been told about, reported as an abandoned
+ * tool rather than as a command that ran out of time.
+ *
+ * So the tool declares a ceiling and the executor is given a deadline above
+ * it (see `timeoutMs` on the definition), which makes this the only clock
+ * that can fire in practice. A request past the ceiling is REFUSED rather
+ * than quietly clamped: the model asked for something specific, and silently
+ * giving it a different number is how it learns to distrust the answer.
+ */
+const MAX_BASH_TIMEOUT_MS = readPositiveIntEnv('NAMZU_BASH_MAX_TIMEOUT_MS', 10 * 60 * 1000)
+
 const inputSchema = z.object({
 	command: z
 		.string()
@@ -32,9 +51,11 @@ const inputSchema = z.object({
 	timeout: z
 		.preprocess(
 			(v) => (typeof v === 'string' ? Number(v) : v),
-			z.number().default(DEFAULT_BASH_TIMEOUT_MS),
+			z.number().positive().max(MAX_BASH_TIMEOUT_MS).default(DEFAULT_BASH_TIMEOUT_MS),
 		)
-		.describe(`Command timeout in milliseconds. Default: ${DEFAULT_BASH_TIMEOUT_MS}`),
+		.describe(
+			`Command timeout in milliseconds. Default: ${DEFAULT_BASH_TIMEOUT_MS}, maximum: ${MAX_BASH_TIMEOUT_MS}. For work that legitimately runs longer than the maximum, start it in the background and poll, rather than holding the turn open.`,
+		),
 })
 
 type BashInput = z.infer<typeof inputSchema>
@@ -53,6 +74,12 @@ export const BashTool = defineTool({
 	readOnly: false,
 	destructive: (input: BashInput) => isDangerousCommand(input.command),
 	concurrencySafe: false,
+	// Above the ceiling the input schema accepts, so the executor's deadline
+	// is a backstop rather than a second clock racing this tool's own. It used
+	// to be undefined, which meant the executor's generic default applied —
+	// the same two minutes as this tool's DEFAULT, so they agreed by accident
+	// and diverged the moment a model asked for longer.
+	timeoutMs: MAX_BASH_TIMEOUT_MS + 30_000,
 
 	async execute(input, context) {
 		if (isDangerousCommand(input.command)) {
@@ -133,26 +160,81 @@ export const BashTool = defineTool({
 		// a Stop tore down the model stream and left the command running,
 		// and the executor's deadline could only ever DETACH from the tool
 		// rather than end the work it started.
-		const { stdout, stderr } = await execAsync(input.command, {
-			cwd: context.workingDirectory,
-			timeout: input.timeout,
-			env: { ...process.env, ...context.env },
-			maxBuffer: DEFAULT_BASH_MAX_BUFFER_BYTES,
-			signal: context.abortSignal,
-		})
-
-		const output = [stdout ? `STDOUT:\n${stdout}` : '', stderr ? `STDERR:\n${stderr}` : '']
-			.filter(Boolean)
-			.join('\n\n')
-
-		return {
-			success: true,
-			output: output || '(no output)',
-			data: { exitCode: 0 },
+		// `exec` REJECTS on a non-zero exit, on its own timeout, and on a
+		// kill — and the rejection carries `stdout`, `stderr`, `code` and
+		// `killed`. Letting it propagate threw all of that away: the registry
+		// turned the throw into a structured failure, so the model was told a
+		// command failed and not one word about how.
+		//
+		// That is the common case, not an edge one. A failing test run and a
+		// failing build are the two things an agent runs bash for most, and
+		// both exit non-zero WITH the output that explains why. The sandbox
+		// branch above already reports all of it; this branch did not, so the
+		// same command told the model two different amounts depending on where
+		// it happened to run.
+		try {
+			const { stdout, stderr } = await execAsync(input.command, {
+				cwd: context.workingDirectory,
+				timeout: input.timeout,
+				env: { ...process.env, ...context.env },
+				maxBuffer: DEFAULT_BASH_MAX_BUFFER_BYTES,
+				signal: context.abortSignal,
+			})
+
+			return {
+				success: true,
+				output: formatShellOutput(stdout, stderr) || '(no output)',
+				data: { exitCode: 0 },
+			}
+		} catch (err) {
+			const failure = err as NodeJS.ErrnoException & {
+				stdout?: string
+				stderr?: string
+				code?: number | string
+				killed?: boolean
+				signal?: string
+			}
+
+			// A caller-owned Stop is the caller's, not a command failure.
+			if (context.abortSignal?.aborted) throw err
+
+			// `exec` reports its own timeout as a kill, and the distinction
+			// matters to the model: "ran out of time" is a different next move
+			// from "exited 1".
+			const timedOut = failure.killed === true && failure.signal === 'SIGTERM'
+			const exitCode = typeof failure.code === 'number' ? failure.code : undefined
+			const output = formatShellOutput(failure.stdout, failure.stderr)
+
+			return {
+				success: false,
+				output: output || '(no output)',
+				data: {
+					...(exitCode !== undefined ? { exitCode } : {}),
+					timedOut,
+					...(failure.signal ? { signal: failure.signal } : {}),
+				},
+				error: timedOut
+					? `Command timed out after ${input.timeout}ms. Any output it produced before the deadline is above.`
+					: exitCode !== undefined
+						? `Command exited with code ${exitCode}`
+						: `Command failed: ${failure.message}`,
+			}
 		}
 	},
 })
 
+/**
+ * The two streams, labelled, with empty ones left out.
+ *
+ * Shared by the success and failure paths so a command tells the model the
+ * same shape either way — the failure path used to tell it nothing at all.
+ */
+function formatShellOutput(stdout: string | undefined, stderr: string | undefined): string {
+	return [stdout ? `STDOUT:\n${stdout}` : '', stderr ? `STDERR:\n${stderr}` : '']
+		.filter(Boolean)
+		.join('\n\n')
+}
+
 function readPositiveIntEnv(key: string, fallback: number): number {
 	const value = process.env[key]?.trim()
 	if (!value) return fallback