@namzu/sdk 50.1.0 → 51.1.0

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
 }
@@ -395,6 +408,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 +420,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

@@ -381,6 +381,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

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.
  *