@linxiraos/pi-ai 1.0.0

package/dist/types/auth-broker/types.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Wire types shared between the auth-broker server and clients.
+ *
+ * The broker holds OAuth refresh tokens and exposes a redacted snapshot;
+ * clients use `access` tokens directly and call back to the broker when a
+ * credential expires or a 401 surfaces on a supposedly-fresh credential.
+ */
+import type { AuthCredential, AuthCredentialSnapshot, AuthCredentialSnapshotEntry, DisabledCredentialSummary, StoredCredentialBlock } from "../auth-storage.js";
+import type { ClientUsageClientSummary, ClientUsageReport, UsageHistoryEntry, UsageReport } from "../usage.js";
+/** GET /v1/healthz response body. */
+export interface HealthzResponse {
+    ok: boolean;
+    version?: string;
+}
+export interface RefresherSchedule {
+    enabled: boolean;
+    intervalMs: number;
+    skewMs: number;
+    nextSweepInMs: number;
+}
+export type CredentialBlockSnapshot = Omit<StoredCredentialBlock, "credentialId">;
+export type SnapshotEntry = AuthCredentialSnapshotEntry & {
+    rotatesInMs: number | null;
+    blocks?: CredentialBlockSnapshot[];
+};
+/** GET /v1/snapshot response body. */
+export interface SnapshotResponse extends Omit<AuthCredentialSnapshot, "credentials"> {
+    serverNowMs: number;
+    refresher: RefresherSchedule;
+    credentials: SnapshotEntry[];
+}
+/** GET /v1/usage response body — matches the local `AuthStorage.fetchUsageReports` shape. */
+export interface UsageResponse {
+    generatedAt: number;
+    reports: UsageReport[];
+}
+/**
+ * GET /v1/usage/history response body. Entries come from the broker host's
+ * durable `usage_history` — the broker performs every upstream usage fetch in
+ * broker deployments, so this is the only complete utilization record.
+ */
+export interface UsageHistoryResponse {
+    generatedAt: number;
+    entries: UsageHistoryEntry[];
+}
+/** POST /v1/usage/observed request body — one client's batched observed usage. */
+export type ClientUsageReportRequest = ClientUsageReport;
+/** POST /v1/usage/observed response body. */
+export interface ClientUsageReportResponse {
+    ok: boolean;
+}
+/** GET /v1/usage/clients response body — per-client token burn aggregates. */
+export interface ClientUsageSummaryResponse {
+    generatedAt: number;
+    clients: ClientUsageClientSummary[];
+}
+/** POST /v1/credential/:id/refresh response body. */
+export interface CredentialRefreshResponse {
+    entry: AuthCredentialSnapshotEntry;
+}
+/** POST /v1/credential/:id/disable request body. */
+export interface CredentialDisableRequest {
+    cause: string;
+}
+/** POST /v1/credential/:id/disable response body. */
+export interface CredentialDisableResponse {
+    ok: boolean;
+}
+/** GET /v1/credentials/disabled response body — tombstones of auto-disabled rows. */
+export interface DisabledCredentialsResponse {
+    generatedAt: number;
+    disabled: DisabledCredentialSummary[];
+}
+/** POST /v1/credential/:id/block request body. */
+export type CredentialBlockRequest = CredentialBlockSnapshot;
+/** POST /v1/credential/:id/block response body. */
+export interface CredentialBlockResponse {
+    ok: boolean;
+}
+/** DELETE /v1/credential/:id/blocks response body. */
+export interface CredentialBlocksDeleteResponse {
+    ok: boolean;
+}
+/** POST /v1/usage/stale response body. */
+export interface UsageStaleResponse {
+    ok: boolean;
+}
+/**
+ * POST /v1/credential request body. The OAuth `refresh` must be the *real*
+ * refresh token (not the sentinel) — the broker is the canonical writer.
+ */
+export interface CredentialUploadRequest {
+    provider: string;
+    credential: AuthCredential;
+}
+/** POST /v1/credential response body — redacted snapshot of the provider's rows after upsert. */
+export interface CredentialUploadResponse {
+    entries: AuthCredentialSnapshotEntry[];
+}
+/**
+ * SSE event kinds emitted on `GET /v1/snapshot/stream`. The same value is set
+ * as the SSE `event:` name (load-bearing for clients) **and** embedded as a
+ * `kind` field inside the JSON body so a Zod discriminated union can validate
+ * the payload without consulting the line metadata.
+ */
+export type SnapshotStreamEventKind = "snapshot" | "entry" | "removed";
+/** Initial frame emitted on connect — the full {@link SnapshotResponse}. */
+export interface SnapshotStreamSnapshotEvent extends SnapshotResponse {
+    kind: "snapshot";
+}
+/** Single credential added/changed (upsert or refresh). */
+export interface SnapshotStreamEntryEvent {
+    kind: "entry";
+    generation: number;
+    serverNowMs: number;
+    refresher: RefresherSchedule;
+    entry: SnapshotEntry;
+}
+/** Single credential disabled/deleted. */
+export interface SnapshotStreamRemovedEvent {
+    kind: "removed";
+    generation: number;
+    serverNowMs: number;
+    refresher: RefresherSchedule;
+    id: number;
+}
+/** Discriminated union of every event the snapshot stream emits. */
+export type SnapshotStreamEvent = SnapshotStreamSnapshotEvent | SnapshotStreamEntryEvent | SnapshotStreamRemovedEvent;
+/**
+ * Default bearer-protected route prefix. The broker exposes `/v1/healthz`
+ * unauthenticated for liveness probes; everything else requires a bearer.
+ */
+export declare const AUTH_BROKER_API_PREFIX = "/v1";
+/** Request header used by clients to advertise optional auth-broker protocol features. */
+export declare const AUTH_BROKER_CAPABILITIES_HEADER = "OMP-Auth-Broker-Capabilities";
+/** Client understands independent Codex `chat` and `spark` credential-block scopes. */
+export declare const AUTH_BROKER_CAPABILITY_CODEX_METER_BLOCK_SCOPES = "codex-meter-block-scopes";
+/** Default port when none is configured. Loopback-only, no external exposure. */
+export declare const DEFAULT_AUTH_BROKER_BIND = "127.0.0.1:8765";
+/** Default broker→provider refresh skew. Refresh credentials this close to expiry. */
+export declare const DEFAULT_REFRESH_SKEW_MS: number;
+/** Default broker refresh-loop cadence. */
+export declare const DEFAULT_REFRESH_INTERVAL_MS = 60000;
+/** Default freshness window for the encrypted local broker snapshot cache. */
+export declare const DEFAULT_SNAPSHOT_CACHE_TTL_MS: number;
+/** Keepalive cadence for `GET /v1/snapshot/stream` SSE comments. */
+export declare const DEFAULT_STREAM_KEEPALIVE_MS = 20000;
+/**
+ * Bun.serve `idleTimeout` (seconds) used by the broker. Default Bun idle
+ * timeout (10s) would close long-lived SSE connections between keepalives.
+ */
+export declare const DEFAULT_SERVER_IDLE_TIMEOUT_S = 255;

