@namzu/sdk 3.0.0 → 3.1.0

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

@@ -1,8 +1,10 @@
-import { access, mkdir, writeFile } from 'node:fs/promises'
+import { access, mkdir } from 'node:fs/promises'
 import { dirname, 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({
@@ -25,17 +27,46 @@ const inputSchema = z
 				'Alias for content. Useful for hosts that expose create/write operations as newStr. Self-budget this payload under 12000 characters before calling.',
 			),
 	})
+	.strict()
 	.refine((value) => typeof value.content === 'string' || typeof value.newStr === 'string', {
 		message: 'Either content or newStr is required.',
 	})
 
 type WriteInput = z.infer<typeof inputSchema>
 
+/**
+ * The single shape a model is constrained to emit.
+ *
+ * `newStr` is a host affordance and deliberately absent here: a model given
+ * two names for the body has to pick, and picking is what produces the
+ * half-filled calls this schema exists to prevent.
+ */
+const modelInputSchema: Record<string, unknown> = {
+	type: 'object',
+	properties: {
+		path: {
+			type: 'string',
+			description: 'Relative path to the file to write. Must not be empty.',
+		},
+		content: {
+			type: 'string',
+			description:
+				'Complete file body. Use "" only for an intentionally empty file. Keep under 12000 characters.',
+		},
+	},
+	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.',
 	inputSchema,
+	modelInputSchema,
+	enforceModelInput: true,
+	validationErrorHint:
+		'Required shape: {"path":"file.md","content":"complete file body"}. Pass the whole body, not a diff.',
 	category: 'filesystem',
 	permissions: ['file_write'],
 	readOnly: false,
@@ -43,40 +74,60 @@ 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)
+		// `execute` is reachable without going through the registry, so the
+		// closed contract has to be enforced on this path too or it is not
+		// closed at all.
+		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 valid = parsed.data
+		const content = valid.content ?? valid.newStr ?? ''
+		const filePath = resolve(context.workingDirectory, valid.path)
+		// The exists-check and the write are a check-then-act pair. Unlocked,
+		// two writers both see "absent", both skip the read-before-overwrite
+		// guard, and the second silently discards the first.
+		const lockKey = `${context.sandbox ? 'sandbox' : 'local'}:${filePath}`
 
-		const filePath = resolve(context.workingDirectory, input.path)
+		return withFileMutationLock(lockKey, async () => {
+			if (context.sandbox) {
+				const sandboxExists = await sandboxFileExists(context, valid.path)
+				if (sandboxExists) {
+					const guard = enforceReadBeforeOverwrite(context, valid.path)
+					if (guard) return guard
+				}
+				await context.sandbox.writeFile(valid.path, content)
+				context.fileReadTracker?.recordRead(valid.path)
+				return {
+					success: true as const,
+					output: `File written successfully: ${valid.path} (${content.length} chars) [sandboxed]`,
+					data: { path: valid.path, size: content.length, sandboxed: true },
+				}
+			}
 
-		const localExists = await pathExists(filePath)
-		if (localExists) {
-			const guard = enforceReadBeforeOverwrite(context, filePath)
-			if (guard) return guard
-		}
+			const localExists = await pathExists(filePath)
+			if (localExists) {
+				const guard = enforceReadBeforeOverwrite(context, filePath)
+				if (guard) return guard
+			}
 
-		await mkdir(dirname(filePath), { recursive: true })
-		await writeFile(filePath, content, 'utf-8')
-		context.fileReadTracker?.recordRead(filePath)
+			await mkdir(dirname(filePath), { recursive: true })
+			// Temp file, fsync, rename. A plain write that fails partway
+			// leaves the destination truncated — and this tool overwrites a
+			// whole file, so the truncation is the user's previous work.
+			await atomicWriteFile(filePath, content)
+			context.fileReadTracker?.recordRead(filePath)
 
-		return {
-			success: true,
-			output: `File written successfully: ${filePath} (${content.length} chars)`,
-			data: { path: filePath, size: content.length },
-		}
+			return {
+				success: true as const,
+				output: `File written successfully: ${filePath} (${content.length} chars)`,
+				data: { path: filePath, size: content.length },
+			}
+		})
 	},
 })
 

package/src/tools/coordinator/__tests__/ask-user-question.test.ts

@@ -368,3 +368,71 @@ describe('coordinator ask_user_question decision -> output mapping', () => {
 		expect(result.output).toBe('User answered "Who is the audience?": "Board"')
 	})
 })
