@namzu/sdk 1.3.0 → 2.0.0

package/src/tools/builtins/edit.ts

@@ -1,76 +1,77 @@
-import { readFile, writeFile } from 'node:fs/promises'
+import { readFile } from 'node:fs/promises'
 import { resolve } from 'node:path'
 import { z } from 'zod'
 import { defineTool } from '../defineTool.js'
+import { atomicWriteFile } from './atomic-write-file.js'
+import { withFileMutationLock } from './file-mutation-lock.js'
 
 const inputSchema = z
 	.object({
-		path: z.string().describe('Path to the file to edit'),
-		old_string: z
+		path: z
 			.string()
-			.optional()
-			.describe('The exact string to find and replace. Must be unique in the file.'),
-		oldStr: z
+			.refine((value) => value.trim().length > 0, 'Path must not be empty.')
+			.describe('Path to the file to edit. Must not be empty.'),
+		old_string: z
 			.string()
-			.optional()
+			.min(1)
 			.describe(
-				'Alias for old_string. Used by hosts that expose text replacement as oldStr/newStr.',
+				'The exact unique text to replace, without read-tool line-number prefixes. Must not be empty.',
 			),
 		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.',
+				'The exact replacement text. May be empty to delete old_string. Keep this payload under 12000 characters.',
 			),
 		replace_all: z
 			.boolean()
 			.default(false)
-			.describe('Replace all occurrences instead of just the first unique match'),
+			.describe('Replace every occurrence instead of requiring one 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.' },
-	)
+	.strict()
 
 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
