@namzu/sdk 0.5.0 → 1.0.0

package/src/tools/builtins/__tests__/edit.test.ts

@@ -0,0 +1,57 @@
+import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import type { ToolContext } from '../../../types/tool/index.js'
+import { EditTool } from '../edit.js'
+
+function makeContext(workingDirectory: string): ToolContext {
+	return {
+		runId: 'run_test' as ToolContext['runId'],
+		workingDirectory,
+		abortSignal: new AbortController().signal,
+		env: {},
+		log: () => {},
+	}
+}
+
+describe('EditTool', () => {
+	it('accepts oldStr/newStr aliases for string replacement', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-edit-'))
+		writeFileSync(join(dir, 'doc.md'), 'alpha\nbeta\n')
+
+		const result = await EditTool.execute(
+			{ path: 'doc.md', oldStr: 'beta', newStr: 'gamma', replace_all: false },
+			makeContext(dir),
+		)
+
+		expect(result.success).toBe(true)
+		expect(readFileSync(join(dir, 'doc.md'), 'utf-8')).toBe('alpha\ngamma\n')
+	})
+
+	it('inserts content after a 1-indexed line number', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-edit-'))
+		writeFileSync(join(dir, 'doc.md'), 'alpha\nbeta\n')
+
+		const result = await EditTool.execute(
+			{ path: 'doc.md', insertLine: 1, newStr: 'inserted', replace_all: false },
+			makeContext(dir),
+		)
+
+		expect(result.success).toBe(true)
+		expect(readFileSync(join(dir, 'doc.md'), 'utf-8')).toBe('alpha\ninserted\nbeta\n')
+	})
+
+	it('inserts content at the end with insertLine=end', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-edit-'))
+		writeFileSync(join(dir, 'doc.md'), 'alpha\n')
+
+		const result = await EditTool.execute(
+			{ path: 'doc.md', insertLine: 'end', newStr: 'omega', replace_all: false },
+			makeContext(dir),
+		)
+
+		expect(result.success).toBe(true)
+		expect(readFileSync(join(dir, 'doc.md'), 'utf-8')).toBe('alpha\nomega\n')
+	})
+})

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

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest'
+import { EditTool } from '../edit.js'
+import { getBuiltinTools } from '../index.js'
+import { WriteFileTool } from '../write-file.js'
+
+describe('filesystem tool payload budgeting', () => {
+	it('does not hard-fail oversized write/edit payloads at schema validation', () => {
+		const oversized = 'x'.repeat(12_500)
+
+		expect(() =>
+			WriteFileTool.inputSchema.parse({ path: 'outputs/long.md', content: oversized }),
+		).not.toThrow()
+		expect(() =>
+			EditTool.inputSchema.parse({
+				path: 'outputs/long.md',
+				oldStr: '{{SECTION}}',
+				newStr: oversized,
+				replace_all: false,
+			}),
+		).not.toThrow()
+	})
+
+	it('keeps append out of the default builtin toolset', () => {
+		const names = getBuiltinTools().map((tool) => tool.name)
+
+		expect(names).toContain('edit')
+		expect(names).not.toContain('append')
+	})
+})

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

@@ -0,0 +1,31 @@
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import type { ToolContext } from '../../../types/tool/index.js'
+import { ReadFileTool } from '../read-file.js'
+
+function makeContext(workingDirectory: string): ToolContext {
+	return {
+		runId: 'run_test' as ToolContext['runId'],
+		workingDirectory,
+		abortSignal: new AbortController().signal,
+		env: {},
+		log: () => {},
+	}
+}
+
+describe('ReadFileTool', () => {
+	it('accepts readRange as a 1-indexed inclusive line range', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-read-'))
+		writeFileSync(join(dir, 'doc.md'), ['one', 'two', 'three', 'four'].join('\n'))
+
+		const result = await ReadFileTool.execute(
+			{ path: 'doc.md', readRange: [2, 3] },
+			makeContext(dir),
+		)
+
+		expect(result.success).toBe(true)
+		expect(result.output).toBe('2\ttwo\n3\tthree')
+	})
+})

package/src/tools/builtins/__tests__/verify-outputs.test.ts

