@namzu/sdk 51.0.0 → 52.0.0

package/src/types/hitl/index.ts

@@ -55,6 +55,14 @@ export type HITLResumeDecision =
 			 * listed here for an unmarked call is ignored rather than trusted.
 			 */
 			skillGranted?: readonly string[]
+			/**
+			 * Ids of calls approved on the strength of a `pre_tool_use` hook's
+			 * `allow` ({@link ToolCallSummary.hookGrant}), with nobody asked.
+			 *
+			 * Audited like `skillGranted`, and ignored for any id whose call did
+			 * not carry the mark.
+			 */
+			hookGranted?: readonly string[]
 	  }
 	| {
 			action: 'modify_tools'
@@ -77,6 +85,15 @@ export type HITLResumeDecision =
 			action: 'answer_question'
 			selectedOptionIds: string[]
 			freeText?: string
+			/**
+			 * One answer per question of a batch (`UserQuestionData.questions`).
+			 * When present it is the answer; `selectedOptionIds`/`freeText`
+			 * then carry nothing the tool reads (send `[]`). Absent on a
+			 * single-question park, and on a batch from a host that only
+			 * knows one question — then `selectedOptionIds`/`freeText`
+			 * answer the first question and the rest are unanswered.
+			 */
+			answers?: readonly UserQuestionAnswer[]
 			/**
 			 * Echo of `UserQuestionData.questionId` — the misdirection
 			 * guard. The park/resolve registry on hosts is typically
@@ -176,6 +193,28 @@ export interface ToolCallSummary {
 	 * and `strict`. A host's own handler may ignore it.
 	 */
 	skillGrant?: { readonly skill: string }
+	/**
+	 * What a `pre_tool_use` hook answered about approving this call, as the
+	 * hooks reported it. `ask` is acted on by the kernel (it makes the call an
+	 * explicit review); `allow` is acted on only through {@link hookGrant}.
+	 */
+	hookPermission?: {
+		readonly decision: 'allow' | 'ask'
+		readonly reason?: string
+	}
+	/**
+	 * Present when a `pre_tool_use` hook said `allow` and nothing stronger
+	 * stands in the way.
+	 *
+	 * Marked on the same terms as {@link skillGrant}: only a call the
+	 * operator's policy left to review (no `deny`, no explicit `ask` rule, no
+	 * hook `ask`), that is not destructive, carries no {@link escalation} and
+	 * is not one the tool always asks about. A sandbox escape, a path outside
+	 * the roots, a tool's own `requiresApproval`, a rule's review and the
+	 * dangerous-pattern floor therefore all still reach a person, or refuse.
+	 * `plan` and `strict` refuse a marked call exactly as they refuse any other.
+	 */
+	hookGrant?: { readonly reason?: string }
 }
 
 /** See {@link ToolCallSummary.escalation}. */
