@namzu/sdk 38.2.1 → 40.0.0

package/src/tools/builtins/edit.ts

@@ -1,11 +1,12 @@
 import { readFile } from 'node:fs/promises'
 
 import { z } from 'zod'
-import type { ToolResult } from '../../types/tool/index.js'
+import type { ToolContext, ToolResult } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
 import { resolveWithinAnyReal, toolRoots } from '../paths.js'
 import { atomicWriteFile } from './atomic-write-file.js'
 import { fingerprintContent, staleFileError } from './content-fingerprint.js'
+import { applyEdit, normalizeEditInput } from './edit-apply.js'
 import { withFileMutationLock } from './file-mutation-lock.js'
 
 /**
@@ -131,7 +132,7 @@ const inputSchema = z
 		},
 	)
 
-type EditInput = z.infer<typeof inputSchema>
+export type EditInput = z.infer<typeof inputSchema>
 
 /**
  * What a capable provider constrains the model to emit: one shape, closed.
@@ -244,19 +245,38 @@ const modelInputSchema: Record<string, unknown> = {
 	additionalProperties: false,
 }
 
-type NormalizedEditInput =
-	| {
-			operation: 'replace'
-			oldString: string
-			newString: string
-			replace_all: boolean
-	  }
-	| {
-			operation: 'insert'
-			insertLine: number | 'end'
-			newString: string
-			replace_all: boolean
-	  }
+/**
+ * Advance the ledger to the body this edit just wrote.
+ *
+ * `recordEdit` where the host's tracker offers it, so the observation carries
+ * the call that produced it and the path keeps a chain back to the write it
+ * started from; `recordRead` otherwise, which is exactly what this line did
+ * before chains existed — and what it still does when no call id is in hand,
+ * since a hop nobody can name is a hop nobody can replay. Both advance the
+ * fingerprint, which is what the next mutation's drift check reads.
+ */
+function recordEditedContent(context: ToolContext, key: string, content: string): void {
+	const tracker = context.fileReadTracker
+	if (!tracker) return
+	if (tracker.recordEdit && context.toolUseId) {
+		tracker.recordEdit(key, content, context.toolUseId)
+		return
+	}
+	tracker.recordRead(key, content)
+}
+
+/**
+ * Tell the ledger the path it holds is behind the disk, on the way out.
+ *
+ * This branch has just read the real file and found it moved, which is the
+ * one moment a reader with no filesystem of its own can learn that for free.
+ * The flag carries no body: recording what was found here would re-baseline
+ * the comparison directly above and admit the mutation it is refusing. It is
+ * optional on the interface, so a tracker without it keeps today's behavior.
+ */
+function recordDrift(context: ToolContext, key: string): void {
+	context.fileReadTracker?.recordDriftObserved?.(key)
+}
 
 export const EditTool = defineTool({
 	name: 'edit',
@@ -365,6 +385,7 @@ export const EditTool = defineTool({
 				const content = buffer.toString('utf-8')
 				const seen = context.fileReadTracker?.fingerprint?.(parsed.data.path)
 				if (seen !== undefined && seen !== fingerprintContent(content)) {
+					recordDrift(context, parsed.data.path)
 					return { success: false as const, output: '', error: staleFileError(parsed.data.path) }
 				}
 				const result = applyEdit(content, normalized.operations)
@@ -373,7 +394,7 @@ export const EditTool = defineTool({
 				}
 
 				await context.sandbox.writeFile(parsed.data.path, result.content)
-				context.fileReadTracker?.recordRead(parsed.data.path, result.content)
+				recordEditedContent(context, parsed.data.path, result.content)
 				return {
 					success: true as const,
 					output: `Edited ${parsed.data.path}: ${result.replacements} replacement(s) [sandboxed]`,
@@ -386,6 +407,7 @@ export const EditTool = defineTool({
 
 			const seen = context.fileReadTracker?.fingerprint?.(hostPath)
 			if (seen !== undefined && seen !== fingerprintContent(content)) {
+				recordDrift(context, hostPath)
 				return { success: false as const, output: '', error: staleFileError(hostPath) }
 			}
 			const result = applyEdit(content, normalized.operations)
@@ -398,7 +420,7 @@ export const EditTool = defineTool({
 			// This runtime is now the last writer, so the next edit in the same
 			// turn compares against what we just wrote rather than the read
 			// before it.
-			context.fileReadTracker?.recordRead(hostPath, result.content)
+			recordEditedContent(context, hostPath, result.content)
 			return {
 				success: true as const,
 				output: `Edited ${hostPath}: ${result.replacements} replacement(s)`,
@@ -407,256 +429,3 @@ export const EditTool = defineTool({
 		})
 	},
 })
-
-/**
- * Turn one call into the ordered list of operations it stands for.
- *
- * A list rather than a single operation because the batch shape is not a
- * different kind of edit, only a longer one. Keeping ONE representation is
- * what stops the two shapes diverging: everything below this function — the
- * uniqueness check, the CRLF reconciliation, the identical-text refusal, the
- * atomic write — sees a list of length one for a single edit and never learns
- * which shape the caller used.
- */
-function normalizeEditInput(
-	input: EditInput,
-): { success: true; operations: NormalizedEditInput[] } | { success: false; error: string } {
-	if (input.edits !== undefined) {
-		return {
-			success: true,
-			operations: input.edits.map((edit) => ({
-				operation: 'replace' as const,
-				oldString: edit.old_string,
-				newString: edit.new_string,
-				replace_all: edit.replace_all ?? false,
-			})),
-		}
-	}
-
-	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
-		return {
-			success: true,
-			operations: [
-				{
-					operation: 'insert',
-					insertLine: insertLine.value,
-					newString,
-					replace_all: input.replace_all ?? false,
-				},
-			],
-		}
-	}
-
-	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,
-		operations: [
-			{
-				operation: 'replace',
-				oldString,
-				newString,
-				replace_all: input.replace_all ?? false,
-			},
-		],
-	}
-}
-
-/**
- * Spellings of "the end of the file" a model reaches for.
- *
- * Liberal here and strict in the schema, which is the right way round: the
- * schema makes `"end"` the only emittable string for a provider that
- * constrains, and this catches the rest for one that does not. None of these
- * is ambiguous — accepting them is not guessing at intent, it is declining to
- * spend a round trip on a synonym.
- */
-const END_ALIASES = new Set(['end', 'eof', 'append', 'last', 'end_of_file', 'end-of-file'])
-
-function normalizeInsertLine(
-	value: string | number,
-): { success: true; value: number | 'end' } | { success: false; error: string } {
-	if (typeof value === 'string') {
-		const normalized = value.trim().toLowerCase()
-		// `"end"` is the only spelling the model-facing schema admits, so a
-		// constrained decoder cannot produce anything else. These aliases are
-		// for the providers that do not constrain: a model reading "appends to
-		// the file" reaches for the word it knows, and every one of these says
-		// the same unambiguous thing. Refusing them bought strictness and cost
-		// a full model round trip per occurrence — measured by a consuming host
-		// as the single largest source of tool-call waste in its runs.
-		if (END_ALIASES.has(normalized)) return { success: true, value: 'end' }
-		const parsed = Number(value)
-		if (Number.isInteger(parsed) && parsed >= 0) return { success: true, value: parsed }
-		return {
-			success: false,
-			error: `insertLine must be a non-negative line number or "end" (also accepted: ${[...END_ALIASES].filter((a) => a !== 'end').join(', ')}). Received ${JSON.stringify(value)}.`,
-		}
-	}
-	return { success: true, value }
-}
-
-/**
- * Apply every operation in order, or none of them.
- *
- * "Or none" is the whole reason this takes a list. Four related changes sent
- * as four calls are four chances to stop halfway, and the file left behind
- * after the third succeeded and the fourth did not is in a state no one wrote
- * and no one is looking at. Here the fold runs entirely in memory and the
- * caller writes once, so a failure anywhere leaves the file exactly as it was.
- *
- * Each operation matches against the content as the ones before it left it,
- * not against the original. That is what lets a later edit target text an
- * earlier one produced — and it is also why a failure names the INDEX: by the
- * time hunk 3 fails, the string it was looking for may have been consumed by
- * hunk 1, and "old_string not found" without a position sends the model to
- * re-check the wrong hunk.
- */
-function applyEdit(
-	content: string,
-	operations: readonly NormalizedEditInput[],
-): { success: true; content: string; replacements: number } | { success: false; error: string } {
-	let current = content
-	let replacements = 0
-
-	for (const [index, operation] of operations.entries()) {
-		const result = applyOne(current, operation)
-		if (!result.success) {
-			return {
-				success: false,
-				error:
-					operations.length === 1
-						? result.error
-						: `edits[${index}] of ${operations.length}: ${result.error} Nothing was written — the whole batch is refused, so the file is exactly as it was.`,
-			}
-		}
-		current = result.content
-		replacements += result.replacements
-	}
-
-	return { success: true, content: current, replacements }
-}
-
-function applyOne(
-	content: string,
-	input: NormalizedEditInput,
-): { success: true; content: string; replacements: number } | { success: false; error: string } {
-	if (input.operation === 'insert') {
-		return applyLineInsert(content, input)
-	}
-
-	const replacement = normalizeLineEndings(content, input)
-
-	if (!content.includes(replacement.oldString)) {
-		return {
-			success: false,
-			error:
-				'old_string/oldStr not found in file. Make sure the string matches exactly, including whitespace and indentation.',
-		}
-	}
-
-	if (replacement.replace_all) {
-		const parts = content.split(replacement.oldString)
-		const replacements = parts.length - 1
-		return {
-			success: true,
-			content: parts.join(replacement.newString),
-			replacements,
-		}
-	}
-
-	// Uniqueness check: old_string/oldStr must appear exactly once
-	const firstIndex = content.indexOf(replacement.oldString)
-	const secondIndex = content.indexOf(replacement.oldString, firstIndex + 1)
-
-	if (secondIndex !== -1) {
-		const lineNumber = 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.`,
-		}
-	}
-
-	return {
-		success: true,
-		content:
-			content.slice(0, firstIndex) +
-			replacement.newString +
-			content.slice(firstIndex + replacement.oldString.length),
-		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,
-	}
-}
-
-/**
- * Reconcile the caller's line endings with the file's.
- *
- * A model reading a CRLF file and writing back LF (or the reverse) produces
- * an `old_string` that is correct in every visible way and matches nothing.
- * The failure reads as "your text is wrong" when the text is right and only
- * the invisible half of each line break differs.
- *
- * Only applied when the file is CONSISTENT. A mixed-ending file has no
- * single right answer, and rewriting boundaries there would corrupt the
- * half that was already correct.
- */
-function normalizeLineEndings(
-	content: string,
-	input: Extract<NormalizedEditInput, { operation: 'replace' }>,
-): Extract<NormalizedEditInput, { operation: 'replace' }> {
-	const withoutCrlf = content.replaceAll('\r\n', '')
-	const usesOnlyCrlf = content.includes('\r\n') && !withoutCrlf.includes('\n')
-	if (usesOnlyCrlf) {
-		return {
-			...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 usesOnlyLf = content.includes('\n') && !content.includes('\r\n')
-	if (usesOnlyLf) {
-		return {
-			...input,
-			oldString: content.includes(input.oldString)
-				? input.oldString
-				: input.oldString.replaceAll('\r\n', '\n'),
-			newString: input.newString.replaceAll('\r\n', '\n'),
-		}
-	}
-	return input
-}

package/src/tools/builtins/index.ts

@@ -6,6 +6,7 @@ export { GlobTool } from './glob.js'
 export { LSP_TOOL_NAME, LspTool, getCodeNavigationTools } from './lsp.js'
 export { GrepTool } from './grep.js'
 export { JobTool } from './job.js'
+export { WaitForJobTool } from './wait-for-job.js'
 export { SKILL_TOOL_NAME, SkillTool, parseAllowedTools } from './skill.js'
 export {
 	WEB_FETCH_TOOL_NAME,
@@ -29,6 +30,7 @@ import { GrepTool } from './grep.js'
 import { JobTool } from './job.js'
 import { ReadFileTool } from './read-file.js'
 import { VerifyOutputsTool } from './verify-outputs.js'
+import { WaitForJobTool } from './wait-for-job.js'
 import { WriteFileTool } from './write-file.js'
 // Note: createStructuredOutputTool is not included in getBuiltinTools()
 // because it requires a schema parameter and is created per-use case.
@@ -46,10 +48,13 @@ export function getBuiltinTools(): ToolDefinition[] {
 	// `job` ships alongside `bash` rather than being opt-in, because the two
 	// are one capability. `bash run_in_background` returns an id, and an id
 	// with no tool that reads it is the exact shape of the suggestion that
-	// was removed from bash's schema for being unbacked.
+	// was removed from bash's schema for being unbacked. `wait_for_job`
+	// ships with it for the same reason `job` does: a job with nothing that
+	// can block on it is a suggestion with the same missing half.
 	//
-	// It costs nothing where the host provides no registry: the tool refuses
-	// and says so, which is a truthful answer rather than a missing one.
+	// It costs nothing where the host provides no registry: both tools
+	// refuse and say so, which is a truthful answer rather than a missing
+	// one.
 	return [
 		BashTool,
 		EditTool,
@@ -58,6 +63,7 @@ export function getBuiltinTools(): ToolDefinition[] {
 		JobTool,
 		ReadFileTool,
 		VerifyOutputsTool,
+		WaitForJobTool,
 		WriteFileTool,
 	]
 }

package/src/tools/builtins/job.ts

@@ -43,15 +43,14 @@ type JobInput = z.infer<typeof inputSchema>
 export const JobTool = defineTool({
 	name: 'job',
 	description:
-		'Reads, lists and stops background jobs started by bash with run_in_background. Poll a job with action "read", passing the previous call\'s next_offset to see only new output.',
+		'Reads, lists and stops background jobs started by bash with run_in_background. Do NOT call action "read" in a loop to find out whether a job finished: use wait_for_job instead — it blocks until the job ends (or goes quiet, or runs long) and returns the output in one call, with no waiting turns spent checking. Use "read" to see output while a job keeps running, or to pick up after a wait_for_job call gave up, passing the previous call\'s next_offset to see only new output.',
 	inputSchema,
 	category: 'shell',
 	permissions: ['shell_execute'],
-	// `read` and `list` observe; `kill` stops work. The tool as a whole is not
-	// read-only, and claiming otherwise would let a read-only permission
-	// preset hand the model a way to terminate a running process.
-	readOnly: false,
-	destructive: (input: JobInput) => input.action === 'kill',
+	// The static permission describes the full capability. The prepared action
+	// determines whether this call only observes its owner-bound registry.
+	readOnly: (input: JobInput) => input?.action === 'read' || input?.action === 'list',
+	destructive: (input: JobInput) => input?.action === 'kill',
 	concurrencySafe: true,
 
 	presentCall(input) {

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

@@ -1,13 +1,26 @@
 import { readFile } from 'node:fs/promises'
 import { extname } from 'node:path'
 import { z } from 'zod'
+import type { ToolContext } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
 import { resolveWithinAnyReal, toolRoots } from '../paths.js'
+import { fingerprintContent } from './content-fingerprint.js'
+import { type RenderedRead, renderNumberedRead } from './read-render.js'
 
 const inputSchema = z.object({
 	path: z.string().describe('Path to the file to read (absolute or relative)'),
+	// A two-element ARRAY, not a `z.tuple`, and the distinction is the whole
+	// reason this comment exists. Both members carry the identical constraint,
+	// so the tuple bought nothing — and it rendered as the draft-07 tuple
+	// `items: [a, b]`, which a wire that validates against JSON Schema 2020-12
+	// refuses outright. It was the only tuple in the first-party tool surface,
+	// and it took down every other tool in the same request with it. The
+	// spelling below means the same thing to the model (`[10, 40]` either way)
+	// and to the parser, and reads identically in both dialects. See
+	// `registry/tool/portable.ts`.
 	readRange: z
-		.tuple([z.coerce.number().int().min(1), z.coerce.number().int().min(1)])
+		.array(z.coerce.number().int().min(1))
+		.length(2)
 		.optional()
 		.describe(
 			'Optional 1-indexed inclusive line range, e.g. [10, 40]. When provided it takes precedence over offset/limit.',
@@ -59,26 +72,16 @@ export const ReadFileTool = defineTool({
 				}
 			}
 			const content = buffer.toString('utf-8')
-			const lines = content.split('\n')
+			const rendered = renderNumberedRead(content, input)
+			recordObservedRead(context, input.path, content, rendered)
 
-			const { start, end } = resolveReadWindow(input, lines.length)
-			const selectedLines = lines.slice(start, end)
-
-			const numberedLines = selectedLines.map((line, i) => `${start + i + 1}\t${line}`).join('\n')
-
-			// The WHOLE body, not the selected window: a later edit is checked
-			// against the file, and a partial read must not fingerprint a
-			// fragment as if it were the file.
-			context.fileReadTracker?.recordRead(input.path, content)
-
-			const partial = selectedLines.length < lines.length
 			return {
 				success: true,
-				output: numberedLines + partialViewNotice(start, selectedLines.length, lines.length),
+				output: rendered.output,
 				data: {
-					totalLines: lines.length,
-					returnedLines: selectedLines.length,
-					truncated: partial,
+					totalLines: rendered.totalLines,
+					returnedLines: rendered.returnedLines,
+					truncated: rendered.partial,
 					path: input.path,
 					sandboxed: true,
 				},
@@ -99,30 +102,52 @@ export const ReadFileTool = defineTool({
 			}
 		}
 		const content = buffer.toString('utf-8')
-		const lines = content.split('\n')
-
-		const { start, end } = resolveReadWindow(input, lines.length)
-		const selectedLines = lines.slice(start, end)
-
-		const numberedLines = selectedLines.map((line, i) => `${start + i + 1}\t${line}`).join('\n')
-
-		context.fileReadTracker?.recordRead(filePath, content)
-
-		const isPartial = selectedLines.length < lines.length
+		const rendered = renderNumberedRead(content, input)
+		recordObservedRead(context, filePath, content, rendered)
 
 		return {
 			success: true,
-			output: numberedLines + partialViewNotice(start, selectedLines.length, lines.length),
+			output: rendered.output,
 			data: {
-				totalLines: lines.length,
-				returnedLines: selectedLines.length,
-				truncated: isPartial,
+				totalLines: rendered.totalLines,
+				returnedLines: rendered.returnedLines,
+				truncated: rendered.partial,
 				path: filePath,
 			},
 		}
 	},
 })
 
+/**
+ * Put this read on the observation ledger.
+ *
+ * Always the WHOLE body, not the selected window: a later edit is checked
+ * against the file, and a partial read must not fingerprint a fragment as if it
+ * were the file.
+ *
+ * A read that returned the file whole additionally witnesses itself, so the
+ * derived work context can reference the body without the model reading it
+ * again. The witness is the fingerprint of the RENDERING — this call's own
+ * `output`, byte for byte — because the rendering is what the receipt carries,
+ * and the body is in front of the model only while the receipt is still exactly
+ * that. A read whose window left any of the file out witnesses nothing: it
+ * shows a fragment, and the fingerprint of the file cannot say which one.
+ */
+function recordObservedRead(
+	context: ToolContext,
+	key: string,
+	content: string,
+	rendered: RenderedRead,
+): void {
+	const tracker = context.fileReadTracker
+	if (!tracker) return
+	if (!rendered.partial && tracker.recordFullRead && context.toolUseId) {
+		tracker.recordFullRead(key, content, context.toolUseId, fingerprintContent(rendered.output))
+		return
+	}
+	tracker.recordRead(key, content)
+}
+
 function describeStructuredBinaryRead(path: string, buffer: Buffer): string | null {
 	const ext = extname(path).toLowerCase()
 	if (ext === '.docx') return buildStructuredBinaryGuidance(path, 'DOCX', 'python-docx')
@@ -146,49 +171,3 @@ function buildStructuredBinaryGuidance(path: string, format: string, extractor:
 		'If extraction fails, report the exact filename and extraction error instead of claiming the attachment is unavailable.',
 	].join('\n')
 }
-
-/**
- * Lines returned when the caller specifies no window.
- *
- * Chosen to cover the overwhelming majority of source files whole while
- * bounding the pathological case.
- */
-const DEFAULT_READ_LINES = 2000
-
-/**
- * Tell the model, explicitly, when it is looking at a window rather than
- * the file.
- *
- * Without this a truncated read is indistinguishable from a short file, and
- * the agent reasons about a fragment as if it were the whole thing — the
- * most expensive silent failure a read tool can have. The notice names the
- * exact next call rather than describing it.
- */
-function partialViewNotice(start: number, returned: number, total: number): string {
-	if (returned >= total) return ''
-	const shownTo = start + returned
-	return [
-		'',
-		'',
-		`[PARTIAL view — lines ${start + 1}-${shownTo} of ${total}.`,
-		`Continue with read({ offset: ${shownTo}, limit: N }), or narrow with grep.]`,
-	].join('\n')
-}
-
-function resolveReadWindow(
-	input: z.infer<typeof inputSchema>,
-	totalLines: number,
-): { start: number; end: number } {
-	if (input.readRange) {
-		const [first, last] = input.readRange
-		const start = Math.max(0, first - 1)
-		const end = Math.min(totalLines, Math.max(start, last))
-		return { start, end }
-	}
-	const start = Math.max(0, input.offset ?? 0)
-	// A bare `read({ path })` used to return the entire file, so a 2 MB
-	// lockfile became ~500k tokens in one tool_result. Default to a window
-	// and say so in the output; the model asks for more when it needs it.
-	const end = input.limit ? start + input.limit : Math.min(totalLines, start + DEFAULT_READ_LINES)
-	return { start, end }
-}