@@ -0,0 +1,71 @@
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import type { ToolContext } from '../../../types/tool/index.js'
+import { VerifyOutputsTool } from '../verify-outputs.js'
+
+function makeContext(workingDirectory: string): ToolContext {
+	return {
+		runId: 'run_test' as ToolContext['runId'],
+		workingDirectory,
+		abortSignal: new AbortController().signal,
+		env: {},
+		log: () => {},
+	}
+}
+
+describe('VerifyOutputsTool', () => {
+	it('reports OK for every existing non-empty file', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-verify-'))
+		writeFileSync(join(dir, 'a.md'), 'hello world')
+		writeFileSync(join(dir, 'b.txt'), 'x'.repeat(500))
+
+		const result = await VerifyOutputsTool.execute({ paths: ['a.md', 'b.txt'] }, makeContext(dir))
+
+		expect(result.success).toBe(true)
+		expect(result.output).toMatch(/2\/2 passed/)
+		expect(result.output).toMatch(/OK {3}a\.md/)
+		expect(result.output).toMatch(/OK {3}b\.txt/)
+	})
+
+	it('flags missing files as FAIL with summary', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-verify-'))
+		writeFileSync(join(dir, 'present.md'), 'data')
+
+		const result = await VerifyOutputsTool.execute(
+			{ paths: ['present.md', 'missing.md', 'also-missing.md'] },
+			makeContext(dir),
+		)
+
+		expect(result.success).toBe(false)
+		expect(result.error).toMatch(/2 of 3 expected outputs failed/)
+		expect(result.output).toMatch(/1\/3 passed/)
+		expect(result.output).toMatch(/FAIL missing\.md — missing/)
+	})
+
+	it('treats files smaller than min_bytes as FAIL', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-verify-'))
+		writeFileSync(join(dir, 'tiny.md'), 'x') // 1 byte
+		writeFileSync(join(dir, 'big.md'), 'y'.repeat(2000))
+
+		const result = await VerifyOutputsTool.execute(
+			{ paths: ['tiny.md', 'big.md'], min_bytes: 1000 },
+			makeContext(dir),
+		)
+
+		expect(result.success).toBe(false)
+		expect(result.output).toMatch(/FAIL tiny\.md — size 1B < min 1000B/)
+		expect(result.output).toMatch(/OK {3}big\.md/)
+	})
+
+	it('rejects directories that match a path', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-verify-'))
+		const result = await VerifyOutputsTool.execute(
+			{ paths: ['.'] }, // working directory itself
+			makeContext(dir),
+		)
+		expect(result.success).toBe(false)
+		expect(result.output).toMatch(/FAIL \. — not a regular file/)
+	})
+})

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

@@ -0,0 +1,97 @@
+import { mkdtempSync, readFileSync, 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 { WriteFileTool } from '../write-file.js'
+
+function makeTracker(): FileReadTracker & { keys(): string[] } {
+	const set = new Set<string>()
+	return {
+		recordRead: (k) => {
+			set.add(k)
+		},
+		hasRead: (k) => set.has(k),
+		keys: () => Array.from(set),
+	}
+}
+
+function makeContext(workingDirectory: string, tracker?: FileReadTracker): ToolContext {
+	return {
+		runId: 'run_test' as ToolContext['runId'],
+		workingDirectory,
+		abortSignal: new AbortController().signal,
+		env: {},
+		log: () => {},
+		fileReadTracker: tracker,
+	}
+}
+
+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()
+		const ctx = makeContext(dir, tracker)
+
+		const result = await WriteFileTool.execute({ path: 'fresh.txt', content: 'hello' }, ctx)
+
+		expect(result.success).toBe(true)
+		expect(readFileSync(join(dir, 'fresh.txt'), 'utf-8')).toBe('hello')
+		expect(tracker.hasRead(join(dir, 'fresh.txt'))).toBe(true)
+	})
+
+	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', newStr: 'hello' }, ctx)
+
+		expect(result.success).toBe(true)
+		expect(readFileSync(join(dir, 'fresh.txt'), 'utf-8')).toBe('hello')
+	})
+
+	it('refuses to overwrite an existing file the agent has not read', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-write-'))
+		writeFileSync(join(dir, 'pre-existing.txt'), 'original')
+		const tracker = makeTracker()
+		const ctx = makeContext(dir, tracker)
+
+		const result = await WriteFileTool.execute(
+			{ path: 'pre-existing.txt', content: 'replaced' },
+			ctx,
+		)
+
+		expect(result.success).toBe(false)
+		expect(result.error).toMatch(/already exists.*read/i)
+		expect(readFileSync(join(dir, 'pre-existing.txt'), 'utf-8')).toBe('original')
+	})
+
+	it('allows overwrite once the file has been read in the same context', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-write-'))
+		const filePath = join(dir, 'pre-existing.txt')
+		writeFileSync(filePath, 'original')
+		const tracker = makeTracker()
+		tracker.recordRead(filePath)
+		const ctx = makeContext(dir, tracker)
+
+		const result = await WriteFileTool.execute(
+			{ path: 'pre-existing.txt', content: 'replaced' },
+			ctx,
+		)
+
+		expect(result.success).toBe(true)
+		expect(readFileSync(filePath, 'utf-8')).toBe('replaced')
+	})
+
+	it('falls back to legacy behaviour when no fileReadTracker is provided (back-compat)', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-write-'))
+		writeFileSync(join(dir, 'legacy.txt'), 'before')
+		const ctx = makeContext(dir)
+
+		const result = await WriteFileTool.execute({ path: 'legacy.txt', content: 'after' }, ctx)
+
+		expect(result.success).toBe(true)
+		expect(readFileSync(join(dir, 'legacy.txt'), 'utf-8')).toBe('after')
+	})
+})

