@namzu/sdk 56.2.0 → 57.0.0

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

@@ -102,7 +102,9 @@ export const ReadFileTool = defineTool({
 			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
-			recordObservedRead(context, input.path, content, rendered)
+			const unchanged = unchangedRead(context, input.path, input, content, buffer.length)
+			if (unchanged) return unchanged
+			recordObservedRead(context, input.path, content, rendered, input)
 
 			return {
 				success: true,
@@ -149,7 +151,12 @@ export const ReadFileTool = defineTool({
 		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
-		recordObservedRead(context, filePath, content, rendered)
+		const unchanged =
+			retained === undefined
+				? unchangedRead(context, filePath, input, content, buffer.length)
+				: undefined
+		if (unchanged) return unchanged
+		recordObservedRead(context, filePath, content, rendered, input)
 
 		return {
 			success: true,
@@ -243,14 +250,69 @@ function recordObservedRead(
 	key: string,
 	content: string,
 	rendered: RenderedRead,
+	input: ReadWindowInput,
 ): 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
+	} else {
+		tracker.recordRead(key, content)
+	}
+	if (tracker.recordReadWindow && context.toolUseId) {
+		tracker.recordReadWindow(key, windowKey(input), {
+			callId: context.toolUseId,
+			renderedFingerprint: fingerprintContent(rendered.output),
+			contentFingerprint: fingerprintContent(content),
+		})
+	}
+}
+
+type ReadWindowInput = {
+	readonly readRange?: readonly number[] | undefined
+	readonly offset?: number | undefined
+	readonly limit?: number | undefined
+	readonly allow_large?: boolean | undefined
+}
+
+/** The lines a read asked for, as one comparable string. */
+function windowKey(input: ReadWindowInput): string {
+	const range = input.readRange
+	const lines = range
+		? `r${range[0]}-${range[1]}`
+		: `o${input.offset ?? 0}l${input.limit === undefined ? 'all' : input.limit}`
+	return input.allow_large === true ? `${lines}+large` : lines
+}
+
+/**
+ * The answer to a repeat read of the same lines of a file that has not changed.
+ *
+ * The earlier result is still in front of the model, so returning the lines a
+ * second time only spends the window. It is given ONLY while that is true:
+ * the body must fingerprint the same as at the earlier read, and the earlier
+ * receipt must still be in the conversation exactly as the tool returned it
+ * (the host says so through `receiptVisible`). A receipt that was cleared,
+ * summarised away or annotated is no answer, and the lines are returned again.
+ */
+function unchangedRead(
+	context: ToolContext,
+	key: string,
+	input: ReadWindowInput,
+	content: string,
+	bytes: number,
+) {
+	const tracker = context.fileReadTracker
+	if (!tracker?.readWindow || !context.receiptVisible) return undefined
+	const earlier = tracker.readWindow(key, windowKey(input))
+	if (!earlier || earlier.contentFingerprint !== fingerprintContent(content)) return undefined
+	if (!context.receiptVisible(earlier.callId, earlier.renderedFingerprint)) return undefined
+	return {
+		success: true as const,
+		output:
+			'Unchanged since your earlier read of the same lines. That result is still current; use it instead of reading again.',
+		data: { path: key, unchanged: true },
+		facts: { kind: 'read' as const, path: key, bytes, unchanged: true },
 	}
-	tracker.recordRead(key, content)
 }
 
 function describeStructuredBinaryRead(path: string, buffer: Buffer): string | null {

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

@@ -1,4 +1,4 @@
-import type { FileReadTracker } from '../types/tool/index.js'
+import type { FileReadTracker, ReadWindowEntry } from '../types/tool/index.js'
 import { fingerprintContent } from './builtins/content-fingerprint.js'
 
 /** Host-owned observation ledger. Share only across turns of the same conversation and filesystem. */
@@ -48,7 +48,31 @@ export function createFileReadTracker(): FileReadTracker {
 			chains.delete(key)
 		}
 	}
+	// The last few windows read of each file, newest last. Bounded because a
+	// long session reads many files and a window key is cheap to repeat.
+	const windows = new Map<string, Map<string, ReadWindowEntry>>()
+	const MAX_WINDOWS_PER_FILE = 6
+	const MAX_WINDOWED_FILES = 512
 	return {
+		recordReadWindow(key, window, entry) {
+			let forFile = windows.get(key)
+			if (forFile) windows.delete(key)
+			else forFile = new Map()
+			forFile.delete(window)
+			forFile.set(window, entry)
+			while (forFile.size > MAX_WINDOWS_PER_FILE) {
+				const oldest = forFile.keys().next().value
+				if (oldest === undefined) break
+				forFile.delete(oldest)
+			}
+			windows.set(key, forFile)
+			while (windows.size > MAX_WINDOWED_FILES) {
+				const oldest = windows.keys().next().value
+				if (oldest === undefined) break
+				windows.delete(oldest)
+			}
+		},
+		readWindow: (key, window) => windows.get(key)?.get(window),
 		recordRead: observe,
 		recordFullRead(key, content, callId, renderedFingerprint) {
 			observe(key, content)

package/src/types/agent/base.ts

@@ -118,6 +118,13 @@ export interface BaseAgentConfig {
 	/** Live project policy, flushed independently of human continuation text. */
 	projectInstructionContext?: ProjectInstructionContext
 
+	/**
+	 * Text the host wants carried across a compaction, such as where its plan
+	 * file is. Asked once per pass, after the summary is written; the answer is
+	 * appended to the restored context. Returning nothing adds nothing.
+	 */
+	postCompactionContext?: () => string | undefined | Promise<string | undefined>
+
 	allowedTools?: readonly string[]
 
 	/**

package/src/types/errors/catalog.ts

@@ -1,4 +1,9 @@
-import { ProviderError, classifyProviderError } from '../provider/errors.js'
+import {
+	ProviderError,
+	type TransportCause,
+	classifyProviderError,
+	readTransportCause,
+} from '../provider/errors.js'
 import { isNamzuError } from './index.js'
 
 /**
@@ -33,6 +38,8 @@ export interface ErrorFacts {
 	readonly retryAfterMs?: number
 	/** A hint the throw site attached directly. See {@link readHint}. */
 	readonly hint?: string
+	/** When the failure is the network path rather than the provider: which part of it. */
+	readonly transport?: TransportCause
 }
 
 export interface ErrorCatalogRule {
@@ -91,10 +98,12 @@ export function factsOf(err: unknown): ErrorFacts {
 				? classifyProviderError(err)
 				: undefined
 	if (providerFailure) {
+		const transport = readTransportCause(providerFailure)
 		return {
 			code: providerFailure.code,
 			message,
 			name: providerFailure.name,
+			...(transport !== undefined ? { transport } : {}),
 			...(providerFailure.status !== undefined ? { status: providerFailure.status } : {}),
 			...(providerFailure.retryAfterMs !== undefined
 				? { retryAfterMs: providerFailure.retryAfterMs }
@@ -159,7 +168,7 @@ export const DEFAULT_ERROR_RULES: readonly ErrorCatalogRule[] = [
 		id: 'provider.rate_limit',
 		when: (facts) => facts.code === 'rate_limit' || facts.status === 429,
 		message: 'The provider is rate limiting this turn.',
-		hint: 'Respect the provider retry delay when reported. Lower concurrency, or wait for the quota window to reset before resuming.',
+		hint: 'Wait for the provider retry delay when reported, or for the quota window to reset, before resuming. When the wait is long, continue on another model or provider.',
 	},
 	{
 		id: 'provider.context_overflow',
@@ -176,6 +185,26 @@ export const DEFAULT_ERROR_RULES: readonly ErrorCatalogRule[] = [
 		message: 'The provider is failing on its own side.',
 		hint: 'Nothing in the turn is wrong. Resume from the last checkpoint once the provider recovers.',
 	},
+	{
+		// Before the general network rule: a proxy that wants a sign-in and a
+		// certificate nobody trusts each have a fix the general advice does not name.
+		id: 'provider.proxy_auth',
+		when: (facts) => facts.transport === 'proxy_auth_required',
+		message: 'The network proxy asked for a sign-in before it would pass the request on.',
+		hint: 'Put the proxy user name and password in the proxy address (for example HTTPS_PROXY=http://user:password@host:port), or ask whoever runs the proxy for access.',
+	},
+	{
+		id: 'provider.proxy_refused',
+		when: (facts) => facts.transport === 'proxy_refused',
+		message: 'The network proxy refused to pass the request on.',
+		hint: 'Check the proxy address and the NO_PROXY list, and ask whoever runs the proxy whether this host is allowed to reach the provider.',
+	},
+	{
+		id: 'provider.untrusted_certificate',
+		when: (facts) => facts.transport === 'untrusted_certificate',
+		message: 'The connection was refused because its certificate is not trusted.',
+		hint: 'If a proxy or firewall inspects encrypted traffic, set NODE_EXTRA_CA_CERTS to the file holding its certificate authority and start again.',
+	},
 	{
 		id: 'provider.network',
 		when: (facts) => facts.code === 'network' || facts.code === 'timeout',

package/src/types/provider/error.ts

@@ -51,4 +51,11 @@ export interface ProviderRequestErrorInit extends ProviderErrorInfo {
 	 * is believed over the status code, so the retry loop leaves it alone.
 	 */
 	readonly shouldRetry?: boolean
+	/**
+	 * Which part of the network path the request tripped on (a proxy that wants a
+	 * sign-in, a certificate nobody trusts), when the vendor error's causes say.
+	 * Data and not a `cause`: the raw error is never attached, but the diagnosis
+	 * has to survive the wrapping or no one downstream can act on it.
+	 */
+	readonly transport?: import('./errors.js').TransportCause
 }

package/src/types/provider/errors.ts

@@ -278,6 +278,59 @@ function isUndiciTermination(err: unknown): boolean {
 	return false
 }
 
+/**
+ * Why a request never reached the model when the cause is the network path
+ * between this host and the provider, not the provider.
+ *
+ * - `proxy_auth_required`: a proxy answered the tunnel request asking for credentials.
+ * - `proxy_refused`: a proxy answered the tunnel request with any other refusal.
+ * - `untrusted_certificate`: the certificate on the connection did not chain to an
+ *   authority this process trusts (typically a firewall that inspects encrypted traffic).
+ */
+export type TransportCause = 'proxy_auth_required' | 'proxy_refused' | 'untrusted_certificate'
+
+const TRANSPORT_CAUSES: ReadonlySet<string> = new Set([
+	'proxy_auth_required',
+	'proxy_refused',
+	'untrusted_certificate',
+])
+
+const UNTRUSTED_CERTIFICATE_CODES: ReadonlySet<string> = new Set([
+	'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
+	'UNABLE_TO_GET_ISSUER_CERT',
+	'UNABLE_TO_GET_ISSUER_CERT_LOCALLY',
+	'SELF_SIGNED_CERT_IN_CHAIN',
+	'DEPTH_ZERO_SELF_SIGNED_CERT',
+	'CERT_UNTRUSTED',
+	'CERT_CHAIN_TOO_LONG',
+])
+
+/**
+ * Read a proxy refusal or an untrusted certificate off a failure's cause chain.
+ *
+ * Structural where it can be (an error code) and, for the proxy, the one
+ * sentence undici writes when a tunnel request is answered with a status other
+ * than 200, because that failure carries no code or status of its own.
+ */
+export function readTransportCause(err: unknown): TransportCause | undefined {
+	for (const link of causeChain(err)) {
+		// A driver's own error carries the diagnosis as data (see
+		// `ProviderRequestError.transport`) because it never keeps the cause.
+		if (typeof link.transport === 'string' && TRANSPORT_CAUSES.has(link.transport)) {
+			return link.transport as TransportCause
+		}
+		if (typeof link.code === 'string' && UNTRUSTED_CERTIFICATE_CODES.has(link.code)) {
+			return 'untrusted_certificate'
+		}
+		const tunnel =
+			typeof link.message === 'string'
+				? /Proxy response \((\d{3})\) !== 200 when HTTP Tunneling/.exec(link.message)
+				: null
+		if (tunnel) return tunnel[1] === '407' ? 'proxy_auth_required' : 'proxy_refused'
+	}
+	return undefined
+}
+
 /** Node/undici transport failures that mean "never reached the model". */
 const NETWORK_ERRNOS: ReadonlySet<string> = new Set([
 	'ECONNRESET',
@@ -288,12 +341,54 @@ const NETWORK_ERRNOS: ReadonlySet<string> = new Set([
 	'ENETUNREACH',
 	'ENOTFOUND',
 	'EAI_AGAIN',
+	'ENETDOWN',
+	'EHOSTDOWN',
+	'ERR_PROXY_TUNNEL',
 	'EPROTO',
 	'UND_ERR_SOCKET',
+	'UND_ERR_CLOSED',
 	'UND_ERR_CONNECT_TIMEOUT',
 	'UND_ERR_RESPONSE_STATUS_CODE',
 ])
 
+/**
+ * A certificate that fails verification. The peer was reached and answered,
+ * and resending the same request meets the same refusal, so it is a network
+ * failure that is not retried.
+ */
+const CERTIFICATE_ERRNOS: ReadonlySet<string> = new Set([
+	'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
+	'UNABLE_TO_GET_ISSUER_CERT',
+	'UNABLE_TO_GET_ISSUER_CERT_LOCALLY',
+	'CERT_HAS_EXPIRED',
+	'CERT_NOT_YET_VALID',
+	'CERT_UNTRUSTED',
+	'CERT_REVOKED',
+	'DEPTH_ZERO_SELF_SIGNED_CERT',
+	'SELF_SIGNED_CERT_IN_CHAIN',
+	'ERR_TLS_CERT_ALTNAME_INVALID',
+	'HOSTNAME_MISMATCH',
+])
+
+/**
+ * The code of a certificate-verification failure anywhere on the chain, or
+ * `undefined`. Other TLS failures (a handshake cut short, a protocol error)
+ * are transient and are not this.
+ */
+export function readCertificateFailure(err: unknown): string | undefined {
+	for (const link of causeChain(err)) {
+		if (typeof link.code === 'string' && CERTIFICATE_ERRNOS.has(link.code)) return link.code
+	}
+	return undefined
+}
+
+/** Other TLS and socket-layer codes that mean the connection broke, not that it was refused. */
+function isTransientTransportCode(code: string): boolean {
+	return (
+		code.startsWith('ERR_SSL_') || (code.startsWith('ERR_TLS_') && !CERTIFICATE_ERRNOS.has(code))
+	)
+}
+
 const TIMEOUT_ERRNOS: ReadonlySet<string> = new Set([
 	'ETIMEDOUT',
 	'ESOCKETTIMEDOUT',
@@ -544,6 +639,20 @@ export function classifyProviderError(
 		})
 	}
 
+	// The network path itself: a proxy that wants credentials or refuses the
+	// tunnel, or a certificate nobody here trusts. Filed as `network` so it falls
+	// over like any unreachable provider, but never retried — the same request
+	// meets the same proxy or the same certificate again.
+	if (readTransportCause(err) !== undefined) {
+		return new ProviderError({
+			code: 'network',
+			message,
+			providerId,
+			retryable: false,
+			cause: err,
+		})
+	}
+
 	// A 400 that is really a window overflow must not be filed as a plain
 	// invalid_request: the caller can recover from one and not the other.
 	if (messages.some((m) => codeFromMessage(m, status) === 'context_length_exceeded')) {
@@ -570,6 +679,16 @@ export function classifyProviderError(
 	}
 
 	if (errno !== undefined) {
+		const certificate = readCertificateFailure(err)
+		if (certificate !== undefined) {
+			return new ProviderError({
+				code: 'network',
+				message,
+				providerId,
+				retryable: false,
+				cause: err,
+			})
+		}
 		if (TIMEOUT_ERRNOS.has(errno)) {
 			return new ProviderError({
 				code: 'timeout',
@@ -579,7 +698,7 @@ export function classifyProviderError(
 				cause: err,
 			})
 		}
-		if (NETWORK_ERRNOS.has(errno)) {
+		if (NETWORK_ERRNOS.has(errno) || isTransientTransportCode(errno)) {
 			return new ProviderError({
 				code: 'network',
 				message,

package/src/types/provider/stream.ts

@@ -204,4 +204,10 @@ export interface ProviderFallbackNotice {
 	readonly status?: number
 	/** The classified failure's own sentence, already redacted at its source. */
 	readonly reason: string
+	/**
+	 * The member that failed had streamed only pieces that can be taken back
+	 * (reasoning, or a tool call still being written). The consumer drops them
+	 * before the next chunk, as it does for a restarting retry.
+	 */
+	readonly restart?: boolean
 }

package/src/types/session/events.ts

@@ -447,6 +447,12 @@ type CoreSessionEvent =
 			status?: number
 			/** The classified failure's own sentence. */
 			reason: string
+			/**
+			 * The member that failed had streamed only pieces that can be taken
+			 * back (reasoning, or a tool call still being written): drop what this
+			 * message showed so far, as for a restarting retry.
+			 */
+			restart?: boolean
 	  }
 	| {
 			type: 'tool_completed'
@@ -800,6 +806,8 @@ type CoreSessionEvent =
 			duplicateToolResultsRemoved: number
 			orphanedToolResultsRemoved: number
 			syntheticToolResultsInserted: number
+			/** Of those, how many say the call never started. Absent when none. */
+			neverRanToolResultsInserted?: number
 			/** Exact number of durable image occurrences withheld from later requests. */
 			providerRejectedImagesSuppressed?: number
 	  }

package/src/types/tool/index.ts

@@ -180,6 +180,18 @@ export interface BackgroundJobRegistryRef {
 		workingDirectory?: string
 		initialOutput?: readonly { readonly stream: 'stdout' | 'stderr'; readonly text: string }[]
 	}): { id: string; status: string }
+	/**
+	 * Offer a foreground command this call is waiting on for hand-over to the
+	 * background, until the returned function is called. `background` is asked
+	 * to take the command over (`user`: the person asked; `message`: a message
+	 * from the person must reach the model) and says whether it did. Optional:
+	 * a host without it never moves a running command, and the call keeps the
+	 * kill.
+	 */
+	registerForeground?(entry: {
+		command: string
+		background(reason: 'user' | 'message'): boolean
+	}): () => void
 	/**
 	 * Resolves once the process exists or failed to start (`error` says why).
 	 * Optional: a host that cannot tell may omit it, and `bash` then replies
@@ -341,6 +353,19 @@ export interface FileReadTracker {
 	 * referencing a body it has been told is stale, without a check of its own.
 	 */
 	recordDriftObserved?(key: string): void
+	/**
+	 * Optional note of the last read of one window of a file: the call whose
+	 * receipt shows it, the fingerprint of that receipt, and the fingerprint of
+	 * the whole body at the time.
+	 *
+	 * Lets a repeat read of the same window answer "unchanged" instead of
+	 * returning the lines again. Only the read tool writes it, and it is only
+	 * trusted together with {@link ToolContext.receiptVisible}: a receipt that
+	 * has since been cleared, summarised away or edited is no answer.
+	 */
+	recordReadWindow?(key: string, window: string, entry: ReadWindowEntry): void
+	/** What {@link recordReadWindow} last noted for this window of this file. */
+	readWindow?(key: string, window: string): ReadWindowEntry | undefined
 	/** Whether a refused mutation has reported this path stale since the last observation. */
 	driftObserved?(key: string): boolean
 	/**
@@ -356,6 +381,15 @@ export interface FileReadTracker {
 	fingerprint?(key: string): string | undefined
 }
 
+/** The last read of one window of a file; see {@link FileReadTracker.recordReadWindow}. */
+export interface ReadWindowEntry {
+	readonly callId: string
+	/** Fingerprint of the exact text the read returned. */
+	readonly renderedFingerprint: string
+	/** Fingerprint of the whole file body at that read. */
+	readonly contentFingerprint: string
+}
+
 export interface ToolPauseOption {
 	readonly id: string
 	readonly label: string
@@ -533,6 +567,12 @@ export interface ToolContext {
 	 */
 	codeAnalysis?: CodeAnalysisProvider
 	fileReadTracker?: FileReadTracker
+	/**
+	 * Whether the receipt of an earlier call is still, byte for byte, in the
+	 * conversation the model is shown. Absent when the host cannot say; a tool
+	 * must then treat the answer as no.
+	 */
+	receiptVisible?: (callId: string, renderedFingerprint: string) => boolean
 
 	/**
 	 * Where work that outlives this call is held.

package/src/types/tool/presentation.ts

@@ -151,6 +151,8 @@ export type ToolFacts =
 			readonly binary?: { readonly bytes: number }
 			/** The command was handed to a background job instead of being waited on. */
 			readonly background?: true
+			/** The command was already running when it was handed over (a key, a message, an interrupt or its timeout). */
+			readonly continued?: true
 	  }
 	| {
 			readonly kind: 'read'
@@ -162,6 +164,8 @@ export type ToolFacts =
 			readonly returnedLines?: number
 			/** Only a window of the file was returned. */
 			readonly partial?: boolean
+			/** The lines were not repeated: an earlier read of the same lines still holds. */
+			readonly unchanged?: boolean
 	  }
 	| {
 			readonly kind: 'search'