@namzu/sdk 49.0.0 → 50.1.0

package/src/tools/builtins/edit.ts

@@ -135,6 +135,38 @@ const inputSchema = z
 
 export type EditInput = z.infer<typeof inputSchema>
 
+/**
+ * What an `edit` call WOULD produce for a file body, without touching any file.
+ *
+ * The same schema, the same normalisation and the same `applyEdit` fold that
+ * `execute` runs, so a host that shows a proposed change before approval is
+ * showing what the tool will do, not a second reading of the arguments. Pure:
+ * the caller supplies the current body (and decides what to do when there is no
+ * file). The no-op refusal is repeated because a call `execute` would refuse
+ * has no change to preview.
+ */
+export function dryRunEdit(
+	content: string,
+	input: unknown,
+): { success: true; content: string } | { success: false; error: string } {
+	const parsed = inputSchema.safeParse(input)
+	if (!parsed.success) {
+		return { success: false, error: parsed.error.issues.map((issue) => issue.message).join('; ') }
+	}
+	const normalized = normalizeEditInput(parsed.data)
+	if (!normalized.success) return normalized
+	if (
+		normalized.operations.some(
+			(operation) =>
+				operation.operation === 'replace' && operation.oldString === operation.newString,
+		)
+	) {
+		return { success: false, error: 'old_string and new_string are identical — no change needed' }
+	}
+	const result = applyEdit(content, normalized.operations)
+	return result.success ? { success: true, content: result.content } : result
+}
+
 /**
  * What a capable provider constrains the model to emit: one shape, closed.
  *
@@ -181,11 +213,22 @@ const modelInputSchema: Record<string, unknown> = {
 			// The two branches are disjoint, so `anyOf` and `oneOf` mean the
 			// same thing here — nothing is loosened.
 			//
+			// Every branch carries a `type`. The strict subset does not let a
+			// branch be a bare `{ const: 'end' }`: a validator answers
+			// `Invalid schema for function 'edit': In context=('properties',
+			// 'insertLine', 'anyOf', '1'), schema must have a 'type' key` and
+			// refuses the WHOLE request, so the tool never mounts and the turn
+			// dies before a single token. Stating `{ type: 'string', const:
+			// 'end' }` says the same thing — `"end"` is still the only string
+			// the branch admits — and satisfies the subset. Observed on the
+			// Zen free-tier gateway, which enforces `strict` on every model
+			// that reaches it.
+			//
 			// `minimum` is gone for the same reason: numeric constraints are
 			// outside the strict subset too. The bound is not lost — the
 			// execution schema still enforces it, which is where a value that
 			// crosses a boundary should be checked anyway.
-			anyOf: [{ type: 'integer' }, { const: 'end' }],
+			anyOf: [{ type: 'integer' }, { type: 'string', const: 'end' }],
 			description:
 				'Insert instead of replacing. The new_string goes after this 1-indexed line; 0 inserts before the first line; "end" appends. Omit for a find-and-replace.',
 		},
@@ -412,6 +455,11 @@ export const EditTool = defineTool({
 					success: true as const,
 					output: `Edited ${parsed.data.path}: ${result.replacements} replacement(s) [sandboxed]`,
 					data: { path: parsed.data.path, replacements: result.replacements, sandboxed: true },
+					facts: {
+						kind: 'edit' as const,
+						path: parsed.data.path,
+						replacements: result.replacements,
+					},
 				}
 			}
 
@@ -438,6 +486,11 @@ export const EditTool = defineTool({
 				success: true as const,
 				output: `Edited ${hostPath}: ${result.replacements} replacement(s)`,
 				data: { path: hostPath, replacements: result.replacements },
+				facts: {
+					kind: 'edit' as const,
+					path: hostPath,
+					replacements: result.replacements,
+				},
 			}
 		})
 	},

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

@@ -59,6 +59,20 @@ export function fileWriteResult(
 	return {
 		success: true,
 		output: `${summary} · ${bytes} bytes`,
+		facts: {
+			kind: 'write',
+			path,
+			operation:
+				operation === 'create'
+					? 'created'
+					: operation === 'replace'
+						? 'updated'
+						: operation === 'unchanged'
+							? 'unchanged'
+							: 'wrote',
+			bytes,
+			...(before === null ? {} : { added: added.length, removed: removed.length }),
+		},
 		data: {
 			path,
 			size: after.length,

package/src/tools/builtins/glob.ts

@@ -77,6 +77,11 @@ export const GlobTool = defineTool({
 			label: `Find ${input.pattern} in ${input.path ?? '.'}`,
 			presentation: 'activity',
 			activity: 'exploration',
+			facts: {
+				kind: 'list',
+				pattern: input.pattern,
+				...(input.path !== undefined ? { path: input.path } : {}),
+			},
 		}
 	},
 
@@ -142,6 +147,13 @@ export const GlobTool = defineTool({
 				[...files.map(displayPath), ...(notice ? [notice] : [])].join('\n') ||
 				`No files found matching pattern "${input.pattern}" in ${root}`,
 			data: { count: files.length, files, truncated, ...(sandbox ? { sandboxed: true } : {}) },
+			facts: {
+				kind: 'list',
+				pattern: input.pattern,
+				...(input.path !== undefined ? { path: input.path } : {}),
+				count: files.length,
+				truncated,
+			},
 			...(failure ? { error: failure } : {}),
 		}
 	},

package/src/tools/builtins/grep.ts

@@ -109,6 +109,11 @@ export const GrepTool = defineTool({
 			label: `Search ${input.pattern} in ${input.path ?? '.'}`,
 			presentation: 'activity',
 			activity: 'exploration',
+			facts: {
+				kind: 'search',
+				pattern: input.pattern,
+				...(input.path !== undefined ? { path: input.path } : {}),
+			},
 		}
 	},
 	timeoutMs: 15_000,
@@ -265,6 +270,15 @@ export const GrepTool = defineTool({
 			success: failure === undefined,
 			output: [results.join('\n'), summary, notice].filter(Boolean).join('\n\n'),
 			data: { totalMatches, filesSearched, filesMatched, truncated },
+			facts: {
+				kind: 'search',
+				pattern: input.pattern,
+				...(input.path !== undefined ? { path: input.path } : {}),
+				matches: totalMatches,
+				filesMatched,
+				filesSearched,
+				truncated,
+			},
 			...(failure ? { error: failure } : {}),
 		}
 	},

package/src/tools/builtins/index.ts

@@ -25,6 +25,8 @@ export { RUN_CODE_TOOL_NAME, buildRunCodeTool } from './run-code.js'
 export { LsTool } from './ls.js'
 export { SearchToolsTool } from './search-tools.js'
 export { VerifyOutputsTool } from './verify-outputs.js'
+export { ViewImageTool, createViewImageTool } from './view-image.js'
+export type { ViewImageToolOptions } from './view-image.js'
 export { createStructuredOutputTool, STRUCTURED_OUTPUT_TOOL_NAME } from './structuredOutput.js'
 export { createComputerUseTool, COMPUTER_USE_TOOL_NAME } from './computer-use.js'
 

package/src/tools/builtins/job.ts

@@ -113,7 +113,9 @@ export const JobTool = defineTool({
 			const status =
 				read.status === 'running'
 					? 'still running'
-					: `${read.status}${read.exitCode === undefined ? '' : ` with code ${read.exitCode}`}`
+					: read.error !== undefined
+						? `failed to start: ${read.error}`
+						: `${read.status}${read.exitCode === undefined ? '' : ` with code ${read.exitCode}`}`
 
 			return {
 				success: true,
@@ -124,6 +126,7 @@ export const JobTool = defineTool({
 					nextOffset: read.nextOffset,
 					droppedBytes: read.droppedBytes,
 					...(read.exitCode === undefined ? {} : { exitCode: read.exitCode }),
+					...(read.error === undefined ? {} : { error: read.error }),
 				},
 			}
 		} catch (err) {

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

@@ -2,8 +2,10 @@ import { readFile } from 'node:fs/promises'
 import { extname } from 'node:path'
 import { z } from 'zod'
 import type { ToolContext } from '../../types/tool/index.js'
+import type { ToolFacts } from '../../types/tool/presentation.js'
 import { defineTool } from '../defineTool.js'
 import { resolveWithinAnyReal, toolRoots } from '../paths.js'
+import { looksBinary } from '../text-window.js'
 import { fingerprintContent } from './content-fingerprint.js'
 import { type RenderedRead, renderNumberedRead } from './read-render.js'
 
@@ -55,6 +57,7 @@ export const ReadFileTool = defineTool({
 			label: `Read ${input.path}`,
 			presentation: 'activity',
 			activity: 'exploration',
+			facts: { kind: 'read', path: input.path },
 		}
 	},
 
@@ -72,6 +75,12 @@ export const ReadFileTool = defineTool({
 						sandboxed: true,
 						binary: true,
 					},
+					facts: {
+						kind: 'read',
+						path: input.path,
+						binary: true,
+						bytes: buffer.length,
+					},
 				}
 			}
 			const content = buffer.toString('utf-8')
@@ -88,6 +97,7 @@ export const ReadFileTool = defineTool({
 					path: input.path,
 					sandboxed: true,
 				},
+				facts: readFacts(input.path, buffer, content, rendered),
 			}
 		}
 
@@ -102,6 +112,12 @@ export const ReadFileTool = defineTool({
 					path: filePath,
 					binary: true,
 				},
+				facts: {
+					kind: 'read',
+					path: filePath,
+					binary: true,
+					bytes: buffer.length,
+				},
 			}
 		}
 		const content = buffer.toString('utf-8')
@@ -117,10 +133,37 @@ export const ReadFileTool = defineTool({
 				truncated: rendered.partial,
 				path: filePath,
 			},
+			facts: readFacts(filePath, buffer, content, rendered),
 		}
 	},
 })
 
+/**
+ * What a read returned, as fields. A file that is not text is named as such,
+ * so a host says "Binary file, 4 KB" instead of drawing the bytes the model's
+ * numbered rendering contains.
+ */
+function readFacts(
+	path: string,
+	buffer: Buffer,
+	content: string,
+	rendered: RenderedRead,
+): ToolFacts {
+	return {
+		kind: 'read',
+		path,
+		bytes: buffer.length,
+		...(looksBinary(content) ? { binary: true } : {}),
+		// A final newline ends a line; it does not start another.
+		totalLines: content.endsWith('\n') ? rendered.totalLines - 1 : rendered.totalLines,
+		returnedLines:
+			content.endsWith('\n') && !rendered.partial
+				? rendered.returnedLines - 1
+				: rendered.returnedLines,
+		...(rendered.partial ? { partial: true } : {}),
+	}
+}
+
 /**
  * Put this read on the observation ledger.
  *
@@ -153,6 +196,20 @@ function recordObservedRead(
 
 function describeStructuredBinaryRead(path: string, buffer: Buffer): string | null {
 	const ext = extname(path).toLowerCase()
+	const image = buffer.subarray(0, 8).equals(Buffer.from('89504e470d0a1a0a', 'hex'))
+		? 'PNG'
+		: buffer[0] === 0xff && buffer[1] === 0xd8
+			? 'JPEG'
+			: buffer.toString('ascii', 0, 4) === 'RIFF' && buffer.toString('ascii', 8, 12) === 'WEBP'
+				? 'WebP'
+				: null
+	if (image) {
+		return [
+			`The file "${path}" is a ${image} raster image, not UTF-8 text.`,
+			'Use an available view_image tool with this path to inspect the actual pixels. Reading binary bytes as text does not provide visual evidence.',
+			'If image inspection is unavailable, open the file in an application and use an available screenshot tool; report the limitation if neither can show the image.',
+		].join('\n')
+	}
 	if (ext === '.docx') return buildStructuredBinaryGuidance(path, 'DOCX', 'python-docx')
 	if (ext === '.pptx') return buildStructuredBinaryGuidance(path, 'PPTX', 'python-pptx')
 	if (ext === '.xlsx') return buildStructuredBinaryGuidance(path, 'XLSX', 'openpyxl')