package/src/tools/builtins/bash.ts

@@ -5,12 +5,31 @@ import { DANGEROUS_PATTERNS } from '../../constants/tools/index.js'
 import { defineTool } from '../defineTool.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,
+// 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)
+const DEFAULT_BASH_MAX_BUFFER_BYTES = readPositiveIntEnv(
+	'NAMZU_BASH_MAX_BUFFER_BYTES',
+	100 * 1024 * 1024,
+)
 
 const inputSchema = z.object({
-	command: z.string().describe('The bash command to execute'),
+	command: z
+		.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 — large content should be created with `write`, then extended with `edit` insertLine: "end", not piped into bash.',
+		),
 	timeout: z
-		.preprocess((v) => (typeof v === 'string' ? Number(v) : v), z.number().default(30_000))
-		.describe('Command timeout in milliseconds. Default: 30000'),
+		.preprocess(
+			(v) => (typeof v === 'string' ? Number(v) : v),
+			z.number().default(DEFAULT_BASH_TIMEOUT_MS),
+		)
+		.describe(`Command timeout in milliseconds. Default: ${DEFAULT_BASH_TIMEOUT_MS}`),
 })
 
 type BashInput = z.infer<typeof inputSchema>
@@ -22,7 +41,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.',
+		'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'],
@@ -39,11 +58,26 @@ export const BashTool = defineTool({
 			}
 		}
 
-		// Sandbox-aware: route through sandbox.exec() when available
+		// Sandbox-aware: route through sandbox.exec() when available.
+		//
+		// `context.workingDirectory` is the HOST-side workspace path the
+		// SDK consumer chose for the run (Vandal: `/var/lib/vandal/sessions/<task>`),
+		// which is meaningless inside the sandbox container. Forwarding
+		// it as `cwd` would either land on a path that doesn't exist
+		// (and the worker would `mkdir -p` it inside the container,
+		// silently divorcing the model's filesystem view from where its
+		// deliverables actually need to land) or, in the case of the
+		// `container:docker` worker, fail the workspace-confinement
+		// guard outright. The right behaviour is to let the worker
+		// fall through to its own default (`NAMZU_SANDBOX_WORKSPACE`
+		// → the per-task mount root the host configured at provider
+		// construction time). Tools that need a sub-cwd inside the
+		// sandbox can be added later as an explicit
+		// `SandboxExecOptions.workspaceRelativeCwd` field; the bash
+		// builtin doesn't have that requirement today.
 		if (context.sandbox) {
 			const result = await context.sandbox.exec('/bin/sh', ['-c', input.command], {
 				timeout: input.timeout,
-				cwd: context.workingDirectory,
 				env: context.env,
 			})
 
@@ -74,7 +108,7 @@ export const BashTool = defineTool({
 			cwd: context.workingDirectory,
 			timeout: input.timeout,
 			env: { ...process.env, ...context.env },
-			maxBuffer: 1024 * 1024 * 10,
+			maxBuffer: DEFAULT_BASH_MAX_BUFFER_BYTES,
 		})
 
 		const output = [stdout ? `STDOUT:\n${stdout}` : '', stderr ? `STDERR:\n${stderr}` : '']
@@ -88,3 +122,10 @@ export const BashTool = defineTool({
 		}
 	},
 })
