@namzu/sdk 56.1.0 → 57.0.0

package/src/types/message/index.ts

@@ -371,6 +371,7 @@ export const RUNTIME_CONTEXT_MESSAGE_KINDS = [
 	'step-context',
 	'structured-output',
 	'task-completion',
+	'turn-context',
 ] as const
 
 export type RuntimeContextMessageKind = (typeof RUNTIME_CONTEXT_MESSAGE_KINDS)[number]
@@ -381,8 +382,18 @@ export interface RuntimeContextMessageSource {
 	readonly kind: RuntimeContextMessageKind
 	/** Optional durable host delivery identity; it never grants operator authority. */
 	readonly deliveryRef?: InboundDeliveryRef
+	/**
+	 * What a `turn-context` entry reports (for example `repository`). A later
+	 * entry with the same key adds to or replaces what an earlier one said.
+	 */
+	readonly key?: string
 }
 
+/** The longest key a recorded context entry may carry. */
+export const MAX_TURN_CONTEXT_KEY_LENGTH = 64
+
+const TURN_CONTEXT_KEY = /^[a-z][a-z0-9-]*$/
+
 export type UserMessageSource =
 	| GoalRoundMessageSource
 	| ProjectInstructionMessageSource
@@ -437,12 +448,14 @@ export function isRuntimeContextMessageSource(
 		readonly type?: unknown
 		readonly kind?: unknown
 		readonly deliveryRef?: unknown
+		readonly key?: unknown
 	}
 	return (
 		candidate.type === 'runtime-context' &&
 		typeof candidate.kind === 'string' &&
 		(RUNTIME_CONTEXT_MESSAGE_KINDS as readonly string[]).includes(candidate.kind) &&
-		(candidate.deliveryRef === undefined || isInboundDeliveryRef(candidate.deliveryRef))
+		(candidate.deliveryRef === undefined || isInboundDeliveryRef(candidate.deliveryRef)) &&
+		(candidate.key === undefined || isTurnContextKey(candidate.key))
 	)
 }
 
@@ -640,6 +653,100 @@ export function createRuntimeContextMessage(
 	})
 }
 
+/** Whether `value` is a name a recorded context entry may be filed under. */
+export function isTurnContextKey(value: unknown): value is string {
+	return (
+		typeof value === 'string' &&
+		value.length <= MAX_TURN_CONTEXT_KEY_LENGTH &&
+		TURN_CONTEXT_KEY.test(value)
+	)
+}
+
+function localTime(at: Date): string {
+	const pad = (n: number) => String(n).padStart(2, '0')
+	return `${at.getFullYear()}-${pad(at.getMonth() + 1)}-${pad(at.getDate())} ${pad(at.getHours())}:${pad(at.getMinutes())}`
+}
+
+/**
+ * Build a recorded context entry: text a step learned for this turn that
+ * stays in the conversation, after whatever came before it, so later requests
+ * keep beginning with it. The header is written into the content once and the
+ * entry is never edited afterwards; a later entry under the same key says what
+ * changed. It is not an operator message and carries no authority.
+ *
+ * The first entry under a key says that a later one adds to or replaces it;
+ * with `later` set, for an entry that follows another under the same key, the
+ * header leaves that sentence out, since the conversation already holds it.
+ */
+export function createTurnContextEntry(
+	key: string,
+	text: string,
+	at: Date = new Date(),
+	options: { readonly later?: boolean } = {},
+): UserMessage {
+	if (!isTurnContextKey(key))
+		throw new TypeError('A recorded context key is lowercase words joined by hyphens.')
+	const label = `Recorded context (runtime-generated; not a new user request) - ${key}, as of ${localTime(at)}`
+	return createUserMessage(
+		`${label}${options.later ? ':' : '. A later entry with this key adds to or replaces what it says:'}\n${text}`,
+		undefined,
+		{ type: 'runtime-context', kind: 'turn-context', key },
+	)
+}
+
+/** The key a recorded context entry is filed under, or undefined for any other message. */
+export function turnContextKey(message: { readonly role: string; readonly source?: unknown }):
+	| string
+	| undefined {
+	if (message.role !== 'user') return undefined
+	const source = message.source as RuntimeContextMessageSource | undefined
+	return source?.type === 'runtime-context' && source.kind === 'turn-context'
+		? source.key
+		: undefined
+}
+
+/** Whether `message` is a recorded context entry. */
+export function isTurnContextEntry(message: {
+	readonly role: string
+	readonly source?: unknown
+}): boolean {
+	if (message.role !== 'user') return false
+	const source = message.source as RuntimeContextMessageSource | undefined
+	return source?.type === 'runtime-context' && source.kind === 'turn-context'
+}
+
+/**
+ * What a step recorded under `key`, oldest first, without each entry's header.
+ * A history that was compacted holds only the entries the compaction kept, so
+ * an empty list means the step may say everything again.
+ */
+export function turnContextEntries(messages: readonly Message[], key: string): readonly string[] {
+	const bodies: string[] = []
+	for (const message of messages) {
+		if (turnContextKey(message) !== key || typeof message.content !== 'string') continue
+		bodies.push(message.content.slice(message.content.indexOf('\n') + 1))
+	}
+	return bodies
+}
+
+/**
+ * The text of the newest user-role message with plain text, skipping recorded
+ * context entries: a history that ends in one (a resumed session) must not
+ * take the host's own recalled text for the question.
+ */
+export function lastPromptText(messages: readonly Message[]): string {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const message = messages[i]
+		if (
+			message?.role === 'user' &&
+			typeof message.content === 'string' &&
+			!isTurnContextEntry(message)
+		)
+			return message.content
+	}
+	return ''
+}
+
 /** Build the retained user-context message that carries live project policy. */
 export function createProjectInstructionMessage(
 	content: string,

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/session/prepare-step.ts

@@ -227,10 +227,36 @@ export interface PrepareStepResult {
 	 */
 	readonly context?: string
 
+	/**
+	 * Text to keep in the conversation from this step on, filed under a key.
+	 *
+	 * Where `context` is gone after the request, an item here becomes a
+	 * recorded entry appended after whatever the history ends with, so every
+	 * later request (of this turn and of the next turns) begins with it and a
+	 * caching provider keeps reading the same prefix. Entries are never edited
+	 * or moved; a step that has something new says only that, under the same
+	 * key, and reads what it said before with `turnContextEntries`. An item
+	 * whose text is empty, or equal to the last entry under its key, adds
+	 * nothing. Entries are ordinary history to compaction, which drops them
+	 * with the messages around them, after which a step sees none and may say
+	 * everything again.
+	 *
+	 * The model reads an entry as recorded context the host generated, not as
+	 * something the operator said, and a person is never shown one.
+	 */
+	readonly recordedContext?: readonly RecordedContextItem[]
+
 	readonly temperature?: number
 	readonly maxResponseTokens?: number
 }
 
+/** One piece of text a step asks to have recorded, under what it reports. */
+export interface RecordedContextItem {
+	/** Lowercase words joined by hyphens (for example `repository`). */
+	readonly key: string
+	readonly text: string
+}
+
 /**
  * Called before each model call, with everything the turn has produced so
  * far.

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'