@namzu/sdk 56.2.0 → 57.1.0

package/src/tools/builtins/bash.ts

@@ -4,6 +4,7 @@ import { SANDBOX_KILL_GRACE_MS } from '../../constants/sandbox/index.js'
 import { DANGEROUS_PATTERNS } from '../../constants/tools/index.js'
 import { killTree } from '../../process/kill-tree.js'
 import { genericLabel } from '../../registry/tool/presentation.js'
+import { cancelCauseOf } from '../../types/session/cancel-cause.js'
 import type { ToolFacts } from '../../types/tool/presentation.js'
 import { subscribeToAbort } from '../../utils/abort.js'
 import { readPositiveIntEnv } from '../../utils/env.js'
@@ -93,6 +94,28 @@ export function movedToBackgroundMessage(jobId: string, timeoutMs: number): stri
 	return `Command did not complete within its ${seconds}s timeout and was moved to the background as job ${jobId}; it was not stopped. You will be told when it ends. Its output so far is above.`
 }
 
+/**
+ * How long a foreground command runs before it is offered for hand-over to
+ * the background. A command that ends sooner is never interrupted by a stray
+ * key press, and a host that shows a hint shows it from this moment.
+ */
+export const FOREGROUND_HANDOFF_AFTER_MS = 2_000
+
+/**
+ * What the model is told when the person moved a running foreground command to
+ * the background instead of stopping it. Exported so the test states the same
+ * words.
+ */
+export function handedOffMessage(jobId: string, reason: 'user' | 'message' | 'interrupt'): string {
+	const why =
+		reason === 'user'
+			? "at the person's request"
+			: reason === 'message'
+				? 'so a message from the person could reach you'
+				: 'because the person interrupted the turn'
+	return `Command was moved to the background as job ${jobId} ${why}; it was not stopped. You will be told when it ends. Its output so far is above.`
+}
+
 const inputSchema = z.object({
 	command: z
 		.string()
@@ -240,10 +263,34 @@ export function execHostShell(
 			child: ReturnType<typeof spawnHostShell>
 			initialOutput: readonly { stream: 'stdout' | 'stderr'; text: string }[]
 		}) => string | undefined
+		/**
+		 * Takes the live process over for a hand-over the person asked for
+		 * (a key press, a message that must reach the model, an interrupt),
+		 * with the same contract as `onTimeout`. Absent, those hand-overs are
+		 * not offered and an interrupt kills the command as it always did.
+		 */
+		adopt?: (running: {
+			child: ReturnType<typeof spawnHostShell>
+			initialOutput: readonly { stream: 'stdout' | 'stderr'; text: string }[]
+		}) => string | undefined
+		/**
+		 * An interrupt the person caused (Esc, Ctrl+C) hands the command to
+		 * `adopt` instead of killing it. Any other abort, a parent stopping a
+		 * child or a budget stop, still kills it.
+		 */
+		adoptOnInterrupt?: boolean
+		/**
+		 * Called once, right after the process is spawned, with the means to
+		 * hand it over later. `background` returns whether the process was
+		 * taken over; it settles the call with `backgroundedJobId` set.
+		 */
+		onRunning?: (control: { background(reason: 'user' | 'message'): boolean }) => void
 	},
 ): Promise<{
-	/** Set when `onTimeout` took the process over; the command was not stopped. */
+	/** Set when the process was taken over; the command was not stopped. */
 	backgroundedJobId?: string
+	/** Why it was taken over. */
+	backgroundedBy?: 'timeout' | 'user' | 'message' | 'interrupt'
 	stdout: string
 	stderr: string
 	/** Bytes captured on each stream, before decoding; absent from a runner that does not count them. */
@@ -401,44 +448,64 @@ export function execHostShell(
 			)
 		}
 		child.once('close', onClose)
