@namzu/sdk 50.1.0 → 51.1.0

package/src/execution/workflow/schema.ts

@@ -0,0 +1,137 @@
+/**
+ * A small JSON Schema validator for `agent(..., { schema })`.
+ *
+ * Supported keywords: `type` (string or list), `enum`, `const`, `properties`,
+ * `required`, `additionalProperties` (boolean or schema), `items` (one
+ * schema), `minItems`, `maxItems`, `minLength`, `maxLength`, `minimum`,
+ * `maximum`, `anyOf`, `oneOf`, `allOf`. Any other keyword is ignored, and the
+ * schema is also handed to the host so a model-side structured-output
+ * mechanism can enforce more. `pattern` is deliberately not supported: the
+ * schema is model-authored and a regular expression is a CPU risk.
+ */
+const MAX_DEPTH = 32
+
+function typeOf(value: unknown): string {
+	if (value === null) return 'null'
+	if (Array.isArray(value)) return 'array'
+	if (typeof value === 'number') return Number.isInteger(value) ? 'integer' : 'number'
+	return typeof value
+}
+
+function matchesType(value: unknown, type: string): boolean {
+	const actual = typeOf(value)
+	return actual === type || (type === 'number' && actual === 'integer')
+}
+
+function same(a: unknown, b: unknown): boolean {
+	return JSON.stringify(a) === JSON.stringify(b)
+}
+
+function isSchema(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function check(value: unknown, schema: unknown, path: string, depth: number): string | undefined {
+	if (schema === true || schema === undefined) return undefined
+	if (schema === false) return `${path}: nothing is allowed here`
+	if (!isSchema(schema)) return undefined
+	if (depth > MAX_DEPTH) return `${path}: schema is nested too deeply`
+	const here = path || 'the result'
+
+	const type = schema.type
+	if (typeof type === 'string' && !matchesType(value, type)) {
+		return `${here} must be ${type}, got ${typeOf(value)}`
+	}
+	if (Array.isArray(type) && !type.some((t) => typeof t === 'string' && matchesType(value, t))) {
+		return `${here} must be one of ${type.join(', ')}, got ${typeOf(value)}`
+	}
+	if (Array.isArray(schema.enum) && !schema.enum.some((e) => same(e, value))) {
+		return `${here} must be one of ${JSON.stringify(schema.enum)}`
+	}
+	if ('const' in schema && !same(schema.const, value)) {
+		return `${here} must equal ${JSON.stringify(schema.const)}`
+	}
+	if (typeof value === 'string') {
+		if (typeof schema.minLength === 'number' && value.length < schema.minLength) {
+			return `${here} is shorter than ${schema.minLength} characters`
+		}
+		if (typeof schema.maxLength === 'number' && value.length > schema.maxLength) {
+			return `${here} is longer than ${schema.maxLength} characters`
+		}
+	}
+	if (typeof value === 'number') {
+		if (typeof schema.minimum === 'number' && value < schema.minimum) {
+			return `${here} is below ${schema.minimum}`
+		}
+		if (typeof schema.maximum === 'number' && value > schema.maximum) {
+			return `${here} is above ${schema.maximum}`
+		}
+	}
+	if (Array.isArray(value)) {
+		if (typeof schema.minItems === 'number' && value.length < schema.minItems) {
+			return `${here} has fewer than ${schema.minItems} items`
+		}
+		if (typeof schema.maxItems === 'number' && value.length > schema.maxItems) {
+			return `${here} has more than ${schema.maxItems} items`
+		}
+		if (schema.items !== undefined) {
+			for (const [i, item] of value.entries()) {
+				const problem = check(item, schema.items, `${path}[${i}]`, depth + 1)
+				if (problem) return problem
+			}
+		}
+	}
+	if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+		const object = value as Record<string, unknown>
+		if (Array.isArray(schema.required)) {
+			for (const key of schema.required) {
+				if (typeof key === 'string' && !Object.hasOwn(object, key)) {
+					return `${here} is missing "${key}"`
+				}
+			}
+		}
+		const properties = isSchema(schema.properties) ? schema.properties : {}
+		for (const [key, child] of Object.entries(object)) {
+			const childPath = path ? `${path}.${key}` : key
+			if (Object.hasOwn(properties, key)) {
+				const problem = check(child, properties[key], childPath, depth + 1)
+				if (problem) return problem
+			} else if (schema.additionalProperties === false) {
+				return `${here} has an unexpected property "${key}"`
+			} else if (isSchema(schema.additionalProperties)) {
+				const problem = check(child, schema.additionalProperties, childPath, depth + 1)
+				if (problem) return problem
+			}
+		}
+	}
+	if (Array.isArray(schema.allOf)) {
+		for (const part of schema.allOf) {
+			const problem = check(value, part, path, depth + 1)
+			if (problem) return problem
+		}
+	}
+	if (Array.isArray(schema.anyOf) && !schema.anyOf.some((p) => !check(value, p, path, depth + 1))) {
+		return `${here} matches none of the allowed shapes`
+	}
+	if (Array.isArray(schema.oneOf)) {
+		const matching = schema.oneOf.filter((p) => !check(value, p, path, depth + 1)).length
+		if (matching !== 1) return `${here} must match exactly one allowed shape, matches ${matching}`
+	}
+	return undefined
+}
+
+/** `undefined` when `value` satisfies `schema`, otherwise a plain sentence naming the first problem. */
+export function validateAgainstSchema(value: unknown, schema: unknown): string | undefined {
+	return check(value, schema, '', 0)
+}
+
+/** Parse a model's text as JSON, tolerating one surrounding code fence. */
+export function parseJsonText(text: string): { ok: true; value: unknown } | { ok: false } {
+	const trimmed = text.trim()
+	const fenced = /^```(?:json)?\s*\n([\s\S]*?)\n```$/.exec(trimmed)
+	try {
+		return { ok: true, value: JSON.parse(fenced ? (fenced[1] as string) : trimmed) }
+	} catch {
+		return { ok: false }
+	}
+}