+
+describe('the question contract is closed, not merely shaped', () => {
+	const noopHandler: ResumeHandler = async () => ({ action: 'continue' })
+
+	it('publishes one closed model-facing schema', () => {
+		const tool = askTool(noopHandler)
+
+		expect(tool.modelInputSchema).toMatchObject({
+			type: 'object',
+			required: ['question', 'options'],
+			additionalProperties: false,
+		})
+		// The whole point of the array declaration: a model that serializes
+		// its options once tends to keep doing it, and a closed schema makes
+		// a capable provider refuse at generation time instead of after.
+		const properties = (tool.modelInputSchema as { properties: Record<string, { type: string }> })
+			.properties
+		expect(properties.options?.type).toBe('array')
+		expect(tool.enforceModelInput).toBe(true)
+	})
+
+	it('rejects a serialized options string and other malformed option shapes', () => {
+		const tool = askTool(noopHandler)
+
+		for (const options of [
+			'<options><option><label>Board</label></option></options>',
+			'[{"label":"Board"},{"label":"Engineering"}]',
+			[42, { label: 'Engineering' }],
+			[{ description: 'Missing label' }, { label: 'Engineering' }],
+			[{ label: 'Board', description: 42 }, { label: 'Engineering' }],
+		]) {
+			expect(
+				tool.inputSchema.safeParse({ question: 'Who is the audience?', options }).success,
+				JSON.stringify(options),
+			).toBe(false)
+		}
+	})
+
+	it('rejects a field it does not declare, rather than dropping it', () => {
+		const tool = askTool(noopHandler)
+		const valid = {
+			question: 'Who is the audience?',
+			options: [{ label: 'Board' }, { label: 'Engineering' }],
+		}
+
+		expect(tool.inputSchema.safeParse(valid).success).toBe(true)
+
+		// Without `.strict()` zod strips these, so the call proceeds as if the
+		// caller had never written them — a misspelling becomes a silent no-op.
+		for (const extra of [
+			{ ...valid, multiSelct: true },
+			{ ...valid, choices: ['a', 'b'] },
+			{
+				...valid,
+				options: [{ label: 'Board', reason: 'why' }, { label: 'Engineering' }],
+			},
+		]) {
+			expect(tool.inputSchema.safeParse(extra).success, JSON.stringify(extra)).toBe(false)
+		}
+	})
+
+	it('carries a recovery hint that names the shape to retry with', () => {
+		const tool = askTool(noopHandler)
+
+		expect(tool.validationErrorHint).toContain('"options" must be a JSON array')
+		expect(tool.validationErrorHint).toContain('never a string')
+	})
+})

package/src/tools/coordinator/index.ts

@@ -78,6 +78,59 @@ const approvePlanStepSchema = z.object({
 	depends_on: z.array(z.string()).optional().describe('Step descriptions this depends on'),
 })
 
