@namzu/sdk 55.1.0 → 56.0.1

package/src/runtime/query/file-evidence-replay.ts

@@ -716,17 +716,20 @@ function observeRead(
  * compared, which is also what makes the figure above exact.
  */
 function wholeFileRenderUnits(body: string, window: ReadWindowRequest): number | undefined {
+	if (body === '') return undefined
 	const lines = countLines(body)
 	const { start, end } = resolveReadWindow(window, lines)
 	if (start !== 0 || end < lines) return undefined
-	return body.length + lines + lineNumberUnits(lines)
+	// The rendering numbers each line and joins them, so a final newline is not
+	// a row of its own and is not carried as a trailing separator.
+	return body.length - (body.endsWith('\n') ? 1 : 0) + lines + lineNumberUnits(lines)
 }
 
-/** Lines the way `String.split('\n')` counts them, without building the array. */
+/** Lines the way a read counts them, without building the array: a final newline ends a line. */
 function countLines(body: string): number {
 	let lines = 1
 	for (let at = body.indexOf('\n'); at !== -1; at = body.indexOf('\n', at + 1)) lines++
-	return lines
+	return body.endsWith('\n') ? lines - 1 : lines
 }
 
 /** Units the line numbers `1..lines` occupy, counted by decade rather than one by one. */

package/src/runtime/query/iteration/index.ts

@@ -28,6 +28,7 @@ import {
 import { getTracer } from '../../../telemetry/runtime-accessors.js'
 import { STRUCTURED_OUTPUT_TOOL_NAME } from '../../../tools/builtins/structuredOutput.js'
 import type { ToolManager } from '../../../toolsets/manager.js'
+import { splitAtEvidenceBlocks } from '../../../turn/evidence-recall.js'
 import type { CostInfo, TokenUsage } from '../../../types/common/index.js'
 import { NamzuError } from '../../../types/errors/index.js'
 import type { MessageId, SessionId, TurnId } from '../../../types/ids/index.js'
@@ -57,6 +58,7 @@ import { createCallbackInference } from '../callback-inference.js'
 import { SandboxAcquisitionStopped } from '../deferred-sandbox.js'
 import { deliverDurableInbound } from '../durable-inbound.js'
 import type { ToolCallOutcome } from '../executor.js'
+import { FILE_EVIDENCE_NONE } from '../file-evidence-context.js'
 import { projectObservationContext } from '../observation-context.js'
 import { applyLifecycleHookResults } from '../plugin-hooks.js'
 import {
@@ -102,14 +104,16 @@ import {
 	streamWithProviderRejectedImageRecovery,
 } from './provider-rejected-image.js'
 import { type MediaRemoval, RequestRepair } from './request-repair.js'
-import { placeBeforeLatestOperatorMessage } from './step-context.js'
+import { TurnContextCarry } from './step-context.js'
 import {
+	FILE_EVIDENCE_KEY,
 	type StepShaping,
 	appendWorkContext,
 	beforeStep,
 	prepareStep,
 	selectContextModel,
 	stepContextMessage,
+	workContextBlocks,
 } from './step-shaping.js'
 import { streamProviderTurn } from './stream-turn.js'
 
@@ -190,6 +194,8 @@ export class IterationOrchestrator {
 	 * one process must not suppress each other's first envelope.
 	 */
 	private lastEnvelopeKey: string | undefined
+	/** Where this turn's request-only data first went, so it stays there. */
+	private readonly turnContext = new TurnContextCarry()
 	private previousRequestContext: RequestContextSnapshot | undefined
 
 	private projectObservations(messages: Message[]): Message[] {
@@ -895,27 +901,35 @@ export class IterationOrchestrator {
 						? [...workingMemory.history, createSystemMessage(stepPreamble)]
 						: [...workingMemory.history]
 					if (workingMemory.context) requestHistory.push(workingMemory.context)
-					// The blocks of data that belong to this turn (recalled memory and
-					// evidence, the context contributions) sit just before the
-					// operator's latest message, so the request is the last thing the
-					// model reads. The short reminders and notices stay after it.
-					placeBeforeLatestOperatorMessage(
-						requestHistory,
-						[contextText, step.context]
-							.filter((text): text is string => Boolean(text))
-							.map(stepContextMessage),
-					)
 					// After the history, never ahead of it: a system message in front
 					// of the conversation moves the prefix every cached request shares,
 					// and a mode change would re-key the whole conversation.
 					if (policyNotice) requestHistory.push(stepContextMessage(policyNotice))
-					const messages = projectRequestRichContent(
+					const projected = projectRequestRichContent(
 						this.projectObservations(requestHistory),
 						this.ctx.turnConfig.maxRequestRichContentBytes ??
 							DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES,
 						{ imagesReadable: this.modelReadsImages(stepModel) },
 					)
-					appendWorkContext(shaping, messages, iterationNum, step)
+					// The blocks of data that belong to this turn (recalled memory and
+					// evidence, the context contributions, the work context) sit just
+					// before the operator's latest message the first time the model
+					// answers it, so the request is the last thing it reads. They stay
+					// there on every later call of the turn, and a block that first
+					// appears on a later call follows the history of that moment, so each
+					// request begins with the whole of the one before it. The short
+					// reminders and notices stay after the history.
+					const messages = [...projected]
+					this.turnContext.place(
+						messages,
+						requestHistory,
+						workingMemory.history.at(-1),
+						[contextText, ...(step.context ? splitAtEvidenceBlocks(step.context) : [])]
+							.filter((text): text is string => Boolean(text))
+							.map(stepContextMessage),
+						workContextBlocks(shaping, projected, iterationNum, step),
+						{ [FILE_EVIDENCE_KEY]: stepContextMessage(FILE_EVIDENCE_NONE) },
+					)
 					if (closingDirective) messages.push(closingDirective)
 					await this.reportUnsupportedToolResults(messages)
 					yield* this.ctx.drainPending()

package/src/runtime/query/iteration/phases/tool-review.ts

@@ -28,6 +28,7 @@ import {
 	formatMonitorNote,
 	takeNoticeMessage,
 	takeSteeringMessage,
+	takeWithheldEnvNotice,
 } from '../../steering.js'
 import { type IterationContext, awaitDecisionDurably } from './context.js'
 import { PerCallReview } from './per-call-review.js'
@@ -295,6 +296,8 @@ export async function* runToolReview(
 			},
 		)
 		if (monitorNotice) ctx.recorder.pushMessage(monitorNotice)
+		const credentialNotice = takeWithheldEnvNotice(ctx.recorder.messages, batch.observations)
+		if (credentialNotice) ctx.recorder.pushMessage(credentialNotice)
 		if (jobNoticeDelivered) ctx.onJobNoticeDelivered?.()
 		if (monitorNoticeDelivered) ctx.onMonitorNoticeDelivered?.()
 		// The complete tool-result batch is already in history before host policy

package/src/runtime/query/iteration/step-context.ts

@@ -44,3 +44,141 @@ export function placeBeforeLatestOperatorMessage(history: Message[], blocks: rea
 	}
 	history.splice(at, 0, ...blocks)
 }
+
+interface PlacedBlock {
+	readonly text: string
+	/** The operator message this block precedes, or the history message it follows. */
+	at: { readonly before: Message } | { readonly after: Message | undefined }
+}
+
+function textOf(message: Message): string {
+	return typeof message.content === 'string' ? message.content : JSON.stringify(message.content)
+}
+
+/** The operator message the model is about to answer, when there is one. */
+function pendingOperatorMessage(history: readonly Message[]): Message | undefined {
+	for (let i = history.length - 1; i >= 0; i--) {
+		const message = history[i] as Message
+		if (isOperatorUserMessage(message)) return message
+		if (message.role === 'assistant' || message.role === 'tool') return undefined
+	}
+	return undefined
+}
+
+/** A block whose own text says that a later one replaces it, under the name of what it reports. */
+export interface ReplaceableBlock {
+	readonly key: string
+	readonly message: Message
+}
+
+/** How many superseded versions of a replaceable block still go with the latest. */
+export const EARLIER_VERSIONS_KEPT = 2
+
+interface VersionedBlock extends PlacedBlock {
+	readonly message: Message
+}
+
+/**
+ * Where a turn's request-only data sits, so it stays put from call to call.
+ *
+ * What a block says is the step's own business: a block it offers again with
+ * the same text is the same block, and it keeps the place it first had; a
+ * block it no longer offers is withdrawn, so corrected data never lingers.
+ * A block seen for the first time goes before the operator's message when that
+ * message is what the model is answering, and otherwise after the history of
+ * that moment. So the requests of a turn share their opening up to the first
+ * block that changed, and a caching driver keeps reading the same prefix
+ * instead of re-reading the turn from the operator's message on.
+ *
+ * A block that says of itself that a later one replaces it (the file
+ * evidence) is never taken back. When its text changes, the earlier text stays
+ * where it went and the new text follows the history of that moment, which is
+ * how the block itself tells the model to read it; when it stops holding, a
+ * short block says so. Only the latest version and the last
+ * `EARLIER_VERSIONS_KEPT` before it are carried, and an earlier version whose
+ * place a compaction rewrote is dropped, so the stale text stays small. Until
+ * a version is dropped no request of the turn rewrites the one before it.
+ *
+ * One carry per turn. A position whose message has left the history (a
+ * compaction rewrote it) is given up and the block follows the history.
+ */
+export class TurnContextCarry {
+	private placed = new Map<string, PlacedBlock>()
+	private readonly versions = new Map<string, VersionedBlock[]>()
+
+	/**
+	 * Put `blocks` and the `replaceable` ones into `request`, the projected copy
+	 * of `history` (same length and order). `end` is the last message of the
+	 * turn's own history. `retractions` says, per replaceable key, what to
+	 * write when an earlier block of that key no longer holds.
+	 */
+	place(
+		request: Message[],
+		history: readonly Message[],
+		end: Message | undefined,
+		blocks: readonly Message[],
+		replaceable: readonly ReplaceableBlock[] = [],
+		retractions: Readonly<Record<string, Message>> = {},
+	): void {
+		const index = (message: Message | undefined) =>
+			message ? history.lastIndexOf(message) : history.length - 1
+		const operator = pendingOperatorMessage(history)
+		const positionOf = (slot: PlacedBlock) =>
+			'before' in slot.at ? index(slot.at.before) : index(slot.at.after) + 1
+		const anchorOf = (slot: PlacedBlock) => ('before' in slot.at ? slot.at.before : slot.at.after)
+		const next = new Map<string, PlacedBlock>()
+		const inserts: { at: number; message: Message }[] = []
+		for (const message of blocks) {
+			const text = textOf(message)
+			if (next.has(text)) continue
+			let slot: PlacedBlock | undefined = this.placed.get(text)
+			if (slot) {
+				const anchor = anchorOf(slot)
+				if (anchor && index(anchor) < 0) slot = { text, at: { after: end } }
+			} else {
+				slot = { text, at: operator ? { before: operator } : { after: end } }
+			}
+			next.set(text, slot)
+			inserts.push({ at: positionOf(slot), message })
+		}
+		this.placed = next
+
+		const offered = new Map(replaceable.map((block) => [block.key, block.message]))
+		for (const key of new Set([...this.versions.keys(), ...offered.keys()])) {
+			const held = this.versions.get(key) ?? []
+			const wanted = offered.get(key) ?? retractions[key]
+			const last = held.at(-1)
+			if (wanted !== undefined && (last === undefined || last.text !== textOf(wanted)))
+				held.push({
+					text: textOf(wanted),
+					message: wanted,
+					// The first version goes where the other blocks go; a later one
+					// follows the history, after the one it replaces.
+					at: last === undefined && operator ? { before: operator } : { after: end },
+				})
+			// An earlier version whose place a compaction rewrote is given up: the
+			// request is rewritten at that point anyway, and stacking stale copies
+			// at the end would only add bulk. The latest version is never given up.
+			const kept = held.filter((version, i) => {
+				if (i === held.length - 1) return true
+				const anchor = anchorOf(version)
+				return !anchor || index(anchor) >= 0
+			})
+			// Only the latest and a few earlier versions are carried, so a long turn
+			// does not grow by a full copy per change.
+			kept.splice(0, Math.max(0, kept.length - (EARLIER_VERSIONS_KEPT + 1)))
+			this.versions.set(key, kept)
+			for (const version of kept) {
+				const anchor = anchorOf(version)
+				if (anchor && index(anchor) < 0) version.at = { after: end }
+				inserts.push({ at: positionOf(version), message: version.message })
+			}
+		}
+
+		// Back to front, so an earlier position is not shifted by a later one;
+		// blocks at one position keep the order they were offered in.
+		const order = inserts.map((entry, position) => ({ ...entry, position }))
+		order.sort((a, b) => b.at - a.at || b.position - a.position)
+		for (const entry of order) request.splice(entry.at, 0, entry.message)
+	}
+}

package/src/runtime/query/iteration/step-shaping.ts

@@ -20,7 +20,11 @@ import { toErrorMessage } from '../../../utils/error.js'
 import { createCallbackInference } from '../callback-inference.js'
 import { measureContext } from './phases/compaction.js'
 import type { IterationContext } from './phases/index.js'
-import { placeBeforeLatestOperatorMessage, stepContextMessage } from './step-context.js'
+import {
+	type ReplaceableBlock,
+	placeBeforeLatestOperatorMessage,
+	stepContextMessage,
+} from './step-context.js'
 
 /**
  * How the next request is shaped: admission, preparation, and the context
@@ -51,28 +55,50 @@ export function appendWorkContext(
 	stepNumber: number,
 	prepared: PrepareStepResult,
 ): void {
+	// Per-turn data goes in front of the operator's new message while that is
+	// what the model is answering, like the other blocks of request-only data.
+	placeBeforeLatestOperatorMessage(
+		messages,
+		workContextBlocks(shaping, messages, stepNumber, prepared).map((block) => block.message),
+	)
+}
+
+/** What the two work-context blocks report; each tells the model a later one replaces it. */
+export const OWNED_WORK_KEY = 'owned-work'
+export const FILE_EVIDENCE_KEY = 'file-evidence'
+
+/**
+ * The work-context blocks for a request whose projected messages are
+ * `messages`, each under the name of what it reports.
+ */
+export function workContextBlocks(
+	shaping: StepShaping,
+	messages: readonly Message[],
+	stepNumber: number,
+	prepared: PrepareStepResult,
+): ReplaceableBlock[] {
 	const { ctx } = shaping
 
-	const contributions = [
-		ctx.completionInbox?.describeOwnedWork(),
-		ctx.toolExecutor.describeFileEvidence(messages),
-	].filter((content): content is string => Boolean(content))
-	if (contributions.length === 0) return
-	const placed: Message[] = []
+	const contributions = (
+		[
+			[OWNED_WORK_KEY, ctx.completionInbox?.describeOwnedWork()],
+			[FILE_EVIDENCE_KEY, ctx.toolExecutor.describeFileEvidence(messages)],
+		] as [string, string | undefined][]
+	).filter((entry): entry is [string, string] => Boolean(entry[1]))
+	if (contributions.length === 0) return []
+	const placed: ReplaceableBlock[] = []
 	let room = stepContext(shaping, stepNumber, prepared).contextBudget?.remainingTokens ?? 0
 	// Leave room for the actual task; admit whole contributions, never dangling partial references.
-	if (room < 1_500) return
-	for (const content of contributions) {
+	if (room < 1_500) return []
+	for (const [key, content] of contributions) {
 		if (!content || content.length > 8_000) continue
 		const message = stepContextMessage(content)
 		const tokens = estimateMessageTokens(message)
 		if (tokens > Math.min(2_000, room - 1_000)) continue
-		placed.push(message)
+		placed.push({ key, message })
 		room -= tokens
 	}
-	// Per-turn data goes in front of the operator's new message while that is
-	// what the model is answering, like the other blocks of request-only data.
-	placeBeforeLatestOperatorMessage(messages, placed)
+	return placed
 }
 
 export function stepContext(

package/src/runtime/query/review-policy.ts

@@ -128,6 +128,16 @@ export const STRICT_MODE_REFUSAL =
 /** The tools `accept-edits` approves without asking. Everything else prompts. */
 export const ACCEPT_EDITS_TOOLS: ReadonlySet<string> = new Set(['edit', 'write'])
 
+/**
+ * `write` declares every call destructive (its input cannot say whether the
+ * file exists), so the flag cannot be what keeps `accept-edits` from covering
+ * it: a new file and a replaced one are the same kind of edit to that mode.
+ * A path outside the roots, a protected file and a rule's ask still stop it.
+ */
+function isFileWrite(name: string): boolean {
+	return name === 'write'
+}
+
 /**
  * Writes that skip review anyway, in spite of declaring `readOnly: false`.
  *
@@ -1028,7 +1038,15 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 		// through beside it would be approving something it did not show.
 		if (
 			mode === 'accept-edits' &&
-			(await Promise.all(request.toolCalls.map(acceptEditsAllows))).every(Boolean)
+			(
+				await Promise.all(
+					request.toolCalls.map((tc) =>
+						// The mode covers a write although the flag is set; the classifier
+						// still judges one, so only this branch lifts the flag.
+						acceptEditsAllows(isFileWrite(tc.name) ? { ...tc, isDestructive: false } : tc),
+					),
+				)
+			).every(Boolean)
 		) {
 			return { action: 'approve_tools' }
 		}

package/src/runtime/query/steering.ts

@@ -1,3 +1,4 @@
+import { withheldEnvNoticeText } from '../../tools/env-scrub.js'
 import { createRuntimeContextMessage } from '../../types/message/index.js'
 import type { Message, UserMessage } from '../../types/message/index.js'
 import { NOTICE_TAG, frameNotice, readOperatorNotice } from '../../types/message/notice-frame.js'
@@ -377,3 +378,53 @@ export function attachSteering(
 	onDelivered?.(guidance)
 	return next
 }
+
+/**
+ * The count of credential-shaped variables a settled batch's shell results
+ * report as removed, or 0. The count rides in a result's `data`, never in the
+ * text the model reads.
+ */
+function withheldEnvCount(
+	observations: readonly { readonly result: { readonly data?: unknown } }[],
+) {
+	let count = 0
+	for (const { result } of observations) {
+		const data = result.data
+		if (typeof data !== 'object' || data === null) continue
+		const n = (data as { withheldEnv?: unknown }).withheldEnv
+		if (typeof n === 'number' && Number.isInteger(n) && n > count) count = n
+	}
+	return count
+}
+
+/**
+ * The credential notice for a settled tool batch, as a user-role message of its
+ * own, or `undefined` when the batch removed nothing or the conversation
+ * already carries this very notice. It is sent once, and again only when the
+ * number of removed variables changes, so a run of failing commands does not
+ * repeat it. The conversation is the record, so a resumed or compacted one
+ * needs no counter of its own.
+ */
+export function takeWithheldEnvNotice(
+	history: readonly Message[],
+	observations: readonly { readonly result: { readonly data?: unknown } }[],
+): UserMessage | undefined {
+	const count = withheldEnvCount(observations)
+	if (count === 0) return undefined
+	const body = withheldEnvNoticeText(count)
+	const said = history.some(
+		(message) =>
+			message.role === 'user' &&
+			message.source?.type === 'runtime-context' &&
+			message.source.kind === 'reminder' &&
+			typeof message.content === 'string' &&
+			message.content.startsWith(`<${NOTICE_TAG}-`) &&
+			message.content.includes(' kind="credentials">') &&
+			message.content.includes(body),
+	)
+	if (said) return undefined
+	return createRuntimeContextMessage(
+		frameNotice('credentials', '[Command environment]', body),
+		'reminder',
+	)
+}

package/src/scheduler/completion-inbox.ts

@@ -479,7 +479,7 @@ export class CompletionInbox {
 			stillRunningNotShown > 0
 				? ` ${shownRunning.length} running tasks are shown below, and ${stillRunningNotShown} more still running.`
 				: ''
-		return `Owned delegated work (current scheduler observations).${overflow} Result delivery is not proof that you answered the original request. Answer the latest operator message and complete the requested synthesis of available results unless the operator cancelled or changed that request. Reuse delivered results when sufficient; do not relaunch completed work. If a delivered result is no longer visible, retrieve it by task ID. A terminal state with a non-end_turn stop reason is not successful task completion. Do not repeat a synthesis already given.\n${JSON.stringify({ tasks, omitted: this.ours.size - ids.length })}`
+		return `Owned delegated work (current scheduler observations; a later block with this heading replaces this one).${overflow} Result delivery is not proof that you answered the original request. Answer the latest operator message and complete the requested synthesis of available results unless the operator cancelled or changed that request. Reuse delivered results when sufficient; do not relaunch completed work. If a delivered result is no longer visible, retrieve it by task ID. A terminal state with a non-end_turn stop reason is not successful task completion. Do not repeat a synthesis already given.\n${JSON.stringify({ tasks, omitted: this.ours.size - ids.length })}`
 	}
 
 	/**

package/src/tools/builtins/bash.ts

@@ -20,7 +20,7 @@ import {
 	withoutBashStartup,
 } from '../command-shell.js'
 import { defineTool } from '../defineTool.js'
-import { scrubInheritedEnv } from '../env-scrub.js'
+import { scrubInheritedEnv, withheldEnvNoticeText } from '../env-scrub.js'
 import { createHostOutputDecoder } from '../host-output.js'
 import { looksBinary, windowText } from '../text-window.js'
 import { judgeExit } from './exit-semantics.js'
@@ -802,10 +802,10 @@ const BashToolBase = defineTool({
 				failure.stdoutTruncated ? 'stdout' : '',
 				failure.stderrTruncated ? 'stderr' : '',
 			].filter(Boolean)
-			// Only on the failure path. A successful command did not need to know,
-			// and appending this to every result would make the common case noisy
-			// to buy nothing. A failing one is exactly where "authentication
-			// failed" has to be distinguishable from "the variable was withheld".
+			// Only the failure path reports removed variables (in `data`, for the
+			// kernel's notice). A successful command did not need to know; a failing
+			// one is where "authentication failed" has to be distinguishable from
+			// "the variable was withheld".
 			// A status the command uses to answer (no match, files differ) is a
 			// result, not a failure; the model sees it as an ordinary call.
 			const judged =
@@ -816,7 +816,6 @@ const BashToolBase = defineTool({
 				clipped.length > 0
 					? `[${clipped.join(' and ')} ${clipped.length === 1 ? 'was' : 'were'} truncated by the host output cap. The omitted output is unavailable in this result.]`
 					: '',
-				answered ? '' : describeWithheldEnv(inherited.dropped),
 			]
 				.filter(Boolean)
 				.join('\n\n')
@@ -827,6 +826,11 @@ const BashToolBase = defineTool({
 				data: {
 					...(exitCode !== undefined ? { exitCode } : {}),
 					...(judged?.note ? { exitNote: judged.note } : {}),
+					// How many variables were removed, for the kernel's own notice; the
+					// model's result stays what the command printed.
+					...(!answered && inherited.dropped.length > 0
+						? { withheldEnv: inherited.dropped.length }
+						: {}),
 					...(leaveSandbox ? { sandboxed: false, sandboxEscape: true } : {}),
 					timedOut,
 					stdoutTruncated: failure.stdoutTruncated ?? false,
@@ -904,16 +908,12 @@ function formatShellOutput(stdout: string | undefined, stderr: string | undefine
 }
 
 /**
- * Say that credential-shaped variables were left out of this command's
- * environment. The count is enough: the model needs to know a missing
- * credential is deliberate and who to ask, and the names are the user's data.
- * A command that failed because it wanted one otherwise reports an
- * authentication error pointing nowhere.
+ * The notice text for the credential-shaped variables left out of a command's
+ * environment (see {@link withheldEnvNoticeText}). It is sent as a notice after
+ * the tool batch, never written into the command's result.
  */
 export function describeWithheldEnv(dropped: readonly string[]): string {
-	if (dropped.length === 0) return ''
-	const one = dropped.length === 1
-	return `NOTE: ${dropped.length} credential-shaped environment ${one ? 'variable was' : 'variables were'} removed from this command's environment, so ${one ? 'it reads' : 'they read'} as unset. Ask the user if the command needs ${one ? 'it' : 'one'}.`
+	return withheldEnvNoticeText(dropped.length)
 }
 
 /**

package/src/tools/builtins/edit.ts

@@ -428,7 +428,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. Self-budget new_string/newStr under 12000 characters before emitting the tool call; 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`: 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.',
 	inputSchema,
 	modelInputSchema,
 	enforceModelInput: true,

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

@@ -8,7 +8,7 @@ import { resolveWithinAnyReal, toolRoots } from '../paths.js'
 import { resolveRetainedOutput } from '../retained-output.js'
 import { looksBinary } from '../text-window.js'
 import { fingerprintContent } from './content-fingerprint.js'
-import { type RenderedRead, renderCappedRead } from './read-render.js'
+import { type RenderedRead, humanBytes, renderCappedRead } from './read-render.js'
 
 const inputSchema = z.object({
 	path: z.string().describe('Path to the file to read (absolute or relative)'),
@@ -98,6 +98,7 @@ export const ReadFileTool = defineTool({
 				}
 			}
 			const content = buffer.toString('utf-8')
+			if (looksBinary(content)) return unreadableAsText(input.path, buffer.length, true)
 			const capped = renderCappedRead(content, buffer.length, input, capOptions(input, context))
 			if (!capped.ok) return refusedRead(input.path, buffer.length, capped.message, true)
 			const rendered = capped.rendered
@@ -144,6 +145,7 @@ export const ReadFileTool = defineTool({
 			}
 		}
 		const content = buffer.toString('utf-8')
+		if (looksBinary(content)) return unreadableAsText(filePath, buffer.length, false)
 		const capped = renderCappedRead(content, buffer.length, input, capOptions(input, context))
 		if (!capped.ok) return refusedRead(filePath, buffer.length, capped.message, false)
 		const rendered = capped.rendered
@@ -176,6 +178,19 @@ function capOptions(
 	}
 }
 
+/**
+ * A file whose bytes are not text. The model gets a short note with the size
+ * and the next step, never the numbered garbage a decode would produce.
+ */
+function unreadableAsText(path: string, bytes: number, sandboxed: boolean) {
+	return {
+		success: false as const,
+		output: `This file is not readable as text (${humanBytes(bytes)} of binary or non-UTF-8 data). Inspect it with a shell command such as file or xxd, or use a tool made for its format.`,
+		data: { path, binary: true, ...(sandboxed ? { sandboxed: true } : {}) },
+		facts: { kind: 'read' as const, path, binary: true, bytes },
+	}
+}
+
 function refusedRead(path: string, bytes: number, message: string, sandboxed: boolean) {
 	return {
 		success: false as const,
@@ -202,12 +217,8 @@ function readFacts(
 		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,
+		totalLines: rendered.totalLines,
+		returnedLines: rendered.returnedLines,
 		...(rendered.partial ? { partial: true } : {}),
 	}
 }