@namzu/sdk 34.2.0 → 36.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,31 +69,215 @@ 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 {
 	return DANGEROUS_PATTERNS.some((pattern) => pattern.test(command))
 }
 
+/** The refusal when a sandbox cannot host a detached process; exported so the test states the same words. */
+export const SANDBOX_CANNOT_DETACH =
+	'run_in_background is unavailable: this sandbox cannot start a detached process, and the job will not be run on the host to get around it. Run the command in the foreground, or raise `timeout` up to the tool maximum.'
+
 export const BashTool = defineTool({
 	name: 'bash',
 	description:
@@ -123,21 +309,16 @@ export const BashTool = defineTool({
 		}
 
 		if (input.run_in_background) {
-			// The current registry owns a host process. Foreground execution,
-			// however, goes through `context.sandbox.exec()` below. Treating the
-			// same command as host work just because `run_in_background` changed
-			// would make that boolean an escape hatch from the configured boundary.
-			//
-			// Query-built contexts structurally withhold the registry in this
-			// composition. This explicit check also protects direct tool callers
-			// and says why the capability is absent instead of misdiagnosing the
-			// host as having configured no registry.
-			if (context.sandbox) {
+			// A sandboxed run gets a registry only when its sandbox can start a
+			// detached process inside the boundary (`Sandbox.spawnDetached`);
+			// the executor withholds it otherwise. This check is for direct
+			// tool callers, who could hand a host registry and a sandbox to the
+			// same context: the boolean is never an escape from the boundary.
+			if (context.sandbox && context.sandbox.spawnDetached === undefined) {
 				return {
 					success: false,
 					output: '',
-					error:
-						'run_in_background is unavailable while a sandbox is active because the host background-job registry cannot preserve that sandbox boundary. Run the command in the foreground, or use a sandbox-aware persistent-process capability.',
+					error: SANDBOX_CANNOT_DETACH,
 				}
 			}
 			// Refused, not degraded to `cmd &`. The fallback is not a lesser
@@ -193,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,
@@ -207,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
@@ -236,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
@@ -279,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)',
@@ -296,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)
@@ -326,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

@@ -152,7 +152,11 @@ function buildDescription(host: ComputerUseHost): string {
 		`Available actions: ${available.join('; ') || 'none'}.`,
 	]
 	if (unavailable.length > 0) {
-		lines.push(`Unavailable on this host: ${unavailable.join(', ')}.`)
+		lines.push(
+			caps.unavailableReason
+				? `Unavailable on this host: ${unavailable.join(', ')} — ${caps.unavailableReason} Do not retry; tell the user.`
+				: `Unavailable on this host: ${unavailable.join(', ')}.`,
+		)
 	}
 	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.',
@@ -303,7 +307,7 @@ export function createComputerUseTool(host: ComputerUseHost): ToolDefinition<Act
 				return {
 					success: false,
 					output: '',
-					error: `computer_use: action "${input.type}" requires capability "${required}" which is not available on this host (displayServer=${host.capabilities.displayServer}).`,
+					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.` : ''}`,
 				}
 			}
 			try {

package/src/tools/builtins/edit.ts

@@ -3,7 +3,7 @@ import { readFile } from 'node:fs/promises'
 import { z } from 'zod'
 import type { ToolResult } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
-import { resolveWithinReal } from '../paths.js'
+import { resolveWithinAnyReal, toolRoots } from '../paths.js'
 import { atomicWriteFile } from './atomic-write-file.js'
 import { fingerprintContent, staleFileError } from './content-fingerprint.js'
 import { withFileMutationLock } from './file-mutation-lock.js'
@@ -350,7 +350,7 @@ export const EditTool = defineTool({
 		// machine, and answers it with whatever happens to exist there.
 		const filePath = context.sandbox
 			? undefined
-			: await resolveWithinReal(context.workingDirectory, parsed.data.path)
+			: await resolveWithinAnyReal(toolRoots(context), parsed.data.path)
 		// Read-modify-write is not atomic on its own: two edits to the same
 		// path interleave their reads, and the second write lands on content
 		// the first had already replaced — so one edit vanishes and the loser