package/dist/types/auth-broker/wire-schema-resource.d.ts

@@ -0,0 +1,53 @@
+/**
+ * ArkType schemas for the auth-broker wire protocol.
+ *
+ * Shared between the server (validates inbound request bodies) and the client
+ * (validates responses from the broker). Schemas mirror the TypeScript types
+ * in `./types.ts` 1:1; the types remain the source of truth for static typing,
+ * and `Type` is asserted-compatible with them where possible.
+ *
+ * Envelope and fixed-shape schemas use `"+": "reject"` so unknown keys are
+ * rejected — the previous implementation used a hand-rolled `hasOnlyFields`
+ * allowlist for the same effect. The OAuth credential schema is the deliberate
+ * exception (standard type keeps extra keys): it preserves provider-specific extension fields so
+ * they round-trip through the broker instead of being dropped (see below).
+ */
+import { type Type } from "@linxiraos/pi-omptype";
+import { type ApiKeyCredential, type AuthCredential, type AuthCredentialSnapshotEntry, type DisabledCredentialSummary, type OAuthCredential, type RemoteOAuthCredential, type SnapshotCredential } from "../auth-storage.js";
+import type { ClientUsageReportRequest, ClientUsageReportResponse, ClientUsageSummaryResponse, CredentialBlockRequest, CredentialBlockResponse, CredentialBlockSnapshot, CredentialBlocksDeleteResponse, CredentialDisableResponse, CredentialRefreshResponse, CredentialUploadRequest, CredentialUploadResponse, DisabledCredentialsResponse, HealthzResponse, RefresherSchedule, SnapshotEntry, SnapshotResponse, SnapshotStreamEntryEvent, SnapshotStreamEvent, SnapshotStreamRemovedEvent, SnapshotStreamSnapshotEvent, UsageHistoryResponse, UsageResponse, UsageStaleResponse } from "./types.js";
+export interface AuthBrokerWireSchemas {
+    readonly oauthCredentialSchema: Type<OAuthCredential>;
+    readonly remoteOauthCredentialSchema: Type<RemoteOAuthCredential>;
+    readonly apiKeyCredentialSchema: Type<ApiKeyCredential>;
+    readonly writableAuthCredentialSchema: Type<AuthCredential>;
+    readonly snapshotCredentialSchema: Type<SnapshotCredential>;
+    readonly credentialSnapshotEntrySchema: Type<AuthCredentialSnapshotEntry>;
+    readonly credentialBlockSnapshotSchema: Type<CredentialBlockSnapshot>;
+    readonly snapshotEntrySchema: Type<SnapshotEntry>;
+    readonly refresherScheduleSchema: Type<RefresherSchedule>;
+    readonly snapshotResponseSchema: Type<SnapshotResponse>;
+    readonly snapshotStreamSnapshotEventSchema: Type<SnapshotStreamSnapshotEvent>;
+    readonly snapshotStreamEntryEventSchema: Type<SnapshotStreamEntryEvent>;
+    readonly snapshotStreamRemovedEventSchema: Type<SnapshotStreamRemovedEvent>;
+    readonly snapshotStreamEventSchema: Type<SnapshotStreamEvent>;
+    readonly healthzResponseSchema: Type<HealthzResponse>;
+    readonly usageResponseSchema: Type<UsageResponse>;
+    readonly usageHistoryResponseSchema: Type<UsageHistoryResponse>;
+    readonly clientUsageReportRequestSchema: Type<ClientUsageReportRequest>;
+    readonly clientUsageReportResponseSchema: Type<ClientUsageReportResponse>;
+    readonly clientUsageSummaryResponseSchema: Type<ClientUsageSummaryResponse>;
+    readonly credentialRefreshResponseSchema: Type<CredentialRefreshResponse>;
+    readonly credentialDisableRequestSchema: Type<{
+        cause?: string;
+    }>;
+    readonly credentialDisableResponseSchema: Type<CredentialDisableResponse>;
+    readonly disabledCredentialSummarySchema: Type<DisabledCredentialSummary>;
+    readonly disabledCredentialsResponseSchema: Type<DisabledCredentialsResponse>;
+    readonly credentialBlockRequestSchema: Type<CredentialBlockRequest>;
+    readonly credentialBlockResponseSchema: Type<CredentialBlockResponse>;
+    readonly credentialBlocksDeleteResponseSchema: Type<CredentialBlocksDeleteResponse>;
+    readonly usageStaleResponseSchema: Type<UsageStaleResponse>;
+    readonly credentialUploadRequestSchema: Type<CredentialUploadRequest>;
+    readonly credentialUploadResponseSchema: Type<CredentialUploadResponse>;
+}
+export declare function getAuthBrokerWireSchemas(): AuthBrokerWireSchemas;

