@namzu/sdk 22.1.0 → 25.0.0

package/src/runtime/query/tool-pause.ts

@@ -32,6 +32,43 @@ import type { PendingAnswers, QuestionParkRecorder } from './question-park.js'
  */
 export const pauseId = (toolUseId: string, name: string): string => `${toolUseId}:${name}`
 
+/**
+ * Does this pause id belong to `callId`?
+ *
+ * The other half of the scheme above, and it lives beside the mint rather
+ * than at the gate that asks it, so the two cannot drift apart again. They
+ * already had: the resume gate compared the whole parked id against a raw
+ * tool-use id, which a composite can never equal, so a pause raised
+ * through {@link createToolPause} was refused by every cross-process
+ * resume — while the built-in question tool, whose `questionId` IS the raw
+ * id, passed the same gate and worked.
+ *
+ * Asked against an id actually present in the turn rather than by
+ * splitting the composite on `:`. The left half is the provider's tool-use
+ * id and nothing forbids a colon in it, so a split takes `call:9:confirm`
+ * apart at the wrong place and then compares against `call` — a string no
+ * provider minted. Testing a `<callId>:` prefix asks about candidates that
+ * exist instead.
+ *
+ * It is not exact, and the inexactness is bounded rather than absent: a
+ * call whose id is literally `call` matches a pause raised on `call:9`.
+ * That costs nothing while the real call is also in the turn, because the
+ * pause does belong to a call there; and when it is not, the answer is
+ * filed under a key no tool asks for, so the tool asks again. A resume
+ * that re-asks, never one that misdelivers — routing below is still an
+ * exact key match.
+ *
+ * Membership only — is there a call in this turn that this pause was
+ * raised from. The full composite still ROUTES the answer, by exact key in
+ * `PendingAnswers`, which is what keeps a call that pauses twice from
+ * delivering its second answer against its first question.
+ *
+ * Every sentence above that names a condition and an outcome is pinned in
+ * `__tests__/tool-pause.test.ts`, under "the id a resume gate matches on".
+ */
+export const isPauseForCall = (pause: string, callId: string): boolean =>
+	pause === callId || pause.startsWith(`${callId}:`)
+
 interface ToolPauseDeps {
 	readonly runId: RunId
 	readonly toolUseId: string

package/src/runtime/query/tooling.ts

@@ -6,6 +6,7 @@ import type { PermissionMode } from '../../types/permission/index.js'
 import type { RunEvent } from '../../types/run/index.js'
 import type { RequestToolPause, ToolRegistryContract } from '../../types/tool/index.js'
 import type { RepairToolCall } from '../../types/tool/repair.js'
+import type { BackoffPolicy } from '../../utils/backoff.js'
 import type { Logger } from '../../utils/logger.js'
 import { ToolExecutor } from './executor.js'
 
@@ -22,6 +23,7 @@ export interface ToolingBootstrapConfig {
 	invocationState?: InvocationState
 	pluginManager?: PluginLifecycleManager
 	toolTimeoutMs?: number
+	toolRetryBackoff?: Partial<BackoffPolicy>
 	maxToolConcurrency?: number
 	maxToolOutputChars?: number
 	maxToolContentBytes?: number
@@ -50,6 +52,9 @@ export class ToolingBootstrap {
 				invocationState: config.invocationState,
 				pluginManager: config.pluginManager,
 				...(config.toolTimeoutMs !== undefined ? { toolTimeoutMs: config.toolTimeoutMs } : {}),
+				...(config.toolRetryBackoff !== undefined
+					? { toolRetryBackoff: config.toolRetryBackoff }
+					: {}),
 				...(config.maxToolConcurrency !== undefined
 					? { maxToolConcurrency: config.maxToolConcurrency }
 					: {}),

package/src/types/agent/reactive.ts

@@ -86,6 +86,7 @@ export interface ReactiveAgentConfig extends BaseAgentConfig {
 	retry?: QueryParams['retry']
 	emergencySave?: boolean
 	toolTimeoutMs?: number
+	toolRetryBackoff?: QueryParams['toolRetryBackoff']
 	maxToolConcurrency?: number
 	maxToolOutputChars?: number
 	/**

package/src/types/run/step.ts

@@ -1,6 +1,7 @@
 import type { CostInfo, TokenUsage } from '../common/index.js'
 import type { MessageId } from '../ids/index.js'
 import type { ToolCall } from '../message/index.js'
+import type { ProviderErrorCode } from '../provider/errors.js'
 
 /**
  * What one iteration of the agent loop did.
@@ -55,13 +56,56 @@ export interface StepResult {
 	 * it is handed.
 	 */
 	servedBy?: StepProvenance
-	messageId: MessageId
+	/**
+	 * The assistant message this step produced.
+	 *
+	 * Absent only on a step whose iteration ended before the model's message
+	 * was announced — a compaction failure, a lifecycle hook that threw, a
+	 * transport error raised before the first chunk. Absence is left meaning
+	 * "there was no message" rather than filled with an id the event stream
+	 * never carried: a `messageId` a reader cannot find a `message_started`
+	 * for is worse evidence than no id at all, because it invites the
+	 * correlation and then loses it.
+	 *
+	 * Present, and correlatable, on every step whose iteration got as far as
+	 * the provider call — including one that failed mid-stream. The loop
+	 * mints the id before the call that announces it, and a dying stream
+	 * emits `message_completed` on its way out, so the events carry both
+	 * ends of the message a failed step points at.
+	 */
+	messageId?: MessageId
 	/** Assistant text for this step, if any. */
 	content: string | null
 	toolCalls: readonly ToolCall[]
-	/** Tool outcomes, in the same order as `toolCalls`. */
+	/**
+	 * Tool outcomes, in the same order as `toolCalls`.
+	 *
+	 * Shorter than `toolCalls` on a step that ended in failure: only the
+	 * outcomes that exist are recorded, so a call with no entry here reads
+	 * as "never came back" rather than as an empty success. Pair by
+	 * `toolCallId`, not by index.
+	 */
 	toolResults: readonly StepToolResult[]
-	finishReason: 'stop' | 'tool_calls' | 'length' | 'content_filter'
+	/**
+	 * How the turn ended.
+	 *
+	 * `error` and `cancelled` are not provider verdicts — no provider reports
+	 * them — but a step exists for a failed iteration too, and it has to say
+	 * how it ended in the same field a reader already sorts by. `error` comes
+	 * with {@link failure}; `cancelled` means a Stop tore the turn down and
+	 * there is no failure to report.
+	 */
+	finishReason: 'stop' | 'tool_calls' | 'length' | 'content_filter' | 'error' | 'cancelled'
+	/**
+	 * What went wrong, on a step with `finishReason: 'error'`.
+	 *
+	 * Absent everywhere else. A run whose ledger is complete except on the
+	 * turns that failed reads as "nothing went wrong" precisely when
+	 * something did, which is worse than an absent record — so the failed
+	 * turn gets the same record as every other, and this is what makes it
+	 * legible as a failure.
+	 */
+	failure?: StepFailure
 	/** Usage for THIS step, not the run's cumulative total. */
 	usage: TokenUsage
 	/** Cost delta attributable to this step. Zero without a pricing table. */
@@ -88,6 +132,35 @@ export interface StepProvenance {
 	readonly chainIndex: number
 }
 
+/**
+ * Why a step ended in `finishReason: 'error'`.
+ *
+ * The step-level counterpart of the pair a failed run already carries —
+ * {@link import('./entity.js').Run.lastError} and
+ * {@link import('./entity.js').Run.lastProviderError} — and shaped from the
+ * same classification, so the two agree when the failed step is the one that
+ * ended the run. What a run records once, a run of twenty iterations records
+ * per iteration, which is the difference between "this run failed" and "this
+ * turn failed, and the next four succeeded".
+ */
+export interface StepFailure {
+	/** The failure's message, as the iteration's span and log recorded it. */
+	readonly message: string
+	/**
+	 * Where the classifier placed it.
+	 *
+	 * `unknown` for a failure that is not a provider failure at all — a
+	 * plugin hook that threw, a bug in a tool wrapper. That is the honest
+	 * reading of the code's own contract ("unclassifiable"), and it is left
+	 * saying so rather than being given a more specific-looking code.
+	 */
+	readonly code: ProviderErrorCode
+	/** HTTP status, when the failure carried one. */
+	readonly status?: number
+	/** Whether sending the same request again could have worked. */
+	readonly retryable: boolean
+}
+
 export interface StepToolResult {
 	toolCallId: string
 	toolName: string

package/src/utils/backoff.ts

@@ -0,0 +1,70 @@
+/**
+ * Exponential backoff with full jitter, and an abortable sleep.
+ *
+ * Both were private to `provider/retry.ts`, which is where they were needed
+ * first and is not where they stop being needed. The tool executor's in-loop
+ * retry re-ran a failed call immediately, several times, which is the pattern
+ * most likely to prolong the very condition it is retrying against — and the
+ * correct implementation was one directory away, already reviewed, already
+ * doing the hard part right.
+ *
+ * So they live here, in one copy, and both retry loops call them. A second
+ * implementation of a backoff curve is a second thing to get wrong, and the
+ * two would drift on exactly the axis nobody re-derives: jitter.
+ */
+
+/** The shape a backoff curve needs. */
+export interface BackoffPolicy {
+	/** First backoff, doubled each attempt. */
+	readonly initialDelayMs: number
+	/** Ceiling for a single backoff, before jitter. */
+	readonly maxDelayMs: number
+}
+
+/**
+ * Full jitter (AWS's formulation): sleep a uniform random amount in
+ * `[0, backoff]` rather than `backoff` exactly. Equal-jitter and no-jitter
+ * both keep a fleet of clients that failed together retrying together;
+ * full jitter is what actually spreads a thundering herd.
+ *
+ * `attempt` is 0-based: attempt 0 draws from `[0, initialDelayMs]`.
+ *
+ * The concurrency this matters for is not hypothetical on the tool path. A
+ * model emits a batch of parallel calls, they hit one rate-limited endpoint
+ * together, and they fail together — so a fixed delay would resynchronise
+ * them on every attempt, which is a herd this loop creates itself.
+ */
+export function backoffWithJitter(
+	attempt: number,
+	policy: BackoffPolicy,
+	random: () => number = Math.random,
+): number {
+	const exponential = Math.min(policy.initialDelayMs * 2 ** attempt, policy.maxDelayMs)
+	return Math.round(random() * exponential)
+}
+
+/**
+ * Sleep, unless the signal says not to.
+ *
+ * Rejects with the signal's reason when aborted — before sleeping if it is
+ * already aborted, and mid-sleep otherwise. A caller that must not throw over
+ * an abort catches it; a caller that wants the abort to propagate does not.
+ */
+export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+	if (ms <= 0) return Promise.resolve()
+	return new Promise<void>((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(signal.reason)
+			return
+		}
+		const timer = setTimeout(() => {
+			signal?.removeEventListener('abort', onAbort)
+			resolve()
+		}, ms)
+		const onAbort = () => {
+			clearTimeout(timer)
+			reject(signal?.reason)
+		}
+		signal?.addEventListener('abort', onAbort, { once: true })
+	})
+}