package/src/execution/workflow/types.ts

@@ -0,0 +1,300 @@
+/**
+ * Types of the workflow runtime: a script the model wrote once decides how
+ * many subagents run, with which prompts and under which phase titles; the
+ * runtime schedules them. See `docs/sdk/workflows.md`.
+ */
+
+/** One phase declared in `meta.phases`. */
+export interface WorkflowPhaseMeta {
+	readonly title: string
+	readonly detail?: string
+	readonly model?: string
+}
+
+/** The pure literal a script exports as `meta`. */
+export interface WorkflowMeta {
+	readonly name: string
+	readonly description: string
+	readonly whenToUse?: string
+	readonly phases: readonly WorkflowPhaseMeta[]
+}
+
+/** What the host is asked to run for one `agent()` call. */
+export interface WorkflowAgentRequest {
+	/** 1-based, in the order the script asked. */
+	readonly index: number
+	readonly label: string
+	readonly prompt: string
+	readonly phaseIndex?: number
+	readonly phaseTitle?: string
+	/** JSON Schema the result must satisfy; the runtime validates `data`. */
+	readonly schema?: Readonly<Record<string, unknown>>
+	readonly agentType?: string
+	readonly model?: string
+	readonly effort?: string
+	/** Report live progress; the runtime turns it into `workflow_agent` events. */
+	readonly onProgress: (progress: WorkflowAgentProgress) => void
+}
+
+export interface WorkflowAgentProgress {
+	readonly tokens?: number
+	readonly toolCalls?: number
+	readonly lastToolName?: string
+	readonly lastToolSummary?: string
+}
+
+/** What the host's agent run came to. */
+export interface WorkflowAgentOutcome {
+	readonly state: 'done' | 'error' | 'skipped'
+	/** The agent's final text. */
+	readonly text?: string
+	/** A structured result, when the host produced one for the schema. */
+	readonly data?: unknown
+	readonly tokens: number
+	readonly toolCalls: number
+	readonly error?: string
+}
+
+/**
+ * Starts one subagent through the host's own delegation path (the same
+ * policy, sandbox, accounting and cancellation as the `Agent` tool).
+ * Must honour `signal`.
+ */
+export type WorkflowSpawnAgent = (
+	request: WorkflowAgentRequest,
+	signal: AbortSignal,
+) => Promise<WorkflowAgentOutcome>
+
+export type WorkflowAgentState = 'start' | 'progress' | 'done' | 'error'
+
+export interface WorkflowStartedEvent {
+	readonly type: 'workflow_started'
+	readonly runId: string
+	readonly name: string
+	readonly description: string
+	readonly phases: readonly WorkflowPhaseMeta[]
+	readonly at: number
+}
+
+export interface WorkflowPhaseEvent {
+	readonly type: 'workflow_phase'
+	readonly runId: string
+	/** 1-based first-seen order; declared titles come first. */
+	readonly index: number
+	readonly title: string
+	readonly declared: boolean
+	readonly at: number
+}
+
+/**
+ * One agent changed state. `start` without `startedAt` means queued;
+ * `start` with `startedAt` means running. A `done` agent that was skipped
+ * (by the host, the operator or the token budget) carries `skipped: true`.
+ */
+export interface WorkflowAgentEvent {
+	readonly type: 'workflow_agent'
+	readonly runId: string
+	readonly state: WorkflowAgentState
+	readonly index: number
+	readonly label: string
+	readonly phaseIndex?: number
+	readonly phaseTitle?: string
+	readonly agentType?: string
+	readonly model?: string
+	readonly queuedAt: number
+	readonly startedAt?: number
+	readonly finishedAt?: number
+	readonly lastProgressAt: number
+	readonly tokens: number
+	readonly toolCalls: number
+	readonly lastToolName?: string
+	readonly lastToolSummary?: string
+	readonly promptPreview: string
+	readonly resultPreview?: string
+	readonly error?: string
+	readonly skipped?: boolean
+}
+
+export interface WorkflowLogEvent {
+	readonly type: 'workflow_log'
+	readonly runId: string
+	readonly message: string
+	readonly at: number
+}
+
+export type WorkflowFinishStatus = 'completed' | 'failed' | 'stopped'
+
+export interface WorkflowUsage {
+	/** Agents the script asked for and the runtime accepted. */
+	readonly agents: number
+	readonly agentsDone: number
+	readonly agentsFailed: number
+	readonly agentsSkipped: number
+	readonly tokens: number
+	readonly toolCalls: number
+	readonly elapsedMs: number
+}
+
+export interface WorkflowFinishedEvent {
+	readonly type: 'workflow_finished'
+	readonly runId: string
+	readonly status: WorkflowFinishStatus
+	readonly result?: unknown
+	readonly error?: string
+	readonly usage: WorkflowUsage
+	readonly at: number
+}
+
+export type WorkflowEvent =
+	| WorkflowStartedEvent
+	| WorkflowPhaseEvent
+	| WorkflowAgentEvent
+	| WorkflowLogEvent
+	| WorkflowFinishedEvent
+
+export type WorkflowPhaseStatus = 'not-started' | 'running' | 'done' | 'failed'
+
+export interface WorkflowPhaseSummary {
+	/** 0 for the derived "Agents" group, which has no phase index. */
+	readonly index: number
+	readonly title: string
+	readonly detail?: string
+	readonly status: WorkflowPhaseStatus
+	readonly agents: number
+	readonly done: number
+	readonly failed: number
+	readonly tokens: number
+}
+
+/** Append-only audit records, one JSON object per line. */
+export type WorkflowJournalRecord =
+	| {
+			readonly type: 'run_started'
+			readonly at: number
+			readonly runId: string
+			readonly scriptSha256: string
+			readonly scriptBytes: number
+			readonly meta: WorkflowMeta
+			readonly args: unknown
+			readonly limits: WorkflowResolvedLimits
+	  }
+	| {
+			readonly type: 'phase'
+			readonly at: number
+			readonly index: number
+			readonly title: string
+			readonly declared: boolean
+	  }
+	| {
+			readonly type: 'agent_request'
+			readonly at: number
+			readonly index: number
+			readonly label: string
+			readonly phaseIndex?: number
+			readonly phaseTitle?: string
+			readonly promptPreview: string
+			readonly promptSha256: string
+			readonly options: {
+				readonly agentType?: string
+				readonly model?: string
+				readonly effort?: string
+				readonly schema: boolean
+			}
+	  }
+	| {
+			readonly type: 'agent_outcome'
+			readonly at: number
+			readonly index: number
+			readonly state: 'done' | 'error' | 'skipped'
+			readonly tokens: number
+			readonly toolCalls: number
+			readonly queuedAt: number
+			readonly startedAt?: number
+			readonly finishedAt: number
+			readonly resultPreview?: string
+			readonly error?: string
+	  }
+	| { readonly type: 'log'; readonly at: number; readonly message: string }
+	| {
+			readonly type: 'run_finished'
+			readonly at: number
+			readonly status: WorkflowFinishStatus
+			readonly result?: unknown
+			readonly error?: string
+			readonly usage: WorkflowUsage
+	  }
+
+/** Where a run's audit trail goes. Injected so the SDK stays host-agnostic. */
+export interface WorkflowJournal {
+	/** Called once, before the first record, with the exact script text. */
+	writeScript?(source: string, sha256: string): Promise<void> | void
+	append(record: WorkflowJournalRecord): Promise<void> | void
+}
+
+export interface WorkflowLimits {
+	/** Agents running at once. Default `min(8, cpus - 2)`, at least 1; at most 16. */
+	readonly maxConcurrency?: number
+	/** Agents one run may start. Default 200; at most 1000. */
+	readonly maxAgents?: number
+	/** UTF-8 script size. Default 256 KiB. */
+	readonly maxSourceBytes?: number
+	/** Interpreter memory. Default 64 MiB. */
+	readonly memoryLimitBytes?: number
+	/** One value crossing the bridge, either way. Default 1 MiB. */
+	readonly maxValueBytes?: number
+	/** Stop admitting new agents once this many tokens are spent. Default: none. */
+	readonly tokenBudget?: number
+	/** Wall clock for the whole run. Default 6 hours. */
+	readonly maxDurationMs?: number
+	/** One synchronous stretch of script execution. Default 2 seconds. */
+	readonly cpuSliceMs?: number
+	/** All synchronous script execution together. Default 60 seconds. */
+	readonly cpuTotalMs?: number
+}
+
+export interface WorkflowResolvedLimits {
+	readonly maxConcurrency: number
+	readonly maxAgents: number
+	readonly maxSourceBytes: number
+	readonly memoryLimitBytes: number
+	readonly maxValueBytes: number
+	readonly tokenBudget?: number
+	readonly maxDurationMs: number
+	readonly cpuSliceMs: number
+	readonly cpuTotalMs: number
+}
+
+/** Lets the host act on one running agent. Handed to `onControl`. */
+export interface WorkflowControl {
+	/** Skip an agent: queued ones never start, running ones are aborted. Its `agent()` resolves `null`. */
+	skipAgent(index: number): boolean
+}
+
+export interface WorkflowRunOptions {
+	/** The script, including its `export const meta` literal. Untrusted. */
+	readonly script: string
+	/** JSON handed to the script as `args`. */
+	readonly args?: unknown
+	readonly limits?: WorkflowLimits
+	readonly spawnAgent: WorkflowSpawnAgent
+	readonly journal?: WorkflowJournal
+	readonly signal?: AbortSignal
+	readonly onEvent?: (event: WorkflowEvent) => void
+	readonly onControl?: (control: WorkflowControl) => void
+	/** Default: a fresh `w` + 8 base36 id. */
+	readonly runId?: string
+}
+
+export interface WorkflowRunResult {
+	readonly runId: string
+	readonly status: WorkflowFinishStatus
+	/** What the script returned (`completed` only). */
+	readonly result?: unknown
+	readonly error?: string
+	readonly usage: WorkflowUsage
+	readonly phases: readonly WorkflowPhaseSummary[]
+	/** True when the script logged more than the output cap and later lines were dropped. */
+	readonly logsTruncated: boolean
+	/** Set when the journal could not be written; the run itself was not affected. */
+	readonly journalError?: string
+}