package/dist/types/auth-broker/wire-schemas.d.ts

@@ -0,0 +1,5 @@
+export declare const oauthCredentialSchema: import("@linxiraos/pi-omptype").Type<import("../index.js").OAuthCredential, import("../index.js").OAuthCredential>, remoteOauthCredentialSchema: import("@linxiraos/pi-omptype").Type<import("../index.js").RemoteOAuthCredential, import("../index.js").RemoteOAuthCredential>, apiKeyCredentialSchema: import("@linxiraos/pi-omptype").Type<import("../index.js").ApiKeyCredential, import("../index.js").ApiKeyCredential>, writableAuthCredentialSchema: import("@linxiraos/pi-omptype").Type<import("../index.js").AuthCredential, import("../index.js").AuthCredential>, snapshotCredentialSchema: import("@linxiraos/pi-omptype").Type<import("../index.js").SnapshotCredential, import("../index.js").SnapshotCredential>, credentialSnapshotEntrySchema: import("@linxiraos/pi-omptype").Type<import("../index.js").AuthCredentialSnapshotEntry, import("../index.js").AuthCredentialSnapshotEntry>, credentialBlockSnapshotSchema: import("@linxiraos/pi-omptype").Type<import("./types.js").CredentialBlockSnapshot, import("./types.js").CredentialBlockSnapshot>, snapshotEntrySchema: import("@linxiraos/pi-omptype").Type<import("./types.js").SnapshotEntry, import("./types.js").SnapshotEntry>, refresherScheduleSchema: import("@linxiraos/pi-omptype").Type<import("./types.js").RefresherSchedule, import("./types.js").RefresherSchedule>, snapshotResponseSchema: import("@linxiraos/pi-omptype").Type<import("./types.js").SnapshotResponse, import("./types.js").SnapshotResponse>, snapshotStreamSnapshotEventSchema: import("@linxiraos/pi-omptype").Type<import("./types.js").SnapshotStreamSnapshotEvent, import("./types.js").SnapshotStreamSnapshotEvent>, snapshotStreamEntryEventSchema: import("@linxiraos/pi-omptype").Type<import("./types.js").SnapshotStreamEntryEvent, import("./types.js").SnapshotStreamEntryEvent>, snapshotStreamRemovedEventSchema: import("@linxiraos/pi-omptype").Type<import("./types.js").SnapshotStreamRemovedEvent, import("./types.js").SnapshotStreamRemovedEvent>, snapshotStreamEventSchema: import("@linxiraos/pi-omptype").Type<import("./types.js").SnapshotStreamEvent, import("./types.js").SnapshotStreamEvent>, healthzResponseSchema: import("@linxiraos/pi-omptype").Type<import("./types.js").HealthzResponse, import("./types.js").HealthzResponse>, usageResponseSchema: import("@linxiraos/pi-omptype").Type<import("./types.js").UsageResponse, import("./types.js").UsageResponse>, usageHistoryResponseSchema: import("@linxiraos/pi-omptype").Type<import("./types.js").UsageHistoryResponse, import("./types.js").UsageHistoryResponse>, clientUsageReportRequestSchema: import("@linxiraos/pi-omptype").Type<import("../index.js").ClientUsageReport, import("../index.js").ClientUsageReport>, clientUsageReportResponseSchema: import("@linxiraos/pi-omptype").Type<import("./types.js").ClientUsageReportResponse, import("./types.js").ClientUsageReportResponse>, clientUsageSummaryResponseSchema: import("@linxiraos/pi-omptype").Type<import("./types.js").ClientUsageSummaryResponse, import("./types.js").ClientUsageSummaryResponse>, credentialRefreshResponseSchema: import("@linxiraos/pi-omptype").Type<import("./types.js").CredentialRefreshResponse, import("./types.js").CredentialRefreshResponse>, credentialDisableRequestSchema: import("@linxiraos/pi-omptype").Type<{
+    cause?: string;
+}, {
+    cause?: string;
+}>, credentialDisableResponseSchema: import("@linxiraos/pi-omptype").Type<import("./types.js").CredentialDisableResponse, import("./types.js").CredentialDisableResponse>, disabledCredentialSummarySchema: import("@linxiraos/pi-omptype").Type<import("../index.js").DisabledCredentialSummary, import("../index.js").DisabledCredentialSummary>, disabledCredentialsResponseSchema: import("@linxiraos/pi-omptype").Type<import("./types.js").DisabledCredentialsResponse, import("./types.js").DisabledCredentialsResponse>, credentialBlockRequestSchema: import("@linxiraos/pi-omptype").Type<import("./types.js").CredentialBlockSnapshot, import("./types.js").CredentialBlockSnapshot>, credentialBlockResponseSchema: import("@linxiraos/pi-omptype").Type<import("./types.js").CredentialBlockResponse, import("./types.js").CredentialBlockResponse>, credentialBlocksDeleteResponseSchema: import("@linxiraos/pi-omptype").Type<import("./types.js").CredentialBlocksDeleteResponse, import("./types.js").CredentialBlocksDeleteResponse>, usageStaleResponseSchema: import("@linxiraos/pi-omptype").Type<import("./types.js").UsageStaleResponse, import("./types.js").UsageStaleResponse>, credentialUploadRequestSchema: import("@linxiraos/pi-omptype").Type<import("./types.js").CredentialUploadRequest, import("./types.js").CredentialUploadRequest>, credentialUploadResponseSchema: import("@linxiraos/pi-omptype").Type<import("./types.js").CredentialUploadResponse, import("./types.js").CredentialUploadResponse>;