@@ -218,6 +257,27 @@ export interface ToolCallEscalation {
 	 * where a program name is actually decided.
 	 */
 	unknownProgram?: string
+	/**
+	 * Absolute paths this call writes that are protected in every mode: git
+	 * hooks and config, shell rc files, editor and tool configuration, the
+	 * project's own `.namzu` directory (see `authorization/protected-paths.ts`
+	 * for the list). A write there plants something that runs later, outside
+	 * the turn, so it is asked about every time and refused when nobody can be
+	 * asked; no rule, mode or remembered approval covers it. Set for the file
+	 * tools' declared path and for the visible write targets of a shell line:
+	 * output redirections, and the operands of `cp`, `mv`, `tee`, `touch`,
+	 * `mkdir`, `rm`, `rmdir` and `sed -i`.
+	 */
+	protectedPaths?: readonly string[]
+	/**
+	 * Why a shell line removes something it must not: the file system root, a
+	 * top-level directory, the home directory, the working directory or one of
+	 * its parents, a glob that crosses directories, or a target a variable or
+	 * substitution may empty. The flags do not matter, only the targets. Asked
+	 * about every time and refused when nobody can be asked. Present only for a
+	 * tool that declares `commandArgument`.
+	 */
+	dangerousRemoval?: string
 }
 
 export interface ToolModification {
@@ -250,6 +310,12 @@ export interface UserQuestionOption {
 	 * Absent, not `false`, on every other option.
 	 */
 	recommended?: boolean
+	/**
+	 * Plain text or markdown a host may show beside the option list while this
+	 * option is focused (a snippet, a mock-up, a side-by-side). Optional and
+	 * never required to answer; a host that has nowhere to show it ignores it.
+	 */
+	preview?: string
 }
 
 /**
@@ -267,6 +333,44 @@ export interface UserQuestionData {
 	options: UserQuestionOption[]
 	multiSelect: boolean
 	allowFreeText: boolean
+	/**
+	 * Present when one `ask_user_question` call carries several related
+	 * questions (two to four; a single question leaves this out). The
+	 * top-level `question`, `header`, `options`, `multiSelect` and
+	 * `allowFreeText` then mirror the FIRST entry, so a host that does not
+	 * know this field still shows a coherent question and answers it; the
+	 * rest read as unanswered.
+	 *
+	 * A host shows all of them together, collects every answer, and returns
+	 * one {@link UserQuestionAnswer} per question it has an answer for through
+	 * `answer_question.answers`.
+	 */
+	questions?: readonly UserQuestionItem[]
+}
+
+/**
+ * One question of a batch. `id` is stable: the asking `tool_use_id`, `#`, and
+ * the question's zero-based position, so an answer names the question it
+ * belongs to even when a host shows them in another order.
+ */
+export interface UserQuestionItem {
+	id: string
+	question: string
+	header?: string
+	options: UserQuestionOption[]
+	multiSelect: boolean
+	allowFreeText: boolean
+}
+
+/**
+ * The answer to one question of a batch. A question with no entry was not
+ * answered; an entry with no selection and no text counts the same.
+ */
+export interface UserQuestionAnswer {
+	/** {@link UserQuestionItem.id}. */
+	questionId: string
+	selectedOptionIds: string[]
+	freeText?: string
 }
 
 export interface PlanApprovalData {

package/src/types/message/index.ts

@@ -352,11 +352,13 @@ export const RUNTIME_CONTEXT_MESSAGE_KINDS = [
 	'answer-review',
 	'auto-continuation',
 	'channel-message',
+	'hook-feedback',
 	'host-observation',
 	'job-exit',
 	'limit-finalization',
 	'peer-message',
 	'peer-notice',
+	'reminder',
 	'repeat-call',
 	'steering',
 	'step-context',

package/src/types/plugin/index.ts

@@ -107,6 +107,24 @@ export type PluginHookEvent =
 	| 'turn_interrupt'
 	| 'pre_tool_use'
 	| 'post_tool_use'
+	/**
+	 * A tool call ended in failure. Fired after `post_tool_use` for the same
+	 * call, only when the result is a failure. Carries `toolName`, `toolInput`
+	 * and `toolResult`.
+	 */
+	| 'post_tool_use_failure'
+	/**
+	 * A person is about to be asked whether a tool call may run. Carries
+	 * `toolName` and `toolInput`. A hook may answer before the question is
+	 * shown: `continue` with `permission: { decision: 'allow' }` approves the
+	 * call (never one that is always asked about), `skip` refuses it.
+	 */
+	| 'permission_request'
+	/**
+	 * The host wants the operator's attention: a review is waiting, or a turn
+	 * settled. Carries `notification` (`type` and `message`). Observational.
+	 */
+	| 'notification'
 	| 'pre_llm_call'
 	| 'post_llm_call'
 	| 'iteration_start'
@@ -139,6 +157,9 @@ export function assertPluginHookEvent(event: PluginHookEvent): void {
 		case 'turn_interrupt':
 		case 'pre_tool_use':
 		case 'post_tool_use':
+		case 'post_tool_use_failure':
+		case 'permission_request':
+		case 'notification':
 		case 'pre_llm_call':
 		case 'post_llm_call':
 		case 'iteration_start':
@@ -196,6 +217,16 @@ export interface PluginCompactionInfo {
 	readonly contextWindowTokens: number
 }
 
+/** What a `notification` hook is shown. */
+export interface PluginNotificationInfo {
+	/**
+	 * `approval_required` (a review is waiting), `turn_settled` (a turn ended) or
+	 * `idle_prompt` (the host has waited for the operator for a while).
+	 */
+	readonly type: 'approval_required' | 'turn_settled' | 'idle_prompt'
+	readonly message: string
+}
+
 export interface PluginHookContext {
 	/** The turn the hook fired in. Absent on `session_start` and `session_end`. */
 	readonly turnId?: TurnId
@@ -214,6 +245,15 @@ export interface PluginHookContext {
 	readonly toolName?: string
 	readonly toolInput?: unknown
 	readonly toolResult?: ToolResult
+	/** What the host is telling the operator, on `notification`. */
+	readonly notification?: PluginNotificationInfo
+	/**
+	 * On `turn_end` and `subagent_stop` when an earlier answer to the same
+	 * event kept the turn going: the hook is being asked again about a turn it
+	 * already refused to let end. A hook that always refuses would otherwise
+	 * keep the model working until the turn's own limits stop it.
+	 */
+	readonly stopHookActive?: boolean
 	readonly iteration?: number
 	/**
 	 * Why the turn was stopped, on `turn_interrupt`.
@@ -267,8 +307,41 @@ export interface PluginHookContext {
 	readonly signal?: AbortSignal
 }
 
+/**
+ * What a hook may say about a tool call beyond letting it run or not. Only
+ * `allow` and `ask` exist here: a refusal is `skip`, which always wins.
+ *
+ * `allow` stands in for the person's yes ONLY on a call that would have been
+ * asked about for no reason beyond "it changes something". It never covers a
+ * sandbox escape, a path outside the roots, a call the tool declares it always
+ * needs approval for, a call a rule sent to review explicitly, or one the tool
+ * declares destructive; and it never reopens what a rule denied.
+ * `ask` makes the call go to a person even where a rule or the tool's own
+ * read-only declaration would have let it through.
+ */
+export interface PluginHookPermission {
+	readonly decision: 'allow' | 'ask'
+	readonly reason?: string
+}
+
+/** Extra facts a hook may attach to the verdicts that let the work go on. */
+export interface PluginHookNotes {
+	/**
+	 * Text for the model. On a tool event it is appended to what the model
+	 * reads of that call; on `user_prompt_submit` it joins the turn's context.
+	 */
+	readonly context?: string
+	/** Stop the turn once the current step is done. `reason` is shown to the operator. */
+	readonly halt?: { readonly reason: string }
+	/** A warning for the operator, reported through the logger. */
+	readonly notice?: string
+}
+
 export type PluginHookResult =
-	| { action: 'continue' }
+	| ({
+			action: 'continue'
+			permission?: PluginHookPermission
+	  } & PluginHookNotes)
 	/**
 	 * Add to what the model is told, without changing anything else.
 	 *
@@ -278,8 +351,12 @@ export type PluginHookResult =
 	 * it is rejected, because a tool result is not a place for context.
 	 */
 	| { action: 'annotate'; text: string }
-	| { action: 'skip'; reason: string }
-	| { action: 'modify'; input: unknown }
+	| ({ action: 'skip'; reason: string } & PluginHookNotes)
+	| ({
+			action: 'modify'
+			input: unknown
+			permission?: PluginHookPermission
+	  } & PluginHookNotes)
 	| { action: 'error'; message: string }
 	| { action: 'retry' }
 	/**
@@ -333,9 +410,15 @@ export type PluginHookResultFor<E extends PluginHookEvent> = E extends 'user_pro
 		? Extract<PluginHookResult, { action: 'continue' | 'skip' | 'modify' | 'error' }>
 		: E extends 'post_tool_use'
 			? Extract<PluginHookResult, { action: 'continue' | 'replace' | 'retry' | 'error' }>
-			: E extends 'turn_interrupt' | 'session_start' | 'session_end'
-				? Extract<PluginHookResult, { action: 'continue' }>
-				: Extract<PluginHookResult, { action: 'continue' | 'error' }>
+			: E extends 'post_tool_use_failure'
+				? Extract<PluginHookResult, { action: 'continue' | 'error' }>
+				: E extends 'permission_request'
+					? Extract<PluginHookResult, { action: 'continue' | 'skip' }>
+					: E extends 'turn_end' | 'subagent_stop' | 'pre_compact'
+						? Extract<PluginHookResult, { action: 'continue' | 'skip' | 'error' }>
+						: E extends 'turn_interrupt' | 'session_start' | 'session_end' | 'notification'
+							? Extract<PluginHookResult, { action: 'continue' }>
+							: Extract<PluginHookResult, { action: 'continue' | 'error' }>
 
 /** The event and its handler verdict stay correlated, including in hook arrays. */
 export type PluginHookDefinition<E extends PluginHookEvent = PluginHookEvent> =
@@ -344,21 +427,21 @@ export type PluginHookDefinition<E extends PluginHookEvent = PluginHookEvent> =
 				readonly event: E
 				readonly handler: (context: PluginHookContext) => Promise<PluginHookResultFor<E>>
 				/**
-				 * Lower runs first. Default 100.
+				 * Lower comes first in the answers. Default 100.
 				 *
-				 * Order was install order, which is neither declared nor stable — it
-				 * depends on when each plugin happened to be installed. That is fine
-				 * for hooks that only observe, and wrong for the ones that decide:
-				 * `executeHooks` SHORT-CIRCUITS on `skip` and `error`, so a hook that
-				 * denies a dangerous command only gets to deny it if it runs before
-				 * whatever else stops the chain. A guard that fires depending on
-				 * installation history is not a guard.
-				 *
-				 * Ties keep registration order, so plugins that never set a priority
-				 * behave exactly as before. Convention: guards below 100, observers
-				 * above.
+				 * The hooks of one event start together and none waits for another, so
+				 * priority no longer says who runs first; it says whose answer is read
+				 * first. The first refusal in that order is the one the model is told,
+				 * and of several rewrites the last in that order wins. Ties keep
+				 * registration order. Convention: guards below 100, observers above.
 				 */
 				readonly priority?: number
+				/**
+				 * Text for the operator's status line while this hook runs. Carried on
+				 * the `plugin_hook_executing` event; a host that draws no status line
+				 * ignores it.
+				 */
+				readonly statusMessage?: string
 			}
 		: never
 

package/src/types/provider/error.ts

@@ -45,4 +45,10 @@ export interface ProviderRequestErrorInit extends ProviderErrorInfo {
 	 * still welcome; what is not welcome is a raw body passed straight in.
 	 */
 	readonly detail?: string
+	/**
+	 * The provider's own `x-should-retry` verdict, when it sent one. Only `false`
+	 * is acted on: a provider that says the same request must not be sent again
+	 * is believed over the status code, so the retry loop leaves it alone.
+	 */
+	readonly shouldRetry?: boolean
 }

package/src/types/provider/errors.ts

@@ -54,6 +54,16 @@ export interface ProviderErrorInit {
 	readonly cause?: unknown
 }
 
+function shouldRetryHeader(link: Record<string, unknown>): false | undefined {
+	const headers = link.headers
+	if (!headers || typeof headers !== 'object') return undefined
+	const raw =
+		typeof (headers as Headers).get === 'function'
+			? (headers as Headers).get('x-should-retry')
+			: (headers as Record<string, unknown>)['x-should-retry']
+	return typeof raw === 'string' && raw.trim().toLowerCase() === 'false' ? false : undefined
+}
+
 /**
  * A `retryable` flag declared anywhere on the cause chain.
  *
@@ -72,6 +82,9 @@ export function declaredRetryable(err: unknown): boolean | undefined {
 	for (const link of causeChain(err)) {
 		const declared = link.retryable
 		if (typeof declared === 'boolean') return declared
+		// A raw vendor error that still carries its response headers: the
+		// provider's own `x-should-retry: false` is a first-hand "do not resend".
+		if (shouldRetryHeader(link) === false) return false
 	}
 	return undefined
 }
@@ -224,6 +237,39 @@ function chainMessages(err: unknown): string[] {
 	return out
 }
 
+/**
+ * What a provider said when prompt plus requested output together passed the
+ * window: the prompt size, the output cap that was asked for, and the window.
+ */
+export interface OutputOverflowFigures {
+	readonly inputTokens: number
+	readonly maxTokens: number
+	readonly contextLimit: number
+}
+
+/**
+ * Read the "input length and `max_tokens` exceed context limit: A + B > C"
+ * wording from a failure, anywhere on its cause chain.
+ *
+ * Different from a prompt that is too long on its own: here the prompt fits
+ * and only the requested output does not, so the remedy is a smaller
+ * `max_tokens`, not a smaller history. `undefined` means the failure does not
+ * carry those figures.
+ */
+export function readOutputOverflow(err: unknown): OutputOverflowFigures | undefined {
+	const pattern = /input length and `?max_tokens`? exceed context limit: (\d+) \+ (\d+) > (\d+)/i
+	for (const message of chainMessages(err)) {
+		const match = pattern.exec(message)
+		if (!match) continue
+		const inputTokens = Number.parseInt(match[1] ?? '', 10)
+		const maxTokens = Number.parseInt(match[2] ?? '', 10)
+		const contextLimit = Number.parseInt(match[3] ?? '', 10)
+		if (![inputTokens, maxTokens, contextLimit].every(Number.isFinite)) continue
+		return { inputTokens, maxTokens, contextLimit }
+	}
+	return undefined
+}
+
 /** Node/undici transport failures that mean "never reached the model". */
 const NETWORK_ERRNOS: ReadonlySet<string> = new Set([
 	'ECONNRESET',
@@ -395,6 +441,7 @@ function classifyFromProviderRequestError(
 		providerId?: unknown
 		status?: unknown
 		retryAfterMs?: unknown
+		shouldRetry?: unknown
 	}
 	if (typeof candidate.kind !== 'string') return undefined
 	const mapped = KIND_TO_CODE[candidate.kind]
@@ -406,7 +453,8 @@ function classifyFromProviderRequestError(
 	return new ProviderError({
 		code: mapped.code,
 		message: err.message,
-		retryable: mapped.retryable,
+		// The provider saying "do not resend" beats the kind's own verdict.
+		retryable: candidate.shouldRetry === false ? false : mapped.retryable,
 		cause: err,
 		...(typeof candidate.providerId === 'string'
 			? { providerId: candidate.providerId }

package/src/types/provider/stream.ts

@@ -173,6 +173,12 @@ export interface ProviderRetryNotice {
 	readonly status?: number
 	/** The delay came from the server's own `Retry-After`, not backoff. */
 	readonly serverDirected: boolean
+	/**
+	 * The failed attempt had already streamed text or reasoning, and the request
+	 * is being sent again from the start. Whatever that attempt produced is void
+	 * and the consumer must drop it before the next chunk.
+	 */
+	readonly restart?: boolean
 }
 
 /**

package/src/types/session/events.ts

@@ -279,11 +279,17 @@ type CoreSessionEvent =
 			 *   `tool_result`, so it was refused wholesale rather than sent to
 			 *   a provider that rejects the pairing. A reducer bug, and one
 			 *   `findSafeTrimIndex` exists to prevent.
+			 * - `breaker_open` — only with `compactionConfig.circuitBreaker`:
+			 *   three passes in a row failed, so automatic compaction is off for
+			 *   the rest of the turn. Sent once. `messages` is the live count.
+			 * - `refilling` — only with `compactionConfig.circuitBreaker`: the
+			 *   context filled back up within three iterations of a compaction,
+			 *   three times in a row, and the turn is stopping. Sent once.
 			 */
-			cause: 'reducer_threw' | 'shed_nothing' | 'split_tool_pair'
+			cause: 'reducer_threw' | 'shed_nothing' | 'split_tool_pair' | 'breaker_open' | 'refilling'
 			/** Unchanged, and stated so a reader need not infer it. */
 			messages: number
-			/** Present only for `reducer_threw`. */
+			/** For `reducer_threw`, the reducer's message; for `breaker_open` and `refilling`, the one line to show. */
 			error?: string
 	  }
 	| {
@@ -381,6 +387,11 @@ type CoreSessionEvent =
 			status?: number
 			/** The delay came from the server's own `Retry-After`. */
 			serverDirected: boolean
+			/**
+			 * The failed attempt had already streamed text or reasoning and the
+			 * request starts over: drop what this message showed so far.
+			 */
+			restart?: boolean
 	  }
 	/**
 	 * A member of the provider chain could not serve, and a later member has
@@ -987,6 +998,8 @@ type CoreSessionEvent =
 			turnId?: TurnId
 			pluginId: PluginId
 			hookEvent: PluginHookEvent
+			/** The hook's own text for a status line while it runs, when it declared one. */
+			statusMessage?: string
 	  }
 	| {
 			type: 'plugin_hook_completed'

package/src/types/session/records.ts

@@ -235,6 +235,7 @@ const stopReason = z.enum([
 	'stop_condition',
 	'step_refused',
 	'structured_output_failed',
+	'output_limit',
 	'answer_rejected',
 	'input_guardrail',
 	'output_guardrail',

package/src/types/session/stop-reason.ts

@@ -38,6 +38,11 @@ export type StopReason =
 	| 'step_refused'
 	/** The model never produced a valid structured output within its retries. */
 	| 'structured_output_failed'
+	/**
+	 * The model's reply was cut off at its output limit more times in a row
+	 * than `maxOutputContinuations` allows. Only with that option set.
+	 */
+	| 'output_limit'
 	/**
 	 * A host reviewer kept rejecting the answer and the turn ran out of
 	 * attempts.

package/src/types/tool/index.ts

@@ -1,3 +1,4 @@
+import type { ChildProcess } from 'node:child_process'
 import type { z } from 'zod'
 import type { CodeNavigationProvider } from '../code-navigation/index.js'
 // Type-only, and circular by design: a tool-result guardrail is described in
@@ -118,7 +119,24 @@ export interface BackgroundJobRegistryRef {
 		id: string
 		status: string
 	}
-	get(id: string): { id: string; status: string; exitCode?: number; error?: string }
+	get(id: string): {
+		id: string
+		status: string
+		exitCode?: number
+		error?: string
+	}
+	/**
+	 * Take over a process the caller already started and is waiting on, so a
+	 * foreground command that outran its timeout can keep running as a job
+	 * instead of being killed. Optional: a host without it (or a sandboxed
+	 * turn) keeps the kill. Throws when the owner is at its job cap.
+	 */
+	adopt?(params: {
+		command: string
+		child: ChildProcess
+		workingDirectory?: string
+		initialOutput?: readonly { readonly stream: 'stdout' | 'stderr'; readonly text: string }[]
+	}): { id: string; status: string }
 	/**
 	 * 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
@@ -483,15 +501,39 @@ export interface ToolContext {
 	 */
 	web?: {
 		readonly fetch?: {
-			fetch(request: { url: string; signal?: AbortSignal }): Promise<{
+			fetch(request: {
+				url: string
+				signal?: AbortSignal
+				/** `same-host` asks for a redirect to another site to be handed back, not followed. */
+				redirects?: 'follow' | 'same-host'
+				headers?: Readonly<Record<string, string>>
+			}): Promise<{
 				url: string
 				status: number
 				contentType?: string
 				body: string
 				truncated: boolean
 				redirects: readonly string[]
+				/** A redirect that was not followed; `body` is then empty. */
+				redirect?: { url: string; status: number }
 			}>
 		}
+		/**
+		 * Answers a prompt from a page with a small model. Optional: without
+		 * it `web_fetch` returns the page as markdown instead of an answer.
+		 */
+		readonly extract?: {
+			extract(request: {
+				url: string
+				prompt: string
+				content: string
+				instruction: string
+				body: string
+				signal?: AbortSignal
+				sessionId: string
+				turnId: string
+			}): Promise<string | undefined>
+		}
 		readonly search?: {
 			search(request: {
 				query: string
@@ -1103,6 +1145,15 @@ export interface ToolDefinition<TInput = unknown> extends ToolPresentation<TInpu
 	 * their external effects have stopped, and does not imply success.
 	 */
 	executionBarrier?: boolean
+	/**
+	 * The tool bounds its own output (a paged read, say), so the turn's default
+	 * per-result cap does not apply to it and its result is never replaced to
+	 * fit the per-message budget.
+	 *
+	 * Only the DEFAULT is lifted. A host that sets `maxToolOutputChars`
+	 * explicitly still bounds this tool's result by it.
+	 */
+	selfLimitingOutput?: boolean
 }
 
 /**

package/src/utils/backoff.ts

@@ -43,6 +43,27 @@ export function backoffWithJitter(
 	return Math.round(random() * exponential)
 }
 
+/**
+ * Exponential backoff that only ever adds jitter: the delay is the exponential
+ * step plus up to `ratio` of itself (a quarter by default), never less.
+ *
+ * Full jitter spreads a herd better but can answer a failure after a few
+ * milliseconds, which is a poor way to treat a server that just said it is
+ * struggling. This curve keeps the floor of every step, so a person watching a
+ * countdown sees a wait that grows the way the numbers on screen say it does.
+ *
+ * `attempt` is 0-based: attempt 0 draws from `[initialDelayMs, initialDelayMs * (1 + ratio)]`.
+ */
+export function backoffProportional(
+	attempt: number,
+	policy: BackoffPolicy,
+	random: () => number = Math.random,
+	ratio = 0.25,
+): number {
+	const exponential = Math.min(policy.initialDelayMs * 2 ** attempt, policy.maxDelayMs)
+	return Math.round(exponential + random() * ratio * exponential)
+}
+
 /**
  * Sleep, unless the signal says not to.
  *