@namzu/sdk 6.1.0 → 6.2.0

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()
+	})
+})

package/src/tools/coordinator/index.ts

@@ -34,6 +34,16 @@ export interface CoordinatorToolsOptions {
 	runtimeContext?: AgentRuntimeContext
 	allowedAgentIds: string[]
 
+	/**
+	 * May this run delegate at all? Defaults to true.
+	 *
+	 * Same field, same name, as SupervisorAgentConfig.allowDelegation — the
+	 * name is kept identical deliberately. This options bag already renames
+	 * agentIds to allowedAgentIds, and a second rename on the road between
+	 * the config and the decision would make the road untraceable.
+	 */
+	allowDelegation?: boolean
+
 	taskStore?: TaskStore
 
 	runId?: RunId
@@ -253,6 +263,7 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 	const {
 		gateway,
 		allowedAgentIds: agentIds,
+		allowDelegation,
 		taskStore,
 		runId,
 		getPlanManager,
@@ -715,8 +726,24 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 	// had to invent something to say — and one that would not do that was left
 	// calling `agent_task_list` in a sleep loop. That was never the model
 	// misbehaving; it was the only move available.
-	const tools: ToolDefinition[] =
-		agentIds.length > 0 ? [createTask, waitForTaskTool, cancelTask, agentTaskList] : [agentTaskList]
+	// Two independent reasons not to mount the delegation surface, and the
+	// second one is not derivable from the first.
+	//
+	// An empty roster answers WHO may be called: nobody, so the tools have
+	// nothing to act on. `allowDelegation: false` answers WHETHER this run may
+	// call anyone, which a non-empty roster cannot settle — a host that runs a
+	// specialist by putting its persona into the supervisor shell and its id
+	// into the roster has a list of one and must still delegate to nobody.
+	// From inside this function that run is indistinguishable from a
+	// supervisor whose roster happens to hold a single specialist, so the
+	// caller states the fact rather than the SDK guessing it.
+	//
+	// `!== false` rather than truthiness, so an absent flag keeps today's
+	// behaviour exactly.
+	const canDelegate = agentIds.length > 0 && allowDelegation !== false
+	const tools: ToolDefinition[] = canDelegate
+		? [createTask, waitForTaskTool, cancelTask, agentTaskList]
+		: [agentTaskList]
 
 	if (getPlanManager) {
 		const approvePlan = defineTool({

package/src/types/agent/supervisor.ts

@@ -19,6 +19,34 @@ export interface SupervisorAgentConfig extends BaseAgentConfig {
 
 	agentIds: string[]
 
+	/**
+	 * May this run invoke subagents at all? Defaults to `true`.
+	 *
+	 * `agentIds` answers WHO may be called; this answers WHETHER, and they are
+	 * different questions. A run whose own persona is the single agent on the
+	 * list has a non-empty list and still must not call anyone.
+	 *
+	 * It cannot be derived. Comparing the list against the executing agent
+	 * fails where a host substitutes a specialist's persona into the
+	 * supervisor shell — the two ids differ, so the predicate says "can
+	 * delegate" about a run that cannot. And no predicate over `agentIds`
+	 * could work, because a supervisor whose list holds one specialist and a
+	 * run that IS that specialist are indistinguishable in it. The fact lives
+	 * with the caller, so the caller states it.
+	 *
+	 * Positive polarity on purpose: `allowDelegation: false` reads correctly
+	 * the first time, where a `delegationDisabled` spelling inverts twice at
+	 * every site that consults it.
+	 *
+	 * **Absolute.** `runtimeToolOverrides` cannot put the delegation tools
+	 * back — the override pass runs over the tools this flag already declined
+	 * to build, and both values come from the same caller in the same call, so
+	 * "must not delegate" plus "give it `create_task`" is a contradiction
+	 * rather than extra knowledge. This matches `agentIds: []`, which is
+	 * absolute today for the same reason.
+	 */
+	allowDelegation?: boolean
+
 	gateway?: TaskGateway
 	agentManager?: AgentManagerContract
 	tools?: ToolRegistryContract