package/dist/types/auth-gateway/http.d.ts

@@ -0,0 +1,56 @@
+import type { Api, AssistantMessage, Model } from "../types.js";
+export declare function json(status: number, body: unknown, headers?: Record<string, string>): Response;
+/**
+ * Diagnostic response headers for translated inference requests, mirroring the
+ * names existing gateway-aware clients already parse: `x-request-id` /
+ * `request-id` (surfaced as `_request_id` by the OpenAI and Anthropic SDKs,
+ * matches the gateway log line), LiteLLM's model-resolution and cost headers,
+ * and OpenAI's `openai-processing-ms`. Model/request-id headers are always
+ * present; `message` — the final assistant message, available only on
+ * non-streaming responses — adds the computed cost, and `startedAt` the wall
+ * time. Streaming responses send headers before usage exists, so they carry
+ * only the identity headers.
+ */
+export declare function gatewayResponseHeaders(model: Model<Api>, info: {
+    requestId: string;
+    message?: AssistantMessage;
+    startedAt?: number;
+}): Record<string, string>;
+export declare function resolvePeer(req: Request): string;
+/**
+ * Constant-time byte comparison. Falls back to a manual XOR accumulator if
+ * `node:crypto.timingSafeEqual` isn't available. Always processes every byte
+ * of the longer input so length itself doesn't leak via timing.
+ */
+export declare function timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean;
+export declare function isAuthorized(req: Request, tokens: ReadonlySet<string>): boolean;
+/**
+ * Extract allow-listed passthrough headers from an inbound request. Keys are
+ * lowercased; empty values are dropped. Called once per request in
+ * `handleFormatEndpoint`; parsers then read `options.headers`.
+ */
+export declare function captureRequestHeaders(headers: Headers): Record<string, string>;
+/**
+ * Resolve a prompt-cache identity from inbound request body + headers.
+ * Order of precedence (first wins):
+ *   1. Body `prompt_cache_key`
+ *   2. Body `metadata.{prompt_cache_key,session_id,conversation_id}`
+ *   3. Header `x-prompt-cache-key`
+ *   4. Header `session_id` / `conversation_id` (Codex / ChatGPT-OAuth surface)
+ *   5. Header `x-session-id` / `x-conversation-id` (common informal)
+ * Returns undefined when none present; the gateway then derives a stable
+ * UUID from the request's stable parts.
+ */
+export declare function resolvePromptCacheKey(body: unknown, headers?: Headers): string | undefined;
+/**
+ * CORS headers for the auth-gateway. Currently echoes a wildcard origin; the
+ * request is accepted so future tightening can mirror `Origin` without
+ * threading the request through every caller.
+ */
+export declare function corsHeaders(_req: Request): Record<string, string>;
+/**
+ * Re-emit `response` with CORS headers merged. The original response body is
+ * passed through unchanged. Used by the gateway wrapper so every outbound
+ * format-endpoint response carries the same CORS surface as the preflight.
+ */
+export declare function withCors(response: Response, req: Request): Response;

