@namzu/sdk 62.6.1 → 62.8.0

package/src/tools/builtins/bash.ts

@@ -520,6 +520,11 @@ export function execHostShell(
 
 export { dangerousCommandReason }
 
+/** A reason as a sentence a person reads under a row: first letter up. */
+function sentence(reason: string): string {
+	return reason ? `${reason.charAt(0).toUpperCase()}${reason.slice(1)}` : reason
+}
+
 /** The dangerous-pattern check `bash` applies, shared so the `monitor` tool refuses the same lines. */
 export function isDangerousCommand(command: string): boolean {
 	return DANGEROUS_PATTERNS.some((pattern) => pattern.test(command))
@@ -537,7 +542,7 @@ export const SANDBOX_ESCAPE_NOT_APPROVED =
 	'dangerously_disable_sandbox was not approved for this call, so the command did not run. Leaving the sandbox needs the user to confirm it each time, and this turn either cannot ask or does not allow it. Run the command inside the sandbox, or tell the user what it needs and let them run it.'
 
 const BASH_DESCRIPTION =
-	'Executes a command line using the execution shell disclosed in the system context and returns stdout/stderr output. The working directory persists between calls, but shell state does not. Command timeout is configurable. The `command` parameter is required, so every call carries one. Long file content goes through `write`, not a heredoc, so it cannot hit the output token limit mid-stream.'
+	'Executes a command line using the execution shell disclosed in the system context and returns stdout/stderr output. The working directory persists between calls, but shell state does not. Command timeout is configurable. Read and search with `read`, `grep` and `glob`, not shell loops: a file read through the shell earns no read credit, so its next edit is refused once. Run a check on its own, not piped: its output is already trimmed, and a pipe hides the exit status.'
 
 const BashToolBase = defineTool({
 	name: 'bash',
@@ -596,7 +601,12 @@ const BashToolBase = defineTool({
 				success: false,
 				output: '',
 				error: `Dangerous command blocked: "${input.command}". Why: ${dangerousCommandReason(input.command)}. Nothing ran. Use a narrower command that avoids it, or ask the user to run this one.`,
-				facts: { kind: 'failure', reason: 'blocked', subject: 'bash' },
+				facts: {
+					kind: 'failure',
+					reason: 'blocked',
+					subject: 'bash',
+					note: sentence(dangerousCommandReason(input.command)),
+				},
 			}
 		}
 

package/src/tools/builtins/bounded-file-read.ts

@@ -1,4 +1,4 @@
-import { constants } from 'node:fs'
+import { constants, closeSync, fstatSync, openSync, readSync } from 'node:fs'
 import { open } from 'node:fs/promises'
 
 const CHUNK_BYTES = 64 * 1024
@@ -40,10 +40,13 @@ export async function readBoundedFile(
 	maximum: number,
 	signal?: AbortSignal,
 	selectLimit?: (prefix: Buffer) => number,
+	extraFlags = 0,
 ): Promise<Buffer> {
 	// O_NONBLOCK prevents a substituted FIFO from blocking open before fstat.
+	// `extraFlags` adds to it, for a caller that also needs the last component
+	// refused when it is a link.
 	signal?.throwIfAborted()
-	const file = await open(path, constants.O_RDONLY | constants.O_NONBLOCK)
+	const file = await open(path, constants.O_RDONLY | constants.O_NONBLOCK | extraFlags)
 	try {
 		const info = await file.stat()
 		if (!info.isFile()) throw new Error('Read requires a regular file.')
@@ -78,3 +81,57 @@ function inputTooLarge(limit: number): Error {
 		`File exceeds the bounded read limit (${limit} bytes). Extract a smaller file with a shell command.`,
 	)
 }
+
+/** True where the platform can refuse a final-component link at open time. */
+export const CAN_REFUSE_LINKS = typeof constants.O_NOFOLLOW === 'number' && constants.O_NOFOLLOW > 0
+
+/** The flag a caller passes to {@link readBoundedFile} to refuse a final-component link. */
+export const REFUSE_LINK_FLAG: number = CAN_REFUSE_LINKS ? constants.O_NOFOLLOW : 0
+
+/**
+ * The same bounded read as {@link readBoundedFile} through one synchronous
+ * handle: open, fstat, read, close. A link in the last path component is
+ * refused at open (`O_NOFOLLOW`), so a link swapped in after a walk listed the
+ * file cannot be followed. Callers yield between files; one file is at most
+ * `maximum` bytes; a file whose size is over it answers `'too-large'`. With a
+ * `scratch` buffer, a file that fits one chunk comes back as a view of it, valid
+ * until the next call. Requires {@link CAN_REFUSE_LINKS}.
+ *
+ * With `syncMaximum`, a file whose size is over it (and within `maximum`) is not
+ * read here: the answer is `'large'`, so the caller reads it through
+ * {@link readBoundedFile}, which does not hold the event loop for the whole file.
+ */
+export function readBoundedFileSync(
+	path: string,
+	maximum: number,
+	scratch?: Buffer,
+	syncMaximum = maximum,
+): Buffer | 'too-large' | 'large' {
+	const fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW)
+	try {
+		const info = fstatSync(fd)
+		if (!info.isFile()) throw new Error('Read requires a regular file.')
+		if (info.size > maximum) return 'too-large'
+		if (info.size > syncMaximum) return 'large'
+		const chunks: Buffer[] = []
+		let offset = 0
+		for (;;) {
+			const length = Math.min(CHUNK_BYTES, maximum + 1 - offset)
+			const buffer =
+				offset === 0 && scratch && scratch.length >= length ? scratch : Buffer.allocUnsafe(length)
+			let used = 0
+			while (used < length) {
+				const bytesRead = readSync(fd, buffer, used, length - used, offset + used)
+				if (bytesRead === 0) break
+				used += bytesRead
+			}
+			offset += used
+			if (offset > maximum) throw inputTooLarge(maximum)
+			chunks.push(buffer.subarray(0, used))
+			if (used < length)
+				return chunks.length === 1 ? (chunks[0] as Buffer) : Buffer.concat(chunks, offset)
+		}
+	} finally {
+		closeSync(fd)
+	}
+}

package/src/tools/builtins/edit-apply.ts

@@ -40,7 +40,7 @@ export type NormalizedEditInput =
 export function normalizeEditInput(
 	input: EditInput,
 ): { success: true; operations: NormalizedEditInput[] } | { success: false; error: string } {
-	if (input.edits !== undefined) {
+	if (input.edits !== undefined && input.edits.length > 0) {
 		return {
 			success: true,
 			operations: input.edits.map((edit) => ({
@@ -197,11 +197,15 @@ function applyOne(
 	if (!content.includes(oldString)) {
 		const resolved = resolveOldString(content, oldString)
 		if (resolved === null) {
+			const near = nearLine(content, oldString)
 			return {
 				success: false,
 				reason: 'text_not_found',
-				error:
-					'old_string/oldStr not found in file. Make sure the string matches exactly, including whitespace and indentation.',
+				error: `old_string/oldStr not found in file. Make sure the string matches exactly, including whitespace and indentation. ${
+					near === undefined
+						? 'Read the lines you mean to change again and copy them as they are.'
+						: `A line that matches its first line apart from spacing is at line ${near}; read around it again and copy it as it is.`
+				}`,
 			}
 		}
 		newString = reconcileNewString(oldString, resolved, newString)
@@ -235,7 +239,7 @@ function applyOne(
 		return {
 			success: false,
 			reason: 'not_unique',
-			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/oldStr is not unique — found at lines ${lineNumber} and ${secondLine}. Provide more surrounding context to make it unique, or use replace_all: true. Read around those lines again to choose context that is only in one of them.`,
 		}
 	}
 
@@ -247,6 +251,24 @@ function applyOne(
 	}
 }
 
+const NEAR_LINE_MIN_CHARS = 8
+
+/** The line of `content` that matches the first non-blank line of `needle` apart from spacing, 1-based. */
+function nearLine(content: string, needle: string): number | undefined {
+	const squash = (text: string) => text.replace(/\s+/g, ' ').trim()
+	const first = needle
+		.split('\n')
+		.map(squash)
+		.find((line) => line !== '')
+	// A bare brace or paren is on many lines; naming the first one would point at the wrong place.
+	if (first === undefined || first.length < NEAR_LINE_MIN_CHARS) return undefined
+	const lines = content.split('\n')
+	for (let i = 0; i < lines.length; i++) {
+		if (squash(lines[i] ?? '') === first) return i + 1
+	}
+	return undefined
+}
+
 function applyLineInsert(
 	content: string,
 	input: Extract<NormalizedEditInput, { operation: 'insert' }>,

package/src/tools/builtins/edit.ts

@@ -22,8 +22,91 @@ import {
 import { withFileMutationLock } from './file-mutation-lock.js'
 import { jsonStringEscapes } from './json-string-hint.js'
 import { lineDiff } from './line-diff.js'
+import { notebookRefusal } from './notebook-guard.js'
 import { staleBeforeReview } from './stale-before-review.js'
 
+type RawEditInput = {
+	path: string
+	old_string?: string
+	oldStr?: string
+	new_string?: string
+	newStr?: string
+	insertLine?: number | string
+	replace_all?: boolean
+	edits?: { old_string: string; new_string: string; replace_all?: boolean }[]
+}
+
+const ONE_SHAPE_EACH =
+	'Single edit: {"path":"file.md","old_string":"exact unique text","new_string":"replacement text"}\nSeveral edits: {"path":"file.md","edits":[{"old_string":"a","new_string":"b"},{"old_string":"c","new_string":"d"}]}'
+
+const hasTopLevelEdit = (value: RawEditInput): boolean =>
+	value.old_string !== undefined ||
+	value.oldStr !== undefined ||
+	value.new_string !== undefined ||
+	value.newStr !== undefined ||
+	value.insertLine !== undefined
+
+/**
+ * A top-level edit that is exactly the one entry of a one-entry batch: the same
+ * call said twice, not two intentions. Anything else (a different text, a
+ * longer list, an insertion) is a real conflict and stays refused.
+ */
+function restatesTheBatch(value: RawEditInput): boolean {
+	const entries = value.edits
+	if (entries === undefined || entries.length !== 1 || value.insertLine !== undefined) return false
+	const [entry] = entries
+	return (
+		entry !== undefined &&
+		(value.old_string ?? value.oldStr) === entry.old_string &&
+		(value.new_string ?? value.newStr) === entry.new_string &&
+		(value.replace_all ?? false) === (entry.replace_all ?? false)
+	)
+}
+
+/**
+ * Which of the two shapes this call is, and what to say when it is neither.
+ *
+ * An empty `edits` beside a top-level edit, and a one-entry `edits` that restates
+ * the top-level edit, are the single edit: the intent is not in doubt and nothing
+ * is dropped. A batch beside a DIFFERENT top-level edit stays refused, because
+ * any precedence would silently drop an edit somebody believes was made.
+ */
+function checkEditShape(value: RawEditInput): string | undefined {
+	const batch = value.edits !== undefined && value.edits.length > 0
+	const top = hasTopLevelEdit(value)
+	if (value.edits !== undefined && !batch && !top) {
+		return `\`edits\` is an empty list, so there is nothing to change. Send exactly one of these, and leave out the field you are not using:\n${ONE_SHAPE_EACH}`
+	}
+	if (batch && top && !restatesTheBatch(value)) {
+		return `This call has both an \`edits\` list and a different top-level edit, and only one can be applied. Send exactly one of these, and leave out the field you are not using:\n${ONE_SHAPE_EACH}`
+	}
+	if (batch) return undefined
+	if (typeof value.new_string !== 'string' && typeof value.newStr !== 'string') {
+		return 'Either new_string or newStr is required.'
+	}
+	if (
+		value.insertLine === undefined &&
+		typeof value.old_string !== 'string' &&
+		typeof value.oldStr !== 'string'
+	) {
+		return 'Either old_string/oldStr or insertLine is required.'
+	}
+	return undefined
+}
+
+/**
+ * The input every later stage sees: one shape, with the redundant half gone. The
+ * review card, the classifier, the dry run and the apply step all read this, so
+ * none of them meets `edits: []` or a restated edit.
+ */
+function canonicalEditInput(value: RawEditInput): RawEditInput {
+	if (value.edits === undefined) return value
+	const { edits, ...rest } = value
+	if (edits.length === 0) return rest
+	const { old_string, oldStr, new_string, newStr, insertLine, ...kept } = rest
+	return { ...kept, edits }
+}
+
 /**
  * Two schemas, on purpose.
  *
@@ -106,48 +189,23 @@ const inputSchema = z
 					})
 					.strict(),
 			)
-			.min(1)
+			// No `.min(1)`: a model that fills every optional field of a flat object
+			// sends `edits: []` next to a single top-level edit, and that is the
+			// single edit, not an error. An empty list with nothing beside it is
+			// refused by `checkEditShape` below, in a sentence that says what to send.
 			.optional()
 			.describe(
-				'Several replacements in one file, applied in order and committed together. Nothing is written unless every one applies.',
+				'Several replacements in one file, applied in order and committed together. Nothing is written unless every one applies. Leave out when sending a single old_string/new_string.',
 			),
 	})
 	.strict()
-	.refine(
-		(value) =>
-			value.edits !== undefined ||
-			typeof value.new_string === 'string' ||
-			typeof value.newStr === 'string',
-		{ message: 'Either new_string or newStr is required.' },
-	)
-	.refine(
-		(value) =>
-			value.edits !== undefined ||
-			value.insertLine !== undefined ||
-			typeof value.old_string === 'string' ||
-			typeof value.oldStr === 'string',
-		{ message: 'Either old_string/oldStr or insertLine is required.' },
-	)
-	// Refused rather than resolved. A call carrying both an `edits` list and a
-	// top-level replacement is two different intentions in one object, and any
-	// precedence this code picked would be a guess about which the model meant
-	// — silently dropping the other. There is no reading of that which is safe:
-	// the dropped half is an edit somebody believes was made.
-	.refine(
-		(value) =>
-			value.edits === undefined ||
-			(value.old_string === undefined &&
-				value.oldStr === undefined &&
-				value.new_string === undefined &&
-				value.newStr === undefined &&
-				value.insertLine === undefined),
-		{
-			message:
-				'Use either `edits` or a single top-level edit, not both. Move the top-level old_string/new_string into the edits list.',
-		},
-	)
+	.superRefine((value, ctx) => {
+		const problem = checkEditShape(value)
+		if (problem) ctx.addIssue({ code: 'custom', message: problem })
+	})
+	.transform(canonicalEditInput)
 
-export type EditInput = z.infer<typeof inputSchema>
+export type EditInput = z.output<typeof inputSchema>
 
 /**
  * What an `edit` call WOULD produce for a file body, without touching any file.
@@ -184,7 +242,10 @@ export function dryRunEdit(
 		}
 	}
 	const result = applyEdit(content, normalized.operations)
-	return result.success ? { success: true, content: result.content } : result
+	if (!result.success) return result
+	const notebook = notebookRefusal(parsed.data.path, result.content, content)
+	if (notebook) return { success: false, error: notebook }
+	return { success: true, content: result.content }
 }
 
 /**
@@ -205,7 +266,7 @@ const modelInputSchema: Record<string, unknown> = {
 		old_string: {
 			type: 'string',
 			description:
-				'Exact unique text from the file, without read-tool line-number prefixes. Must not be empty.',
+				'For a single change: exact unique text from the file, without read-tool line-number prefixes. Must not be empty. Do not send together with edits.',
 		},
 		new_string: {
 			type: 'string',
@@ -282,7 +343,7 @@ const modelInputSchema: Record<string, unknown> = {
 				additionalProperties: false,
 			},
 			description:
-				'Several replacements in one file, applied in order and committed together. Nothing is written unless every one applies. Use this instead of several edit calls when the changes only make sense together.',
+				'For SEVERAL changes to one file: a non-empty list, applied in order and committed together. Nothing is written unless every one applies. Leave this field out entirely when you send old_string/new_string; never send an empty list.',
 		},
 	},
 	// `old_string` is deliberately NOT required, and this is the fix.
@@ -437,7 +498,7 @@ function refusedEdit(result: EditApplyFailure, path: string) {
 export const EditTool = defineTool({
 	name: 'edit',
 	description:
-		'Makes targeted edits to a file using exact string find-and-replace or line insertion. To change an existing file, use `edit`: `write` overwrites the whole body and discards earlier work on partial failure, while `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. Keep new_string/newStr under 12000 characters, because a longer payload can be cut off mid-call and fail; use repeated bounded edits for long sections. Preserves file formatting and indentation. To make several changes to one file that only make sense together, send them as `edits`: a list of {old_string, new_string} applied in order and committed as one write — if any of them does not apply, nothing is written and the reply names which one, so the file is never left half-changed.',
+		'Makes targeted edits to a file using exact string find-and-replace or line insertion. To change an existing file, use `edit`: `write` overwrites the whole body and discards earlier work on partial failure, while `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. Keep new_string/newStr under 12000 characters, because a longer payload can be cut off mid-call and fail; use repeated bounded edits for long sections. Preserves file formatting and indentation. To make several changes to one file that only make sense together, send them as `edits` (and then no top-level old_string/new_string; for a single change leave `edits` out): a list of {old_string, new_string} applied in order and committed as one write — if any of them does not apply, nothing is written and the reply names which one, so the file is never left half-changed. An edit that would leave a `.ipynb` file as invalid notebook JSON is refused and the file is unchanged.',
 	inputSchema,
 	modelInputSchema,
 	enforceModelInput: true,
@@ -458,7 +519,7 @@ export const EditTool = defineTool({
 	refuseBeforeReview: (input: EditInput, context) => staleBeforeReview(context, input.path, 'edit'),
 	// The classifier judges which file changes and in what way, in a line.
 	classifierInput: (input: EditInput) => {
-		if (input.edits !== undefined) {
+		if (input.edits !== undefined && input.edits.length > 0) {
 			const shown = input.edits.slice(0, 5).map((e) => describeChange(e.old_string, e.new_string))
 			const more =
 				input.edits.length > shown.length ? `; ${input.edits.length - shown.length} more` : ''
@@ -570,6 +631,8 @@ export const EditTool = defineTool({
 				if (!admitted.success) return admitted
 				const result = admitted.result
 				if (!result.success) return refusedEdit(result, parsed.data.path)
+				const notebook = notebookRefusal(parsed.data.path, result.content, content)
+				if (notebook) return { success: false as const, output: '', error: notebook }
 
 				await context.sandbox.writeFile(parsed.data.path, result.content)
 				recordEditedContent(context, parsed.data.path, result.content)
@@ -593,6 +656,8 @@ export const EditTool = defineTool({
 			if (!admitted.success) return admitted
 			const result = admitted.result
 			if (!result.success) return refusedEdit(result, hostPath)
+			const notebook = notebookRefusal(hostPath, result.content, content)
+			if (notebook) return { success: false as const, output: '', error: notebook }
 
 			// Temp file, fsync, rename — a reader sees the old body or the new
 			// one, never a half-written one. A plain `writeFile` that fails

package/src/tools/builtins/glob.ts

@@ -68,7 +68,7 @@ function relativePattern(pattern: string, root: string, sandboxed: boolean): str
 export const GlobTool = defineTool({
 	name: 'glob',
 	description:
-		'Finds regular files by glob pattern in a bounded search. "*" searches one directory; use "**" explicitly for recursive discovery. Skips files that .gitignore and .ignore rules exclude unless include_ignored is set, and files the read rules of the session deny. Returns at most 500 paths and says when a result is limited or a search stopped early. Does not follow symlinks.',
+		'Finds regular files by glob pattern in a bounded search. "*" searches one directory; use "**" explicitly for recursive discovery. Skips files that .gitignore and .ignore rules exclude unless include_ignored is set, and files the read rules of the session deny. Returns at most 500 paths and says when a result is limited or a search stopped early. Does not follow symlinks. To search inside files, use grep.',
 	inputSchema,
 	category: 'filesystem',
 	// Declared so a path outside the turn's roots can be reviewed before the