@namzu/sdk 56.0.0 → 56.1.0

package/src/tools/builtins/read-render.ts

@@ -54,14 +54,37 @@ export interface RenderedRead {
  */
 export function renderNumberedRead(content: string, input: ReadWindowRequest): RenderedRead {
 	const lines = content.split('\n')
-	const { start, end } = resolveReadWindow(input, lines.length)
-	const selected = lines.slice(start, end)
+	// One definition of a file's length for the header, the notice and the
+	// past-end warning: a final newline ends a line, it does not start another.
+	const lineCount = countFileLines(content)
+	const { start, end } = resolveReadWindow(input, lineCount)
+	// A file with no text in it, or a window that opens after its last line,
+	// has nothing to number. Say that in words instead of printing a numbered
+	// empty line or a "PARTIAL view" range that runs backwards.
+	if (content === '') {
+		return {
+			output: 'Warning: the file exists but is empty.',
+			totalLines: 0,
+			returnedLines: 0,
+			partial: false,
+		}
+	}
+	if (start >= lineCount) {
+		return {
+			output: `Warning: the file is shorter than the requested start (line ${start + 1}). It has ${lineCount} ${lineCount === 1 ? 'line' : 'lines'}.`,
+			totalLines: lineCount,
+			returnedLines: 0,
+			// Nothing of the file was shown, so this must never stand in for it.
+			partial: true,
+		}
+	}
+	const selected = lines.slice(start, Math.min(end, lineCount))
 	const numbered = selected.map((line, i) => `${start + i + 1}\t${line}`).join('\n')
 	return {
-		output: numbered + partialViewNotice(start, selected.length, lines.length),
-		totalLines: lines.length,
+		output: numbered + partialViewNotice(start, selected.length, lineCount),
+		totalLines: lineCount,
 		returnedLines: selected.length,
-		partial: selected.length < lines.length,
+		partial: selected.length < lineCount,
 	}
 }
 
@@ -85,6 +108,13 @@ function partialViewNotice(start: number, returned: number, total: number): stri
 	].join('\n')
 }
 
