@namzu/sdk 2.0.0 → 3.1.0

package/src/tools/builtins/__tests__/payload-budget.test.ts

@@ -17,8 +17,8 @@ describe('filesystem tool payload budgeting', () => {
 		expect(() =>
 			EditTool.inputSchema.parse({
 				path: 'outputs/long.md',
-				old_string: '{{SECTION}}',
-				new_string: oversized,
+				oldStr: '{{SECTION}}',
+				newStr: oversized,
 				replace_all: false,
 			}),
 		).not.toThrow()
@@ -31,7 +31,7 @@ describe('filesystem tool payload budgeting', () => {
 		expect(names).not.toContain('append')
 	})
 
-	it('assembles replay-safe long documents by advancing an exact marker', async () => {
+	it('assembles long documents with bounded write plus edit insert chunks', async () => {
 		const dir = mkdtempSync(join(tmpdir(), 'namzu-long-doc-'))
 		const ctx: ToolContext = {
 			runId: 'run_test' as ToolContext['runId'],
@@ -40,12 +40,12 @@ describe('filesystem tool payload budgeting', () => {
 			env: {},
 			log: () => {},
 		}
-		const opening = '# Long document regression\n\n{{CHUNK_001}}\n'
+		const opening = '# Long document regression\n\n{{BODY}}\n'
 		const chunks = Array.from({ length: 6 }, (_, sectionIndex) => {
 			const lines = Array.from({ length: 45 }, (_, lineIndex) => {
 				const section = sectionIndex + 1
 				const line = lineIndex + 1
-				return `Section ${section}.${line}: this bounded paragraph proves long-form output grows through exact marker edits rather than one oversized JSON tool argument.`
+				return `Section ${section}.${line}: this bounded paragraph proves long-form output grows through edit insertions rather than one oversized JSON tool argument.`
 			})
 			const chunk = [`## Section ${sectionIndex + 1}`, ...lines, ''].join('\n')
 			expect(chunk.length).toBeLessThan(12_000)
@@ -58,52 +58,32 @@ describe('filesystem tool payload budgeting', () => {
 		)
 		expect(writeResult.success).toBe(true)
 
-		for (const [index, chunk] of chunks.entries()) {
-			const currentMarker = `{{CHUNK_${String(index + 1).padStart(3, '0')}}}`
-			const nextMarker = `{{CHUNK_${String(index + 2).padStart(3, '0')}}}`
+		const firstEdit = await EditTool.execute(
+			{
+				path: 'outputs/regression-long-document.md',
+				oldStr: '{{BODY}}',
+				newStr: chunks[0],
+				replace_all: false,
+			},
+			ctx,
+		)
+		expect(firstEdit.success).toBe(true)
+
+		for (const chunk of chunks.slice(1)) {
 			const result = await EditTool.execute(
 				{
 					path: 'outputs/regression-long-document.md',
-					old_string: currentMarker,
-					new_string: `${chunk}\n${nextMarker}`,
+					insertLine: 'end',
+					newStr: chunk,
 					replace_all: false,
 				},
 				ctx,
 			)
 			expect(result.success).toBe(true)
-
-			if (index === 0) {
-				const beforeReplay = readFileSync(join(dir, 'outputs/regression-long-document.md'), 'utf-8')
-				const replay = await EditTool.execute(
-					{
-						path: 'outputs/regression-long-document.md',
-						old_string: currentMarker,
-						new_string: `${chunk}\n${nextMarker}`,
-						replace_all: false,
-					},
-					ctx,
-				)
-				expect(replay.success).toBe(false)
-				expect(readFileSync(join(dir, 'outputs/regression-long-document.md'), 'utf-8')).toBe(
-					beforeReplay,
-				)
-			}
 		}
 
-		const finalMarker = `{{CHUNK_${String(chunks.length + 1).padStart(3, '0')}}}`
-		const finalize = await EditTool.execute(
-			{
-				path: 'outputs/regression-long-document.md',
-				old_string: finalMarker,
-				new_string: '',
-				replace_all: false,
-			},
-			ctx,
-		)
-		expect(finalize.success).toBe(true)
-
 		const final = readFileSync(join(dir, 'outputs/regression-long-document.md'), 'utf-8')
-		expect(final).not.toContain('{{CHUNK_')
+		expect(final).not.toContain('{{BODY}}')
 		expect(final.split('\n').length).toBeGreaterThan(250)
 		expect(final).toContain('## Section 1')
 		expect(final).toContain('## Section 6')

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

@@ -26,7 +26,35 @@ describe('ReadFileTool', () => {
 		)
 
 		expect(result.success).toBe(true)
-		expect(result.output).toBe('2\ttwo\n3\tthree')
+		expect(result.output).toContain('2\ttwo\n3\tthree')
+		// A window over a longer file now says so: the model must be able to
+		// tell "these are all the lines" from "these are the lines I asked
+		// for", or it reasons about a fragment as if it were the file.
+		expect(result.output).toContain('PARTIAL view — lines 2-3 of 4')
+		expect(result.data).toMatchObject({ truncated: true, returnedLines: 2, totalLines: 4 })
+	})
+
+	it('adds no partial-view notice when the whole file was returned', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-read-'))
+		writeFileSync(join(dir, 'doc.md'), ['one', 'two'].join('\n'))
+
+		const result = await ReadFileTool.execute({ path: 'doc.md' }, makeContext(dir))
+
+		expect(result.output).toBe('1\tone\n2\ttwo')
+		expect(result.data).toMatchObject({ truncated: false })
+	})
+
+	it('defaults to a bounded window instead of returning an entire large file', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-read-'))
+		const lines = Array.from({ length: 5000 }, (_, i) => `line ${i + 1}`)
+		writeFileSync(join(dir, 'big.txt'), lines.join('\n'))
+
+		const result = await ReadFileTool.execute({ path: 'big.txt' }, makeContext(dir))
+
+		expect(result.data).toMatchObject({ returnedLines: 2000, totalLines: 5000, truncated: true })
+		expect(result.output).toContain('PARTIAL view — lines 1-2000 of 5000')
+		// The notice names the exact next call rather than describing it.
+		expect(result.output).toContain('offset: 2000')
 	})
 
 	it('guides binary Office documents through extractor tooling', async () => {

package/src/tools/builtins/__tests__/stale-file-refusal.test.ts

@@ -0,0 +1,258 @@
+import { lstatSync, mkdtempSync, readFileSync, symlinkSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+import type { FileReadTracker, ToolContext } from '../../../types/tool/index.js'
+import { atomicWriteFile } from '../atomic-write-file.js'
+import { fingerprintContent } from '../content-fingerprint.js'
+import { EditTool } from '../edit.js'
+
+/**
+ * The mutation lock serializes THIS runtime's writers. It cannot see a
+ * person editing in an editor, another process, or a second agent run —
+ * and an edit computed against a body that has since moved is a lost
+ * update whichever of those did the moving.
+ *
+ * Worse than undetected, it was misreported: an `old_string` that no
+ * longer matches came back as "not found in file — make sure the string
+ * matches exactly", which tells the agent its input was wrong when the
+ * file changed underneath it. The agent then retries the same edit
+ * against the same moved file.
+ */
+
+function trackerOver(store: Map<string, string>): FileReadTracker {
+	return {
+		recordRead: (key, content) => {
+			if (content !== undefined) store.set(key, fingerprintContent(content))
+		},
+		hasRead: (key) => store.has(key),
+		fingerprint: (key) => store.get(key),
+	}
+}
+
+function contextWith(workingDirectory: string, tracker?: FileReadTracker): ToolContext {
+	return {
+		runId: 'run_stale' as ToolContext['runId'],
+		workingDirectory,
+		abortSignal: new AbortController().signal,
+		env: {},
+		log: () => {},
+		...(tracker ? { fileReadTracker: tracker } : {}),
+	}
+}
+
+describe('an edit against a file that moved is refused, not applied', () => {
+	it('refuses when the body changed since the agent read it', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-stale-'))
+		const file = join(dir, 'doc.md')
+		writeFileSync(file, 'alpha\nbeta\n')
+
+		const store = new Map<string, string>()
+		const tracker = trackerOver(store)
+		tracker.recordRead(file, 'alpha\nbeta\n')
+
+		// Somebody else rewrites the very line this edit anchors on.
+		writeFileSync(file, 'alpha\nBETA WAS REWRITTEN\n')
+
+		const result = await EditTool.execute(
+			{ path: 'doc.md', old_string: 'beta', new_string: 'gamma', replace_all: false },
+			contextWith(dir, tracker),
+		)
+
+		expect(result.success).toBe(false)
+		expect(result.error).toContain('changed on disk after you read it')
+		// The refusal has to be actionable, and "nothing was written" is the
+		// part that stops the agent re-running the same edit blind.
+		expect(result.error).toContain('Read the file again')
+		expect(result.error).toContain('Nothing was written')
+		expect(readFileSync(file, 'utf-8')).toBe('alpha\nBETA WAS REWRITTEN\n')
+	})
+
+	it('applies normally when the file is untouched', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-stale-'))
+		const file = join(dir, 'doc.md')
+		writeFileSync(file, 'alpha\nbeta\n')
+
+		const tracker = trackerOver(new Map())
+		tracker.recordRead(file, 'alpha\nbeta\n')
+
+		const result = await EditTool.execute(
+			{ path: 'doc.md', old_string: 'beta', new_string: 'gamma', replace_all: false },
+			contextWith(dir, tracker),
+		)
+
+		expect(result.success).toBe(true)
+		expect(readFileSync(file, 'utf-8')).toBe('alpha\ngamma\n')
+	})
+
+	it('lets a second edit in the same turn proceed against what the first wrote', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-stale-'))
+		const file = join(dir, 'doc.md')
+		writeFileSync(file, 'alpha\nbeta\n')
+
+		const tracker = trackerOver(new Map())
+		tracker.recordRead(file, 'alpha\nbeta\n')
+		const context = contextWith(dir, tracker)
+
+		const first = await EditTool.execute(
+			{ path: 'doc.md', old_string: 'beta', new_string: 'gamma', replace_all: false },
+			context,
+		)
+		// Without re-fingerprinting after a successful write, this second edit
+		// would see its own predecessor's output as someone else's drift.
+		const second = await EditTool.execute(
+			{ path: 'doc.md', old_string: 'alpha', new_string: 'omega', replace_all: false },
+			context,
+		)
+
+		expect(first.success).toBe(true)
+		expect(second.success).toBe(true)
+		expect(readFileSync(file, 'utf-8')).toBe('omega\ngamma\n')
+	})
+
+	it('proceeds when the host tracks nothing, which is the older contract', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-stale-'))
+		writeFileSync(join(dir, 'doc.md'), 'alpha\nbeta\n')
+
+		// `fingerprint` is optional. A host that never captured one must not
+		// have every edit refused.
+		const result = await EditTool.execute(
+			{ path: 'doc.md', old_string: 'beta', new_string: 'gamma', replace_all: false },
+			contextWith(dir),
+		)
+
+		expect(result.success).toBe(true)
+	})
+
+	it('proceeds when the path was never read, so there is nothing to be stale against', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-stale-'))
+		writeFileSync(join(dir, 'doc.md'), 'alpha\nbeta\n')
+
+		const result = await EditTool.execute(
+			{ path: 'doc.md', old_string: 'beta', new_string: 'gamma', replace_all: false },
+			contextWith(dir, trackerOver(new Map())),
+		)
+
+		expect(result.success).toBe(true)
+	})
+})
+
+describe('the fingerprint distinguishes bodies', () => {
+	it('is stable for identical content', () => {
+		expect(fingerprintContent('alpha\n')).toBe(fingerprintContent('alpha\n'))
+	})
+
+	it('differs on a one-character change', () => {
+		expect(fingerprintContent('alpha\n')).not.toBe(fingerprintContent('alphb\n'))
+	})
+
+	it('differs on trailing whitespace, which a diff would also treat as a change', () => {
+		expect(fingerprintContent('alpha')).not.toBe(fingerprintContent('alpha '))
+	})
+})
+
+describe('an atomic commit writes through a symlink rather than over it', () => {
+	/** Creating one needs a privilege this platform does not always grant. */
+	function symlinkOrSkip(target: string, link: string): boolean {
+		try {
+			symlinkSync(target, link)
+			return true
+		} catch {
+			return false
+		}
+	}
+
+	it('keeps the link and updates its target', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-symlink-'))
+		const real = join(dir, 'real.md')
+		const link = join(dir, 'link.md')
+		writeFileSync(real, 'original\n')
+		if (!symlinkOrSkip(real, link)) return
+
+		await atomicWriteFile(link, 'replaced\n')
+
+		// `rename` onto the link path would have swapped the link for a plain
+		// file, silently detaching every other path that pointed through it.
+		expect(lstatSync(link).isSymbolicLink()).toBe(true)
+		expect(readFileSync(real, 'utf-8')).toBe('replaced\n')
+		expect(readFileSync(link, 'utf-8')).toBe('replaced\n')
+	})
+
+	it('still creates a file that does not exist yet', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-symlink-'))
+		const fresh = join(dir, 'new.md')
+
+		await atomicWriteFile(fresh, 'created\n')
+
+		expect(readFileSync(fresh, 'utf-8')).toBe('created\n')
+	})
+})
+
+describe('drift that does not touch the anchor is not a conflict', () => {
+	it('applies when someone changed an unrelated part of the file', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-stale-'))
+		const file = join(dir, 'doc.md')
+		writeFileSync(file, 'alpha\nbeta\n')
+
+		const tracker = trackerOver(new Map())
+		tracker.recordRead(file, 'alpha\nbeta\n')
+
+		// Someone appends a line. The edit's anchor is untouched, so the edit
+		// is still exactly as well defined as when it was computed —
+		// refusing here would reject a safe edit every time anybody wrote
+		// anywhere in the file.
+		writeFileSync(file, 'alpha\nbeta\nan unrelated new line\n')
+
+		const result = await EditTool.execute(
+			{ path: 'doc.md', old_string: 'beta', new_string: 'gamma', replace_all: false },
+			contextWith(dir, tracker),
+		)
+
+		expect(result.success).toBe(true)
+		expect(readFileSync(file, 'utf-8')).toBe('alpha\ngamma\nan unrelated new line\n')
+	})
+
+	it('reports a genuinely wrong anchor as wrong, not as drift', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-stale-'))
+		const file = join(dir, 'doc.md')
+		writeFileSync(file, 'alpha\nbeta\n')
+
+		const tracker = trackerOver(new Map())
+		tracker.recordRead(file, 'alpha\nbeta\n')
+
+		// Nothing moved. The anchor is simply not in the file, and telling
+		// the agent to re-read would send it to look for a change that never
+		// happened.
+		const result = await EditTool.execute(
+			{ path: 'doc.md', old_string: 'nowhere', new_string: 'x', replace_all: false },
+			contextWith(dir, tracker),
+		)
+
+		expect(result.success).toBe(false)
+		expect(result.error).toContain('not found in file')
+		expect(result.error).not.toContain('changed on disk')
+	})
+
+	it('reports drift when the anchor became ambiguous because of it', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-stale-'))
+		const file = join(dir, 'doc.md')
+		writeFileSync(file, 'alpha\nbeta\n')
+
+		const tracker = trackerOver(new Map())
+		tracker.recordRead(file, 'alpha\nbeta\n')
+
+		// A second copy of the anchor appears. "not unique — add more
+		// context" would send the agent to widen an anchor that was unique
+		// when it read the file.
+		writeFileSync(file, 'alpha\nbeta\nbeta\n')
+
+		const result = await EditTool.execute(
+			{ path: 'doc.md', old_string: 'beta', new_string: 'gamma', replace_all: false },
+			contextWith(dir, tracker),
+		)
+
+		expect(result.success).toBe(false)
+		expect(result.error).toContain('changed on disk')
+	})
+})

package/src/tools/builtins/__tests__/write-file.test.ts

@@ -8,10 +8,10 @@ import { WriteFileTool } from '../write-file.js'
 function makeTracker(): FileReadTracker & { keys(): string[] } {
 	const set = new Set<string>()
 	return {
-		recordRead: (key) => {
-			set.add(key)
+		recordRead: (k) => {
+			set.add(k)
 		},
-		hasRead: (key) => set.has(key),
+		hasRead: (k) => set.has(k),
 		keys: () => Array.from(set),
 	}
 }
@@ -27,33 +27,7 @@ function makeContext(workingDirectory: string, tracker?: FileReadTracker): ToolC
 	}
 }
 
-describe('WriteFileTool — canonical contract and read-before-overwrite invariant', () => {
-	it('publishes one closed path + content contract', () => {
-		expect(WriteFileTool.modelInputSchema).toEqual({
-			type: 'object',
-			properties: {
-				path: {
-					type: 'string',
-					description: 'Non-empty path to the file to write.',
-				},
-				content: {
-					type: 'string',
-					description:
-						'Complete bounded file body. May be empty only for an intentionally empty file.',
-				},
-			},
-			required: ['path', 'content'],
-			additionalProperties: false,
-		})
-		expect(WriteFileTool.inputSchema.safeParse({ path: 'doc.md', content: '' }).success).toBe(true)
-		expect(WriteFileTool.inputSchema.safeParse({ path: 'doc.md', newStr: 'legacy' }).success).toBe(
-			false,
-		)
-		expect(WriteFileTool.inputSchema.safeParse({ path: '   ', content: 'body' }).success).toBe(
-			false,
-		)
-	})
-
+describe('WriteFileTool — read-before-overwrite invariant', () => {
 	it('writes a new file without requiring a prior read', async () => {
 		const dir = mkdtempSync(join(tmpdir(), 'namzu-write-'))
 		const tracker = makeTracker()
@@ -66,28 +40,15 @@ describe('WriteFileTool — canonical contract and read-before-overwrite invaria
 		expect(tracker.hasRead(join(dir, 'fresh.txt'))).toBe(true)
 	})
 
-	it('preserves edge whitespace in a valid path', async () => {
+	it('accepts newStr as the canonical create/write content alias', async () => {
 		const dir = mkdtempSync(join(tmpdir(), 'namzu-write-'))
+		const tracker = makeTracker()
+		const ctx = makeContext(dir, tracker)
 
-		const result = await WriteFileTool.execute(
-			{ path: ' fresh.txt ', content: 'hello' },
-			makeContext(dir),
-		)
+		const result = await WriteFileTool.execute({ path: 'fresh.txt', newStr: 'hello' }, ctx)
 
 		expect(result.success).toBe(true)
-		expect(readFileSync(join(dir, ' fresh.txt '), 'utf-8')).toBe('hello')
-	})
-
-	it('rejects legacy content aliases even when execute is called directly', async () => {
-		const dir = mkdtempSync(join(tmpdir(), 'namzu-write-'))
-
-		const result = await WriteFileTool.execute(
-			{ path: 'fresh.txt', newStr: 'legacy' } as never,
-			makeContext(dir),
-		)
-
-		expect(result.success).toBe(false)
-		expect(result.error).toContain('Invalid write input')
+		expect(readFileSync(join(dir, 'fresh.txt'), 'utf-8')).toBe('hello')
 	})
 
 	it('refuses to overwrite an existing file the agent has not read', async () => {
@@ -123,14 +84,14 @@ describe('WriteFileTool — canonical contract and read-before-overwrite invaria
 		expect(readFileSync(filePath, 'utf-8')).toBe('replaced')
 	})
 
-	it('preserves existing hosts without a file read tracker', async () => {
+	it('falls back to legacy behaviour when no fileReadTracker is provided (back-compat)', async () => {
 		const dir = mkdtempSync(join(tmpdir(), 'namzu-write-'))
-		writeFileSync(join(dir, 'existing.txt'), 'before')
+		writeFileSync(join(dir, 'legacy.txt'), 'before')
 		const ctx = makeContext(dir)
 
-		const result = await WriteFileTool.execute({ path: 'existing.txt', content: 'after' }, ctx)
+		const result = await WriteFileTool.execute({ path: 'legacy.txt', content: 'after' }, ctx)
 
 		expect(result.success).toBe(true)
-		expect(readFileSync(join(dir, 'existing.txt'), 'utf-8')).toBe('after')
+		expect(readFileSync(join(dir, 'legacy.txt'), 'utf-8')).toBe('after')
 	})
 })

package/src/tools/builtins/atomic-write-file.ts

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto'
-import { type FileHandle, mkdir, open, rename, stat, unlink } from 'node:fs/promises'
+import { type FileHandle, mkdir, open, realpath, rename, stat, unlink } from 'node:fs/promises'
 import { basename, dirname, join } from 'node:path'
 
 interface AtomicWriteHooks {
@@ -14,10 +14,17 @@ interface AtomicWriteHooks {
  * filesystem. A failed pre-commit write leaves the original untouched.
  */
 export async function atomicWriteFile(
-	filePath: string,
+	requestedPath: string,
 	content: string,
 	hooks: AtomicWriteHooks = {},
 ): Promise<void> {
+	// Write THROUGH a symlink, not over it. `rename` replaces whatever sits
+	// at the destination, so committing onto a link path swaps the link for
+	// a regular file: the link is gone, and every other path that pointed
+	// through it now reads stale content. Resolving first keeps the link and
+	// updates what it points at, which is what a caller editing a linked
+	// file means. A path that does not exist yet resolves to itself.
+	const filePath = await realpath(requestedPath).catch(() => requestedPath)
 	const directory = dirname(filePath)
 	await mkdir(directory, { recursive: true })
 
@@ -47,11 +54,32 @@ export async function atomicWriteFile(
 	}
 }
 
+/**
+ * Best-effort, and only after the rename has already committed.
+ *
+ * Syncing the directory is what makes the RENAME survive a power loss on a
+ * POSIX filesystem. Not every platform permits it — opening a directory and
+ * calling fsync raises `EPERM` on Windows — and there the whole builtin was
+ * unusable: every `edit` and every `write` failed with `EPERM: operation not
+ * permitted, fsync` after correctly writing the file.
+ *
+ * Swallowing is right here and nowhere else in this file. By this point the
+ * destination already holds the complete new body; the only thing still at
+ * stake is durability across an OS-level crash, and on a platform that
+ * refuses the call there is no second way to ask. Failing the write would
+ * trade a durability refinement for a guaranteed error on every write.
+ *
+ * The sibling in `utils/atomic-write.ts` — the one the disk stores use, and
+ * the one that has run on this platform all along — does not sync the
+ * directory at all.
+ */
 async function syncDirectory(directory: string): Promise<void> {
 	let handle: FileHandle | undefined
 	try {
 		handle = await open(directory, 'r')
 		await handle.sync()
+	} catch {
+		// Unsupported on this platform; the rename already landed.
 	} finally {
 		await handle?.close().catch(() => undefined)
 	}

package/src/tools/builtins/bash.ts

@@ -11,7 +11,12 @@ const execAsync = promisify(exec)
 // but Namzu shouldn't read a consumer's env name. Consumers can
 // still alias their own var to `NAMZU_BASH_TIMEOUT_MS` at deploy
 // time if they want a unified knob.
-const DEFAULT_BASH_TIMEOUT_MS = readPositiveIntEnv('NAMZU_BASH_TIMEOUT_MS', 60 * 60 * 1000)
+// Two minutes, not an hour. The old default meant a wedged command held
+// the turn — and, before per-tool deadlines existed, the whole run — for
+// up to 3600s while ignoring Stop entirely. The model can still ask for
+// longer via the tool's own `timeout` argument when it knows a build is
+// slow; the point is that the DEFAULT is survivable.
+const DEFAULT_BASH_TIMEOUT_MS = readPositiveIntEnv('NAMZU_BASH_TIMEOUT_MS', 2 * 60 * 1000)
 const DEFAULT_BASH_MAX_BUFFER_BYTES = readPositiveIntEnv(
 	'NAMZU_BASH_MAX_BUFFER_BYTES',
 	100 * 1024 * 1024,
@@ -22,7 +27,7 @@ const inputSchema = z.object({
 		.string()
 		.min(1)
 		.describe(
-			'The bash command to execute. Required, non-empty. Single command per call (use `&&` / `;` chaining for compound commands). Avoid heredocs that span more than a few hundred bytes — create large content with bounded write plus exact marker-advancing edit calls instead.',
+			'The bash command to execute. Required, non-empty. Single command per call (use `&&` / `;` chaining for compound commands). Avoid heredocs that span more than a few hundred bytes — large content should be created with `write`, then extended with `edit` insertLine: "end", not piped into bash.',
 		),
 	timeout: z
 		.preprocess(
@@ -41,7 +46,7 @@ function isDangerousCommand(command: string): boolean {
 export const BashTool = defineTool({
 	name: 'bash',
 	description:
-		'Executes a bash command and returns stdout/stderr output. Command timeout is configurable. The `command` parameter is required — never call this tool with empty arguments. For very long content, prefer a bounded write with a deterministic marker followed by exact marker-advancing edit calls over a heredoc.',
+		'Executes a bash command and returns stdout/stderr output. Command timeout is configurable. The `command` parameter is required — never call this tool with empty arguments. For very long content (e.g. building a large file), prefer `write` for the opening and `edit` with insertLine: "end" for follow-up chunks over a heredoc to avoid hitting the output token limit mid-stream.',
 	inputSchema,
 	category: 'shell',
 	permissions: ['shell_execute'],
@@ -79,6 +84,9 @@ export const BashTool = defineTool({
 			const result = await context.sandbox.exec('/bin/sh', ['-c', input.command], {
 				timeout: input.timeout,
 				env: context.env,
+				// Same reason as the host path below: a Stop must reach the
+				// process, not just the promise waiting on it.
+				signal: context.abortSignal,
 			})
 
 			if (result.timedOut) {
@@ -89,9 +97,21 @@ export const BashTool = defineTool({
 				}
 			}
 
+			// 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
+			// that it does not truncate silently.
+			const clipped = [
+				result.stdoutTruncated ? 'stdout' : '',
+				result.stderrTruncated ? 'stderr' : '',
+			].filter(Boolean)
+
 			const output = [
 				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]`
+					: '',
 			]
 				.filter(Boolean)
 				.join('\n\n')
@@ -99,16 +119,26 @@ export const BashTool = defineTool({
 			return {
 				success: result.exitCode === 0,
 				output: output || '(no output)',
-				data: { exitCode: result.exitCode, sandboxed: true },
+				data: {
+					exitCode: result.exitCode,
+					sandboxed: true,
+					stdoutTruncated: result.stdoutTruncated ?? false,
+					stderrTruncated: result.stderrTruncated ?? false,
+				},
 				error: 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.
 		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}` : '']

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' },
 			}
 		}