package/src/index.ts

@@ -19,6 +19,10 @@ export {
 	UnknownBackgroundJobError,
 	bindOwner,
 } from './runtime/jobs/registry.js'
+export {
+	createBackgroundJobId,
+	isBackgroundJobId,
+} from './runtime/jobs/job-id.js'
 export type {
 	BackgroundJob,
 	BackgroundJobOutput,

package/src/plugin/shell-hook.ts

@@ -231,7 +231,8 @@ export function runShellHook(
 				// its own — the hook's deadline becomes the grandchild's.
 				detached: process.platform !== 'win32',
 				// A hook has always run under `sh`, whatever shell the `bash` tool
-				// chose. Windows has no `sh`, so there the host's own shell runs it.
+				// chose. Windows has no `sh`, so there the host's own shell runs it: Git Bash
+				// when installed, cmd.exe when not.
 				...(process.platform === 'win32'
 					? {}
 					: { shell: { path: 'sh', dialect: 'sh', source: 'sh' } as const }),

package/src/process/kill-tree.ts

@@ -1,6 +1,47 @@
 import { execFileSync } from 'node:child_process'
 import type { spawn } from 'node:child_process'
 
+/**
+ * Git Bash children that the Windows process tree cannot reach.
+ *
+ * Git for Windows' msys runtime starts a command that is not the last of its
+ * line by `fork`, and the process that forked is gone by the time the command
+ * runs: the command's Windows parent no longer exists, so `taskkill /T` walks
+ * from the shell to its child and never finds the grandchild (`sleep 60; echo`,
+ * `cd app && npm start & wait`). Each such shell is started with a unique tag
+ * in its environment, which every descendant inherits however it was started;
+ * the tag is how the tree is found again.
+ */
+const MSYS_SHELLS = new WeakMap<object, { readonly bash: string; readonly tag: string }>()
+
+/** Remember how to find every process a Git Bash child started. Called by the spawn. */
+export function registerMsysShell(child: object, shell: { bash: string; tag: string }): void {
+	MSYS_SHELLS.set(child, shell)
+}
+
+/** The environment variable that carries the tag. */
+export const MSYS_TAG_VARIABLE = 'NAMZU_SHELL_TAG'
+
+/** Kill every process whose environment carries the tag, from inside the msys runtime. */
+function killMsysTagged(shell: { readonly bash: string; readonly tag: string }): void {
+	// `$$` is skipped so the killer cannot end itself. Parameter expansion keeps
+	// the script to the two programs (grep, kill) the launcher puts on PATH.
+	const script = [
+		`for f in $(grep -laF "${MSYS_TAG_VARIABLE}=${shell.tag}" /proc/[0-9]*/environ 2>/dev/null); do`,
+		'p=${f#/proc/}; p=${p%/environ}; [ "$p" != "$$" ] && kill -9 $p;',
+		'done',
+	].join(' ')
+	try {
+		execFileSync(shell.bash, ['-c', script], {
+			stdio: 'ignore',
+			windowsHide: true,
+			timeout: 5000,
+		})
+	} catch {
+		// Nothing tagged was left, or the runtime could not start: taskkill still runs.
+	}
+}
+
 /** The system's own taskkill, so a PATH entry cannot stand in for it. */
 function taskkillPath(): string {
 	const root = process.env.SystemRoot ?? process.env.windir
@@ -46,6 +87,8 @@ export function killTree(child: ReturnType<typeof spawn>, signal: NodeJS.Signals
 	if (!child.pid) return
 	try {
 		if (process.platform === 'win32') {
+			const msys = MSYS_SHELLS.get(child)
+			if (msys !== undefined) killMsysTagged(msys)
 			execFileSync(taskkillPath(), ['/pid', String(child.pid), '/t', '/f'], {
 				stdio: 'ignore',
 				windowsHide: true,

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 } : {}),
 					},
 				}