-	  }
+const modelInputSchema: Record<string, unknown> = {
+	type: 'object',
+	properties: {
+		path: {
+			type: 'string',
+			description: 'Path to the file to edit. Must not be empty.',
+		},
+		old_string: {
+			type: 'string',
+			description:
+				'Exact unique text from the file, without read-tool line-number prefixes. Must not be empty.',
+		},
+		new_string: {
+			type: 'string',
+			description:
+				'Exact replacement text. May be empty to delete old_string. Keep under 12000 characters.',
+		},
+		replace_all: {
+			type: 'boolean',
+			description: 'Replace every occurrence instead of requiring one unique match.',
+		},
+	},
+	required: ['path', 'old_string', 'new_string'],
+	additionalProperties: false,
+}
+
+type ExactReplacement = Readonly<{
+	oldString: string
+	newString: string
+	replaceAll: boolean
+}>
 
 export const EditTool = defineTool({
 	name: 'edit',
 	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.',
+		"Performs one targeted exact-string replacement in an existing file. Pass path + old_string + new_string; old_string must match exactly and be unique unless replace_all is true. Read the file immediately before editing, preserve whitespace and indentation, and never include the read tool's line-number prefix in old_string. To append or insert, replace a unique existing tail/marker with itself plus the new text; advance a deterministic marker such as {{CHUNK_001}} to {{CHUNK_002}} so replaying a completed edit cannot duplicate content. Prefer this tool over rewriting an existing file. Self-budget new_string under 12000 characters.",
 	inputSchema,
+	modelInputSchema,
+	enforceModelInput: true,
+	validationErrorHint:
+		'Required shape: {"path":"file.md","old_string":"exact unique text","new_string":"replacement text"}. Optional: "replace_all": true.',
 	category: 'filesystem',
 	permissions: ['file_write'],
 	readOnly: false,
@@ -78,144 +79,120 @@ export const EditTool = defineTool({
 	concurrencySafe: false,
 
 	async execute(input: EditInput, context) {
-		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
-		) {
+		const parsed = inputSchema.safeParse(input)
+		if (!parsed.success) {
 			return {
 				success: false,
 				output: '',
-				error: 'old_string/oldStr and new_string/newStr are identical — no change needed',
+				error: `Invalid edit input: ${parsed.error.issues.map((issue) => issue.message).join('; ')}`,
 			}
 		}
+		const canonicalInput = parsed.data
 
-		// Sandbox-aware: route through sandbox when available
-		if (context.sandbox) {
-			const buffer = await context.sandbox.readFile(input.path)
-			const content = buffer.toString('utf-8')
-
-			const result = applyEdit(content, normalized.operation)
-			if (!result.success) {
-				return { success: false, output: '', error: result.error }
-			}
-
-			await context.sandbox.writeFile(input.path, result.content)
+		const replacement: ExactReplacement = {
+			oldString: canonicalInput.old_string,
+			newString: canonicalInput.new_string,
+			replaceAll: canonicalInput.replace_all,
+		}
+		if (replacement.oldString === replacement.newString) {
 			return {
-				success: true,
-				output: `Edited ${input.path}: ${result.replacements} replacement(s) [sandboxed]`,
-				data: { path: input.path, replacements: result.replacements, sandboxed: true },
+				success: false,
+				output: '',
+				error: 'old_string and new_string are identical — no change needed.',
 			}
 		}
 
-		const filePath = resolve(context.workingDirectory, input.path)
-		const content = await readFile(filePath, 'utf-8')
+		const filePath = resolve(context.workingDirectory, canonicalInput.path)
+		const lockKey = `${context.sandbox ? 'sandbox' : 'local'}:${filePath}`
+
+		return withFileMutationLock(lockKey, async () => {
+			if (context.sandbox) {
+				const buffer = await context.sandbox.readFile(canonicalInput.path)
+				const result = applyEdit(buffer.toString('utf-8'), replacement)
+				if (!result.success) return { success: false as const, output: '', error: result.error }
+
+				await context.sandbox.writeFile(canonicalInput.path, result.content)
+				return {
+					success: true as const,
+					output: `Edited ${canonicalInput.path}: ${result.replacements} replacement(s) [sandboxed]`,
+					data: {
+						path: canonicalInput.path,
+						replacements: result.replacements,
+						sandboxed: true,
+					},
+				}
+			}
 
-		const result = applyEdit(content, normalized.operation)
-		if (!result.success) {
-			return { success: false, output: '', error: result.error }
-		}
+			const content = await readFile(filePath, 'utf-8')
+			const result = applyEdit(content, replacement)
+			if (!result.success) return { success: false as const, output: '', error: result.error }
 
-		await writeFile(filePath, result.content, 'utf-8')
-		return {
-			success: true,
-			output: `Edited ${filePath}: ${result.replacements} replacement(s)`,
-			data: { path: filePath, replacements: result.replacements },
-		}
+			await atomicWriteFile(filePath, result.content)
+			return {
+				success: true as const,
+				output: `Edited ${filePath}: ${result.replacements} replacement(s)`,
+				data: { path: filePath, replacements: result.replacements },
+			}
+		})
 	},
 })
 
-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
+function normalizeLineEndings(content: string, input: ExactReplacement): ExactReplacement {
+	const withoutCrlf = content.replaceAll('\r\n', '')
+	const usesOnlyCrlf = content.includes('\r\n') && !withoutCrlf.includes('\n')
+	if (usesOnlyCrlf) {
 		return {
-			success: true,
-			operation: {
-				operation: 'insert',
-				insertLine: insertLine.value,
-				newString,
-				replace_all: input.replace_all,
-			},
+			...input,
+			oldString: content.includes(input.oldString)
+				? input.oldString
+				: input.oldString.replaceAll('\r\n', '\n').replaceAll('\n', '\r\n'),
+			newString: input.newString.replaceAll('\r\n', '\n').replaceAll('\n', '\r\n'),
 		}
 	}
 
-	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 }
+	const usesOnlyLf = content.includes('\n') && !content.includes('\r\n')
+	if (usesOnlyLf) {
 		return {
-			success: false,
-			error: 'insertLine must be a non-negative line number or "end".',
+			...input,
+			oldString: content.includes(input.oldString)
+				? input.oldString
+				: input.oldString.replaceAll('\r\n', '\n'),
+			newString: input.newString.replaceAll('\r\n', '\n'),
 		}
 	}
-	return { success: true, value }
+	return input
 }
 
 function applyEdit(
 	content: string,
-	input: NormalizedEditInput,
+	rawInput: ExactReplacement,
 ): { success: true; content: string; replacements: number } | { success: false; error: string } {
-	if (input.operation === 'insert') {
-		return applyLineInsert(content, input)
-	}
-
+	const input = normalizeLineEndings(content, rawInput)
 	if (!content.includes(input.oldString)) {
 		return {
 			success: false,
 			error:
-				'old_string/oldStr not found in file. Make sure the string matches exactly, including whitespace and indentation.',
+				'old_string was not found. Read the file again and copy exact text without line-number prefixes.',
 		}
 	}
 
-	if (input.replace_all) {
+	if (input.replaceAll) {
 		const parts = content.split(input.oldString)
-		const replacements = parts.length - 1
 		return {
 			success: true,
 			content: parts.join(input.newString),
-			replacements,
+			replacements: parts.length - 1,
 		}
 	}
 
-	// Uniqueness check: old_string/oldStr must appear exactly once
 	const firstIndex = content.indexOf(input.oldString)
-	const secondIndex = content.indexOf(input.oldString, firstIndex + 1)
-
+	const secondIndex = content.indexOf(input.oldString, firstIndex + input.oldString.length)
 	if (secondIndex !== -1) {
-		const lineNumber = content.slice(0, firstIndex).split('\n').length
+		const firstLine = content.slice(0, firstIndex).split('\n').length
 		const secondLine = content.slice(0, secondIndex).split('\n').length
 		return {
 			success: false,
-			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.`,
+			error: `old_string is not unique — found at lines ${firstLine} and ${secondLine}. Include more surrounding context, or use replace_all: true.`,
 		}
 	}
 
@@ -228,26 +205,3 @@ function applyEdit(
 		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,
-	}
-}

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/index.ts

@@ -26,8 +26,8 @@ import { WriteFileTool } from './write-file.js'
 // `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.
+// tools that look right but degrade alignment. File extension uses canonical
+// exact replacement against a unique tail or deterministic marker.
 // Hosts that genuinely want LS/search can still register them explicitly.
 
 export function getBuiltinTools(): ToolDefinition[] {

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

@@ -1,41 +1,53 @@
-import { access, mkdir, writeFile } from 'node:fs/promises'
-import { dirname, resolve } from 'node:path'
+import { access } from 'node:fs/promises'
+import { resolve } from 'node:path'
 import { z } from 'zod'
 import type { ToolContext } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
+import { atomicWriteFile } from './atomic-write-file.js'
+import { withFileMutationLock } from './file-mutation-lock.js'
 
 const inputSchema = z
 	.object({
 		path: z
 			.string()
-			.min(1)
+			.refine((value) => value.trim().length > 0, 'Path must not be empty.')
 			.describe(
-				'Relative path to the file to write (e.g. "outputs/report.md"). Required. Must be a non-empty string.',
+				'Relative path to the file to write (e.g. "outputs/report.md"). Must not be empty.',
 			),
 		content: z
 			.string()
-			.optional()
 			.describe(
-				'Full file body to write. Required (use "" only for an intentionally empty file). The file is fully overwritten — pass the COMPLETE intended content for this bounded chunk, not a diff. Self-budget content under 12000 characters before calling; if the intended body is longer, write a smaller opening section here, then use `edit` with insertLine: "end" to extend the file section by section. Do NOT try to chain multiple `write` calls, since each one overwrites the previous.',
-			),
-		newStr: z
-			.string()
-			.optional()
-			.describe(
-				'Alias for content. Useful for hosts that expose create/write operations as newStr. Self-budget this payload under 12000 characters before calling.',
+				'Complete bounded file body. Use "" only for an intentionally empty file. Keep under 12000 characters. For longer documents, include a deterministic marker such as {{CHUNK_001}} and advance it with exact edit calls.',
 			),
 	})
-	.refine((value) => typeof value.content === 'string' || typeof value.newStr === 'string', {
-		message: 'Either content or newStr is required.',
-	})
+	.strict()
 
 type WriteInput = z.infer<typeof inputSchema>
 
+const modelInputSchema: Record<string, unknown> = {
+	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,
+}
+
 export const WriteFileTool = defineTool({
 	name: 'write',
 	description:
-		'Writes a file to the local filesystem. Overwrites the existing file at the path if there is one.\n\n- If the file already exists, you must use the `read` tool on it first in this conversation, or this call will fail.\n- Prefer the `edit` tool for modifying existing files — it only sends the diff and preserves the rest of the file byte-for-byte.\n- Use `write` to create a new file or to perform a deliberate full rewrite of a file you have already read.\n- Self-budget content/newStr under 12000 characters before emitting the tool call. For long content, write a smaller opening section, then use `edit` with insertLine: "end" to extend the file section by section. Do not chain multiple `write` calls — each one overwrites the previous.',
+		'Writes a complete bounded file body. Pass exactly path + content. If the file exists, read it first; prefer edit for targeted changes. Self-budget content under 12000 characters. For longer documents, write an opening with a deterministic marker such as {{CHUNK_001}}, then use exact edit calls that advance the marker one chunk at a time. Do not chain write calls because each overwrites the file.',
 	inputSchema,
+	modelInputSchema,
+	enforceModelInput: true,
+	validationErrorHint: 'Required shape: {"path":"file.md","content":"complete bounded file body"}.',
 	category: 'filesystem',
 	permissions: ['file_write'],
 	readOnly: false,
@@ -43,40 +55,52 @@ export const WriteFileTool = defineTool({
 	concurrencySafe: false,
 
 	async execute(input: WriteInput, context) {
-		const content = input.content ?? input.newStr ?? ''
-		// Sandbox-aware: route through sandbox.writeFile() when available
-		if (context.sandbox) {
-			const sandboxExists = await sandboxFileExists(context, input.path)
-			if (sandboxExists) {
-				const guard = enforceReadBeforeOverwrite(context, input.path)
-				if (guard) return guard
-			}
-			await context.sandbox.writeFile(input.path, content)
-			context.fileReadTracker?.recordRead(input.path)
+		const parsed = inputSchema.safeParse(input)
+		if (!parsed.success) {
 			return {
-				success: true,
-				output: `File written successfully: ${input.path} (${content.length} chars) [sandboxed]`,
-				data: { path: input.path, size: content.length, sandboxed: true },
+				success: false,
+				output: '',
+				error: `Invalid write input: ${parsed.error.issues.map((issue) => issue.message).join('; ')}`,
 			}
 		}
+		const canonicalInput = parsed.data
 
-		const filePath = resolve(context.workingDirectory, input.path)
-
-		const localExists = await pathExists(filePath)
-		if (localExists) {
-			const guard = enforceReadBeforeOverwrite(context, filePath)
-			if (guard) return guard
-		}
+		const filePath = resolve(context.workingDirectory, canonicalInput.path)
+		const lockKey = `${context.sandbox ? 'sandbox' : 'local'}:${filePath}`
+		return withFileMutationLock(lockKey, async () => {
+			if (context.sandbox) {
+				const sandboxExists = await sandboxFileExists(context, canonicalInput.path)
+				if (sandboxExists) {
+					const guard = enforceReadBeforeOverwrite(context, canonicalInput.path)
+					if (guard) return guard
+				}
+				await context.sandbox.writeFile(canonicalInput.path, canonicalInput.content)
+				context.fileReadTracker?.recordRead(canonicalInput.path)
+				return {
+					success: true as const,
+					output: `File written successfully: ${canonicalInput.path} (${canonicalInput.content.length} chars) [sandboxed]`,
+					data: {
+						path: canonicalInput.path,
+						size: canonicalInput.content.length,
+						sandboxed: true,
+					},
+				}
+			}
 
-		await mkdir(dirname(filePath), { recursive: true })
-		await writeFile(filePath, content, 'utf-8')
-		context.fileReadTracker?.recordRead(filePath)
+			const localExists = await pathExists(filePath)
+			if (localExists) {
+				const guard = enforceReadBeforeOverwrite(context, filePath)
+				if (guard) return guard
+			}
 
-		return {
-			success: true,
-			output: `File written successfully: ${filePath} (${content.length} chars)`,
-			data: { path: filePath, size: content.length },
-		}
+			await atomicWriteFile(filePath, canonicalInput.content)
+			context.fileReadTracker?.recordRead(filePath)
+			return {
+				success: true as const,
+				output: `File written successfully: ${filePath} (${canonicalInput.content.length} chars)`,
+				data: { path: filePath, size: canonicalInput.content.length },
+			}
+		})
 	},
 })
 

package/src/tools/coordinator/__tests__/task-list.test.ts

@@ -179,4 +179,20 @@ describe('coordinator agent_task_list tool', () => {
 		expect(names).toContain('agent_task_list')
 		expect(names).not.toContain('task_list')
 	})
+
+	it('does not advertise per-task cancellation on the blocking coordinator surface', () => {
+		const coordinatorTools = buildCoordinatorTools({
+			gateway: gatewayWith([]),
+			workingDirectory: '/tmp/test',
+			allowedAgentIds: ['solution-architecture'],
+		})
+		const names = coordinatorTools.map((tool) => tool.name)
+
+		// create_task returns only after the worker is terminal, so the
+		// supervisor cannot know a live task id in a later model turn.
+		// Keeping cancel_task here only manufactured success for missing
+		// or terminal ids because every gateway cancellation is a void
+		// no-op in those states.
+		expect(names).not.toContain('cancel_task')
+	})
 })

package/src/tools/coordinator/agent.ts

@@ -19,14 +19,12 @@ 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 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 is not what Claude Code trained against.
- * For free agentic alignment, prefer the canonical `Agent` tool; keep
- * the legacy coordinator tools only when you genuinely need
- * fire-and-forget multi-task fan-out.
+ * 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.
  */
 export interface AgentToolOptions {
 	gateway: TaskGateway