+/** The number of lines a file has: a final newline ends a line, it does not start another. */
+export function countFileLines(content: string): number {
+	if (content === '') return 0
+	const parts = content.split('\n').length
+	return content.endsWith('\n') ? parts - 1 : parts
+}
+
 export function resolveReadWindow(
 	input: ReadWindowRequest,
 	totalLines: number,
@@ -153,7 +183,7 @@ export function estimateReadTokens(text: string, ext: string): number {
 	return Math.round(text.length / perToken)
 }
 
-function humanBytes(n: number): string {
+export function humanBytes(n: number): string {
 	if (n >= 1024 * 1024) return `${(n / (1024 * 1024)).toFixed(1)} MiB`
 	if (n >= 1024) return `${Math.round(n / 1024)} KiB`
 	return `${n} B`
@@ -200,8 +230,9 @@ export function renderCappedRead(
 	}
 
 	const lines = content.split('\n')
-	const { start, end } = resolveReadWindow(input, lines.length)
-	const selected = lines.slice(start, end)
+	const lineCount = countFileLines(content)
+	const { start, end } = resolveReadWindow(input, lineCount)
+	const selected = lines.slice(start, Math.min(end, lineCount))
 	const selectedText = selected.join('\n')
 
 	const selectedBytes = Buffer.byteLength(selectedText, 'utf8')
@@ -226,7 +257,7 @@ export function renderCappedRead(
 	}
 	return {
 		ok: true,
-		rendered: trimFirstPage(selected, lines.length, selectedText, tokens, maxTokens, options.path),
+		rendered: trimFirstPage(selected, lineCount, selectedText, tokens, maxTokens, options.path),
 	}
 }
 

package/src/tools/builtins/stale-before-review.ts

@@ -0,0 +1,45 @@
+import { readFile } from 'node:fs/promises'
+
+import type { ToolContext } from '../../types/tool/index.js'
+import type { ToolFacts } from '../../types/tool/presentation.js'
+import { resolveWithinAnyReal, toolRoots } from '../paths.js'
+import { movedSinceRead, staleFileError } from './content-fingerprint.js'
+
+/**
+ * The refusal a file mutation would give for a file that moved on disk since
+ * the session read it, asked before a person is.
+ *
+ * `edit` and `write` refuse such a call when they run. By then the person has
+ * already been shown a change and said yes to it, so the answer is asked here
+ * too, ahead of the review. It looks at the same body the tool will (the host
+ * file, or the sandbox's) and says nothing when it cannot tell: a path that is
+ * missing or outside the roots, an unreadable file, or a session that never
+ * read the path. Those keep their own answers at run time.
+ */
+export async function staleBeforeReview(
+	context: ToolContext,
+	path: string,
+	operation: 'edit' | 'write',
+): Promise<{ readonly error: string; readonly facts: ToolFacts } | undefined> {
+	const tracker = context.fileReadTracker
+	if (!tracker) return undefined
+	let key: string
+	let current: string
+	try {
+		if (context.sandbox) {
+			key = path
+			current = (await context.sandbox.readFile(path)).toString('utf-8')
+		} else {
+			key = await resolveWithinAnyReal(toolRoots(context), path)
+			current = await readFile(key, 'utf-8')
+		}
+	} catch {
+		return undefined
+	}
+	if (!movedSinceRead(tracker, key, current)) return undefined
+	tracker.recordDriftObserved?.(key)
+	return {
+		error: staleFileError(key, operation),
+		facts: { kind: 'failure', reason: 'changed_on_disk', subject: key },
+	}
+}

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

@@ -11,6 +11,7 @@ import { fingerprintContent, staleFileError } from './content-fingerprint.js'
 import { withFileMutationLock } from './file-mutation-lock.js'
 import { fileWriteResult } from './file-write-result.js'
 import { jsonStringEscapes } from './json-string-hint.js'
+import { staleBeforeReview } from './stale-before-review.js'
 
 const inputSchema = z
 	.object({
@@ -94,6 +95,10 @@ export const WriteFileTool = defineTool({
 	// Declared so a path outside the turn's roots can be reviewed before the
 	// call runs, rather than refused after. See `ToolDefinition.pathArgument`.
 	pathArgument: 'path',
+	// An overwrite of a file that moved since the read is refused when it runs,
+	// so the person is not asked to approve one that cannot.
+	refuseBeforeReview: (input: WriteInput, context) =>
+		staleBeforeReview(context, input.path, 'write'),
 	// The classifier judges where a file is written and how much, not the body.
 	classifierInput: (input: WriteInput) => {
 		const body = input.content ?? input.newStr ?? ''

package/src/tools/defineTool.ts

@@ -83,6 +83,8 @@ export interface DefineToolOptions<S extends z.ZodType> {
 	commandDialect?: ToolDefinition['commandDialect']
 	/** The argument holding a filesystem path; see {@link ToolDefinition.pathArgument}. */
 	pathArgument?: string
+	/** A refusal known before any reviewer is asked; see {@link ToolDefinition.refuseBeforeReview}. */
+	refuseBeforeReview?: ToolDefinition<z.infer<S>>['refuseBeforeReview']
 	/** The argument holding a canonical URL; see {@link ToolDefinition.urlArgument}. */
 	urlArgument?: string
 	/** The argument asking to leave the sandbox; see {@link ToolDefinition.sandboxEscapeArgument}. */
@@ -146,6 +148,7 @@ export function defineTool<S extends z.ZodType>(
 		...(options.commandArgument !== undefined ? { commandArgument: options.commandArgument } : {}),
 		...(options.commandDialect !== undefined ? { commandDialect: options.commandDialect } : {}),
 		...(options.pathArgument !== undefined ? { pathArgument: options.pathArgument } : {}),
+		...(options.refuseBeforeReview ? { refuseBeforeReview: options.refuseBeforeReview } : {}),
 		...(options.urlArgument !== undefined ? { urlArgument: options.urlArgument } : {}),
 		...(options.sandboxEscapeArgument !== undefined
 			? { sandboxEscapeArgument: options.sandboxEscapeArgument }

package/src/types/tool/index.ts

@@ -1050,6 +1050,24 @@ export interface ToolDefinition<TInput = unknown> extends ToolPresentation<TInpu
 	 * the safe direction to be wrong in.
 	 */
 	pathArgument?: string
+	/**
+	 * A refusal that needs no person's answer: the call cannot run as it stands,
+	 * and the tool can already tell.
+	 *
+	 * Asked once the arguments are valid and BEFORE the call is put to a
+	 * reviewer, so a person is never asked to approve a change that would be
+	 * refused the moment they said yes. A file tool answers here when the file
+	 * moved on disk after the session read it. Returning `undefined` means no
+	 * objection; the call goes on to review and `execute`, which keep their own
+	 * checks, since the state may move again in between. A hook that throws is
+	 * read as no objection too.
+	 */
+	refuseBeforeReview?(
+		input: TInput,
+		context: ToolContext,
+	): Promise<
+		{ readonly error: string; readonly facts?: import('./presentation.js').ToolFacts } | undefined
+	>
 	/**
 	 * The argument that holds an absolute URL the tool has already
 	 * canonicalised in its input schema — one spelling, no whitespace.