+/**
+ * The single closed shape a capable provider constrains this call to.
+ *
+ * `options` arriving as a STRING is the failure this exists for: a model that
+ * serializes the array once tends to keep doing it, and the parse error it
+ * gets back never says the array was the problem.
+ * `additionalProperties: false` turns that into a refusal at generation time
+ * rather than a rejection after the fact.
+ */
+const askUserQuestionModelInputSchema: Record<string, unknown> = {
+	type: 'object',
+	properties: {
+		question: {
+			type: 'string',
+			description: 'Full question text — clear, specific, and ending with a question mark.',
+		},
+		header: {
+			type: 'string',
+			description: 'Optional very short topic label, no more than 24 characters.',
+		},
+		options: {
+			type: 'array',
+			description: 'A JSON array of 2-4 genuinely distinct, context-derived option objects.',
+			items: {
+				type: 'object',
+				properties: {
+					label: {
+						type: 'string',
+						description:
+							'Concise option label. Put the recommended option first and append " (Recommended)".',
+					},
+					description: {
+						type: 'string',
+						description: 'Optional one-line explanation of what changes if selected.',
+					},
+				},
+				required: ['label'],
+				additionalProperties: false,
+			},
+		},
+		multiSelect: {
+			type: 'boolean',
+			description: 'True only when several options can apply at once.',
+		},
+		allowFreeText: {
+			type: 'boolean',
+			description: 'Whether the user may answer in their own words.',
+		},
+	},
+	required: ['question', 'options'],
+	additionalProperties: false,
+}
+
 function normalizeApprovePlanSteps(value: unknown): unknown {
 	if (typeof value !== 'string') return value
 
@@ -437,47 +490,55 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 			name: 'ask_user_question',
 			description:
 				'Ask the user ONE question ONLY when you are blocked on a decision that is genuinely theirs to make — one you cannot resolve from their request, your tools, the files you can read, or sensible defaults. The question must be the genuinely undecidable thing in THIS task. Never ask for information a tool can discover (do not ask what you can read, list, or search), never re-ask what the conversation already answers, and never ask meta-questions like "Shall I proceed?" — plan ratification goes through approve_plan. Provide 2-4 genuinely distinct options derived from the actual context — concrete paths, never generic placeholders (for example, asked to prepare a presentation, ask "Who is the audience?" with options like Board / Engineering team / Customer); keep labels short (1-5 words) and give each option a one-line description of what practically changes if it is chosen. Put your recommended option FIRST and append " (Recommended)" to its label. Set multiSelect: true only when several options can apply at once. A free-text "Something else" escape hatch is always shown automatically — do not add your own "Other" option. Ask ONE question per call and prefer at most one question per assistant turn; if several decisions block you, ask only the ones that materially change your next actions, in sequence — most work needs at most 2-3 questions, so prefer proceeding on stated defaults over interrogating the user. Never invent answers or synthetic content on the user\'s behalf unless they explicitly asked for a random/test scenario. The answer arrives as this tool\'s result; if the result says the user did not answer, do not ask this or any other question again — proceed on your best judgment without assuming consent.',
-			inputSchema: z.object({
-				question: z
-					.string()
-					.min(1)
-					.describe('Full question text — clear, specific, ends with a question mark.'),
-				header: z
-					.string()
-					.max(24)
-					.optional()
-					.describe('Very short topic label for the question (e.g. "Audience", "Auth method").'),
-				options: z
-					.array(
-						z.object({
-							label: z
-								.string()
-								.min(1)
-								.max(80)
-								.describe(
-									'Concise option label (1-5 words). Recommended option goes first with " (Recommended)" appended.',
-								),
-							description: z
-								.string()
-								.max(300)
-								.optional()
-								.describe('One line on what practically changes if this option is chosen.'),
-						}),
-					)
-					.min(2)
-					.max(4)
-					.describe('2-4 genuinely distinct, context-derived options.'),
-				multiSelect: z
-					.boolean()
-					.optional()
-					.default(false)
-					.describe('True only when several options can apply at once.'),
-				allowFreeText: z
-					.boolean()
-					.optional()
-					.default(true)
-					.describe('Whether the user may answer in their own words.'),
-			}),
+			inputSchema: z
+				.object({
+					question: z
+						.string()
+						.min(1)
+						.describe('Full question text — clear, specific, ends with a question mark.'),
+					header: z
+						.string()
+						.max(24)
+						.optional()
+						.describe('Very short topic label for the question (e.g. "Audience", "Auth method").'),
+					options: z
+						.array(
+							z
+								.object({
+									label: z
+										.string()
+										.min(1)
+										.max(80)
+										.describe(
+											'Concise option label (1-5 words). Recommended option goes first with " (Recommended)" appended.',
+										),
+									description: z
+										.string()
+										.max(300)
+										.optional()
+										.describe('One line on what practically changes if this option is chosen.'),
+								})
+								.strict(),
+						)
+						.min(2)
+						.max(4)
+						.describe('2-4 genuinely distinct, context-derived options.'),
+					multiSelect: z
+						.boolean()
+						.optional()
+						.default(false)
+						.describe('True only when several options can apply at once.'),
+					allowFreeText: z
+						.boolean()
+						.optional()
+						.default(true)
+						.describe('Whether the user may answer in their own words.'),
+				})
+				.strict(),
+			modelInputSchema: structuredClone(askUserQuestionModelInputSchema),
+			enforceModelInput: true,
+			validationErrorHint:
+				'Required shape: {"question":"...?","options":[{"label":"First (Recommended)","description":"What changes"},{"label":"Second","description":"What changes"}]}. "options" must be a JSON array of 2-4 objects, never a string.',
 			category: 'custom',
 			permissions: [],
 			readOnly: true,

package/src/types/tool/index.ts

@@ -19,8 +19,24 @@ export interface ToolRegistryRef {
  * is active, absolute (`workingDirectory`-resolved) otherwise.
  */
 export interface FileReadTracker {
-	recordRead(key: string): void
+	/**
+	 * `content` lets the tracker fingerprint what was read, which is what
+	 * makes drift detectable later. Optional so a host that only needs the
+	 * read-before-overwrite guard can keep its existing implementation.
+	 */
+	recordRead(key: string, content?: string): void
 	hasRead(key: string): boolean
+	/**
+	 * Fingerprint of the body captured at the last read, when one was.
+	 *
+	 * A file mutation is computed against what the agent READ, and between
+	 * that read and the write the file may have moved under it — a person
+	 * editing in an editor, another process, a second agent. The in-process
+	 * lock cannot see any of those. Comparing this against the body actually
+	 * on disk at mutation time is what turns a silent lost update into a
+	 * refusal the agent can act on by re-reading.
+	 */
+	fingerprint?(key: string): string | undefined
 }
 
 export interface ToolPauseOption {