@linxiraos/pi-ai 1.2.0 → 1.3.0

package/src/types.ts

@@ -40,7 +40,7 @@ import type { ApiKey } from "./auth-retry";
 import type { OAuthRequestIdentity } from "./auth/types";
 import type { BedrockOptions } from "./providers/amazon-bedrock";
 import type { AnthropicOptions } from "./providers/anthropic";
-import type { FallbackParam, StopDetails } from "./providers/anthropic-wire";
+import type { FallbackParam, MessageCreateParamsStreaming, StopDetails } from "./providers/anthropic-wire";
 import type { AzureOpenAIResponsesOptions } from "./providers/azure-openai-responses";
 import type { CursorOptions } from "./providers/cursor";
 import type { AppleFoundationModelsOptions } from "./providers/apple-foundation-models";
@@ -497,6 +497,11 @@ export interface StreamOptions {
 	frequencyPenalty?: number;
 	maxTokens?: number;
 	signal?: AbortSignal;
+	/**
+	 * OpenAI chat-completions HTTP attempt budget. When set, transient provider
+	 * errors are not replayed above the transport, so retries share this limit.
+	 */
+	maxHttpAttempts?: number;
 	apiKey?: string;
 	/** @internal Stored credential row serving this request, when known. */
 	credentialId?: number;
@@ -628,8 +633,6 @@ export interface StreamOptions {
 	liveSteering?: LiveSteering;
 	/** Canonical Codex compaction classification; ignored by other providers. */
 	codexCompaction?: CodexCompactionRequestContext;
-	/** Codex Code Mode tool exposure snapshot emitted as `tool_namespaces_info` turn metadata; ignored by other providers. */
-	toolNamespacesInfo?: unknown;
 	/**
 	 * Optional per-provider concurrent request cap for LLM stream calls. Keys are
 	 * provider ids (`model.provider`); positive numeric values cap in-flight
@@ -893,6 +896,13 @@ export interface ThinkingContent {
 	 * replay natively on another host.
 	 */
 	summary?: boolean;
+	/**
+	 * `true`: the block is narration — prose the model addressed to the user
+	 * between tool calls, which the provider returned as a signed thinking block
+	 * (Anthropic connector-text summarization). It stays a thinking block for
+	 * replay; user-facing surfaces present it as answer text.
+	 */
+	narration?: boolean;
 }
 
 export interface RedactedThinkingContent {
@@ -902,11 +912,12 @@ export interface RedactedThinkingContent {
 
 /**
  * Anthropic server-side-fallback boundary marker persisted on assistant
- * turns whose provider request opted into
- * `AnthropicOptions.fallbacks`. Consumers other than the Anthropic
- * provider MUST ignore it — `transformMessages` strips the block on any
- * cross-provider hop and on non-official Anthropic replays, so downstream
- * converters never see it.
+ * turns whose response switched models mid-stream, whether the request
+ * opted into `AnthropicOptions.fallbacks` or a gateway opted in on its
+ * behalf. Consumers other than the Anthropic provider MUST ignore it —
+ * `transformMessages` strips the block on any non-Anthropic hop, and
+ * `convertAnthropicMessages` only puts it on the wire for an opted-in
+ * request to the official endpoint.
  */
 export interface AnthropicFallbackContent {
 	type: "fallback";
@@ -1230,6 +1241,12 @@ export type AssistantRetryRecovery =
 export interface ContextSnapshot {
 	promptTokens: number; // authoritative provider prompt/input tokens
 	nonMessageTokens: number; // estimated non-message total at send time
+	/**
+	 * Estimated tool-schema tokens included in `nonMessageTokens` (0 when the
+	 * model defers schemas server-side). Lets a later model whose schema policy
+	 * differs rebase the provider anchor instead of inheriting its schemas.
+	 */
+	toolSchemaTokens?: number;
 	/** Estimated prompt tokens removed by local history rewrites after this provider snapshot was recorded. */
 	historyRewriteTokensRemoved?: number;
 	/**
@@ -1287,6 +1304,12 @@ export interface AssistantMessage {
 	 */
 	serviceTier?: ServiceTier;
 	usage: Usage;
+	/**
+	 * Visible output tokens a history rewrite (shake) has since removed from
+	 * `content`. `usage.output` still counts them, so a replay estimate subtracts
+	 * them to keep the turn's reasoning without recharging the removed text.
+	 */
+	elidedOutputTokens?: number;
 	stopReason: StopReason;
 	stopDetails?: StopDetails | null;
 	errorMessage?: string;
@@ -1661,7 +1684,8 @@ export type AssistantMessageEvent =
 export interface AnthropicFallbackCreditHandle {
 	token: string;
 	prefillClaim?: boolean | null;
-	params: unknown;
+	/** The refused request's body, replayed with the credit token on the fallback model. */
+	params: MessageCreateParamsStreaming;
 	betas?: readonly string[];
 	betaHeader?: string;
 	expiresAt: number;

package/src/usage/claude.ts

@@ -1,5 +1,6 @@
 import { classifyModel } from "@linxiraos/pi-catalog/compat/taxonomy";
 import { isAnthropicOAuthToken, toNumber } from "@linxiraos/pi-catalog/utils";
+import { slugify } from "@linxiraos/pi-utils";
 import * as AIError from "../error";
 import {
 	type CredentialRankingContext,
@@ -545,14 +546,6 @@ function buildUsageLimit(args: {
 	};
 }
 
-function slugifyClaudeLimitDisplayName(displayName: string): string {
-	return displayName
-		.trim()
-		.toLowerCase()
-		.replace(/[^a-z0-9]+/g, "-")
-		.replace(/^-+|-+$/g, "");
-}
-
 /**
  * Scoped weekly rows are per-model-family counters, not account-wide windows.
  * They deliberately leave `scope.shared` unset so credential-wide exhaustion
@@ -564,7 +557,7 @@ function buildScopedWeeklyUsageLimits(entries: readonly ParsedApiLimitEntry[]):
 	const limits: UsageLimit[] = [];
 	for (const entry of entries) {
 		if (entry.kind !== "weekly_scoped" || !entry.displayName) continue;
-		const slug = slugifyClaudeLimitDisplayName(entry.displayName);
+		const slug = slugify(entry.displayName);
 		if (!slug || seenSlugs.has(slug)) continue;
 		seenSlugs.add(slug);
 		const limit = buildUsageLimit({

package/src/usage/github-copilot.ts

@@ -9,6 +9,7 @@ import { COPILOT_GITHUB_HEADERS } from "@linxiraos/pi-catalog/wire/github-copilo
 import * as AIError from "../error";
 import type {
 	UsageAmount,
+	UsageUnit,
 	UsageFetchContext,
 	UsageFetchParams,
 	UsageLimit,
@@ -47,7 +48,7 @@ type BillingUsageItem = {
 	product: string;
 	sku: string;
 	model?: string;
-	unitType: string;
+	unitType?: string;
 	grossQuantity: number;
 	netQuantity: number;
 	limit?: number;
@@ -266,6 +267,23 @@ function normalizeQuotaSnapshots(
 	return { limits, window };
 }
 
+/**
+ * The unit GitHub's billing API metered one usage item in, plus the label
+ * that names it. Only AI credits is recognised: any other value keeps the
+ * legacy wording, since an unrecognised unit is not evidence about how the
+ * account is billed.
+ */
+function resolveBillingUnit(unitType: string | undefined): { unit: UsageUnit; label: string } {
+	if (typeof unitType !== "string") return { unit: "requests", label: "Premium Requests" };
+	// "AI_CREDITS", "ai-credits" and "Ai Credits" all name the same unit.
+	return unitType
+		.toUpperCase()
+		.replace(/[^A-Z]/g, "")
+		.includes("CREDIT")
+		? { unit: "credits", label: "AI Credits" }
+		: { unit: "requests", label: "Premium Requests" };
+}
+
 function normalizeBillingUsage(data: BillingUsageResponse): UsageLimit[] {
 	const limits: UsageLimit[] = [];
 	const periodLabel = data.timePeriod.month
@@ -279,12 +297,15 @@ function normalizeBillingUsage(data: BillingUsageResponse): UsageLimit[] {
 	const premiumItems = data.usageItems.filter(
 		item => item.sku === "Copilot Premium Request" || item.sku.includes("Premium"),
 	);
+	// The allowance is metered in one unit, and the items name it. Take it from
+	// the first item that states a unit rather than assuming the legacy one.
+	const allowanceUnit = resolveBillingUnit(premiumItems.find(item => item.unitType !== undefined)?.unitType);
 	const totalUsed = premiumItems.reduce((sum, item) => sum + item.grossQuantity, 0);
 	const totalLimit = premiumItems.reduce((sum, item) => sum + (item.limit ?? 0), 0) || undefined;
-	const totalAmount = buildAmount(totalUsed, totalLimit, "requests");
+	const totalAmount = buildAmount(totalUsed, totalLimit, allowanceUnit.unit);
 	limits.push({
 		id: "copilot:premium",
-		label: "Premium Requests",
+		label: allowanceUnit.label,
 		scope: {
 			provider: "github-copilot",
 			accountId: data.user,
@@ -298,7 +319,8 @@ function normalizeBillingUsage(data: BillingUsageResponse): UsageLimit[] {
 	for (const item of data.usageItems) {
 		if (!item.model) continue;
 		if (item.grossQuantity <= 0) continue;
-		const amount = buildAmount(item.grossQuantity, item.limit, "requests");
+		// Each model row is metered in its own item's unit, not the legacy default.
+		const amount = buildAmount(item.grossQuantity, item.limit, resolveBillingUnit(item.unitType).unit);
 		limits.push({
 			id: `copilot:model:${item.model}`,
 			label: `Model ${item.model}`,

package/src/usage/openai-codex.ts

@@ -1,7 +1,8 @@
 import { Buffer } from "node:buffer";
 import { planRequirementFor, quotaTierFor } from "@linxiraos/pi-catalog/compat/behavior";
 import { toNumber } from "@linxiraos/pi-catalog/utils";
-import { USER_AGENT } from "@linxiraos/pi-utils";
+import { slugify, USER_AGENT } from "@linxiraos/pi-utils";
+import { ProviderHttpError } from "../error";
 import type {
 	CredentialRankingContext,
 	CredentialRankingStrategy,
@@ -393,12 +394,7 @@ function additionalLimitSlug(args: { limitName?: string; meteredFeature?: string
 	const probe = `${args.limitName ?? ""} ${args.meteredFeature ?? ""}`.toLowerCase();
 	if (probe.includes("spark") || probe.includes("bengalfox")) return "spark";
 	const source = (args.meteredFeature ?? args.limitName ?? "extra").toLowerCase();
-	return (
-		source
-			.replace(/^codex[-_]/, "")
-			.replace(/[^a-z0-9]+/g, "-")
-			.replace(/^-+|-+$/g, "") || "extra"
-	);
+	return slugify(source.replace(/^codex[-_]/, "")) || "extra";
 }
 
 function additionalDisplayName(slug: string, limitName?: string): string {
@@ -542,11 +538,21 @@ export const openaiCodexUsageProvider: UsageProvider = {
 		try {
 			const response = await ctx.fetch(url, { headers, signal: params.signal });
 			if (!response.ok) {
+				// A rejected token must purge the cached report and fail the health
+				// check: only a thrown auth status does that, while `null` is the
+				// transient-failure path that keeps serving last-good quota.
+				if (response.status === 401 || response.status === 403) {
+					throw new ProviderHttpError(
+						`Codex usage endpoint returned ${response.status} ${response.statusText}`.trim(),
+						response.status,
+					);
+				}
 				ctx.logger?.warn("Codex usage request failed", { status: response.status, provider: params.provider });
 				return null;
 			}
 			payload = await response.json();
 		} catch (error) {
+			if (error instanceof ProviderHttpError) throw error;
 			ctx.logger?.warn("Codex usage request error", { provider: params.provider, error: String(error) });
 			return null;
 		}

package/src/usage/opencode-go.ts

@@ -15,13 +15,12 @@ import { DAY_MS, HOUR_MS } from "./shared";
 
 const OPENCODE_GO_PROVIDER = "opencode-go";
 const DEFAULT_ENDPOINT = "https://opencode.ai/zen/go";
+const MODEL_ENDPOINT = "https://opencode.ai/inference/go";
 const USAGE_PATH = "/v1/usage";
 
 /**
- * `GET /zen/go/v1/usage` response windows. The route is first-party but
- * undocumented (`anomalyco/opencode` `packages/console/app/src/routes/zen/go/v1/usage.ts`)
- * and its shape changed once on merge day, so each window is decoded
- * defensively and malformed windows are skipped rather than failing the report.
+ * `GET /zen/go/v1/usage` response windows. The account endpoint remains on
+ * Zen even though inference and model discovery use `/inference/go/v1`.
  *
  * Per window: `status` is `"ok" | "rate-limited"`, `percent` is a floored,
  * clamped integer 0-100, and `resetsAt` is an ISO timestamp computed server
@@ -36,11 +35,11 @@ const OPENCODE_GO_WINDOWS = [
 
 function normalizeBaseUrl(baseUrl?: string): string {
 	if (!baseUrl?.trim()) return DEFAULT_ENDPOINT;
-	// Strip a trailing `/v1` (models.json carries both `zen/go` and
-	// `zen/go/v1` base URLs) so the usage path doesn't double it, while
-	// preserving any path-mounted gateway prefix.
+	// Preserve custom gateway prefixes while mapping first-party model URLs
+	// back to the separate Zen account endpoint.
 	const withoutTrailingSlash = baseUrl.trim().replace(/\/+$/, "");
-	return withoutTrailingSlash.replace(/\/v1$/i, "") || DEFAULT_ENDPOINT;
+	const normalized = withoutTrailingSlash.replace(/\/v1$/i, "");
+	return normalized === MODEL_ENDPOINT ? DEFAULT_ENDPOINT : normalized || DEFAULT_ENDPOINT;
 }
 
 function resolveStatus(windowStatus: unknown, usedFraction: number): UsageStatus {

package/src/usage/xai-oauth.ts

@@ -10,6 +10,7 @@
  */
 
 import { toNumber } from "@linxiraos/pi-catalog/utils";
+import { slugify } from "@linxiraos/pi-utils";
 import { isUsageLimitExhausted } from "../auth/usage-report";
 import {
 	buildXAICliBillingUrl,
@@ -95,14 +96,6 @@ function buildPercentAmount(usagePercent: number): UsageAmount {
 	};
 }
 
-function slugifyProduct(product: string): string {
-	return product
-		.trim()
-		.toLowerCase()
-		.replace(/[^a-z0-9]+/g, "-")
-		.replace(/^-+|-+$/g, "");
-}
-
 function buildPeriodWindow(period: XaiBillingPeriod): UsageWindow {
 	return {
 		id: "1w",
@@ -262,7 +255,7 @@ function buildLimits(config: XaiBillingConfig, accountId: string | undefined): U
 
 		for (const item of config.productUsage) {
 			const amount = buildPercentAmount(item.usagePercent);
-			const slug = slugifyProduct(item.product);
+			const slug = slugify(item.product);
 			if (!slug) continue;
 			limits.push({
 				id: `${PROVIDER_ID}:product:${slug}:1w`,

package/src/utils/dsml-leak.ts

@@ -13,8 +13,8 @@
 import type { AssistantMessage, Model } from "../types";
 
 // Structural DSML tags in either pipe spelling (fullwidth `｜` U+FF5C or ASCII),
-// tolerating stray whitespace inside the delimiter run.
-const DSML_TAG_PATTERN = /<\s*\/?\s*[｜|]\s*DSML\s*[｜|]\s*(?:tool_calls|invoke|parameter)\b[^<>]*>?/gu;
+// including doubled delimiters and the observed malformed ` calls` wrapper.
+const DSML_TAG_PATTERN = /<\s*\/?\s*[｜|]{1,2}\s*DSML\s*[｜|]{1,2}\s*(?:tool_calls|invoke|parameter|calls)\b[^<>]*>?/gu;
 // Code the model deliberately quoted (fences, inline spans) is not a leak.
 const QUOTED_CODE_PATTERN = /(```|~~~)[\s\S]*?(?:\1|$)|`[^`\n]*`/g;
 // The identifier-only line a degraded model writes in place of
@@ -89,21 +89,37 @@ export function stripDsmlToolMarkup(text: string): string | undefined {
 }
 
 /**
- * Remove leaked DSML tool-call markup from `message`'s text blocks in place,
- * dropping blocks left empty. Returns true when anything was removed.
+ * Remove leaked DSML tool-call markup from an assistant message before commit,
+ * including reasoning blocks and turns with valid structured calls. Rewritten
+ * thinking with an opaque signature is discarded; OpenAI-compatible reasoning
+ * field names are replay markers, not signatures, and survive cleanup.
  */
 export function removeDsmlToolMarkupLeak(message: AssistantMessage): boolean {
-	let removed = false;
-	const content: AssistantMessage["content"] = [];
-	for (const block of message.content) {
-		const stripped = block.type === "text" ? stripDsmlToolMarkup(block.text) : undefined;
-		if (block.type !== "text" || stripped === undefined) {
-			content.push(block);
+	let content: AssistantMessage["content"] | undefined;
+	for (let index = 0; index < message.content.length; index++) {
+		const block = message.content[index]!;
+		if (block.type !== "text" && block.type !== "thinking") {
+			content?.push(block);
 			continue;
 		}
-		removed = true;
-		if (stripped.trim().length > 0) content.push({ ...block, text: stripped });
+		const stripped = stripDsmlToolMarkup(block.type === "text" ? block.text : block.thinking);
+		if (stripped === undefined) {
+			content?.push(block);
+			continue;
+		}
+		content ??= message.content.slice(0, index);
+		if (block.type === "text") {
+			if (stripped.trim().length > 0) content.push({ ...block, text: stripped });
+		} else {
+			const signature = block.thinkingSignature;
+			const reasoningField =
+				(message.api === "openai-completions" || message.api === "openrouter") &&
+				(signature === "reasoning_content" || signature === "reasoning" || signature === "reasoning_text");
+			if ((!signature || reasoningField) && stripped.trim().length > 0) {
+				content.push({ ...block, thinking: stripped });
+			}
+		}
 	}
-	if (removed) message.content = content;
-	return removed;
+	if (content) message.content = content;
+	return content !== undefined;
 }

package/src/utils/leaked-thinking-stream.ts

@@ -141,6 +141,16 @@ export function wrapLeakedThinkingStream(inner: AssistantMessageEventStream): As
 						return;
 					}
 					case "error": {
+						// An error message with empty content means the provider
+						// discarded the partial turn; forward it as-is rather than
+						// rebuild it from #partial, which would resurrect exactly what
+						// was discarded. Non-empty error content is still healed: a
+						// provider that reports partial output alongside the error did
+						// send that output.
+						if (projector !== undefined && event.error.content.length === 0) {
+							out.push({ type: "error", reason: event.reason, error: event.error });
+							return;
+						}
 						projector ??= new LeakedThinkingProjector(out, event.error);
 						const content = projector.finish(event.error);
 						out.push({ type: "error", reason: event.reason, error: { ...event.error, content } });

package/src/utils/narration.ts

@@ -0,0 +1,18 @@
+import type { AssistantMessage } from "../types";
+
+/**
+ * The message as a user-facing surface should present it: every narration
+ * thinking block (see `ThinkingContent.narration`) becomes a text block, so it
+ * renders as part of the answer instead of folding into reasoning. Returns the
+ * input unchanged when it holds no narration. Display-only: replay must keep
+ * the original thinking blocks and their signatures.
+ */
+export function presentNarrationAsAnswer(message: AssistantMessage): AssistantMessage {
+	if (!message.content.some(block => block.type === "thinking" && block.narration)) return message;
+	return {
+		...message,
+		content: message.content.map(block =>
+			block.type === "thinking" && block.narration ? { type: "text", text: block.thinking } : block,
+		),
+	};
+}

package/src/utils/openai-http.ts

@@ -68,6 +68,8 @@ export interface OpenAIStreamRequestInit {
 	body: unknown;
 	signal: AbortSignal;
 	fetch?: FetchImpl;
+	/** Override the default transport attempt budget for this request. */
+	maxAttempts?: number;
 	/** Optional caller-specific gate composed with shared transport retry exclusions. */
 	shouldRetryResponse?: (response: Response, bodyText: string) => boolean | Promise<boolean>;
 	/**
@@ -96,24 +98,31 @@ export interface OpenAIStreamHandle<TEvent> {
  * watchdog timers and abort-reason bookkeeping.
  */
 export async function postOpenAIStream<TEvent>(init: OpenAIStreamRequestInit): Promise<OpenAIStreamHandle<TEvent>> {
-	const response = await fetchWithRetry(init.url, {
-		method: "POST",
-		headers: { "Content-Type": "application/json", Accept: "text/event-stream", ...init.headers },
-		body: JSON.stringify(init.body),
-		signal: init.signal,
-		fetch: init.fetch,
-		maxAttempts: DEFAULT_MAX_ATTEMPTS,
-		// A proxy concurrency-admission 429 (`rate_limit_type: max_parallel_requests`)
-		// surfaces immediately instead of being slept-and-retried here; session
-		// recovery owns its backoff/fallback (issue #8854).
-		shouldRetryResponse: async (response, bodyText) =>
-			!isConcurrencyAdmissionRejection(response, bodyText) &&
-			(init.shouldRetryResponse === undefined || (await init.shouldRetryResponse(response, bodyText))),
-		// Bun's native fetch enforces a hard ~300s pre-response timeout (issue #2422).
-		// Cold large-context streams legitimately exceed it; the caller's
-		// `firstEventTimeoutMs`/`AbortSignal` already govern stuck requests.
-		timeout: false,
-	});
+	let response: Response;
+	try {
+		response = await fetchWithRetry(init.url, {
+			method: "POST",
+			headers: { "Content-Type": "application/json", Accept: "text/event-stream", ...init.headers },
+			body: JSON.stringify(init.body),
+			signal: init.signal,
+			fetch: init.fetch,
+			maxAttempts: init.maxAttempts ?? DEFAULT_MAX_ATTEMPTS,
+			// A proxy concurrency-admission 429 (`rate_limit_type: max_parallel_requests`)
+			// surfaces immediately instead of being slept-and-retried here; session
+			// recovery owns its backoff/fallback (issue #8854).
+			shouldRetryResponse: async (response, bodyText) =>
+				!isConcurrencyAdmissionRejection(response, bodyText) &&
+				(init.shouldRetryResponse === undefined || (await init.shouldRetryResponse(response, bodyText))),
+			// Bun's native fetch enforces a hard ~300s pre-response timeout (issue #2422).
+			// Cold large-context streams legitimately exceed it; the caller's
+			// `firstEventTimeoutMs`/`AbortSignal` already govern stuck requests.
+			timeout: false,
+		});
+	} catch (error) {
+		// Transport rejection after the retry budget: name the host and the cause
+		// instead of surfacing the runtime's bare `getaddrinfo …` text.
+		throw AIError.networkFailureError(error, init.url);
+	}
 	if (!response.ok) {
 		throw await captureOpenAIHttpError(response);
 	}

package/src/utils/request-body.ts

@@ -0,0 +1,27 @@
+/**
+ * Bytes of a request body as the server reads them: the `gzip`/`zstd`
+ * `Content-Encoding` applied by request compression is undone, any other
+ * encoding is returned untouched.
+ */
+export function decodeRequestBodyBytes(bytes: Uint8Array, contentEncoding: string | null): Uint8Array {
+	switch (contentEncoding?.trim().toLowerCase()) {
+		case "gzip":
+			return Bun.gunzipSync(bytes as Uint8Array<ArrayBuffer>);
+		case "zstd":
+			return Bun.zstdDecompressSync(bytes);
+		default:
+			return bytes;
+	}
+}
+
+/**
+ * Text of a string or byte request body after undoing its content encoding;
+ * `undefined` when the request has no such body (none, stream, form data).
+ */
+export function requestBodyText(init: RequestInit | undefined): string | undefined {
+	const body = init?.body;
+	if (typeof body === "string") return body;
+	if (!(body instanceof Uint8Array)) return undefined;
+	const encoding = new Headers(init?.headers).get("content-encoding");
+	return new TextDecoder().decode(decodeRequestBodyBytes(body, encoding));
+}