@namzu/sdk 51.0.0 → 52.0.0

package/src/provider/errors.ts

@@ -76,6 +76,8 @@ export class ProviderRequestError extends Error {
 	 * See {@link vendorDetail} for what is kept and what is scrubbed.
 	 */
 	public readonly detail?: string
+	/** The provider's `x-should-retry` verdict, when it sent one; see {@link ProviderRequestErrorInit.shouldRetry}. */
+	public readonly shouldRetry?: boolean
 
 	constructor(init: ProviderRequestErrorInit) {
 		super(buildProviderErrorMessage(init))
@@ -87,6 +89,7 @@ export class ProviderRequestError extends Error {
 		if (init.status !== undefined) this.status = init.status
 		if (init.retryAfterMs !== undefined) this.retryAfterMs = init.retryAfterMs
 		if (init.detail !== undefined) this.detail = init.detail
+		if (init.shouldRetry !== undefined) this.shouldRetry = init.shouldRetry
 	}
 }
 
@@ -273,6 +276,15 @@ export function bodySaysContextOverflow(body: string | undefined | null): boolea
  * a negative delay is worse than none, because a caller would treat it as
  * "retry immediately" against a provider that just asked it to wait.
  */
+/**
+ * `x-should-retry` is only read when it says `false`: that is the provider
+ * refusing a resend, and it outranks the status code. `true` changes nothing,
+ * because a retryable status is already retried.
+ */
+export function parseShouldRetry(value: string | null | undefined): false | undefined {
+	return value?.trim().toLowerCase() === 'false' ? false : undefined
+}
+
 export function parseRetryAfterMs(
 	headerValue: string | null | undefined,
 	now: number = Date.now(),
@@ -525,6 +537,7 @@ export function providerVendorError(input: {
 		input.retryAfter ?? vendorRetryAfter(error),
 		input.now ?? Date.now(),
 	)
+	const shouldRetry = parseShouldRetry(vendorHeader(error, ['x-should-retry']))
 	const fields = error as { type?: unknown; param?: unknown; requestID?: unknown } | null
 	// A message that already carries its body (Anthropic's) has the fields; one that is only the
 	// parsed sentence (OpenAI's) gets them from the SDK error's own properties.
@@ -544,6 +557,7 @@ export function providerVendorError(input: {
 		...(status !== undefined ? { status } : {}),
 		...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
 		...(detail !== undefined ? { detail } : {}),
+		...(shouldRetry !== undefined ? { shouldRetry } : {}),
 	})
 }
 
@@ -605,6 +619,8 @@ export function providerHttpError(input: {
 	readonly retryAfter?: string | null
 	/** The response's request ID header, when the driver read one. */
 	readonly requestId?: string | null
+	/** The response's `x-should-retry` header, when the driver read one. */
+	readonly shouldRetry?: string | null
 	readonly now?: number
 }): ProviderRequestError {
 	const kind = classifyProviderHttpStatus(input.status, input.body)
@@ -621,6 +637,7 @@ export function providerHttpError(input: {
 			})
 		: vendorDetail(input.body)
 	const exactProviderCode = providerCode(input.body)
+	const shouldRetry = parseShouldRetry(input.shouldRetry)
 	return new ProviderRequestError({
 		kind,
 		providerId: input.providerId,
@@ -628,5 +645,6 @@ export function providerHttpError(input: {
 		status: input.status,
 		...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
 		...(detail !== undefined ? { detail } : {}),
+		...(shouldRetry !== undefined ? { shouldRetry } : {}),
 	})
 }

package/src/provider/retry.ts

@@ -1,7 +1,12 @@
 import { GENAI } from '../constants/telemetry/index.js'
 import { classifyProviderError, isAbortError } from '../types/provider/errors.js'
 import type { ChatCompletionParams, LLMProvider, StreamChunk } from '../types/provider/index.js'
-import { type BackoffPolicy, backoffWithJitter, sleep } from '../utils/backoff.js'
+import {
+	type BackoffPolicy,
+	backoffProportional,
+	backoffWithJitter,
+	sleep,
+} from '../utils/backoff.js'
 import type { Logger } from '../utils/logger.js'
 import { isProviderRequestError } from './errors.js'
 
@@ -31,6 +36,33 @@ export interface ProviderRetryConfig extends BackoffPolicy {
 	 * still slept exactly as instructed.
 	 */
 	readonly maxRetryAfterMs: number
+	/**
+	 * Shape of the random part of a backoff.
+	 *
+	 * `'full'` (the default) sleeps a uniform amount in `[0, backoff]`.
+	 * `'proportional'` sleeps the backoff plus up to a quarter of it, so a step
+	 * is never shorter than its exponential value.
+	 */
+	readonly jitter?: 'full' | 'proportional'
+	/**
+	 * What a server-named wait means.
+	 *
+	 * `'exact'` (the default) sleeps exactly what `Retry-After` said.
+	 * `'floor'` sleeps the longer of that and the backoff for this attempt, so
+	 * a server that says "1 second" on the seventh failure is still given the
+	 * backoff's thirty. The ceiling above applies either way.
+	 */
+	readonly retryAfter?: 'exact' | 'floor'
+	/**
+	 * Also retry a stream that failed AFTER it produced text or reasoning.
+	 *
+	 * Off by default, because the decorator cannot un-emit: the consumer has
+	 * already seen those deltas. When on, the retry notice carries
+	 * `restart: true` and the consumer must discard what the failed attempt
+	 * produced; the runtime does this itself. A stream that has begun a tool
+	 * call is never restarted, because the call may already be underway.
+	 */
+	readonly retryMidStream?: boolean
 }
 
 export const DEFAULT_PROVIDER_RETRY: ProviderRetryConfig = {
@@ -97,6 +129,9 @@ export function withProviderRetry(
 	async function* chatStream(params: ChatCompletionParams): AsyncIterable<StreamChunk> {
 		for (let attempt = 0; ; attempt++) {
 			let produced = false
+			// A tool call or hosted tool began: past this point a restart could
+			// repeat work that is already underway, so it is never offered.
+			let acted = false
 			try {
 				for await (const chunk of provider.chatStream(params)) {
 					// An error-only chunk is a failure report, not output: it
@@ -106,6 +141,9 @@ export function withProviderRetry(
 						chunk.error !== undefined && !chunk.delta.content && !chunk.delta.toolCalls?.length
 
 					if (!isErrorOnly) produced = true
+					if (chunk.delta.toolCalls?.length || chunk.delta.toolCallEnd || chunk.delta.hostedTool) {
+						acted = true
+					}
 
 					if (isErrorOnly && !produced && attempt < config.maxRetries) {
 						throw new Error(chunk.error)
@@ -132,7 +170,8 @@ export function withProviderRetry(
 				const classified = classifyProviderError(err, provider.id)
 				const exhausted = attempt >= config.maxRetries
 
-				if (produced || !classified.retryable || exhausted) {
+				const restartable = produced && config.retryMidStream === true && !acted
+				if ((produced && !restartable) || !classified.retryable || exhausted) {
 					log?.warn('Provider call failed', {
 						[GENAI.SYSTEM]: provider.id,
 						'namzu.provider.code': classified.code,
@@ -200,7 +239,16 @@ export function withProviderRetry(
 					throw isProviderRequestError(err) ? err : classified
 				}
 
-				const delay = serverDirected ?? backoffWithJitter(attempt, config, random)
+				const backoff =
+					config.jitter === 'proportional'
+						? backoffProportional(attempt, config, random)
+						: backoffWithJitter(attempt, config, random)
+				const delay =
+					serverDirected === undefined
+						? backoff
+						: config.retryAfter === 'floor'
+							? Math.max(serverDirected, backoff)
+							: serverDirected
 
 				log?.warn('Provider call failed — retrying', {
 					[GENAI.SYSTEM]: provider.id,
@@ -210,6 +258,7 @@ export function withProviderRetry(
 					'namzu.provider.max_retries': config.maxRetries,
 					'namzu.provider.delay_ms': delay,
 					'namzu.provider.server_directed': serverDirected !== undefined,
+					'namzu.provider.restart': restartable,
 				})
 
 				// Tell the consumer BEFORE sleeping. With the default policy a
@@ -231,6 +280,7 @@ export function withProviderRetry(
 						code: classified.code,
 						...(classified.status !== undefined ? { status: classified.status } : {}),
 						serverDirected: serverDirected !== undefined,
+						...(restartable ? { restart: true } : {}),
 					},
 				}
 

package/src/public-runtime.ts

@@ -318,6 +318,12 @@ export {
 	formatSteeringNote,
 } from './runtime/query/steering.js'
 export type { SteeringChannel } from './runtime/query/steering.js'
+// Hidden mid-conversation reminders a host feeds per model request (opt-in).
+export { isReminderMessage } from './runtime/query/reminders.js'
+export type {
+	ReminderContext,
+	ReminderSource,
+} from './runtime/query/reminders.js'
 export {
 	BidiSessionCloseTimeoutError,
 	createMockBidiProvider,
@@ -628,6 +634,7 @@ export {
 	runShellHook,
 	SHELL_HOOK_EVENTS,
 	SHELL_HOOKS_PLUGIN_ID,
+	shellHookIfMatches,
 	shellHookMatches,
 	shellHookVerdict,
 } from './plugin/index.js'
@@ -1505,6 +1512,7 @@ export {
 // consumer (`SpanProcessorLike`, then `CompactNowInput` and `CompactionResult`).
 // The gate is the reason this is a list rather than a fourth accident.
 export type { ResolvedContextWindow } from './compaction/context-window.js'
+export { resolveTriggerThreshold } from './compaction/context-window.js'
 export type { CompactRegionInput } from './compaction/manual.js'
 export type {
 	CompactionVerificationOptions,

package/src/public-types.ts

@@ -204,6 +204,7 @@ export type {
 	Disposable,
 	RunAgentOptions,
 	RunAgentResult,
+	SupervisorResumeTarget,
 } from './agents/index.js'
 
 export type {
@@ -457,7 +458,10 @@ export type {
 
 export type {
 	GuardedFetchConfig,
+	WebContentExtractor,
+	WebExtractRequest,
 	WebFetchProvider,
+	WebFetchRedirectPolicy,
 	WebFetchRefusalReason,
 	WebFetchRequest,
 	WebFetchResult,

package/src/runtime/jobs/registry.ts

@@ -99,6 +99,21 @@ export interface StartJobParams {
 	 * expect stdin.
 	 */
 	readonly spawn?: () => JobProcess
+	/**
+	 * Output the process already wrote before the registry took it over, in
+	 * the order it was written. Used when a foreground command is moved to the
+	 * background, so a later `read` starts with what the model was shown.
+	 */
+	readonly initialOutput?: readonly {
+		readonly stream: 'stdout' | 'stderr'
+		readonly text: string
+	}[]
+	/**
+	 * `spawn` returned a process on THIS host that the host shell started (a
+	 * foreground command being moved to the background), so its bytes are
+	 * decoded the way a foreground command's are, not as a Linux guest's.
+	 */
+	readonly hostOutput?: boolean
 }
 
 export interface BackgroundJobRegistryConfig {
@@ -333,8 +348,12 @@ export class BackgroundJobRegistry {
 		// Raw bytes, decoded here: a Windows console writes its OEM code page.
 		// A process a sandbox started runs a Linux guest, so it is UTF-8.
 		const decoders = {
-			stdout: createHostOutputDecoder(params.spawn ? { platform: 'linux' } : {}),
-			stderr: createHostOutputDecoder(params.spawn ? { platform: 'linux' } : {}),
+			stdout: createHostOutputDecoder(
+				params.spawn && !params.hostOutput ? { platform: 'linux' } : {},
+			),
+			stderr: createHostOutputDecoder(
+				params.spawn && !params.hostOutput ? { platform: 'linux' } : {},
+			),
 		}
 		let startError: string | undefined
 		let settleStarted!: () => void
@@ -473,6 +492,7 @@ export class BackgroundJobRegistry {
 			const text = typeof data === 'string' ? data : decoders[stream].write(data)
 			if (text) append(text, stream)
 		}
+		for (const seed of params.initialOutput ?? []) append(seed.text, seed.stream)
 		child.stdout?.on('data', onData('stdout'))
 		child.stderr?.on('data', onData('stderr'))
 
@@ -855,6 +875,23 @@ export function bindOwner(
 					: {}),
 			})
 		},
+		// A foreground command that ran out of time, kept instead of killed.
+		// The same owner and cap as `start`; the process is the one already
+		// running, with what it has written so far.
+		adopt: (params: {
+			command: string
+			child: ReturnType<typeof spawn>
+			workingDirectory?: string
+			initialOutput?: StartJobParams['initialOutput']
+		}) =>
+			registry.start({
+				owner,
+				command: params.command,
+				workingDirectory: params.workingDirectory ?? defaults.workingDirectory ?? process.cwd(),
+				spawn: () => ({ child: params.child }),
+				hostOutput: true,
+				...(params.initialOutput ? { initialOutput: params.initialOutput } : {}),
+			}),
 		get: (id: string) => mine(id),
 		awaitStarted: (id: string) => {
 			mine(id)

package/src/runtime/query/executor/tool-call-admission.ts

@@ -2,7 +2,7 @@ import { GENAI, NAMZU } from '../../../constants/telemetry/index.js'
 import { callableToolNames, formatToolNames } from '../../../registry/tool/callable.js'
 import { renderToolSchema } from '../../../registry/tool/schema.js'
 import type { ToolCall, ToolInputError } from '../../../types/message/index.js'
-import type { PluginHookResult } from '../../../types/plugin/index.js'
+import type { PluginHookPermission, PluginHookResult } from '../../../types/plugin/index.js'
 import type { ToolDefinition } from '../../../types/tool/index.js'
 import type { ToolCallRepair, ToolCallRepairReason } from '../../../types/tool/repair.js'
 import { awaitWithAbort } from '../../../utils/await-with-abort.js'
@@ -10,6 +10,7 @@ import { toErrorMessage } from '../../../utils/error.js'
 import type { Logger } from '../../../utils/logger.js'
 import type {
 	EmitEvent,
+	PreToolHookNotes,
 	PreToolHookOutcome,
 	PreparedDirectCall,
 	ToolExecutorConfig,
@@ -49,6 +50,11 @@ export interface ToolAdmissionHost {
 	 * step, which is the answer that sent a model round in a circle.
 	 */
 	readonly allowedTools: readonly string[] | undefined
+	/**
+	 * A hook asked for the turn to stop after the current step. Optional so a
+	 * host that builds an admission by hand (a test) need not say anything.
+	 */
+	readonly requestHalt?: (reason: string) => void
 }
 
 /**
@@ -89,7 +95,7 @@ export async function runPreToolHook(
 		signal,
 	)
 	signal.throwIfAborted()
-	return interpretPreToolResults(toolName, input, results)
+	return interpretPreToolResults(toolName, input, results, host.requestHalt)
 }
 
 export async function prepareDirectCall(
@@ -169,6 +175,7 @@ export async function prepareDirectCall(
 				...(providerInput && !truncationRepair && !preOutcome.modified && resolved.inputFailure
 					? { inputFailure: resolved.inputFailure }
 					: {}),
+				...hookNotesOf(preOutcome),
 			}
 		}
 		return {
@@ -321,6 +328,20 @@ export async function prepareDirectCall(
 		toolName,
 		input: preparation.prepared.input,
 		prepared: preparation.prepared,
+		...hookNotesOf(preOutcome),
+	}
+}
+
+/** The hook answers a ready or legacy call carries forward, or nothing. */
+function hookNotesOf(outcome: Extract<PreToolHookOutcome, { kind: 'continue' }>): {
+	hook?: PreToolHookNotes
+} {
+	if (outcome.permission === undefined && outcome.context === undefined) return {}
+	return {
+		hook: {
+			...(outcome.permission ? { permission: outcome.permission } : {}),
+			...(outcome.context !== undefined ? { context: outcome.context } : {}),
+		},
 	}
 }
 
@@ -328,29 +349,49 @@ function interpretPreToolResults(
 	toolName: string,
 	initialInput: unknown,
 	results: readonly PluginHookResult[],
+	requestHalt?: (reason: string) => void,
 ): PreToolHookOutcome {
 	let currentInput = initialInput
 	let modified = false
+	let permission: PluginHookPermission | undefined
+	const contexts: string[] = []
+	/** `ask` outranks `allow`: the stricter answer is the one that stands. */
+	const takePermission = (next: PluginHookPermission | undefined) => {
+		if (next === undefined) return
+		if (permission === undefined || (permission.decision === 'allow' && next.decision === 'ask')) {
+			permission = next
+		}
+	}
+	const withContext = (text: string): string =>
+		contexts.length === 0 ? text : `${text}\n\n${hookNote(contexts)}`
+	// The hooks ran side by side on the original input, and their answers are
+	// combined here. The first refusal (or failure) in registration order is the
+	// answer, whatever the others said; of several rewrites the last wins;
+	// `ask` outranks `allow`; every context is kept; every request to stop is
+	// passed on.
+	let refusal: { kind: 'skip' | 'error'; text: string } | undefined
 	for (const result of results) {
 		switch (result.action) {
 			case 'continue':
+				takePermission(result.permission)
+				if (result.context) contexts.push(result.context)
+				if (result.halt) requestHalt?.(result.halt.reason)
 				continue
 			case 'modify':
 				currentInput = result.input
 				modified = true
+				takePermission(result.permission)
+				if (result.context) contexts.push(result.context)
+				if (result.halt) requestHalt?.(result.halt.reason)
 				continue
 			case 'skip':
-				return {
-					kind: 'skip',
-					input: currentInput,
-					output: skippedToolResultText(toolName, result.reason),
-				}
+				if (result.context) contexts.push(result.context)
+				if (result.halt) requestHalt?.(result.halt.reason)
+				refusal ??= { kind: 'skip', text: skippedToolResultText(toolName, result.reason) }
+				continue
 			case 'error':
-				return {
-					kind: 'error',
-					input: currentInput,
-					output: `Error: ${result.message}`,
-				}
+				refusal ??= { kind: 'error', text: `Error: ${result.message}` }
+				continue
 			case 'retry':
 			case 'annotate':
 			// There is no result to replace yet. Rejecting loudly beats
@@ -367,9 +408,34 @@ function interpretPreToolResults(
 			}
 		}
 	}
-	return { kind: 'continue', input: currentInput, modified }
+	if (refusal) {
+		return {
+			kind: refusal.kind,
+			input: currentInput,
+			output: refusal.kind === 'skip' ? withContext(refusal.text) : refusal.text,
+		}
+	}
+	return {
+		kind: 'continue',
+		input: currentInput,
+		modified,
+		...(permission ? { permission } : {}),
+		...(contexts.length > 0 ? { context: contexts.join('\n') } : {}),
+	}
+}
+
+/**
+ * Hook text, framed so the model reads it as what a configured hook said and
+ * not as something the tool returned.
+ */
+export function hookNote(texts: readonly string[]): string {
+	const joined = texts.join('\n')
+	return `[Hook note]\n${joined.length > MAX_HOOK_NOTE_CHARS ? `${joined.slice(0, MAX_HOOK_NOTE_CHARS)}\n[truncated]` : joined}`
 }
 
+/** A hook's text is one more thing for the model to read; it gets a bound. */
+const MAX_HOOK_NOTE_CHARS = 8_000
+
 /**
  * Turn the call the model issued into a name and a parsed input, giving
  * a configured repairer one chance to fix it first.