@namzu/sdk 3.0.0 → 3.2.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/__tests__/plan-dependencies.test.ts

@@ -0,0 +1,186 @@
+import { describe, expect, it } from 'vitest'
+
+import { resolvePlanDependencies } from '../plan-dependencies.js'
+
+/**
+ * The model is shown `depends_on` on every plan step and told it means
+ * "Step descriptions this depends on". `approve_plan` then passed
+ * `dependsOn: []` for every step, so the ordering it declared was discarded
+ * at the only place it entered the system.
+ *
+ * The cost is not scheduling — the dependency gate in `PlanManager` has no
+ * callers — it is the approval. `dependsOn` is serialized into the
+ * `plan_approval` payload a human reads before saying yes, so the reviewer
+ * saw a plan whose steps all looked independent however carefully the model
+ * had ordered them.
+ */
+
+const id = (index: number) => `step_${index + 1}`
+
+describe('what the model described becomes what the plan holds', () => {
+	it('resolves a description to the step that carries it', () => {
+		const result = resolvePlanDependencies(
+			[
+				{ description: 'Read the config' },
+				{ description: 'Write the report', depends_on: ['Read the config'] },
+			],
+			id,
+		)
+
+		expect(result).toEqual({ ok: true, dependsOn: [[], ['step_1']] })
+	})
+
+	it('resolves several dependencies on one step', () => {
+		const result = resolvePlanDependencies(
+			[
+				{ description: 'Read the config' },
+				{ description: 'Read the code' },
+				{ description: 'Write the report', depends_on: ['Read the config', 'Read the code'] },
+			],
+			id,
+		)
+
+		expect(result.ok && result.dependsOn[2]).toEqual(['step_1', 'step_2'])
+	})
+
+	it('resolves a forward dependency, since order of declaration is not order of execution', () => {
+		const result = resolvePlanDependencies(
+			[
+				{ description: 'Write the report', depends_on: ['Read the config'] },
+				{ description: 'Read the config' },
+			],
+			id,
+		)
+
+		expect(result.ok && result.dependsOn[0]).toEqual(['step_2'])
+	})
+
+	it('leaves a step with no dependencies empty', () => {
+		const result = resolvePlanDependencies([{ description: 'Read the config' }], id)
+
+		expect(result).toEqual({ ok: true, dependsOn: [[]] })
+	})
+
+	it('forgives whitespace and casing a model did not keep identical', () => {
+		const result = resolvePlanDependencies(
+			[
+				{ description: 'Read  the config' },
+				{ description: 'Write', depends_on: ['read the   CONFIG '] },
+			],
+			id,
+		)
+
+		// Rejecting this would teach the model nothing, for a plan that was
+		// right.
+		expect(result.ok && result.dependsOn[1]).toEqual(['step_1'])
+	})
+
+	it('collapses the same dependency named twice', () => {
+		const result = resolvePlanDependencies(
+			[{ description: 'Read' }, { description: 'Write', depends_on: ['Read', 'Read'] }],
+			id,
+		)
+
+		expect(result.ok && result.dependsOn[1]).toEqual(['step_1'])
+	})
+})
+
+describe('a dependency that cannot mean anything is refused, not dropped', () => {
+	it('refuses a dependency naming no step', () => {
+		const result = resolvePlanDependencies(
+			[{ description: 'Write', depends_on: ['Read the config'] }],
+			id,
+		)
+
+		expect(result.ok).toBe(false)
+		// The model has to be able to act on it, so the offending text is named.
+		expect(!result.ok && result.error).toContain('Read the config')
+	})
+
+	it('refuses a dependency two steps could answer', () => {
+		const result = resolvePlanDependencies(
+			[
+				{ description: 'Review' },
+				{ description: 'Review' },
+				{ description: 'Report', depends_on: ['Review'] },
+			],
+			id,
+		)
+
+		// Picking either is a coin flip whose result a human then approves as
+		// if it were the model's intent.
+		expect(result.ok).toBe(false)
+		expect(!result.ok && result.error).toContain('2 steps share that description')
+	})
+
+	it('refuses a step that depends on itself', () => {
+		const result = resolvePlanDependencies([{ description: 'Loop', depends_on: ['Loop'] }], id)
+
+		expect(result.ok).toBe(false)
+		expect(!result.ok && result.error).toContain('depends on itself')
+	})
+
+	it('refuses a two-step cycle', () => {
+		const result = resolvePlanDependencies(
+			[
+				{ description: 'A', depends_on: ['B'] },
+				{ description: 'B', depends_on: ['A'] },
+			],
+			id,
+		)
+
+		expect(result.ok).toBe(false)
+		expect(!result.ok && result.error).toContain('loop')
+	})
+
+	it('refuses a cycle several steps long', () => {
+		const result = resolvePlanDependencies(
+			[
+				{ description: 'A', depends_on: ['C'] },
+				{ description: 'B', depends_on: ['A'] },
+				{ description: 'C', depends_on: ['B'] },
+			],
+			id,
+		)
+
+		// This is the failure worth catching hardest: no step in a loop can
+		// start, so the plan does not error — it simply stops.
+		expect(result.ok).toBe(false)
+		expect(!result.ok && result.error).toContain('loop')
+	})
+
+	it('names every step in the loop so it can be broken', () => {
+		const result = resolvePlanDependencies(
+			[
+				{ description: 'Alpha', depends_on: ['Gamma'] },
+				{ description: 'Beta' },
+				{ description: 'Gamma', depends_on: ['Alpha'] },
+			],
+			id,
+		)
+
+		expect(result.ok).toBe(false)
+		if (result.ok) return
+		expect(result.error).toContain('Alpha')
+		expect(result.error).toContain('Gamma')
+		// Beta is not in the loop and must not be blamed for it.
+		expect(result.error).not.toContain('Beta')
+	})
+
+	it('accepts a diamond, which is not a cycle', () => {
+		const result = resolvePlanDependencies(
+			[
+				{ description: 'Start' },
+				{ description: 'Left', depends_on: ['Start'] },
+				{ description: 'Right', depends_on: ['Start'] },
+				{ description: 'Join', depends_on: ['Left', 'Right'] },
+			],
+			id,
+		)
+
+		// Two paths reaching one step is an ordinary plan shape, and a naive
+		// visited-set cycle check calls it a loop.
+		expect(result.ok).toBe(true)
+		expect(result.ok && result.dependsOn[3]).toEqual(['step_2', 'step_3'])
+	})
+})

