@namzu/sdk 1.4.0 → 3.0.0

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

@@ -101,9 +101,15 @@ function resultToToolResult(result: ComputerUseResult): ToolResult {
 	switch (result.type) {
 		case 'screenshot': {
 			const { data, mimeType, width, height } = result.result
+			// `output` used to BE the base64 payload, which meant the model
+			// received 400 KB–2.7 MB of undecodable characters as text —
+			// roughly 100k–670k tokens — and could not see the screen at
+			// all. The image now travels as a content block; `output` keeps
+			// the short human/transcript-facing description.
 			return {
 				success: true,
-				output: data.toString('base64'),
+				output: `Screenshot captured (${width}x${height}, ${mimeType}).`,
+				content: [{ type: 'image', data: data.toString('base64'), mediaType: mimeType }],
 				data: { mimeType, width, height, encoding: 'base64' },
 			}
 		}

package/src/tools/builtins/edit.ts

@@ -29,10 +29,10 @@ const inputSchema = z
 				'Alias for new_string. Also used as inserted content when insertLine is provided. Self-budget this payload under 12000 characters before calling.',
 			),
 		insertLine: z
-			.union([z.number().int().min(0), z.literal('end')])
+			.union([z.coerce.number().int().min(0), z.string().min(1)])
 			.optional()
 			.describe(
-				'Optional line insertion target. Pass a JSON integer to insert after that 1-indexed line, 0 to insert before the first line, or the exact string "end" to append. Headings, anchors, numeric strings, null, and empty strings are invalid.',
+				'Optional line insertion target. Inserts the replacement after this 1-indexed line; 0 inserts before the first line; "end" appends to the file.',
 			),
 		replace_all: z
 			.boolean()
@@ -71,8 +71,6 @@ export const EditTool = defineTool({
 	description:
 		'Makes targeted edits to a file using exact string find-and-replace or line insertion. THIS IS THE PREFERRED WAY TO MODIFY AN EXISTING FILE — never reach for `write` to change a file that already exists, because `write` overwrites the whole body and discards earlier work on partial failure. `edit` keeps the rest of the file byte-for-byte intact and is recoverable: if a single edit fails (old_string/oldStr ambiguous, broader restructuring needed), follow up with another `edit` instead of re-emitting the entire file via `write`. The old_string/oldStr must be unique in the file unless replace_all is true. For insertions, pass insertLine plus new_string/newStr; use insertLine: "end" to extend a file at the end. Self-budget new_string/newStr under 12000 characters before emitting the tool call; use repeated bounded edits for long sections. Preserves file formatting and indentation.',
 	inputSchema,
-	validationErrorHint:
-		'Accepted shapes: {"path":"file.md","insertLine":"end","new_string":"text"} or {"path":"file.md","old_string":"old","new_string":"new"}. Always include path; insertLine accepts only a non-negative JSON integer or the exact string "end".',
 	category: 'filesystem',
 	permissions: ['file_write'],
 	readOnly: false,
@@ -168,16 +166,18 @@ function normalizeEditInput(
 }
 
 function normalizeInsertLine(
-	value: unknown,
+	value: string | number,
 ): { success: true; value: number | 'end' } | { success: false; error: string } {
-	if (value === 'end') return { success: true, value: 'end' }
-	if (typeof value === 'number' && Number.isInteger(value) && value >= 0) {
-		return { success: true, value }
-	}
-	return {
-		success: false,
-		error: 'insertLine must be a non-negative line number or "end".',
+	if (typeof value === 'string') {
+		if (value.trim().toLowerCase() === 'end') return { success: true, value: 'end' }
+		const parsed = Number(value)
+		if (Number.isInteger(parsed) && parsed >= 0) return { success: true, value: parsed }
+		return {
+			success: false,
+			error: 'insertLine must be a non-negative line number or "end".',
+		}
 	}
+	return { success: true, value }
 }
 
 function applyEdit(

package/src/tools/builtins/file-mutation-lock.ts

@@ -0,0 +1,27 @@
+const mutationTails = new Map<string, Promise<void>>()
+
+/**
+ * Serialize read-modify-write filesystem operations by resolved path within
+ * one SDK process. Distributed hosts must still assign one writer per file or
+ * provide a storage-level compare-and-swap primitive.
+ */
+export async function withFileMutationLock<T>(
+	key: string,
+	operation: () => Promise<T>,
+): Promise<T> {
+	const previous = mutationTails.get(key) ?? Promise.resolve()
+	let release = () => {}
+	const current = new Promise<void>((resolve) => {
+		release = resolve
+	})
+	const tail = previous.then(() => current)
+	mutationTails.set(key, tail)
+
+	await previous
+	try {
+		return await operation()
+	} finally {
+		release()
+		if (mutationTails.get(key) === tail) mutationTails.delete(key)
+	}
+}

package/src/tools/builtins/glob.ts

@@ -1,7 +1,65 @@
 import { glob } from 'node:fs/promises'
 import { basename, dirname, relative, resolve, sep } from 'node:path'
 import { z } from 'zod'
+import type { Sandbox } from '../../types/sandbox/index.js'
+import type { ToolResult } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
+import { matchesGlob } from '../glob-match.js'
+import { resolveWithin } from '../paths.js'
+import { joinPosix, relativePosix, resolveWithinPosix } from '../posix-path.js'
+
+/**
+ * Cap on results, shared by both paths so a sandboxed search and a host
+ * search truncate at the same point.
+ */
+const MAX_GLOB_RESULTS = 500
+
+/**
+ * Enumerate inside the sandbox and match there.
+ *
+ * This tool read the HOST filesystem through `node:fs` and referenced
+ * `context.sandbox` nowhere, so with a container backend wired in the
+ * sandbox was not a read boundary at all. The paths it returned were
+ * host-relative too, while `read` resolves what it is given INSIDE the
+ * sandbox — so every glob-to-read handoff either failed or opened a
+ * different file. Every sibling builtin already remembers this branch.
+ *
+ * `listFiles` returns sandbox-relative paths, which is the coordinate
+ * system `read` and `grep` already speak, so a path from here can be
+ * handed straight to them.
+ */
+async function globInSandbox(
+	input: { pattern: string; path?: string },
+	sandbox: Sandbox,
+): Promise<ToolResult> {
+	// The sandbox's own coordinate system — see `posix-path`.
+	const root = resolveWithinPosix(sandbox.rootDir, input.path)
+	const entries = await sandbox.listFiles(root)
+
+	let pattern = input.pattern
+	if (!pattern.includes('/') && !pattern.startsWith('**/')) pattern = `**/${pattern}`
+
+	const matches: string[] = []
+	for (const entry of entries) {
+		const relPath = relativePosix(sandbox.rootDir, joinPosix(root, entry.path))
+		if (!matchesGlob(relPath, pattern)) continue
+		matches.push(`./${relPath}`)
+		if (matches.length >= MAX_GLOB_RESULTS) break
+	}
+
+	if (matches.length === 0) {
+		return {
+			success: true,
+			output: `No files found matching pattern "${input.pattern}" in ${root}`,
+			data: { count: 0, files: [], sandboxed: true },
+		}
+	}
+	return {
+		success: true,
+		output: matches.join('\n'),
+		data: { count: matches.length, files: matches, sandboxed: true },
+	}
+}
 
 const inputSchema = z.object({
 	pattern: z.string().describe('Glob pattern (e.g. "**/*.ts", "src/**/*.js")'),
@@ -46,16 +104,24 @@ export const GlobTool = defineTool({
 	concurrencySafe: true,
 
 	async execute(input, context) {
-		const basePath = input.path
-			? resolve(context.workingDirectory, input.path)
-			: context.workingDirectory
+		if (context.sandbox) {
+			return await globInSandbox(input, context.sandbox)
+		}
+
+		// Contained, not merely resolved. This was a bare `resolve`, so
+		// `path: "../../.."` reached whatever sits above the working
+		// directory — with no sandbox needed to make it work.
+		const basePath = resolveWithin(context.workingDirectory, input.path)
 
 		let searchPath = basePath
 		let pattern = input.pattern
 
 		const { baseDir, relativePattern } = extractGlobBaseDirectory(pattern)
 		if (baseDir) {
-			const resolvedPatternBase = resolve(context.workingDirectory, baseDir)
+			// A base directory lifted out of the PATTERN is caller-supplied
+			// too: `pattern: "../../**/*.pem"` is the same escape wearing a
+			// different argument.
+			const resolvedPatternBase = resolveWithin(context.workingDirectory, baseDir)
 			if (resolvedPatternBase === basePath || resolvedPatternBase.startsWith(`${basePath}/`)) {
 				searchPath = resolvedPatternBase
 				pattern = relativePattern
@@ -67,12 +133,11 @@ export const GlobTool = defineTool({
 		}
 
 		const matches: string[] = []
-		const MAX_RESULTS = 500
 
 		for await (const entry of glob(pattern, { cwd: searchPath })) {
 			const absolutePath = resolve(searchPath, entry)
 			matches.push(`./${relative(context.workingDirectory, absolutePath)}`)
-			if (matches.length >= MAX_RESULTS) break
+			if (matches.length >= MAX_GLOB_RESULTS) break
 		}
 
 		if (matches.length === 0) {

package/src/tools/builtins/grep.ts

@@ -1,7 +1,61 @@
 import { glob, readFile } from 'node:fs/promises'
-import { relative, resolve } from 'node:path'
+import { relative, resolve, sep } from 'node:path'
 import { z } from 'zod'
+import type { Sandbox } from '../../types/sandbox/index.js'
 import { defineTool } from '../defineTool.js'
+import { matchesGlob } from '../glob-match.js'
+import { resolveWithin } from '../paths.js'
+import { joinPosix, relativePosix, resolveWithinPosix } from '../posix-path.js'
+
+/**
+ * Where the files come from.
+ *
+ * The host and the sandbox differ in exactly two operations — enumerate
+ * and read — so that is all this abstracts. Matching, context lines and
+ * the caps stay in one implementation; duplicating them per source is how
+ * the two would drift apart, and the sandbox path is the one nobody runs
+ * by accident.
+ */
+interface FileSource {
+	/** The root every reported path is relative to. */
+	readonly root: string
+	/** True when paths are the sandbox's, not the host's. */
+	readonly posix?: boolean
+	list(searchRoot: string, pattern: string): AsyncIterable<string>
+	read(path: string): Promise<Buffer>
+}
+
+function hostSource(workingDirectory: string): FileSource {
+	return {
+		root: workingDirectory,
+		async *list(searchRoot, pattern) {
+			for await (const entry of glob(pattern, { cwd: searchRoot })) {
+				yield resolve(searchRoot, entry)
+			}
+		},
+		read: (path) => readFile(path),
+	}
+}
+
+function sandboxSource(sandbox: Sandbox): FileSource {
+	return {
+		root: sandbox.rootDir,
+		posix: true,
+		async *list(searchRoot, pattern) {
+			for (const entry of await sandbox.listFiles(searchRoot)) {
+				// Sandbox paths stay in the sandbox's own coordinate system.
+				// Running them through the host's path module would rewrite a
+				// POSIX container path into a host-shaped one whenever the
+				// two disagree, and then hand the model a path its own
+				// sandbox cannot open.
+				const absolute = joinPosix(searchRoot, entry.path)
+				const relPath = relativePosix(sandbox.rootDir, absolute)
+				if (matchesGlob(relPath, pattern)) yield absolute
+			}
+		},
+		read: (path) => sandbox.readFile(path),
+	}
+}
 
 const inputSchema = z.object({
 	pattern: z.string().describe('Regular expression pattern to search for in file contents'),
@@ -63,9 +117,25 @@ export const GrepTool = defineTool({
 			}
 		}
 
-		const searchRoot = input.path
-			? resolve(context.workingDirectory, input.path)
-			: context.workingDirectory
+		// Inside the sandbox when there is one, on the host otherwise. Only
+		// the file SOURCE differs — matching, context lines and the caps are
+		// one implementation, because duplicating the substantive half is
+		// how the two paths would drift.
+		//
+		// This tool read the host filesystem through `node:fs` and
+		// referenced `context.sandbox` nowhere, so with a container backend
+		// wired in the sandbox was not a read boundary at all — and grep
+		// returns file CONTENT, so what leaked was not a listing.
+		const source: FileSource = context.sandbox
+			? sandboxSource(context.sandbox)
+			: hostSource(context.workingDirectory)
+
+		// Contained, not merely resolved — see `resolveWithin`. Bare
+		// resolution let `path: "../../.."` read whatever sits above the
+		// working directory, with no sandbox needed to make it work.
+		const searchRoot = source.posix
+			? resolveWithinPosix(source.root, input.path)
+			: resolveWithin(source.root, input.path)
 
 		// Auto-prepend **/ for simple patterns (e.g. "*.ts" → "**/*.ts")
 		let filePattern = input.include ?? '**/*'
@@ -78,13 +148,12 @@ export const GrepTool = defineTool({
 		let filesSearched = 0
 		let filesMatched = 0
 
-		for await (const entry of glob(filePattern, { cwd: searchRoot })) {
-			const filePath = resolve(searchRoot, entry)
+		for await (const filePath of source.list(searchRoot, filePattern)) {
 			filesSearched++
 
 			let content: string
 			try {
-				const buffer = await readFile(filePath)
+				const buffer = await source.read(filePath)
 				if (buffer.length > MAX_FILE_SIZE) continue
 				if (isBinaryContent(buffer)) continue
 				content = buffer.toString('utf-8')
@@ -105,7 +174,12 @@ export const GrepTool = defineTool({
 					filesMatched++
 				}
 
-				const relPath = `./${relative(context.workingDirectory, filePath)}`
+				// Relative to the root the file came FROM. Reporting a
+				// host-relative path for a file read inside the sandbox would
+				// hand the model a string `read` then resolves somewhere else.
+				const relPath = source.posix
+					? `./${relativePosix(source.root, filePath)}`
+					: `./${relative(source.root, filePath).split(sep).join('/')}`
 
 				if (input.context_lines > 0) {
 					const start = Math.max(0, i - input.context_lines)

package/src/tools/builtins/index.ts

@@ -22,12 +22,12 @@ import { WriteFileTool } from './write-file.js'
 // because it requires a schema parameter and is created per-use case.
 //
 // `LsTool` and `SearchToolsTool` are still exported for direct use but are
-// NOT in the default builtin set. Claude Code's training distribution (per
-// `code.claude.com/docs/en/tools-reference`) does NOT include `LS` —
-// directory listing is canonical `Bash` + `Glob`. `search_tools` has no
-// Claude analogue at all. Including these in the defaults gives the model
-// tools that look right but degrade alignment. File extension is canonical
-// `edit` with `insertLine: "end"` — the legacy `Append` tool is gone.
+// NOT in the default builtin set. A directory listing is already reachable
+// through `bash` + `glob`, and `search_tools` answers a question the tool
+// catalog in the prompt has already answered. Offering a model two ways to
+// do one thing costs a decision on every turn and buys nothing. File
+// extension is canonical `edit` with `insertLine: "end"` — the legacy
+// `Append` tool is gone.
 // Hosts that genuinely want LS/search can still register them explicitly.
 
 export function getBuiltinTools(): ToolDefinition[] {

package/src/tools/builtins/ls.ts

@@ -1,7 +1,8 @@
 import { readdir, stat } from 'node:fs/promises'
-import { join, relative, resolve } from 'node:path'
+import { join, relative } from 'node:path'
 import { z } from 'zod'
 import { defineTool } from '../defineTool.js'
+import { resolveWithin } from '../paths.js'
 
 const inputSchema = z.object({
 	path: z.string().default('.').describe('Directory path to list. Defaults to working directory.'),
@@ -116,7 +117,8 @@ export const LsTool = defineTool({
 	concurrencySafe: true,
 
 	async execute(input, context) {
-		const targetPath = resolve(context.workingDirectory, input.path)
+		// Contained, not merely resolved — see `resolveWithin`.
+		const targetPath = resolveWithin(context.workingDirectory, input.path)
 
 		if (input.recursive) {
 			const output: string[] = []

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

@@ -23,7 +23,7 @@ const inputSchema = z.object({
 export const ReadFileTool = defineTool({
 	name: 'read',
 	description:
-		'Reads a file and returns its contents with line numbers. Supports readRange ([start,end], 1-indexed inclusive) or offset/limit for large files.',
+		'Reads a file and returns its contents with line numbers. Supports readRange ([start,end], 1-indexed inclusive) or offset/limit for large files. Without a window it returns the first 2000 lines and says so — pass offset/limit to continue.',
 	inputSchema,
 	category: 'filesystem',
 	permissions: ['file_read'],
@@ -57,12 +57,14 @@ export const ReadFileTool = defineTool({
 
 			context.fileReadTracker?.recordRead(input.path)
 
+			const partial = selectedLines.length < lines.length
 			return {
 				success: true,
-				output: numberedLines,
+				output: numberedLines + partialViewNotice(start, selectedLines.length, lines.length),
 				data: {
 					totalLines: lines.length,
 					returnedLines: selectedLines.length,
+					truncated: partial,
 					path: input.path,
 					sandboxed: true,
 				},
@@ -92,12 +94,15 @@ export const ReadFileTool = defineTool({
 
 		context.fileReadTracker?.recordRead(filePath)
 
+		const isPartial = selectedLines.length < lines.length
+
 		return {
 			success: true,
-			output: numberedLines,
+			output: numberedLines + partialViewNotice(start, selectedLines.length, lines.length),
 			data: {
 				totalLines: lines.length,
 				returnedLines: selectedLines.length,
+				truncated: isPartial,
 				path: filePath,
 			},
 		}
@@ -128,6 +133,34 @@ function buildStructuredBinaryGuidance(path: string, format: string, extractor:
 	].join('\n')
 }
 
+/**
+ * Lines returned when the caller specifies no window.
+ *
+ * Chosen to cover the overwhelming majority of source files whole while
+ * bounding the pathological case.
+ */
+const DEFAULT_READ_LINES = 2000
+
+/**
+ * Tell the model, explicitly, when it is looking at a window rather than
+ * the file.
+ *
+ * Without this a truncated read is indistinguishable from a short file, and
+ * the agent reasons about a fragment as if it were the whole thing — the
+ * most expensive silent failure a read tool can have. The notice names the
+ * exact next call rather than describing it.
+ */
+function partialViewNotice(start: number, returned: number, total: number): string {
+	if (returned >= total) return ''
+	const shownTo = start + returned
+	return [
+		'',
+		'',
+		`[PARTIAL view — lines ${start + 1}-${shownTo} of ${total}.`,
+		`Continue with read({ offset: ${shownTo}, limit: N }), or narrow with grep.]`,
+	].join('\n')
+}
+
 function resolveReadWindow(
 	input: z.infer<typeof inputSchema>,
 	totalLines: number,
@@ -139,6 +172,9 @@ function resolveReadWindow(
 		return { start, end }
 	}
 	const start = Math.max(0, input.offset ?? 0)
-	const end = input.limit ? start + input.limit : totalLines
+	// A bare `read({ path })` used to return the entire file, so a 2 MB
+	// lockfile became ~500k tokens in one tool_result. Default to a window
+	// and say so in the output; the model asks for more when it needs it.
+	const end = input.limit ? start + input.limit : Math.min(totalLines, start + DEFAULT_READ_LINES)
 	return { start, end }
 }

package/src/tools/coordinator/__tests__/agent.test.ts

@@ -4,7 +4,7 @@
  * - Reports `success: true` only when BOTH the gateway task state and
  *   the underlying `BaseAgentResult.status` say completed.
  * - Reports `success: false` and surfaces `lastError` when either
- *   layer disagrees — the canonical bug Codex caught was that a
+ *   layer disagrees — the canonical bug review caught was that a
  *   failed subagent could be reported as successful when the gateway
  *   forwarded `state: 'completed'` from a manager that did not
  *   propagate the run's `status: 'failed'`.
@@ -152,7 +152,7 @@ describe('buildAgentTool', () => {
 	it("does not accept a taskStore or runId — plan-task lifecycle is the parent's job", () => {
 		// Compile-time pin: AgentToolOptions must NOT include `taskStore`
 		// or `runId`. The Agent tool used to manage a per-call plan task
-		// internally and Codex caught a leak: when the subagent failed,
+		// internally and review caught a leak: when the subagent failed,
 		// the plan task stayed `'in_progress'` forever because
 		// `TaskStatus` has no `'failed'` value to flip to. Drop the
 		// integration entirely; if a host wants to track delegations as

package/src/tools/coordinator/agent.ts

@@ -8,9 +8,7 @@ import { defineTool } from '../defineTool.js'
 import type { TaskLaunchedCallback } from './index.js'
 
 /**
- * Build the canonical Claude Code `Agent` tool — synchronous subagent
- * delegation that mirrors what Claude is trained against in
- * `code.claude.com/docs/en/sub-agents`.
+ * Build the `Agent` tool — synchronous subagent delegation.
  *
  * Semantics: parent calls `Agent({ description, prompt, subagent_type })`,
  * the runtime spawns the chosen subagent with its own context window,
@@ -19,12 +17,14 @@ import type { TaskLaunchedCallback } from './index.js'
  * subagent tool calls are isolated — only the summary surfaces to
  * the parent.
  *
- * This is **NOT** the same shape as the coordinator `create_task`
- * tool that this package ships alongside it. That tool exposes
- * Namzu's task IDs and optional planning integration, while still
- * returning results synchronously. For free agentic alignment,
- * prefer the canonical `Agent` tool; use the coordinator tool when
- * the host needs task tracking.
+ * This is **NOT** the same shape as the legacy `create_task` /
+ * `continue_task` / `cancel_task` trio that this package ships
+ * alongside it: those are non-blocking and use a `<task-notification>`
+ * callback model. The async pattern is useful for hosts that want a
+ * work-queue surface, but it asks the model to track work it cannot
+ * see finish. Prefer the blocking `Agent` tool; keep the legacy
+ * coordinator tools only when you genuinely need fire-and-forget
+ * multi-task fan-out.
  */
 export interface AgentToolOptions {
 	gateway: TaskGateway
@@ -33,6 +33,18 @@ export interface AgentToolOptions {
 	allowedAgentIds: string[]
 
 	onTaskLaunched?: TaskLaunchedCallback
+
+	/**
+	 * Settle the parent run with the subagent's answer instead of looping
+	 * once more to restate it. See {@link ToolDefinition.terminal}.
+	 *
+	 * For a router — an agent whose whole job is to pick a specialist —
+	 * the relay turn is pure overhead at the parent's full context size,
+	 * and it hands the caller the parent's paraphrase rather than the
+	 * specialist's answer. Off by default: an agent that delegates as one
+	 * step of a longer plan needs the loop to continue.
+	 */
+	terminal?: boolean
 }
 
 export function buildAgentTool(opts: AgentToolOptions): ToolDefinition {
@@ -62,6 +74,7 @@ export function buildAgentTool(opts: AgentToolOptions): ToolDefinition {
 		readOnly: false,
 		destructive: false,
 		concurrencySafe: true,
+		...(opts.terminal !== undefined ? { terminal: opts.terminal } : {}),
 		async execute({ description, prompt, subagent_type }, context) {
 			// With a single registered subagent the type is optional — default to
 			// it so the model can't trip the "subagent_type required" validation.
@@ -109,7 +122,7 @@ export function buildAgentTool(opts: AgentToolOptions): ToolDefinition {
 			// Treat the subagent as successful only when BOTH agree.
 			// Reporting a failed subagent as successful would silently
 			// hand the parent garbage output and make debugging
-			// impossible, which is what Codex flagged on the first cut.
+			// impossible, which is what review flagged on the first cut.
 			const runStatus = completed.result?.status
 			const succeeded =
 				completed.state === 'completed' && (runStatus === undefined || runStatus === 'completed')