@namzu/sdk 6.1.0 → 7.0.0

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

package/src/tools/coordinator/__tests__/allow-delegation.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it } from 'vitest'
+
+import type { TaskGateway } from '../../../types/agent/gateway.js'
+import { buildCoordinatorTools } from '../index.js'
+
+/**
+ * Whether a run may delegate is not the same question as who it may delegate
+ * to, and only the caller can answer the first.
+ *
+ * The roster answers WHO. It cannot answer WHETHER, because two runs are
+ * indistinguishable in it: a supervisor whose roster happens to hold one
+ * specialist, where delegating is the point; and a run whose own persona IS
+ * that specialist, where delegating is delegating to itself. A host builds the
+ * second by putting a specialist's persona into the supervisor shell and its
+ * id into the roster — so a predicate comparing the roster against the
+ * executing agent sees two different ids and cheerfully says "can delegate".
+ *
+ * Measured before this existed: such a run carried `create_task`,
+ * `wait_for_task`, `cancel_task` and `agent_task_list`, byte-identical to a
+ * run that could actually delegate, and the model could only discover the
+ * refusal by spending a turn on it.
+ */
+
+const gateway = {
+	listTasks: () => [],
+	onTaskCompleted: () => () => {},
+} as unknown as TaskGateway
+
+function namesFor(opts: {
+	agentIds: string[]
+	allowDelegation?: boolean
+	withHitl?: boolean
+}): string[] {
+	return buildCoordinatorTools({
+		gateway,
+		workingDirectory: '/tmp/test',
+		allowedAgentIds: opts.agentIds,
+		...(opts.allowDelegation !== undefined ? { allowDelegation: opts.allowDelegation } : {}),
+		...(opts.withHitl
+			? { resumeHandler: (async () => ({ action: 'continue' })) as never, runId: 'run_1' as never }
+			: {}),
+	}).map((t) => t.name)
+}
+
+describe('a run can decline to delegate while still naming who it would have called', () => {
+	it('withholds the delegation tools when delegation is off', () => {
+		const names = namesFor({ agentIds: ['specialist'], allowDelegation: false })
+
+		expect(names).not.toContain('create_task')
+		expect(names).not.toContain('wait_for_task')
+		expect(names).not.toContain('cancel_task')
+	})
+
+	it('produces exactly the empty-roster surface', () => {
+		// The two reasons differ but the outcome is the same one tool, so a
+		// reader does not have to hold two shapes in their head.
+		expect(namesFor({ agentIds: ['specialist'], allowDelegation: false })).toEqual(
+			namesFor({ agentIds: [] }),
+		)
+	})
+
+	it('keeps the listing, because a run may still want to see what is running', () => {
+		expect(namesFor({ agentIds: ['specialist'], allowDelegation: false })).toContain(
+			'agent_task_list',
+		)
+	})
+
+	it('leaves the human channel alone — that is not delegation', () => {
+		// `approve_plan` and `ask_user_question` are the HITL park surface. A
+		// run that must not delegate needs them as much as any other.
+		const names = namesFor({ agentIds: ['specialist'], allowDelegation: false, withHitl: true })
+
+		expect(names).toContain('ask_user_question')
+	})
+})
+
+describe('an absent flag changes nothing', () => {
+	it('mounts the full surface, as it always did', () => {
+		const names = namesFor({ agentIds: ['specialist'] })
+
+		expect(names).toContain('create_task')
+		expect(names).toContain('wait_for_task')
+		expect(names).toContain('cancel_task')
+		expect(names).toContain('agent_task_list')
+	})
+
+	it('is identical to opting in explicitly', () => {
+		// So adopting the flag cannot change a caller that says yes out loud.
+		expect(namesFor({ agentIds: ['a', 'b'], allowDelegation: true })).toEqual(
+			namesFor({ agentIds: ['a', 'b'] }),
+		)
+	})
+
+	it('still withholds everything on an empty roster, flag or no flag', () => {
+		expect(namesFor({ agentIds: [], allowDelegation: true })).toEqual(['agent_task_list'])
+	})
+})
+
+describe('the flag is absolute', () => {
+	it('cannot be overridden back on', () => {
+		// Worth a test precisely because the opposite is the intuitive guess:
+		// "explicit beats implicit" would say a runtime override should win.
+		// It cannot, mechanically — the override pass in SupervisorAgent runs
+		// over the array this builder returns, and there is no entry for it to
+		// act on. And it should not: both values come from the same caller in
+		// the same call, so "this run must not delegate" plus "give it
+		// create_task" is a caller contradicting itself, not one who knows
+		// something extra.
+		//
+		// Same rule the empty roster has always had.
+		const tools = buildCoordinatorTools({
+			gateway,
+			workingDirectory: '/tmp/test',
+			allowedAgentIds: ['specialist'],
+			allowDelegation: false,
+		})
+
+		expect(tools.find((t) => t.name === 'create_task')).toBeUndefined()
+	})
+})