@namzu/sdk 56.2.0 → 57.1.0

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,28 @@ 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
+
+	/**
+	 * The conversation this call belongs to, read live: the messages the model
+	 * is shown right now, including the assistant message that issued this
+	 * call, and the system prompt assembled for the current iteration.
+	 *
+	 * Absent when the host cannot say. A tool that needs it (one that starts a
+	 * delegate which continues this conversation) must then refuse rather than
+	 * start the delegate without the context it was asked to inherit. Read
+	 * only: the arrays are the turn's own and a tool must copy before it
+	 * changes anything.
+	 */
+	conversation?: {
+		messages(): readonly import('../message/index.js').Message[]
+		systemPrompt(): string | undefined
+	}
 
 	/**
 	 * 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'