package/dist/types/auth-gateway/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./http.js";
+export * from "./server.js";
+export * from "./types.js";

package/dist/types/auth-gateway/server.d.ts

@@ -0,0 +1,36 @@
+/**
+ * omp auth-gateway HTTP server.
+ *
+ * Accepts any provider-format request (OpenAI chat-completions, Anthropic
+ * messages, OpenAI Responses) and dispatches through pi-ai's `streamSimple()`
+ * — which handles credential injection, anthropic-beta headers, codex
+ * websocket transport, and all the per-provider intricacies. The gateway is
+ * pure protocol translation: foreign wire → omp Context → pi-ai stream() →
+ * omp events → foreign wire.
+ *
+ * Endpoints:
+ *   GET  /healthz                          → unauth; ok + version
+ *   GET  /v1/usage                         → aggregated provider usage (5-min per-credential cache via AuthStorage)
+ *   GET  /v1/credentials/check             → per-credential auth probe (diagnose 401s in a multi-account pool)
+ *   GET  /v1/models                        → list known models from the registry
+ *   POST /v1/chat/completions              → OpenAI chat-completions in/out
+ *   POST /v1/messages                      → Anthropic messages in/out
+ *   POST /v1/responses                     → OpenAI Responses in/out
+ */
+import type { AuthStorage } from "../auth-storage.js";
+import type { Api, Model } from "../types.js";
+import type { AuthGatewayServerHandle, AuthGatewayServerOptions } from "./types.js";
+export type ModelResolver = (modelId: string) => Model<Api> | undefined;
+export interface AuthGatewayBootOptions extends AuthGatewayServerOptions {
+    /** Source of credentials. Caller wires this to a broker-backed AuthStorage. */
+    storage: AuthStorage;
+    /**
+     * Resolve a client-requested model id to a pi-ai Model. Caller supplies
+     * this from a ModelRegistry (lives in `coding-agent` to avoid an inverse
+     * dependency in `pi-ai`).
+     */
+    resolveModel: ModelResolver;
+    /** Optional supplier for `/v1/models` listing. Returns the full model array. */
+    listModels?: () => Iterable<Model<Api>>;
+}
+export declare function startAuthGateway(opts: AuthGatewayBootOptions): AuthGatewayServerHandle;

package/dist/types/auth-gateway/types.d.ts

