@namzu/sdk 57.0.0 → 58.0.0

package/src/tools/builtins/bash-cwd.ts

@@ -0,0 +1,156 @@
+/**
+ * The directory a `bash` call starts in, carried from one call to the next.
+ *
+ * A model that runs `cd packages/app` expects the next call to be there; shell
+ * state (variables, functions, aliases) does not carry over, but the directory
+ * does. After a foreground command the shell writes its physical directory to a
+ * private file, and the next call of the same session starts there.
+ *
+ * Two limits keep this from widening what a command can reach. The new
+ * directory has to lie inside the turn's roots (the working directory, the
+ * directories added for the session, any path this call was approved for); a
+ * command that leaves them is put back at the session's working directory and
+ * the result says so. And a directory that no longer exists is dropped without
+ * ceremony. Nothing here applies to a sandboxed command or to Windows shells,
+ * whose paths a host process cannot use as they are printed.
+ */
+
+import { randomUUID } from 'node:crypto'
+import { statSync } from 'node:fs'
+import { rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { type CommandShell, hostCommandShell } from '../command-shell.js'
+import { pathOutsideRoots, toolRoots } from '../paths.js'
+import { readBoundedFile } from './bounded-file-read.js'
+
+interface Carried {
+	/** The working directory the session started with; the fallback. */
+	readonly base: string
+	cwd: string
+}
+
+/** Sessions remembered; the oldest is forgotten first. */
+const MAX_SESSIONS = 256
+const carried = new Map<string, Carried>()
+
+/** The notice appended to a result when the command left the allowed directories. */
+export function cwdResetNotice(base: string): string {
+	return `Shell cwd was reset to ${base}`
+}
+
+/** Single-quote `text` for a POSIX shell. */
+function shellQuote(text: string): string {
+	return `'${text.replace(/'/g, `'\\''`)}'`
+}
+
+/**
+ * Runs `command` unchanged and records the directory it ended in. The exit
+ * status is the command's own. A command that ends the shell itself (`exit`)
+ * records nothing, so the directory stays as it was.
+ */
+export function withCwdCapture(command: string, file: string): string {
+	return `eval ${shellQuote(command)}\n__namzu_status=$?\npwd -P >| ${shellQuote(file)} 2>/dev/null\nexit $__namzu_status`
+}
+
+export function newCwdFile(): string {
+	return join(tmpdir(), `namzu-cwd-${randomUUID()}`)
+}
+
+/** Where this session's next foreground call starts. Synchronous: the spawn must not wait on it. */
+export function startingDirectory(sessionId: string, base: string): string {
+	const entry = carried.get(sessionId)
+	if (entry === undefined) return base
+	if (entry.base !== base) {
+		carried.delete(sessionId)
+		return base
+	}
+	try {
+		if (statSync(entry.cwd).isDirectory()) return entry.cwd
+	} catch {
+		// Removed or unreadable: start again from the base.
+	}
+	entry.cwd = base
+	return base
+}
+
+/**
+ * The cwd used by bash execution and host authorization. Hosts must resolve it
+ * for each call, not cache the session's initial directory. Sandboxed commands
+ * (including sandbox escapes) and Windows never use the carried POSIX cwd.
+ */
+export function effectiveBashWorkingDirectory(
+	sessionId: string | undefined,
+	workingDirectory: string,
+	options: {
+		sandboxed?: boolean
+		shell?: Pick<CommandShell, 'path' | 'windows'>
+	} = {},
+): string {
+	const shell = options.shell ?? hostCommandShell()
+	if (options.sandboxed || sessionId === undefined || shell.windows || shell.path === undefined)
+		return workingDirectory
+	return startingDirectory(sessionId, workingDirectory)
+}
+
+/**
+ * Reads what the finished command recorded and keeps it for the next call.
+ * Returns the notice to append when the directory was outside the roots.
+ */
+export async function recordDirectory(
+	sessionId: string,
+	file: string,
+	context: Parameters<typeof toolRoots>[0],
+): Promise<string | undefined> {
+	let reported: string
+	try {
+		reported = (await readBoundedFile(file, 64 * 1024)).toString('utf8').trim()
+	} catch {
+		return undefined
+	} finally {
+		await rm(file, { force: true })
+	}
+	if (reported === '') return undefined
+	const base = context.workingDirectory
+	const outside = await pathOutsideRoots(toolRoots(context), reported)
+	const next = outside === undefined ? reported : base
+	carried.delete(sessionId)
+	if (next !== base) {
+		carried.set(sessionId, { base, cwd: next })
+		if (carried.size > MAX_SESSIONS) {
+			const oldest = carried.keys().next().value
+			if (oldest !== undefined) carried.delete(oldest)
+		}
+	}
+	return outside === undefined ? undefined : cwdResetNotice(base)
+}
+
+/** For tests: forget every session. */
+export function forgetCarriedDirectories(): void {
+	carried.clear()
+}
+
+// Enumerable symbol crosses the executor's context copies, never the model's
+// JSON input. No public ToolContext field or caller-authored cwd is trusted.
+const REVIEWED_CWD = Symbol('namzu.bash.reviewed-cwd')
+
+export function pinBashWorkingDirectory(context: object, cwd: string): void {
+	Object.defineProperty(context, REVIEWED_CWD, { value: cwd, enumerable: true, configurable: true })
+}
+
+export function bashWorkingDirectoryForExecution(context: {
+	sessionId?: string
+	workingDirectory: string
+	sandbox?: unknown
+}): string {
+	const current = effectiveBashWorkingDirectory(context.sessionId, context.workingDirectory, {
+		sandboxed: context.sandbox !== undefined,
+	})
+	const reviewed = (context as { [REVIEWED_CWD]?: string })[REVIEWED_CWD]
+	if (reviewed !== undefined && current !== reviewed)
+		throw new Error(
+			'Shell working directory changed after this call was reviewed. Nothing ran. Retry the call so its paths can be checked in the current directory.',
+		)
+	return reviewed ?? current
+}

package/src/tools/builtins/bash.ts

@@ -1,3 +1,4 @@
+import { rm } from 'node:fs/promises'
 import { z } from 'zod'
 import { isReadOnlyCommandLine } from '../../authorization/readonly-commands.js'
 import { SANDBOX_KILL_GRACE_MS } from '../../constants/sandbox/index.js'
@@ -24,8 +25,15 @@ import { defineTool } from '../defineTool.js'
 import { scrubInheritedEnv, withheldEnvNoticeText } from '../env-scrub.js'
 import { createHostOutputDecoder } from '../host-output.js'
 import { looksBinary, windowText } from '../text-window.js'
+import {
+	bashWorkingDirectoryForExecution,
+	newCwdFile,
+	recordDirectory,
+	withCwdCapture,
+} from './bash-cwd.js'
 import { judgeExit } from './exit-semantics.js'
 import { jsonStringEscapes } from './json-string-hint.js'
+import { leadingLongSleep, longSleepRefusal } from './sleep-guard.js'
 
 // Namzu owns its own bash timeout knob — `NAMZU_BASH_TIMEOUT_MS` — and
 // reads no consumer's env name. A consumer that wants one knob aliases
@@ -526,7 +534,7 @@ export const SANDBOX_ESCAPE_NOT_APPROVED =
 	'dangerously_disable_sandbox was not approved for this call, so the command did not run. Leaving the sandbox needs the user to confirm it each time, and this turn either cannot ask or does not allow it. Run the command inside the sandbox, or tell the user what it needs and let them run it.'
 
 const BASH_DESCRIPTION =
-	'Executes a command line using the execution shell disclosed in the system context and returns stdout/stderr output. Command timeout is configurable. The `command` parameter is required, so every call carries one. Long file content goes through `write`, not a heredoc, so it cannot hit the output token limit mid-stream.'
+	'Executes a command line using the execution shell disclosed in the system context and returns stdout/stderr output. The working directory persists between calls, but shell state does not. Command timeout is configurable. The `command` parameter is required, so every call carries one. Long file content goes through `write`, not a heredoc, so it cannot hit the output token limit mid-stream.'
 
 const BashToolBase = defineTool({
 	name: 'bash',
@@ -579,6 +587,7 @@ const BashToolBase = defineTool({
 	},
 
 	async execute(input, context) {
+		const startDirectory = bashWorkingDirectoryForExecution(context)
 		if (isDangerousCommand(input.command)) {
 			return {
 				success: false,
@@ -588,6 +597,15 @@ const BashToolBase = defineTool({
 			}
 		}
 
+		// Where a job registry exists to wait on, a long leading sleep only
+		// holds the turn; it is refused with the better ways to wait.
+		if (!input.run_in_background && context.backgroundJobs && !backgroundTasksDisabled()) {
+			const longSleep = leadingLongSleep(input.command)
+			if (longSleep !== null) {
+				return { success: false, output: '', error: longSleepRefusal(longSleep) }
+			}
+		}
+
 		// Asked to leave the sandbox. Honoured only on the executor's word that
 		// a reviewer confirmed THIS call (`sandboxEscapeApproved`); the input
 		// alone is the model's request, never the permission. Without a
@@ -648,7 +666,7 @@ const BashToolBase = defineTool({
 			try {
 				const job = context.backgroundJobs.start({
 					command: input.command,
-					workingDirectory: context.workingDirectory,
+					workingDirectory: startDirectory,
 				})
 				// `start` returns before the process exists, and a spawn that
 				// fails (no such shell, bad directory) reports a tick later.
@@ -799,38 +817,57 @@ const BashToolBase = defineTool({
 		let withdrawOffer: (() => void) | undefined
 		const offer = context.backgroundJobs?.registerForeground?.bind(context.backgroundJobs)
 
+		// The directory carries over between calls of a session on a POSIX host
+		// shell; the shell records where it ended, read back in `finally`.
+		const hostShell = hostCommandShell()
+		const carryDirectory =
+			context.sandbox === undefined &&
+			typeof context.sessionId === 'string' &&
+			hostShell.path !== undefined &&
+			hostShell.windows !== true
+		const cwdFile = carryDirectory ? newCwdFile() : undefined
+		let settled = false
+		const settle = async (): Promise<string | undefined> => {
+			if (cwdFile === undefined) return undefined
+			settled = true
+			return recordDirectory(context.sessionId, cwdFile, context)
+		}
+
 		try {
 			const { stdout, stderr, stdoutBytes, stderrBytes, backgroundedJobId, backgroundedBy } =
-				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,
-					...(canMoveOnTimeout ? { onTimeout: adoptRunning } : {}),
-					...(canHandOff
-						? {
-								adopt: adoptRunning,
-								adoptOnInterrupt: true,
-								...(offer
-									? {
-											onRunning: (control: {
-												background(reason: 'user' | 'message'): boolean
-											}) => {
-												offerTimer = setTimeout(() => {
-													withdrawOffer = offer({
-														command: input.command,
-														background: (reason) => control.background(reason),
-													})
-												}, FOREGROUND_HANDOFF_AFTER_MS)
-												offerTimer.unref?.()
-											},
-										}
-									: {}),
-							}
-						: {}),
-				})
+				await execHostShell(
+					cwdFile === undefined ? input.command : withCwdCapture(input.command, cwdFile),
+					{
+						cwd: startDirectory,
+						timeout: input.timeout,
+						env: { ...inherited.env, ...context.env },
+						maxBuffer: DEFAULT_BASH_MAX_BUFFER_BYTES,
+						signal: context.abortSignal,
+						onOutput,
+						...(canMoveOnTimeout ? { onTimeout: adoptRunning } : {}),
+						...(canHandOff
+							? {
+									adopt: adoptRunning,
+									adoptOnInterrupt: true,
+									...(offer
+										? {
+												onRunning: (control: {
+													background(reason: 'user' | 'message'): boolean
+												}) => {
+													offerTimer = setTimeout(() => {
+														withdrawOffer = offer({
+															command: input.command,
+															background: (reason) => control.background(reason),
+														})
+													}, FOREGROUND_HANDOFF_AFTER_MS)
+													offerTimer.unref?.()
+												},
+											}
+										: {}),
+								}
+							: {}),
+					},
+				)
 			if (backgroundedJobId !== undefined) {
 				const timedOut = backgroundedBy === 'timeout'
 				return {
@@ -853,9 +890,10 @@ const BashToolBase = defineTool({
 					facts: { kind: 'command', command: input.command, background: true, continued: true },
 				}
 			}
+			const reset = await settle()
 			return {
 				success: true,
-				output: formatShellOutput(stdout, stderr) || '(no output)',
+				output: withResetNotice(formatShellOutput(stdout, stderr) || '(no output)', reset),
 				data: {
 					exitCode: 0,
 					...(leaveSandbox ? { sandboxed: false, sandboxEscape: true } : {}),
@@ -903,6 +941,7 @@ const BashToolBase = defineTool({
 			const judged =
 				!timedOut && exitCode !== undefined ? judgeExit(input.command, exitCode) : undefined
 			const answered = judged !== undefined && !judged.isError
+			const reset = await settle()
 			const output = [
 				formatShellOutput(failure.stdout, failure.stderr),
 				clipped.length > 0
@@ -914,7 +953,7 @@ const BashToolBase = defineTool({
 
 			return {
 				success: answered,
-				output: output || '(no output)',
+				output: withResetNotice(output || '(no output)', reset),
 				data: {
 					...(exitCode !== undefined ? { exitCode } : {}),
 					...(judged?.note ? { exitNote: judged.note } : {}),
@@ -949,6 +988,7 @@ const BashToolBase = defineTool({
 				}),
 			}
 		} finally {
+			if (cwdFile !== undefined && !settled) await rm(cwdFile, { force: true })
 			if (offerTimer !== undefined) clearTimeout(offerTimer)
 			withdrawOffer?.()
 		}
@@ -1002,6 +1042,11 @@ function formatShellOutput(stdout: string | undefined, stderr: string | undefine
 		.join('\n\n')
 }
 
+/** The result text with the directory-reset line, when there is one, on its own last line. */
+function withResetNotice(output: string, notice: string | undefined): string {
+	return notice === undefined ? output : `${output}\n${notice}`
+}
+
 /**
  * The notice text for the credential-shaped variables left out of a command's
  * environment (see {@link withheldEnvNoticeText}). It is sent as a notice after

package/src/tools/builtins/bounded-file-read.ts

@@ -0,0 +1,80 @@
+import { constants } from 'node:fs'
+import { open } from 'node:fs/promises'
+
+const CHUNK_BYTES = 64 * 1024
+
+/** A hard input ceiling, independent of output windows and allow_large. */
+export const TEXT_MAX_INPUT_BYTES = 32 * 1024 * 1024
+
+/**
+ * Read at most the limit plus one sentinel byte, even if the file grows after
+ * stat. No allocation or request is derived from an untrusted file size.
+ * The first bounded chunk can choose a stricter limit from the file signature.
+ */
+export async function readBoundedChunks(
+	read: (offset: number, length: number) => Promise<Buffer>,
+	maximum: number,
+	signal?: AbortSignal,
+	selectLimit?: (prefix: Buffer) => number,
+): Promise<Buffer> {
+	const chunks: Buffer[] = []
+	let offset = 0
+	let limit = maximum
+	for (;;) {
+		signal?.throwIfAborted()
+		const length = Math.min(CHUNK_BYTES, limit + 1 - offset)
+		const chunk = await read(offset, length)
+		signal?.throwIfAborted()
+		if (chunk.length > length)
+			throw new Error('The file backend returned more bytes than the requested bounded range.')
+		if (offset === 0 && selectLimit) limit = Math.min(maximum, selectLimit(chunk))
+		offset += chunk.length
+		if (offset > limit) throw inputTooLarge(limit)
+		chunks.push(chunk)
+		if (chunk.length < length) return Buffer.concat(chunks, offset)
+	}
+}
+
+export async function readBoundedFile(
+	path: string,
+	maximum: number,
+	signal?: AbortSignal,
+	selectLimit?: (prefix: Buffer) => number,
+): Promise<Buffer> {
+	// O_NONBLOCK prevents a substituted FIFO from blocking open before fstat.
+	signal?.throwIfAborted()
+	const file = await open(path, constants.O_RDONLY | constants.O_NONBLOCK)
+	try {
+		const info = await file.stat()
+		if (!info.isFile()) throw new Error('Read requires a regular file.')
+		if (info.size > maximum) throw inputTooLarge(maximum)
+		return await readBoundedChunks(
+			async (offset, length) => {
+				const buffer = Buffer.allocUnsafe(length)
+				let used = 0
+				while (used < length) {
+					signal?.throwIfAborted()
+					const { bytesRead } = await file.read(buffer, used, length - used, offset + used)
+					if (bytesRead === 0) break
+					used += bytesRead
+				}
+				return buffer.subarray(0, used)
+			},
+			maximum,
+			signal,
+			(prefix) => {
+				const limit = selectLimit?.(prefix) ?? maximum
+				if (info.size > limit) throw inputTooLarge(limit)
+				return limit
+			},
+		)
+	} finally {
+		await file.close()
+	}
+}
+
+function inputTooLarge(limit: number): Error {
+	return new Error(
+		`File exceeds the bounded read limit (${limit} bytes). Extract a smaller file with a shell command.`,
+	)
+}