@oh-my-pi/pi-ai 18.3.0 → 18.3.2

package/src/providers/anthropic-slow-mode.ts

@@ -0,0 +1,232 @@
+/**
+ * Anthropic subscription "slow mode" (Claude Code's `/low-priority`).
+ *
+ * After a Claude subscription account hits its 5-hour session limit, Anthropic
+ * may offer to keep serving it on spare capacity. A request opts in with
+ * `anthropic-usage-limit: slow`; the server reports the lane state back in
+ * `anthropic-ratelimit-unified-slow-*` response headers, and answers "no spare
+ * capacity right now" with a 429 `slot_busy` or a 529 overload that the client
+ * retries after the server-stated interval.
+ *
+ * Before the slow lane, the server may grant a small wrap-up allowance (drawn
+ * from the weekly limit) past the session limit: 2xx responses then carry
+ * `anthropic-ratelimit-unified-grace-{5h,7d}-utilization` above zero.
+ *
+ * This module owns the wire contract only (header names, parsing). The mode's
+ * state machine lives with the caller, which plugs into the Anthropic provider
+ * through {@link AnthropicSlowModeHooks}.
+ */
+import type { HeadersLike } from "../utils/retry-after";
+
+/** Request header that opts a first-party OAuth request into the slow lane. */
+export const ANTHROPIC_USAGE_LIMIT_HEADER = "anthropic-usage-limit";
+/** {@link ANTHROPIC_USAGE_LIMIT_HEADER} value selecting the slow lane. */
+export const ANTHROPIC_SLOW_USAGE_LIMIT = "slow";
+
+/** Server-side experiment arm; only `treatment` accounts may enter the slow lane. */
+export type AnthropicSlowOffer = "treatment" | "control";
+
+/** `anthropic-ratelimit-unified-slow-status` values; unknown strings map to `unrecognized`. */
+export type AnthropicSlowStatus =
+	| "active"
+	| "not_needed"
+	| "slot_busy"
+	| "weekly_limit"
+	| "budget_exhausted"
+	| "ineligible"
+	| "off"
+	| "unrecognized";
+
+/** Slow-lane facts carried by one Anthropic response (success or error). */
+export interface AnthropicSlowModeSignal {
+	offer?: AnthropicSlowOffer;
+	status?: AnthropicSlowStatus;
+	/** Server-stated interval between capacity retries. */
+	retryAfterMs?: number;
+	/** Server-stated ceiling on total time spent waiting for capacity. */
+	maxWaitMs?: number;
+	/** Fraction (0..1) of the weekly slow-lane allowance already used. */
+	budgetUtilization?: number;
+	/** Epoch seconds when the slow-lane allowance resets. */
+	budgetResetAtSec?: number;
+	/** Epoch seconds of `anthropic-ratelimit-unified-reset` (the limit that was hit). */
+	unifiedResetAtSec?: number;
+	/** Epoch seconds of the 5-hour window reset. */
+	fiveHourResetAtSec?: number;
+	/** Epoch seconds of the weekly window reset. */
+	weeklyResetAtSec?: number;
+	/** True when the response carries unified usage-limit claim headers (a limit wall). */
+	unifiedLimitClaim: boolean;
+	/** True when extra usage (overage) is serving this account. */
+	overageInUse: boolean;
+	/**
+	 * Wrap-up allowance usage (0..1) past the 5-hour and weekly limits; any
+	 * value above zero means the request ran on the allowance. Present only on
+	 * responses carrying `anthropic-ratelimit-unified-status`.
+	 */
+	graceUtilization?: { fiveHour: number; sevenDay: number };
+	/** True when `anthropic-ratelimit-unified-overage-status` lets extra usage serve requests. */
+	overageAllowed?: boolean;
+}
+
+/** One pre-content failure the provider hands to {@link AnthropicSlowModeHooks.onFailure}. */
+export interface AnthropicSlowModeFailure {
+	/** Account lane of the failed request (see {@link AnthropicSlowModeHooks}). */
+	lane: string;
+	httpStatus?: number;
+	/** 529 or an `overloaded_error` envelope. */
+	overloaded: boolean;
+	signal?: AnthropicSlowModeSignal;
+	/** Whether the failed request carried `anthropic-usage-limit: slow`. */
+	sentSlow: boolean;
+	/** Milliseconds this request has already spent waiting for slow-lane capacity. */
+	waitedMs: number;
+	/** Capacity waits already taken by this request. */
+	attempts: number;
+}
+
+/** Retry decision returned by {@link AnthropicSlowModeHooks.onFailure}. */
+export interface AnthropicSlowModeRetry {
+	/** Delay before resending; `0` resends immediately. */
+	delayMs: number;
+	/** True when the delay is a capacity wait (counts toward the max-wait budget). */
+	capacityWait: boolean;
+}
+
+/**
+ * Caller-owned slow-mode state machine. The Anthropic provider only consults
+ * it for first-party OAuth requests (`api.anthropic.com` with a subscription
+ * bearer); every other route ignores it.
+ *
+ * Slow-lane state belongs to one Claude account, so every call carries a
+ * `lane` key identifying the credential that served the request: `cred:<id>`
+ * for a stored credential, else `key:<hash>` of the bearer.
+ */
+export interface AnthropicSlowModeHooks {
+	/** Whether the next request on `lane` should carry `anthropic-usage-limit: slow`. */
+	isActive(lane: string): boolean;
+	/** Observe the slow-lane headers of a successful (2xx) response on `lane`. */
+	observe(signal: AnthropicSlowModeSignal, lane: string): void;
+	/**
+	 * Decide how to react to a failure that arrived before any content. Return
+	 * a retry to resend the request (with or without the slow header, per
+	 * {@link isActive}), or `undefined` to let normal error handling run.
+	 */
+	onFailure(
+		failure: AnthropicSlowModeFailure,
+	): AnthropicSlowModeRetry | undefined | Promise<AnthropicSlowModeRetry | undefined>;
+}
+
+const SLOW_HEADER_PREFIX = "anthropic-ratelimit-unified-slow-";
+
+function readHeader(headers: HeadersLike, name: string): string | undefined {
+	if (!headers) return undefined;
+	if (headers instanceof Headers) return headers.get(name) ?? undefined;
+	const direct = headers[name];
+	if (direct !== undefined) return direct;
+	for (const key in headers) {
+		if (key.toLowerCase() === name) return headers[key];
+	}
+	return undefined;
+}
+
+function readNonNegative(headers: HeadersLike, name: string): number | undefined {
+	const raw = readHeader(headers, name)?.trim();
+	if (!raw) return undefined;
+	const value = Number(raw);
+	return Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+
+/** Utilization header clamped to 0..1; absent or malformed reads as 0. */
+function readUtilization(headers: HeadersLike, name: string): number {
+	const value = readNonNegative(headers, name);
+	return value === undefined ? 0 : Math.min(1, value);
+}
+
+function parseStatus(raw: string | undefined): AnthropicSlowStatus | undefined {
+	if (raw === undefined) return undefined;
+	switch (raw.trim()) {
+		case "active":
+			return "active";
+		case "not_needed":
+			return "not_needed";
+		case "slot_busy":
+			return "slot_busy";
+		case "weekly_limit":
+			return "weekly_limit";
+		case "budget_exhausted":
+			return "budget_exhausted";
+		case "ineligible":
+			return "ineligible";
+		case "off":
+			return "off";
+		default:
+			return "unrecognized";
+	}
+}
+
+/**
+ * Parse the slow-lane and unified-limit headers relevant to slow mode.
+ * Returns `undefined` when the response carries none of them.
+ */
+export function parseAnthropicSlowModeHeaders(headers: HeadersLike): AnthropicSlowModeSignal | undefined {
+	if (!headers) return undefined;
+	const offerRaw = readHeader(headers, `${SLOW_HEADER_PREFIX}offer`)?.trim();
+	const offer = offerRaw === "treatment" || offerRaw === "control" ? offerRaw : undefined;
+	const status = parseStatus(readHeader(headers, `${SLOW_HEADER_PREFIX}status`));
+	const retryAfterSec = readNonNegative(headers, `${SLOW_HEADER_PREFIX}retry-after`);
+	const maxWaitSec = readNonNegative(headers, `${SLOW_HEADER_PREFIX}max-wait`);
+	const budgetUtilization = readNonNegative(headers, `${SLOW_HEADER_PREFIX}budget-utilization`);
+	const budgetResetAtSec = readNonNegative(headers, `${SLOW_HEADER_PREFIX}budget-reset`);
+	const unifiedResetAtSec = readNonNegative(headers, "anthropic-ratelimit-unified-reset");
+	const fiveHourResetAtSec = readNonNegative(headers, "anthropic-ratelimit-unified-5h-reset");
+	const weeklyResetAtSec = readNonNegative(headers, "anthropic-ratelimit-unified-7d-reset");
+	const unifiedLimitClaim = Boolean(
+		readHeader(headers, "anthropic-ratelimit-unified-representative-claim") ||
+		readHeader(headers, "anthropic-ratelimit-unified-overage-status"),
+	);
+	const overageInUse = readHeader(headers, "anthropic-ratelimit-unified-overage-in-use")?.trim() === "true";
+	const overageStatus = readHeader(headers, "anthropic-ratelimit-unified-overage-status")?.trim();
+	const overageAllowed = overageStatus === "allowed" || overageStatus === "allowed_warning";
+	const graceUtilization =
+		readHeader(headers, "anthropic-ratelimit-unified-status") === undefined
+			? undefined
+			: {
+					fiveHour: readUtilization(headers, "anthropic-ratelimit-unified-grace-5h-utilization"),
+					sevenDay: readUtilization(headers, "anthropic-ratelimit-unified-grace-7d-utilization"),
+				};
+	const signal: AnthropicSlowModeSignal = {
+		...(offer !== undefined ? { offer } : {}),
+		...(status !== undefined ? { status } : {}),
+		...(retryAfterSec !== undefined ? { retryAfterMs: Math.round(retryAfterSec * 1000) } : {}),
+		...(maxWaitSec !== undefined ? { maxWaitMs: Math.round(maxWaitSec * 1000) } : {}),
+		...(budgetUtilization !== undefined ? { budgetUtilization: Math.min(1, budgetUtilization) } : {}),
+		...(budgetResetAtSec !== undefined ? { budgetResetAtSec } : {}),
+		...(unifiedResetAtSec !== undefined ? { unifiedResetAtSec } : {}),
+		...(fiveHourResetAtSec !== undefined ? { fiveHourResetAtSec } : {}),
+		...(weeklyResetAtSec !== undefined ? { weeklyResetAtSec } : {}),
+		unifiedLimitClaim,
+		overageInUse,
+		...(overageAllowed ? { overageAllowed } : {}),
+		...(graceUtilization !== undefined ? { graceUtilization } : {}),
+	};
+	const hasSlowFacts =
+		offer !== undefined ||
+		status !== undefined ||
+		retryAfterSec !== undefined ||
+		maxWaitSec !== undefined ||
+		budgetUtilization !== undefined ||
+		budgetResetAtSec !== undefined;
+	// A unified-status response always carries wrap-up facts, even when both
+	// grace readings are zero: that is how the controller sees the window close.
+	if (
+		!hasSlowFacts &&
+		graceUtilization === undefined &&
+		!unifiedLimitClaim &&
+		fiveHourResetAtSec === undefined &&
+		unifiedResetAtSec === undefined
+	) {
+		return undefined;
+	}
+	return signal;
+}

package/src/providers/anthropic-wire.ts

@@ -342,6 +342,8 @@ export type MessageCreateParams = {
 	 * header: `server-side-fallback-2026-06-01`.
 	 */
 	fallbacks?: FallbackParam[];
+	/** Fallback credit token redeemed from a prior refusal (`fallback-credit-2026-06-01` / `fallback-credit-2026-07-01`). */
+	fallback_credit_token?: string;
 };
 
 export type MessageCreateParamsStreaming = MessageCreateParams & { stream: true };
@@ -452,6 +454,8 @@ export type StopDetails = {
 	type: string;
 	category?: string | null;
 	explanation?: string | null;
+	fallback_credit_token?: string | null;
+	fallback_has_prefill_claim?: boolean | null;
 };
 
 export type MessageDelta = {