-		const deadline = setTimeout(() => {
-			if (options.onTimeout && !closed && cause === undefined) {
-				let jobId: string | undefined
-				try {
-					jobId = options.onTimeout({
-						child,
-						initialOutput: (['stdout', 'stderr'] as const)
-							.map((stream) => ({ stream, text: decodeCapture(stream) }))
-							.filter((part) => part.text !== ''),
-					})
-				} catch {
-					// A host that cannot take the process over leaves the kill in place.
-				}
-				if (jobId !== undefined) {
-					// The registry owns the process from here: stop listening to it,
-					// so a later Stop or its exit is not this call's business.
-					closed = true
-					disposeAbort?.()
-					child.stdout?.off('data', onStdout)
-					child.stderr?.off('data', onStderr)
-					child.off('close', onClose)
-					child.off('error', onError)
-					child.off('spawn', onSpawn)
-					resolve({
-						backgroundedJobId: jobId,
-						stdout: decodeCapture('stdout'),
-						stderr: decodeCapture('stderr'),
-					})
-					return
-				}
+		// Hands the live process to the host's job registry, once. `onTimeout`
+		// answers for the deadline; every other reason goes to `adopt`.
+		const takeOver = (reason: 'timeout' | 'user' | 'message' | 'interrupt'): boolean => {
+			const adopter =
+				reason === 'timeout' ? options.onTimeout : (options.adopt ?? options.onTimeout)
+			if (!adopter || closed || cause !== undefined) return false
+			let jobId: string | undefined
+			try {
+				jobId = adopter({
+					child,
+					initialOutput: (['stdout', 'stderr'] as const)
+						.map((stream) => ({ stream, text: decodeCapture(stream) }))
+						.filter((part) => part.text !== ''),
+				})
+			} catch {
+				// A host that cannot take the process over leaves the process where it is.
 			}
+			if (jobId === undefined) return false
+			// The registry owns the process from here: stop listening to it,
+			// so a later Stop or its exit is not this call's business.
+			closed = true
+			disposeAbort?.()
+			clearTimeout(deadline)
+			child.stdout?.off('data', onStdout)
+			child.stderr?.off('data', onStderr)
+			child.off('close', onClose)
+			child.off('error', onError)
+			child.off('spawn', onSpawn)
+			resolve({
+				backgroundedJobId: jobId,
+				backgroundedBy: reason,
+				stdout: decodeCapture('stdout'),
+				stderr: decodeCapture('stderr'),
+			})
+			return true
+		}
+		const deadline = setTimeout(() => {
+			if (takeOver('timeout')) return
 			cancel('timeout')
 		}, options.timeout)
 		deadline.unref?.()
 		if (options.signal) {
-			disposeAbort = subscribeToAbort(options.signal, () => cancel('caller'))
-			if (options.signal.aborted) cancel('caller')
+			const signal = options.signal
+			const onAbort = () => {
+				// Esc or Ctrl+C keeps what the command was doing; any other stop
+				// (a parent cancelling a child, a budget) still ends it.
+				if (
+					options.adoptOnInterrupt === true &&
+					cancelCauseOf(signal.reason) === 'user' &&
+					takeOver('interrupt')
+				)
+					return
+				cancel('caller')
+			}
+			disposeAbort = subscribeToAbort(signal, onAbort)
+			if (signal.aborted) onAbort()
 		}
+		options.onRunning?.({ background: (reason) => takeOver(reason) })
 	})
 }
 