package/src/tools/coordinator/index.ts

@@ -8,6 +8,7 @@ import type { RunId, TaskId } from '../../types/ids/index.js'
 import type { TaskStore } from '../../types/task/index.js'
 import type { ToolDefinition } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
+import { resolvePlanDependencies } from './plan-dependencies.js'
 
 export type TaskLaunchedCallback = (
 	agentTaskId: TaskId,
@@ -78,6 +79,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
 
@@ -384,6 +438,15 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 					}
 				}
 
+				// Resolve BEFORE touching the plan manager. A refusal here has to
+				// leave no half-built plan behind: `startGenerating` replaces the
+				// current plan, so failing after it would discard a plan that was
+				// fine in favour of one that never completes.
+				const dependencies = resolvePlanDependencies(steps, (index) => `step_${index + 1}`)
+				if (!dependencies.ok) {
+					return { success: false, output: '', error: dependencies.error }
+				}
+
 				pm.startGenerating(title)
 				for (let i = 0; i < steps.length; i++) {
 					const step = steps[i]
@@ -392,7 +455,10 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 						id: `step_${i + 1}`,
 						description: step.description,
 						toolName: step.agent_id ? 'create_task' : undefined,
-						dependsOn: [],
+						// Was `[]` unconditionally, which dropped every ordering
+						// constraint the model was invited to express — and put an
+						// empty dependency list in front of the human approving it.
+						dependsOn: [...(dependencies.dependsOn[i] ?? [])],
 						order: i + 1,
 					})
 				}
@@ -437,47 +503,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,