+
+function readPositiveIntEnv(key: string, fallback: number): number {
+	const value = process.env[key]?.trim()
+	if (!value) return fallback
+	const parsed = Number(value)
+	return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback
+}

package/src/tools/builtins/edit.ts

@@ -3,24 +3,73 @@ import { resolve } from 'node:path'
 import { z } from 'zod'
 import { defineTool } from '../defineTool.js'
 
-const inputSchema = z.object({
-	path: z.string().describe('Path to the file to edit'),
-	old_string: z
-		.string()
-		.describe('The exact string to find and replace. Must be unique in the file.'),
-	new_string: z.string().describe('The replacement string'),
-	replace_all: z
-		.boolean()
-		.default(false)
-		.describe('Replace all occurrences instead of just the first unique match'),
-})
+const inputSchema = z
+	.object({
+		path: z.string().describe('Path to the file to edit'),
+		old_string: z
+			.string()
+			.optional()
+			.describe('The exact string to find and replace. Must be unique in the file.'),
+		oldStr: z
+			.string()
+			.optional()
+			.describe(
+				'Alias for old_string. Used by hosts that expose text replacement as oldStr/newStr.',
+			),
+		new_string: z
+			.string()
+			.optional()
+			.describe(
+				'The replacement string. Self-budget this payload under 12000 characters before calling.',
+			),
+		newStr: z
+			.string()
+			.optional()
+			.describe(
+				'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.coerce.number().int().min(0), z.string().min(1)])
+			.optional()
+			.describe(
+				'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()
+			.default(false)
+			.describe('Replace all occurrences instead of just the first unique match'),
+	})
+	.refine((value) => typeof value.new_string === 'string' || typeof value.newStr === 'string', {
+		message: 'Either new_string or newStr is required.',
+	})
+	.refine(
+		(value) =>
+			value.insertLine !== undefined ||
+			typeof value.old_string === 'string' ||
+			typeof value.oldStr === 'string',
+		{ message: 'Either old_string/oldStr or insertLine is required.' },
+	)
 
 type EditInput = z.infer<typeof inputSchema>
 
+type NormalizedEditInput =
+	| {
+			operation: 'replace'
+			oldString: string
+			newString: string
+			replace_all: boolean
+	  }
+	| {
+			operation: 'insert'
+			insertLine: number | 'end'
+			newString: string
+			replace_all: boolean
+	  }
+
 export const EditTool = defineTool({
 	name: 'edit',
 	description:
-		'Makes targeted edits to a file using exact string find-and-replace. The old_string must be unique in the file unless replace_all is true. Preserves file formatting and indentation.',
+		'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,
 	category: 'filesystem',
 	permissions: ['file_write'],
@@ -29,11 +78,18 @@ export const EditTool = defineTool({
 	concurrencySafe: false,
 
 	async execute(input: EditInput, context) {
-		if (input.old_string === input.new_string) {
+		const normalized = normalizeEditInput(input)
+		if (!normalized.success) {
+			return { success: false, output: '', error: normalized.error }
+		}
+		if (
+			normalized.operation.operation === 'replace' &&
+			normalized.operation.oldString === normalized.operation.newString
+		) {
 			return {
 				success: false,
 				output: '',
-				error: 'old_string and new_string are identical — no change needed',
+				error: 'old_string/oldStr and new_string/newStr are identical — no change needed',
 			}
 		}
 
@@ -42,7 +98,7 @@ export const EditTool = defineTool({
 			const buffer = await context.sandbox.readFile(input.path)
 			const content = buffer.toString('utf-8')
 
-			const result = applyEdit(content, input)
+			const result = applyEdit(content, normalized.operation)
 			if (!result.success) {
 				return { success: false, output: '', error: result.error }
 			}
@@ -58,7 +114,7 @@ export const EditTool = defineTool({
 		const filePath = resolve(context.workingDirectory, input.path)
 		const content = await readFile(filePath, 'utf-8')
 
-		const result = applyEdit(content, input)
+		const result = applyEdit(content, normalized.operation)
 		if (!result.success) {
 			return { success: false, output: '', error: result.error }
 		}
@@ -72,38 +128,94 @@ export const EditTool = defineTool({
 	},
 })
 
+function normalizeEditInput(
+	input: EditInput,
+): { success: true; operation: NormalizedEditInput } | { success: false; error: string } {
+	const newString = input.new_string ?? input.newStr
+	if (typeof newString !== 'string') {
+		return { success: false, error: 'Either new_string or newStr is required.' }
+	}
+
+	if (input.insertLine !== undefined) {
+		const insertLine = normalizeInsertLine(input.insertLine)
+		if (!insertLine.success) return insertLine
+		return {
+			success: true,
+			operation: {
+				operation: 'insert',
+				insertLine: insertLine.value,
+				newString,
+				replace_all: input.replace_all,
+			},
+		}
+	}
+
+	const oldString = input.old_string ?? input.oldStr
+	if (typeof oldString !== 'string') {
+		return { success: false, error: 'Either old_string/oldStr or insertLine is required.' }
+	}
+	return {
+		success: true,
+		operation: {
+			operation: 'replace',
+			oldString,
+			newString,
+			replace_all: input.replace_all,
+		},
+	}
+}
+
+function normalizeInsertLine(
+	value: string | number,
+): { success: true; value: number | 'end' } | { success: false; error: string } {
+	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(
 	content: string,
-	input: EditInput,
+	input: NormalizedEditInput,
 ): { success: true; content: string; replacements: number } | { success: false; error: string } {
-	if (!content.includes(input.old_string)) {
+	if (input.operation === 'insert') {
+		return applyLineInsert(content, input)
+	}
+
+	if (!content.includes(input.oldString)) {
 		return {
 			success: false,
 			error:
-				'old_string not found in file. Make sure the string matches exactly, including whitespace and indentation.',
+				'old_string/oldStr not found in file. Make sure the string matches exactly, including whitespace and indentation.',
 		}
 	}
 
 	if (input.replace_all) {
-		const parts = content.split(input.old_string)
+		const parts = content.split(input.oldString)
 		const replacements = parts.length - 1
 		return {
 			success: true,
-			content: parts.join(input.new_string),
+			content: parts.join(input.newString),
 			replacements,
 		}
 	}
 
-	// Uniqueness check: old_string must appear exactly once
-	const firstIndex = content.indexOf(input.old_string)
-	const secondIndex = content.indexOf(input.old_string, firstIndex + 1)
+	// Uniqueness check: old_string/oldStr must appear exactly once
+	const firstIndex = content.indexOf(input.oldString)
+	const secondIndex = content.indexOf(input.oldString, firstIndex + 1)
 
 	if (secondIndex !== -1) {
 		const lineNumber = content.slice(0, firstIndex).split('\n').length
 		const secondLine = content.slice(0, secondIndex).split('\n').length
 		return {
 			success: false,
-			error: `old_string is not unique — found at lines ${lineNumber} and ${secondLine}. Provide more surrounding context to make it unique, or use replace_all: true.`,
+			error: `old_string/oldStr is not unique — found at lines ${lineNumber} and ${secondLine}. Provide more surrounding context to make it unique, or use replace_all: true.`,
 		}
 	}
 
@@ -111,8 +223,31 @@ function applyEdit(
 		success: true,
 		content:
 			content.slice(0, firstIndex) +
-			input.new_string +
-			content.slice(firstIndex + input.old_string.length),
+			input.newString +
+			content.slice(firstIndex + input.oldString.length),
+		replacements: 1,
+	}
+}
+
+function applyLineInsert(
+	content: string,
+	input: Extract<NormalizedEditInput, { operation: 'insert' }>,
+): { success: true; content: string; replacements: number } {
+	const hasTrailingNewline = content.endsWith('\n')
+	const lines = content.split('\n')
+	if (hasTrailingNewline) lines.pop()
+
+	const line =
+		input.insertLine === 'end'
+			? lines.length
+			: Math.min(Math.max(input.insertLine, 0), lines.length)
+	const inserted = input.newString.endsWith('\n')
+		? input.newString.slice(0, -1).split('\n')
+		: input.newString.split('\n')
+	lines.splice(line, 0, ...inserted)
+	return {
+		success: true,
+		content: `${lines.join('\n')}${hasTrailingNewline ? '\n' : ''}`,
 		replacements: 1,
 	}
 }