@@ -0,0 +1,127 @@
+import type { Effort } from "@linxiraos/pi-catalog/effort";
+import type { AssistantMessage, AssistantMessageEventStream, CacheRetention, Context, OpenAIResponseInclude, ServiceTier, TokenTaskBudget } from "../types.js";
+/**
+ * Wire types for the omp auth-gateway.
+ *
+ * The gateway sits between unauthenticated clients (containerized omp,
+ * llm-git, …) and the broker. It accepts provider-format HTTP requests
+ * (OpenAI chat-completions / Anthropic messages / OpenAI Responses),
+ * dispatches them through pi-ai's `streamSimple()`, and translates the
+ * canonical event stream back to the matching wire format. The gateway
+ * injects `Authorization` server-side so clients never see access tokens.
+ */
+/** Default bind. Loopback-only — front with reverse proxy for remote access. */
+export declare const DEFAULT_AUTH_GATEWAY_BIND = "127.0.0.1:4000";
+export type AuthGatewayToolChoice = "auto" | "none" | "required" | {
+    name: string;
+} | {
+    type: "computer";
+};
+export interface AuthGatewayParsedRequestOptions {
+    maxOutputTokens?: number;
+    temperature?: number;
+    topP?: number;
+    topK?: number;
+    /** OpenAI nucleus-min sampling (`min_p`). */
+    minP?: number;
+    /** Anthropic `stop_sequences` / OpenAI `stop`. */
+    stopSequences?: string[];
+    /** OpenAI `presence_penalty`. */
+    presencePenalty?: number;
+    /** OpenAI `frequency_penalty`. */
+    frequencyPenalty?: number;
+    /** OpenRouter / vLLM `repetition_penalty`. */
+    repetitionPenalty?: number;
+    /** OpenAI deterministic-sampling `seed`. */
+    seed?: number;
+    /** OpenAI `logit_bias` map (token id → bias). */
+    logitBias?: Record<string, number>;
+    /** OpenAI `response_format` (text | json_object | json_schema). Opaque passthrough. */
+    responseFormat?: unknown;
+    toolChoice?: AuthGatewayToolChoice;
+    /** OpenAI `parallel_tool_calls`. */
+    parallelToolCalls?: boolean;
+    /** OpenAI Responses fields requested in the response payload. */
+    include?: OpenAIResponseInclude[];
+    /** Effort-level reasoning request (OpenAI Responses / Chat `reasoning_effort`). */
+    reasoning?: Effort;
+    /** Force-disable reasoning (Anthropic `thinking: { type: "disabled" }`). */
+    disableReasoning?: boolean;
+    /**
+     * Explicit Anthropic `thinking.budget_tokens`. Mirrors Rust's
+     * `resolve_thinking_budget`: pins onto whichever effort the client
+     * requested (defaulting to High when unspecified). Preferred over the
+     * removed legacy single-number `thinkingBudget` for new code.
+     */
+    explicitThinkingBudgetTokens?: number;
+    /** Per-effort thinking budget map. */
+    thinkingBudgets?: Partial<Record<Effort, number>>;
+    /** Suppress the provider's reasoning summary stream. */
+    hideThinkingSummary?: boolean;
+    /** Anthropic `output_config.task_budget` advisory loop budget. */
+    taskBudget?: TokenTaskBudget;
+    /** OpenAI service tier (auto|default|flex|scale|priority). */
+    serviceTier?: ServiceTier;
+    /** Cache retention hint derived from inbound `cache_control` markers. */
+    cacheRetention?: CacheRetention;
+    /** OpenAI Responses `prompt_cache_key`; also seeds provider routing when no separate session id exists. */
+    promptCacheKey?: string;
+    /** OpenAI Responses `previous_response_id` for response chaining. */
+    previousResponseId?: string;
+    /** OpenAI / abuse-tracking `user` field. */
+    user?: string;
+    /**
+     * Provider-specific metadata. Anthropic uses `metadata.user_id`; OpenRouter
+     * carries routing hints; xAI uses `search_parameters`; OpenAI accepts a
+     * free-form bag. The gateway forwards as-is.
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * Captured allow-listed passthrough headers (anthropic-beta,
+     * anthropic-version, openai-organization, openai-project, openai-beta,
+     * x-stainless-*). Keys are lowercased.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Escape hatch for provider-specific request controls that don't yet have a
+     * first-class field. Prefer adding a typed field over widening this.
+     */
+    extra?: Record<string, unknown>;
+}
+export interface AuthGatewayParsedRequest {
+    modelId: string;
+    context: Context;
+    stream: boolean;
+    options: AuthGatewayParsedRequestOptions;
+}
+export interface AuthGatewayStreamControl {
+    /** Gateway request signal. Encoders stop producing frames when it aborts. */
+    signal?: AbortSignal;
+    /** Called when the HTTP response body is cancelled by the client. */
+    onCancel?: (reason?: unknown) => void;
+}
+export interface AuthGatewayFormatModule {
+    parseRequest(body: unknown, headers?: Headers): AuthGatewayParsedRequest;
+    encodeResponse(message: AssistantMessage, requestedModelId: string): Record<string, unknown>;
+    encodeStream(events: AssistantMessageEventStream, requestedModelId: string, options?: AuthGatewayParsedRequestOptions, control?: AuthGatewayStreamControl): ReadableStream<Uint8Array>;
+    /**
+     * Emit a protocol-specific error envelope. OpenAI returns
+     * `{ error: { message, type } }`; Anthropic returns
+     * `{ type: "error", error: { type, message } }`.
+     */
+    formatError(status: number, type: string, message: string): Response;
+}
+export interface AuthGatewayServerOptions {
+    /** Listen address. Default `127.0.0.1:4000`. */
+    bind?: string;
+    /** Accept any of these bearer tokens. Empty allows unauthenticated calls. */
+    bearerTokens: string[];
+    /** Version surfaced on `/healthz`. */
+    version?: string;
+}
+export interface AuthGatewayServerHandle {
+    url: string;
+    port: number;
+    hostname: string;
+    close(): Promise<void>;
+}