@@ -714,51 +781,76 @@ const BashToolBase = defineTool({
 		// registry, a sandboxed turn, a one-off sandbox escape, a plain wait)
 		// is there anything to hand the process to, so those keep the kill.
 		const adopt = context.backgroundJobs?.adopt?.bind(context.backgroundJobs)
-		const canMoveToBackground =
-			adopt !== undefined &&
-			context.sandbox === undefined &&
-			!backgroundTasksDisabled() &&
-			!startsWithSleep(input.command)
+		const canHandOff =
+			adopt !== undefined && context.sandbox === undefined && !backgroundTasksDisabled()
+		const canMoveOnTimeout = canHandOff && !startsWithSleep(input.command)
+		const adoptRunning = (running: {
+			child: Parameters<NonNullable<typeof adopt>>[0]['child']
+			initialOutput: Parameters<NonNullable<typeof adopt>>[0]['initialOutput']
+		}) =>
+			adopt?.({
+				command: input.command,
+				child: running.child,
+				workingDirectory: context.workingDirectory,
+				initialOutput: running.initialOutput,
+			}).id
+		// Offered for hand-over once it has run long enough to be worth moving.
+		let offerTimer: ReturnType<typeof setTimeout> | undefined
+		let withdrawOffer: (() => void) | undefined
+		const offer = context.backgroundJobs?.registerForeground?.bind(context.backgroundJobs)
 
 		try {
-			const { stdout, stderr, stdoutBytes, stderrBytes, backgroundedJobId } = await execHostShell(
-				input.command,
-				{
+			const { stdout, stderr, stdoutBytes, stderrBytes, backgroundedJobId, backgroundedBy } =
+				await execHostShell(input.command, {
 					cwd: context.workingDirectory,
 					timeout: input.timeout,
 					env: { ...inherited.env, ...context.env },
 					maxBuffer: DEFAULT_BASH_MAX_BUFFER_BYTES,
 					signal: context.abortSignal,
 					onOutput,
-					...(canMoveToBackground
+					...(canMoveOnTimeout ? { onTimeout: adoptRunning } : {}),
+					...(canHandOff
 						? {
-								onTimeout: ({ child, initialOutput }) =>
-									adopt({
-										command: input.command,
-										child,
-										workingDirectory: context.workingDirectory,
-										initialOutput,
-									}).id,
+								adopt: adoptRunning,
+								adoptOnInterrupt: true,
+								...(offer
+									? {
+											onRunning: (control: {
+												background(reason: 'user' | 'message'): boolean
+											}) => {
+												offerTimer = setTimeout(() => {
+													withdrawOffer = offer({
+														command: input.command,
+														background: (reason) => control.background(reason),
+													})
+												}, FOREGROUND_HANDOFF_AFTER_MS)
+												offerTimer.unref?.()
+											},
+										}
+									: {}),
 							}
 						: {}),
-				},
-			)
+				})
 			if (backgroundedJobId !== undefined) {
+				const timedOut = backgroundedBy === 'timeout'
 				return {
 					success: true,
 					output: [
 						formatShellOutput(stdout, stderr),
-						movedToBackgroundMessage(backgroundedJobId, input.timeout),
+						timedOut || backgroundedBy === undefined
+							? movedToBackgroundMessage(backgroundedJobId, input.timeout)
+							: handedOffMessage(backgroundedJobId, backgroundedBy),
 					]
 						.filter(Boolean)
 						.join('\n\n'),
 					data: {
 						jobId: backgroundedJobId,
 						background: true,
-						timedOut: true,
+						...(timedOut || backgroundedBy === undefined ? { timedOut: true } : {}),
 						movedToBackground: true,
+						...(backgroundedBy ? { backgroundedBy } : {}),
 					},
-					facts: { kind: 'command', command: input.command, background: true },
+					facts: { kind: 'command', command: input.command, background: true, continued: true },
 				}
 			}
 			return {
@@ -856,6 +948,9 @@ const BashToolBase = defineTool({
 					...(failure.stderrBytes !== undefined ? { stderrBytes: failure.stderrBytes } : {}),
 				}),
 			}
+		} finally {
+			if (offerTimer !== undefined) clearTimeout(offerTimer)
+			withdrawOffer?.()
 		}
 	},
 })

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

@@ -1,3 +1,4 @@
+import type { CompactionSummaryRouter } from '../../compaction/model-summary.js'
 import type { ProjectInstructionContext } from '../../runtime/query/project-instructions.js'
 import type { SessionPaths } from '../../session/paths.js'
 import type { SessionTokenBudget } from '../../store/budget/index.js'
@@ -118,6 +119,21 @@ 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>
+
+	/**
+	 * Names the model that writes a compaction summary, asked once per pass.
+	 * Absent, or resolving nothing, the summary is the extracted working state;
+	 * a call that fails falls back to it too. The call's cost is charged to the
+	 * turn.
+	 */
+	compactionSummaryRoute?: CompactionSummaryRouter
+
 	allowedTools?: readonly string[]
 
 	/**

package/src/types/agent/scheduler.ts

@@ -132,6 +132,15 @@ export interface CreateTaskOptions {
 
 	prompt: string
 
+	/**
+	 * Messages the child starts from, placed before {@link prompt}. A host that
+	 * delegates work which continues the caller's conversation passes that
+	 * conversation here; the prompt then arrives as the last user message.
+	 * Absent, the child sees only the prompt. The caller is responsible for the
+	 * list being a valid conversation (every tool call answered).
+	 */
+	readonly inheritedMessages?: readonly import('../message/index.js').Message[]
+
 	workingDirectory: string
 
 	runtimeContext?: AgentRuntimeContext

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
 }