@namzu/sdk 35.0.0 → 37.0.0

package/src/tools/builtins/bash.ts

@@ -1,11 +1,13 @@
-import { exec } from 'node:child_process'
-import { promisify } from 'node:util'
+import { spawn } from 'node:child_process'
+import { StringDecoder } from 'node:string_decoder'
 import { z } from 'zod'
+import { SANDBOX_KILL_GRACE_MS } from '../../constants/sandbox/index.js'
 import { DANGEROUS_PATTERNS } from '../../constants/tools/index.js'
+import { killTree } from '../../process/kill-tree.js'
+import { subscribeToAbort } from '../../utils/abort.js'
 import { defineTool } from '../defineTool.js'
 import { scrubInheritedEnv } from '../env-scrub.js'
 
-const execAsync = promisify(exec)
 // Namzu owns its own bash timeout knob — `NAMZU_BASH_TIMEOUT_MS`.
 // The Vandal fallback (`VANDAL_NAMZU_TIMEOUT_MS`) lived here as a
 // historical bridge while Namzu was carved out of the Vandal repo,
@@ -67,25 +69,205 @@ const inputSchema = z.object({
 
 type BashInput = z.infer<typeof inputSchema>
 
+const MAX_SHELL_PROGRESS_CHARS = 160
+
+/** Keep a bounded tail even when a process never writes a newline. */
+function appendProgressTail(previous: string, chunk: string, start: number, end: number): string {
+	return (previous + chunk.slice(Math.max(start, end - MAX_SHELL_PROGRESS_CHARS), end)).slice(
+		-MAX_SHELL_PROGRESS_CHARS,
+	)
+}
+
+/** Clipping a UTF-16 string must not display half of a surrogate pair. */
+function progressLine(value: string): string {
+	let line = value.trim()
+	const first = line.charCodeAt(0)
+	if (first >= 0xdc00 && first <= 0xdfff) line = line.slice(1)
+	const last = line.charCodeAt(line.length - 1)
+	if (last >= 0xd800 && last <= 0xdbff) line = line.slice(0, -1)
+	return line
+}
+
 /**
- * The last line worth showing from one chunk of streamed output.
- *
- * A progress line is a status, not a log: the host renders one line and
- * replaces it as the next arrives, so sending a whole chunk sends a wall
- * of text into a slot that shows one line of it. A chunk usually ends
- * mid-line and usually ends with a newline, so the last NON-EMPTY line is
- * the most recent complete thing the command actually said.
- *
- * Progress is capped rather than truncated with an ellipsis: this is
- * glanced at, and a marker in a line nobody reads to the end is noise.
+ * One latest line per stream, independent of transport chunk boundaries.
+ * Reports stay synchronous: the executor owns coalescing and backpressure.
+ * This projection adds neither an output log nor a queue of pending reports.
  */
-function lastNonEmptyLine(chunk: string): string | undefined {
-	const lines = chunk.split('\n')
-	for (let i = lines.length - 1; i >= 0; i--) {
-		const line = lines[i]?.trim()
-		if (line) return line.length > 160 ? line.slice(0, 160) : line
+function shellProgress(report?: (message: string) => void) {
+	if (!report) return undefined
+	const partial = { stdout: '', stderr: '' }
+	let lastMessage = ''
+	return ({ stream, data }: { stream: 'stdout' | 'stderr'; data: string }): void => {
+		let line = partial[stream]
+		let latest = ''
+		let start = 0
+		// Scan delimiters without allocating an array for arbitrarily chatty output.
+		for (const match of data.matchAll(/[\r\n]/g)) {
+			line = appendProgressTail(line, data, start, match.index)
+			latest = progressLine(line) || latest
+			line = ''
+			start = match.index + 1
+		}
+		line = appendProgressTail(line, data, start, data.length)
+		partial[stream] = line
+		const message = progressLine(line) || latest
+		if (!message || message === lastMessage) return
+		lastMessage = message
+		try {
+			report(message)
+		} catch {
+			// A diagnostic observer cannot break the process output reader.
+		}
 	}
-	return undefined
+}
+
+/**
+ * Keep the shell's process group until inherited pipes close. Node's exec
+ * timeout/AbortSignal kills only the wrapper and closes its pipes immediately,
+ * leaving the command and its descendants running after the promise settles.
+ */
+function execHostShell(
+	command: string,
+	options: {
+		cwd: string
+		env: NodeJS.ProcessEnv
+		timeout: number
+		maxBuffer: number
+		signal?: AbortSignal
+		onOutput?: ReturnType<typeof shellProgress>
+	},
+): Promise<{ stdout: string; stderr: string }> {
+	options.signal?.throwIfAborted()
+	return new Promise((resolve, reject) => {
+		const child = spawn(command, {
+			cwd: options.cwd,
+			env: options.env,
+			shell: true,
+			// killTree's negative PID must never target the caller's own group.
+			detached: process.platform !== 'win32',
+		})
+		const captures = {
+			stdout: {
+				chunks: [] as Buffer[],
+				bytes: 0,
+				truncated: false,
+				decoder: new StringDecoder('utf8'),
+			},
+			stderr: {
+				chunks: [] as Buffer[],
+				bytes: 0,
+				truncated: false,
+				decoder: new StringDecoder('utf8'),
+			},
+		}
+		let cause: 'caller' | 'timeout' | 'maxBuffer' | undefined
+		let failure: (Error & { code?: string | number }) | undefined
+		let escalation: ReturnType<typeof setTimeout> | undefined
+		let disposeAbort: (() => void) | undefined
+		let closed = false
+		const cancel = (origin: NonNullable<typeof cause>) => {
+			if (closed || cause !== undefined) return
+			cause = origin
+			escalation = setTimeout(() => {
+				escalation = undefined
+				killTree(child, 'SIGKILL')
+				// A descendant can deliberately start a separate session. It is
+				// outside this group, but its inherited pipes must not hold the
+				// cancelled call forever. Keep what was captured during grace.
+				child.stdin?.destroy()
+				child.stdout?.destroy()
+				child.stderr?.destroy()
+			}, SANDBOX_KILL_GRACE_MS)
+			escalation.unref?.()
+			killTree(child, 'SIGTERM')
+		}
+		const capture = (stream: 'stdout' | 'stderr', chunk: Buffer) => {
+			const state = captures[stream]
+			const kept = Math.min(chunk.length, options.maxBuffer - state.bytes)
+			if (kept > 0) {
+				state.chunks.push(Buffer.from(chunk.subarray(0, kept)))
+				state.bytes += kept
+			}
+			if (kept < chunk.length) {
+				state.truncated = true
+				if (cause === undefined) {
+					failure = Object.assign(new RangeError(`${stream} maxBuffer length exceeded`), {
+						code: 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER',
+					})
+					cancel('maxBuffer')
+				}
+			}
+			if (options.onOutput) {
+				const data = state.decoder.write(chunk)
+				if (data) options.onOutput({ stream, data })
+			}
+		}
+		const onStdout = (chunk: Buffer) => capture('stdout', chunk)
+		const onStderr = (chunk: Buffer) => capture('stderr', chunk)
+		child.stdout?.on('data', onStdout)
+		child.stderr?.on('data', onStderr)
+		child.once('error', (error: NodeJS.ErrnoException) => {
+			failure ??= error
+		})
+		child.once('close', (code, signal) => {
+			closed = true
+			disposeAbort?.()
+			clearTimeout(deadline)
+			if (escalation !== undefined) {
+				clearTimeout(escalation)
+				// Pipes closing can precede a descendant which closed its copies.
+				// Force the owned group now instead of retaining its PID in a timer.
+				killTree(child, 'SIGKILL')
+			}
+			child.stdout?.off('data', onStdout)
+			child.stderr?.off('data', onStderr)
+			for (const stream of ['stdout', 'stderr'] as const) {
+				const data = captures[stream].decoder.end()
+				if (data) options.onOutput?.({ stream, data })
+			}
+			const decodeCapture = (stream: 'stdout' | 'stderr') => {
+				const state = captures[stream]
+				const bytes = Buffer.concat(state.chunks, state.bytes)
+				// Do not flush an incomplete UTF-8 character cut by our byte cap.
+				return state.truncated ? new StringDecoder('utf8').write(bytes) : bytes.toString('utf8')
+			}
+			const stdout = decodeCapture('stdout')
+			const stderr = decodeCapture('stderr')
+			if (!failure && cause === undefined && code === 0 && signal === null) {
+				resolve({ stdout, stderr })
+				return
+			}
+			const error =
+				failure ??
+				(cause === 'caller'
+					? Object.assign(
+							new Error('The operation was aborted', { cause: options.signal?.reason }),
+							{
+								name: 'AbortError',
+								code: 'ABORT_ERR',
+							},
+						)
+					: new Error(`Command failed: ${command}\n${stderr}`))
+			reject(
+				Object.assign(error, {
+					stdout,
+					stderr,
+					stdoutTruncated: captures.stdout.truncated,
+					stderrTruncated: captures.stderr.truncated,
+					code: failure?.code ?? (cause === 'caller' ? 'ABORT_ERR' : code),
+					killed: cause !== undefined,
+					signal,
+					timedOut: cause === 'timeout',
+				}),
+			)
+		})
+		const deadline = setTimeout(() => cancel('timeout'), options.timeout)
+		deadline.unref?.()
+		if (options.signal) {
+			disposeAbort = subscribeToAbort(options.signal, () => cancel('caller'))
+			if (options.signal.aborted) cancel('caller')
+		}
+	})
 }
 
 function isDangerousCommand(command: string): boolean {
@@ -192,6 +374,7 @@ export const BashTool = defineTool({
 		// sandbox can be added later as an explicit
 		// `SandboxExecOptions.workspaceRelativeCwd` field; the bash
 		// builtin doesn't have that requirement today.
+		const onOutput = shellProgress(context.report)
 		if (context.sandbox) {
 			const result = await context.sandbox.exec('/bin/sh', ['-c', input.command], {
 				timeout: input.timeout,
@@ -206,22 +389,9 @@ export const BashTool = defineTool({
 				// durable transcript — so this is a progress signal, not a
 				// second copy of the output. `result.stdout` remains the
 				// answer the model is given.
-				onOutput: context.report
-					? ({ data }) => {
-							const line = lastNonEmptyLine(data)
-							if (line) context.report?.(line)
-						}
-					: undefined,
+				onOutput,
 			})
 
-			if (result.timedOut) {
-				return {
-					success: false,
-					output: '',
-					error: `Command timed out after ${input.timeout}ms`,
-				}
-			}
-
 			// The sandbox reports when IT clipped a stream. Dropping those
 			// flags meant the model saw a complete-looking result that had
 			// silently lost its tail — and the kernel's own convention is
@@ -235,41 +405,32 @@ export const BashTool = defineTool({
 				result.stdout ? `STDOUT:\n${result.stdout}` : '',
 				result.stderr ? `STDERR:\n${result.stderr}` : '',
 				clipped.length > 0
-					? `[${clipped.join(' and ')} was truncated by the sandbox output cap — re-run with a filter (grep/head/tail) to see the rest]`
+					? `[${clipped.join(' and ')} was truncated by the sandbox output cap. The omitted output is unavailable in this result. Use a saved artifact or a read-only observation; do not repeat a state-changing action to recover its output.]`
 					: '',
 			]
 				.filter(Boolean)
 				.join('\n\n')
 
 			return {
-				success: result.exitCode === 0,
+				success: !result.timedOut && result.exitCode === 0,
 				output: output || '(no output)',
 				data: {
 					exitCode: result.exitCode,
 					sandboxed: true,
+					timedOut: result.timedOut,
 					stdoutTruncated: result.stdoutTruncated ?? false,
 					stderrTruncated: result.stderrTruncated ?? false,
 				},
-				error: result.exitCode !== 0 ? `Command exited with code ${result.exitCode}` : undefined,
+				error: result.timedOut
+					? `Command timed out after ${input.timeout}ms. Any captured output before the deadline is above.`
+					: result.exitCode !== 0
+						? `Command exited with code ${result.exitCode}`
+						: undefined,
 			}
 		}
 
-		// Thread the run/deadline signal into the child process. Without it
-		// 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.
-		// `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.
+		// The owned runner retains stdout/stderr on non-zero exit and timeout,
+		// so a failed command still returns the evidence explaining its failure.
 		// The inherited half is scrubbed; `context.env` is not. Inheritance is
 		// implicit — nobody decided this command should see `process.env` — while
 		// a `context.env` key is one a host wrote on purpose. See
@@ -278,14 +439,14 @@ export const BashTool = defineTool({
 		const inherited = scrubInheritedEnv()
 
 		try {
-			const { stdout, stderr } = await execAsync(input.command, {
+			const { stdout, stderr } = await execHostShell(input.command, {
 				cwd: context.workingDirectory,
 				timeout: input.timeout,
 				env: { ...inherited.env, ...context.env },
 				maxBuffer: DEFAULT_BASH_MAX_BUFFER_BYTES,
 				signal: context.abortSignal,
+				onOutput,
 			})
-
 			return {
 				success: true,
 				output: formatShellOutput(stdout, stderr) || '(no output)',
@@ -295,25 +456,34 @@ export const BashTool = defineTool({
 			const failure = err as NodeJS.ErrnoException & {
 				stdout?: string
 				stderr?: string
+				stdoutTruncated?: boolean
+				stderrTruncated?: boolean
 				code?: number | string
 				killed?: boolean
 				signal?: string
+				timedOut?: boolean
 			}
 
 			// 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'
+			// A maxBuffer stop or an ordinary signal is not a deadline. The
+			// runner latches the first cancellation cause before signalling.
+			const timedOut = failure.timedOut === true
 			const exitCode = typeof failure.code === 'number' ? failure.code : undefined
+			const clipped = [
+				failure.stdoutTruncated ? 'stdout' : '',
+				failure.stderrTruncated ? 'stderr' : '',
+			].filter(Boolean)
 			// Only on the failure path. A successful command did not need to know,
 			// and appending this to every result would make the common case noisy
 			// to buy nothing. A failing one is exactly where "authentication
 			// failed" has to be distinguishable from "the variable was withheld".
 			const output = [
 				formatShellOutput(failure.stdout, failure.stderr),
+				clipped.length > 0
+					? `[${clipped.join(' and ')} ${clipped.length === 1 ? 'was' : 'were'} truncated by the host output cap. The omitted output is unavailable in this result.]`
+					: '',
 				describeWithheldEnv(inherited.dropped),
 			]
 				.filter(Boolean)
@@ -325,6 +495,8 @@ export const BashTool = defineTool({
 				data: {
 					...(exitCode !== undefined ? { exitCode } : {}),
 					timedOut,
+					stdoutTruncated: failure.stdoutTruncated ?? false,
+					stderrTruncated: failure.stderrTruncated ?? false,
 					...(failure.signal ? { signal: failure.signal } : {}),
 				},
 				error: timedOut

package/src/tools/builtins/computer-use.ts

@@ -63,7 +63,7 @@ const pointModelInputSchema = {
 	additionalProperties: false,
 } as const
 
-const modelInputSchema: Record<string, unknown> = {
+const modelInputSchema = {
 	type: 'object',
 	properties: {
 		type: {
@@ -136,16 +136,17 @@ function requiredCapability(type: ComputerUseAction['type']): keyof ComputerUseC
 
 function buildDescription(host: ComputerUseHost): string {
 	const caps = host.capabilities
-	const available: string[] = []
-	if (caps.screenshot) available.push('screenshot')
-	if (caps.cursorPosition) available.push('cursor_position')
-	if (caps.mouse) available.push('mouse_move, mouse_click, mouse_drag, scroll')
-	if (caps.keyboard) available.push('type_text, key')
+	const available = availableActions(caps)
 	const unavailable: string[] = []
 	if (!caps.screenshot) unavailable.push('screenshot')
 	if (!caps.cursorPosition) unavailable.push('cursor_position')
 	if (!caps.mouse) unavailable.push('mouse')
 	if (!caps.keyboard) unavailable.push('keyboard')
+	if (caps.supportedActions) {
+		for (const action of actionSchema.options.map((option) => option.shape.type.value)) {
+			if (!available.includes(action)) unavailable.push(action)
+		}
+	}
 
 	const lines = [
 		`Controls the user's desktop on a ${caps.displayServer} host. Use to take screenshots and drive mouse/keyboard input for GUI tasks.`,
@@ -161,9 +162,42 @@ function buildDescription(host: ComputerUseHost): string {
 	lines.push(
 		'Coordinates are in logical pixels from the top-left of the primary display. Call getDisplayGeometry through screenshot output before clicking to confirm bounds.',
 	)
+	if (caps.mouseClickButtons && available.includes('mouse_click'))
+		lines.push(`Click buttons: ${caps.mouseClickButtons.join(', ') || 'none'}.`)
+	if (caps.mouseDragButtons && available.includes('mouse_drag'))
+		lines.push(`Drag buttons: ${caps.mouseDragButtons.join(', ') || 'none'}.`)
 	return lines.join(' ')
 }
 
+function availableActions(caps: ComputerUseCapabilities): ComputerUseAction['type'][] {
+	return actionSchema.options
+		.map((option) => option.shape.type.value)
+		.filter((action) => {
+			const required = requiredCapability(action)
+			return (
+				(required === null || caps[required] === true) &&
+				(caps.supportedActions === undefined || caps.supportedActions.includes(action)) &&
+				(action !== 'mouse_click' || caps.mouseClickButtons?.length !== 0) &&
+				(action !== 'mouse_drag' || caps.mouseDragButtons?.length !== 0)
+			)
+		})
+}
+
+function hostModelSchema(caps: ComputerUseCapabilities): Record<string, unknown> {
+	const schema = structuredClone(modelInputSchema)
+	const actions = availableActions(caps)
+	// An unavailable host remains a diagnostic tool. Avoid invalid empty enums
+	// on provider wires; every execution is still refused before host access.
+	if (actions.length > 0) schema.properties.type.enum = actions
+	const buttons = new Set<string>()
+	if (actions.includes('mouse_click'))
+		for (const button of caps.mouseClickButtons ?? ['left', 'right', 'middle']) buttons.add(button)
+	if (actions.includes('mouse_drag'))
+		for (const button of caps.mouseDragButtons ?? ['left', 'right', 'middle']) buttons.add(button)
+	if (buttons.size > 0) schema.properties.button.enum = [...buttons]
+	return schema
+}
+
 function pointLabel(point: { readonly x: number; readonly y: number }): string {
 	return `(${point.x}, ${point.y})`
 }
@@ -283,7 +317,7 @@ export function createComputerUseTool(host: ComputerUseHost): ToolDefinition<Act
 		name: COMPUTER_USE_TOOL_NAME,
 		description: buildDescription(host),
 		inputSchema: actionSchema,
-		modelInputSchema: structuredClone(modelInputSchema),
+		modelInputSchema: hostModelSchema(host.capabilities),
 		validationErrorHint:
 			'Action requirements: mouse_move needs "to"; mouse_click needs "at" and "button"; mouse_drag needs "from", "to", and "button"; scroll needs "at", "direction", and positive "amount"; type_text needs "text"; key needs "keys".',
 		category: 'custom',
@@ -310,6 +344,26 @@ export function createComputerUseTool(host: ComputerUseHost): ToolDefinition<Act
 					error: `computer_use: action "${input.type}" requires capability "${required}" which is not available on this host (displayServer=${host.capabilities.displayServer}).${host.capabilities.unavailableReason ? ` ${host.capabilities.unavailableReason} Do not retry; tell the user.` : ''}`,
 				}
 			}
+			if (!availableActions(host.capabilities).includes(input.type)) {
+				return {
+					success: false,
+					output: '',
+					error: `computer_use: action "${input.type}" is not supported on this host.`,
+				}
+			}
+			const buttons =
+				input.type === 'mouse_click'
+					? host.capabilities.mouseClickButtons
+					: input.type === 'mouse_drag'
+						? host.capabilities.mouseDragButtons
+						: undefined
+			if (buttons && 'button' in input && !buttons.includes(input.button)) {
+				return {
+					success: false,
+					output: '',
+					error: `computer_use: action "${input.type}" does not support button "${input.button}" on this host.`,
+				}
+			}
 			try {
 				const result = await host.execute(input as ComputerUseAction)
 				return resultToToolResult(result)