package/dist/types/auth-retry.d.ts

@@ -0,0 +1,150 @@
+import type { OAuthAccess } from "./auth-storage.js";
+import { isAuthRetryableError } from "./error/auth-classify.js";
+/**
+ * Context passed to an {@link ApiKeyResolver} on each resolution attempt.
+ *
+ * The `error`/`lastChance` pair preserves the legacy a/b/c resolver contract
+ * shared by streaming ({@link streamSimple}) and non-streaming ({@link withAuth})
+ * drivers:
+ * - `error === undefined` → **initial resolve** (no force-refresh; cheap, may
+ *   return a locally-cached not-yet-expired token).
+ * - `error !== undefined && !lastChance` → **step (b): refresh the SAME
+ *   account** (force a token re-mint / await an in-flight broker refresh).
+ * - `error !== undefined && lastChance` → **step (c): switch account**
+ *   (invalidate/usage-limit the current credential and rotate to a sibling).
+ *
+ * Current drivers preserve that bounded a/b/c sequence for ordinary 401/auth
+ * failures. 403/usage-limit failures skip refresh and may repeat step (c)
+ * until the resolver returns `undefined`, cycles, or hits
+ * {@link AUTH_RETRY_MAX_ATTEMPTS}.
+ */
+export interface ApiKeyResolveContext {
+    /** True when the resolver should rotate to a sibling credential. */
+    lastChance: boolean;
+    /** The auth error that triggered this re-resolution, or `undefined` on the initial resolve. */
+    error: unknown;
+    /** Bearer used by the failed attempt, when the caller can expose it. */
+    previousKey?: string;
+    /** Caller cancel signal, threaded into any credential refresh / rotation work. */
+    signal?: AbortSignal;
+}
+/**
+ * Resolves the API key to send for a request, retried through the a/b/c policy
+ * described on {@link ApiKeyResolveContext}.
+ */
+export type ApiKeyResolver = (ctx: ApiKeyResolveContext) => Promise<string | undefined> | string | undefined;
+/** A static bearer string, or a {@link ApiKeyResolver} that mints/rotates one. */
+export type ApiKey = string | ApiKeyResolver;
+/** Narrows {@link ApiKey} to its resolver form. */
+export declare function isApiKeyResolver(key: ApiKey | undefined): key is ApiKeyResolver;
+/**
+ * Performs the initial resolve of an {@link ApiKey} (`error: undefined`,
+ * `lastChance: false`). Static keys pass through unchanged.
+ */
+export declare function resolveApiKeyOnce(key: ApiKey | undefined, signal?: AbortSignal): Promise<string | undefined>;
+/**
+ * Wraps a resolver with a bearer that was already selected for this request.
+ *
+ * Callers that preflight credentials can pass the returned resolver to the
+ * auth-retry driver without making the driver know about that preflight: the
+ * first initial resolution reuses `seed`, and all later resolutions delegate to
+ * `resolver`.
+ */
+export declare function seedApiKeyResolver(seed: string | undefined, resolver: ApiKeyResolver): ApiKeyResolver;
+export { isAuthRetryableError };
+/**
+ * Legacy bounded a/b/c retry sequence retained for public compatibility:
+ * `false` → refresh-same, `true` → rotate/switch. Current drivers consume it
+ * once for ordinary 401/auth failures; usage/account-limit failures may repeat
+ * sibling rotation until a termination guard fires.
+ */
+export declare const AUTH_RETRY_STEPS: readonly boolean[];
+export declare const AUTH_RETRY_MAX_ATTEMPTS = 64;
+/** Resolve a single retry step, swallowing resolver failures into `undefined`. */
+export declare function resolveRetryKey(resolver: ApiKeyResolver, lastChance: boolean, error: unknown, signal?: AbortSignal, previousKey?: string): Promise<string | undefined>;
+export interface AuthRetryKeyState {
+    /** Bearer strings already sent during this logical operation. */
+    attemptedKeys: Set<string>;
+    /** Bearer used by the most recent failed attempt. */
+    lastKey: string;
+    /** Whether the current credential already consumed its 401 refresh-same retry. */
+    refreshedCurrent: boolean;
+    /** Whether the legacy non-usage auth path already switched to one sibling. */
+    legacyAuthSwitchUsed: boolean;
+    /** Total outbound attempts accepted for this logical operation, including the initial request. */
+    attempts: number;
+}
+export declare function createAuthRetryKeyState(initialKey: string): AuthRetryKeyState;
+export declare function resolveNextAuthRetryKey(state: AuthRetryKeyState, resolver: ApiKeyResolver, error: unknown, signal?: AbortSignal): Promise<string | undefined>;
+/**
+ * Runs an auth-protected operation through the central a/b/c retry policy.
+ *
+ * - A static string key (or any non-resolver) → a single `attempt` with no
+ *   retry (identical to the legacy static-key path).
+ * - A resolver → initial `attempt`, then resolver-driven retries until the
+ *   applicable policy is exhausted, the resolver declines or cycles, or the
+ *   operation reaches {@link AUTH_RETRY_MAX_ATTEMPTS}. Ordinary 401/auth
+ *   failures retain one refresh-same plus one sibling switch; 403/usage-limit
+ *   failures rotate directly through distinct siblings.
+ *
+ * Used by non-streaming consumers (image generation, web search, completion
+ * helpers). The streaming driver in `stream.ts` implements the same policy with
+ * its replay-safe buffering machinery.
+ */
+export declare function withAuth<T>(key: ApiKey | undefined, attempt: (key: string) => Promise<T>, opts?: {
+    isAuthError?: (error: unknown) => boolean;
+    signal?: AbortSignal;
+    missingKeyMessage?: string;
+}): Promise<T>;
+/**
+ * Minimal structural slice of `AuthStorage` consumed by {@link withOAuthAccess}.
+ * Typed structurally (and importing only the `OAuthAccess` type) so this module
+ * never takes a runtime dependency on `./auth-storage`.
+ */
+export interface OAuthAccessSource {
+    getOAuthAccess(provider: string, sessionId?: string, options?: {
+        forceRefresh?: boolean;
+        signal?: AbortSignal;
+    }): Promise<OAuthAccess | undefined>;
+    rotateSessionCredential(provider: string, sessionId: string | undefined, options?: {
+        error?: unknown;
+        signal?: AbortSignal;
+        apiKey?: string;
+        credentialId?: number;
+    }): Promise<boolean>;
+}
+export interface WithOAuthAccessOptions {
+    /** Session id for credential stickiness, threaded into every resolve. */
+    sessionId?: string;
+    signal?: AbortSignal;
+    /** Override the retryable-error classifier (default {@link isAuthRetryableError}). */
+    isAuthError?: (error: unknown) => boolean;
+    /**
+     * Pre-resolved access used for the initial attempt. Callers that already
+     * resolved access for an availability gate pass it here so the helper
+     * doesn't double-resolve (mirrors the gateway resolver's `initialKey`).
+     */
+    seed?: OAuthAccess;
+    missingAccessMessage?: string;
+}
+/**
+ * {@link withAuth} for OAuth-access consumers: runs an auth-protected
+ * operation through the central a/b/c retry policy, handing the attempt the
+ * full {@link OAuthAccess} (bearer + identity metadata: `accountId`,
+ * `projectId`, `enterpriseUrl`) instead of bare API-key bytes.
+ *
+ * - initial → `getOAuthAccess` (or `opts.seed`).
+ * - 401/auth failure → one `getOAuthAccess` with `forceRefresh: true` for the
+ *   current account, then sibling rotation.
+ * - 403/usage-limit failure → `rotateSessionCredential` directly, without a
+ *   force-refresh detour.
+ *
+ * A refresh-same step may retry a new bearer for the same credential identity;
+ * sibling rotation stops when it yields a credential identity
+ * (`credentialId ?? accessToken`) or bearer already attempted in this turn.
+ * All OAuth attempts share the {@link AUTH_RETRY_MAX_ATTEMPTS} ceiling.
+ * Non-auth errors propagate immediately. Use this instead of hand-rolled
+ * `getOAuthAccess` + fetch flows so 401s and usage-limits rotate credentials
+ * instead of failing the call.
+ */
+export declare function withOAuthAccess<T>(storage: OAuthAccessSource, provider: string, attempt: (access: OAuthAccess) => Promise<T>, opts?: WithOAuthAccessOptions): Promise<T>;