@oh-my-pi/pi-ai 15.1.1 → 15.1.3

package/CHANGELOG.md

@@ -2,6 +2,116 @@
 
 ## [Unreleased]
 
+## [15.1.3] - 2026-05-17
+### Breaking Changes
+
+- Changed `AuthBrokerClient.fetchSnapshot()` to return status-based results (`200` or `304`) instead of always returning a raw snapshot body, so callers now need to branch on `status`
+- Renamed public schema utilities in `@oh-my-pi/pi-ai/utils/schema` by replacing `sanitizeSchemaForGoogle`, `sanitizeSchemaForCCA`, `prepareSchemaForCCA`, and `sanitizeSchemaForMCP` with `normalizeSchemaForGoogle`, `normalizeSchemaForCCA`, and `normalizeSchemaForMCP`
+- Added MCP schema normalization via `normalizeSchemaForMCP` for compatibility checks
+- Removed the `StringEnum` helper from `@oh-my-pi/pi-ai/utils/schema`. Use `z.enum([...])` directly; Zod's emitted JSON Schema is already wire-compatible with Google and other providers.
+- Renamed the concrete SQLite credential store class from `AuthCredentialStore` to `SqliteAuthCredentialStore`. `AuthCredentialStore` is now the persistence interface implemented by both the SQLite store and the new `RemoteAuthCredentialStore`. Update `new AuthCredentialStore(db)` / `AuthCredentialStore.open(...)` call-sites to `SqliteAuthCredentialStore`; type-position uses (`store: AuthCredentialStore`) continue to work unchanged.
+
+### Added
+
+- Added `onAuthError` to `StreamOptions` and wired `streamSimple()` to retry once with a replacement API key when the first provider response is a 401 before any assistant events are emitted
+- Added generation-aware snapshot metadata (`generation`, `serverNowMs`, `refresher`, and `rotatesInMs`) to auth-broker snapshot responses to support client-side credential-rotation planning
+- Added `transport: "pi-native"` on `Model` and the matching `streamPiNative` client. When `model.transport === "pi-native"`, `streamSimple` short-circuits the per-provider dispatch and POSTs the canonical `Context` to the auth-gateway's `POST /v1/pi/stream` endpoint. The response is SSE-framed `AssistantMessageEvent`s parsed by `readSseJson` and pushed verbatim into the local `AssistantMessageEventStream` — no wire-format translation, no partial-stripping reconstruction. Used by containerized omp installs (robomp slots, swarm extension, etc.) to route every LLM call through a credential-holding sidecar; the slot itself never sees the real provider tokens. Server-controlled fields (`apiKey`, `signal`, `fetch`, lifecycle callbacks, the provider-session map) are stripped from the wire body — `apiKey` rides in the `Authorization` header as the gateway bearer.
+- Added `POST /v1/pi/stream` to the auth-gateway. Same auth + abort + model-resolution + codex-compat + prefix-cache plumbing as the foreign-wire routes; only the wire-format translation is skipped. Request body is `{ modelId, context, options?, stream? }` where `context` is the canonical pi-ai `Context` and `options` is `SimpleStreamOptions` with non-serializable fields stripped. Response is SSE-framed `AssistantMessageEvent` (terminated by `data: [DONE]`) when streaming, or `{ message: AssistantMessage }` JSON when `stream: false`.
+- Added Vertex AI authentication via Google Application Default Credentials from `GOOGLE_APPLICATION_CREDENTIALS`, `~/.config/gcloud/application_default_credentials.json`, or metadata server tokens, with token caching and refresh skew control via `GOOGLE_VERTEX_REFRESH_SKEW_MS`
+- Added support for Anthropic image message parts with `type: "url"` and `type: "file"` sources
+- Added `stopSequences` and `frequencyPenalty` to shared stream options and wired them through to OpenAI request translation
+- Added optional request cancellation support to auth-broker interactions by propagating `AbortSignal` into health, snapshot, usage, and refresh calls
+- Added `AuthStorage.setConfigApiKey` / `removeConfigApiKey` / `clearConfigApiKeys` for config-sourced per-provider bearers (e.g. `models.yml` `providers.<name>.apiKey`). The new tier sits between runtime `--api-key` and stored credentials in `getApiKey`/`peekApiKey` resolution, so a bearer pinned in config now beats the broker's OAuth access token. Also suppresses OAuth `account_uuid` attribution when active, since outbound auth is the explicit config bearer, not OAuth. `describeCredentialSource` reports `"config override (models.yml)"` for visibility.
+- Added per-model `additional_rate_limits` parsing to `openaiCodexUsageProvider`. The Codex `wham/usage` endpoint surfaces a separate `GPT-5.3-Codex-Spark` rate limit (`metered_feature: codex_bengalfox`) on Pro accounts; these now emit dedicated `openai-codex:spark:{primary,secondary}` `UsageLimit` entries with `scope.tier = "spark"`, mirroring how Anthropic exposes `anthropic:7d:sonnet` separately from the umbrella `anthropic:7d` bucket. The osx-widgets client already keyed spark detection off `limit.id.includes("spark")`; this populates that contract end-to-end.
+- Added `GET /v1/usage` to the auth-broker API to expose aggregated usage reports from `AuthStorage.fetchUsageReports`
+- Added auth-broker usage polling response handling that returns normalized usage reports plus generation timestamp for clients (5-min per-credential cache via `AuthStorage`)
+- Added the auth-broker subsystem (`@oh-my-pi/pi-ai/auth-broker`) for sharing OAuth credentials across machines without leaking refresh tokens.
+- `startAuthBroker(...)` boots a `Bun.serve` HTTP server exposing `GET /v1/healthz`, `GET /v1/snapshot`, `POST /v1/credential` (upsert), `POST /v1/credential/:id/refresh`, and `POST /v1/credential/:id/disable`.
+- `AuthBrokerClient` is the matching HTTP client used by remote clients.
+- `RemoteAuthCredentialStore` is a client-side `AuthCredentialStore` that mirrors a broker snapshot in memory; mutating methods (`replace*`, `upsert*`, `delete*ForProvider`) throw because writes are server-side only.
+- `AuthBrokerRefresher` is the background refresh loop that pre-refreshes credentials within `refreshSkewMs` and disables on definitive failure (`invalid_grant` / non-network 401-403).
+- Added `AuthStorage.exportSnapshot()`, `AuthStorage.upsertCredential(provider, credential)`, `AuthStorage.forceRefreshCredentialById(id)`, and `AuthStorage.disableCredentialById(id, cause)` public methods consumed by the auth-broker server.
+- Added `AuthStorageOptions.refreshOAuthCredential` override so a remote-store client can route every OAuth refresh through the broker instead of the local OAuth endpoint.
+- Added `REMOTE_REFRESH_SENTINEL` (`"__remote__"`) — the wire placeholder substituted for OAuth refresh tokens in broker snapshots; clients never see the real refresh token.
+- Exposed the OAuth provider catalog (`getOAuthProviders`, `OAuthProvider`, `OAuthProviderInfo`) and `refreshOAuthToken` through the package barrel so the coding-agent CLI can target them without reaching into `utils/oauth`.
+- Added the auth-gateway subsystem (`@oh-my-pi/pi-ai/auth-gateway`) — a forward-proxy that sits between unauthenticated clients (the macOS usage widget, llm-git, robomp containers, …) and the broker. Clients send standard provider-format requests; the gateway parses them into omp's canonical `Context`, dispatches through pi-ai's `streamSimple()`, and translates the canonical event stream back to the matching wire format. `Authorization` is injected server-side so access tokens never leave the gateway host. Wire surface:
+- `GET  /healthz` — unauth liveness.
+- `GET  /v1/usage` — aggregated provider usage; 5-min per-credential cache via `AuthStorage.fetchUsageReports`.
+- `GET  /v1/models` — model catalog (scoped to providers with credentials).
+- `POST /v1/chat/completions` — OpenAI chat-completions in/out.
+- `POST /v1/messages` — Anthropic messages in/out (text + thinking + tool_use blocks, SSE event taxonomy preserved).
+- `POST /v1/responses` — OpenAI Responses in/out (reasoning items + function_call output items, SSE pass-through).
+- Added exports from `@oh-my-pi/pi-ai/auth-gateway`: `startAuthGateway`, `AuthGatewayServerOptions`, `AuthGatewayBootOptions`, `AuthGatewayServerHandle`, `ModelResolver`, `DEFAULT_AUTH_GATEWAY_BIND`. Per-format `parseRequest` / `encodeResponse` / `encodeStream` triples are reachable via the `./providers/*` subpath as `openai-chat-server`, `anthropic-messages-server`, and `openai-responses-server`.
+- Added `listProvidersWithEnvKey()` to enumerate every provider with an env-var fallback (used by the new migrate command in coding-agent).
+
+### Changed
+
+- Changed `GET /v1/snapshot` to support generation-based polling with `If-None-Match` and `wait` for long-poll updates and to return `304` when no snapshot changes are available
+- Changed Bedrock credential resolution for streaming calls to prefer environment keys, AWS profile/SSO credentials, and IMDSv2 fallback when available
+- Changed auth-gateway parsing for OpenAI chat-completions and Responses to ignore unsupported SDK-only fields instead of rejecting requests
+- Changed auth-gateway protocol handling to include CORS headers on responses and support browser-origin requests
+- Changed prompt-cache handling to resolve cache keys from request metadata and headers and preserve them through protocol translation
+- Changed Anthropic messages parsing to forward request `metadata` through to downstream execution
+- Changed usage report caching to use a 5-minute per-credential TTL with jittered refresh timing to reduce usage endpoint rate-limit collisions
+- Changed usage polling failure handling so transient errors continue serving the last known report instead of returning null and dropping the credential from usage aggregates after cache expiry
+- Changed `sanitizeSchemaForGoogle` to normalize snake_case schema keys (such as `any_of` and `additional_properties`) to camelCase and auto-generate `propertyOrdering` for multi-property objects
+- Changed strict-mode sanitization to resolve `$ref` nodes with sibling keys by inlining and merging referenced local definitions
+- Changed strict-mode sanitization to flatten single-entry `allOf` nodes and remove the `allOf` wrapper
+- Changed Anthropic tool schema normalization to preserve supported metadata keywords such as `$ref`, `$defs`, `$schema`, `enum`, `const`, `default`, `title`, and `nullable` instead of stripping them
+- Changed string schema processing to retain only supported `format` values (`date-time`, `time`, `date`, `duration`, `email`, `hostname`, `uri`, `ipv4`, `ipv6`, `uuid`) and demote unsupported `format` values to `description` hints
+
+### Fixed
+
+- Fixed OAuth credential refresh flow so concurrent manual and background refreshes now share one in-flight attempt per credential, and `RemoteAuthCredentialStore` now re-synchronizes before using near-expiring OAuth credentials
+- Fixed stale-credential handling after auth failures by waiting for updated broker snapshots and refreshing suspect credentials through broker endpoints before continuing
+- Fixed Google Generative AI startup behavior to throw a clear API-key-required error when no key is configured
+- Fixed AWS Bedrock image message serialization to preserve base64 `source.bytes` payloads instead of decoding and rebuilding them
+- Fixed Google provider error handling to extract the API-reported `error.message` from JSON response bodies when available
+- Fixed `RemoteAuthCredentialStore.getUsageReport` to return the matching credential-specific usage report and coalesce parallel callers into one broker `/v1/usage` fetch
+- Fixed auth-broker credential upload validation to reject the remote refresh-token sentinel and prevent storing a non-refresh value
+- Fixed OpenAI Responses streaming output to emit `reasoning_summary_text` events and parse/send `summary_text` reasoning payloads
+- Fixed Anthropic stop-sequence handling by trimming requests to the API limit of four entries before forwarding
+- Fixed prompt caching behavior across protocol translations so cached-token usage is preserved when Anthropic and OpenAI requests are routed through each other
+- Fixed Claude usage fetching to retry transient `429` and `5xx` responses with exponential backoff, respecting `Retry-After` before returning failure
+- Fixed auth-gateway request translation to preserve OpenAI Responses string/system message content, reasoning replay payloads, completed item text in stream item-done events, Anthropic tool-result ordering, and OpenAI Chat/Responses cached-token usage totals
+- Fixed auth-gateway failure handling so unsupported request controls, upstream terminal errors, non-streaming aborts, and already-aborted client requests fail explicitly instead of being accepted, ignored, or encoded as successful HTTP 200 responses
+- Fixed Gemini CLI / Antigravity tool schema normalization to run the full Cloud Code Assist pipeline, matching shared Google schema handling for union/object merging and nullable extraction
+- Fixed stripped validation hints to be preserved as description spill text (`{key: value}` blocks) when `normalizeSchemaForGoogle` and `normalizeSchemaForCCA` drop unsupported schema keywords
+- Fixed `sanitizeSchemaForGoogle` to collapse nullability forms (`type:'null'` and null-bearing `anyOf` variants) into `nullable` while preserving remaining variants
+- Fixed `sanitizeSchemaForGoogle` to inline local `$defs` references instead of dropping `$ref`/`$defs` structure during Google schema sanitization
+- Fixed `normalizeAnthropicToolSchema` to handle self-referential schemas without infinite recursion
+- Fixed object schema normalization so explicit open-map declarations (`additionalProperties: true` and schema-valued `additionalProperties`) are preserved instead of being converted to closed objects
+- Fixed unsupported schema constraints on arrays and strings (`maxItems`, `uniqueItems`, `pattern`, `minLength`, `maxLength`, and `minItems` when greater than 1) by demoting them into `description` rather than dropping them
+
+### Security
+
+- Hardened auth-gateway bearer-token checks with constant-time comparison to avoid timing-side-channel leaks
+
+## [15.1.2] - 2026-05-15
+### Breaking Changes
+
+- Rejected draft-07 tuple and dependency keywords (`items` arrays, `dependencies`, `additionalItems`) in JSON Schema validation
+
+### Added
+
+- Added `responseHeaders`, `responseStatus`, and `responseRequestId` fields to `MockResponse` so mock providers can provide synthetic `ProviderResponseMetadata`
+- Added `onResponse` metadata emission for mocks that sends lowercased headers and a default status of 200 before streaming when response headers are configured
+- Added recursive strict-mode sanitization for array `prefixItems` entries so tuple schemas now enforce object constraints per item
+
+### Changed
+
+- Normalized legacy draft-07 JSON Schema constructs used in tool parameters (`items` arrays, `additionalItems`, `definitions`, `dependencies`) to draft 2020-12 before OpenAI/Google/CCA sanitization, wire conversion, and argument validation
+- Reworked OpenAI response schema adaptation to rewrite `oneOf` into `anyOf` while preserving existing `anyOf` branches
+- Changed tuple array validation to validate per-index schemas from `prefixItems` and apply `items` only to remaining elements
+
+### Fixed
+
+- Fixed validation of plain JSON Schema tool arguments that omitted a `$schema` URI so draft-07-shaped schemas now pass validation instead of being rejected
+- Fixed tuple-array validation for legacy JSON Schema tool schemas to enforce `additionalItems: false` and per-position constraints after automatic draft upgrade
+- Fixed Anthropic tool schema normalization to recurse into `prefixItems` so unsupported constraints inside tuple items are stripped in the generated input schema
+- Fixed Anthropic tool-schema normalization stripping the body of explicit open `additionalProperties` (e.g. Zod's `z.record(z.string(), z.unknown())` compiling to `additionalProperties: {}`) by unconditionally overwriting it with `false`, which closed record-style fields and prevented models from supplying any key. The coding-agent's `resolve` tool exposes plan-approval titles via such a field, so Kimi K2 (and any other Anthropic-shaped provider) could not pass `extra: { title }`, blocking plan mode entirely ([#1104](https://github.com/can1357/oh-my-pi/issues/1104))
+- Fixed Anthropic strict tool planning to leave tools with open `additionalProperties` maps non-strict instead of sending schemas Anthropic rejects.
+
 ## [15.1.0] - 2026-05-15
 
 ### Breaking Changes

package/README.md

@@ -89,7 +89,7 @@ npm install @oh-my-pi/pi-ai
 ## Quick Start
 
 ```typescript
-import { z, getModel, stream, complete, Context, Tool, StringEnum } from "@oh-my-pi/pi-ai";
+import { z, getModel, stream, complete, Context, Tool } from "@oh-my-pi/pi-ai";
 
 // Fully typed with auto-complete support for both providers and models
 const model = getModel("openai", "gpt-4o-mini");
@@ -221,7 +221,7 @@ Tools enable LLMs to interact with external systems. This library uses **Zod** s
 ### Defining Tools
 
 ```typescript
-import { z, Tool, StringEnum } from "@oh-my-pi/pi-ai";
+import { z, Tool } from "@oh-my-pi/pi-ai";
 
 // Define tool parameters with Zod
 const weatherTool: Tool = {
@@ -229,13 +229,10 @@ const weatherTool: Tool = {
 	description: "Get current weather for a location",
 	parameters: z.object({
 		location: z.string().describe("City name or coordinates"),
-		units: StringEnum(["celsius", "fahrenheit"], { default: "celsius" }),
+		units: z.enum(["celsius", "fahrenheit"]).default("celsius"),
 	}),
 };
 
-// Note: For Google API compatibility, use the StringEnum helper instead of z.enum alone
-// when you need wire-compatible { type: "string", enum: [...] } shapes.
-
 const bookMeetingTool: Tool = {
 	name: "book_meeting",
 	description: "Schedule a meeting",

package/dist/types/api-registry.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Custom API provider registry.
+ *
+ * Allows extensions to register streaming functions for custom API types
+ * (e.g., "vertex-claude-api") that are not built into stream.ts.
+ */
+import type { Api, AssistantMessageEventStream, Context, Model, SimpleStreamOptions, StreamOptions } from "./types";
+export type CustomStreamFn = (model: Model<Api>, context: Context, options?: StreamOptions) => AssistantMessageEventStream;
+export type CustomStreamSimpleFn = (model: Model<Api>, context: Context, options?: SimpleStreamOptions) => AssistantMessageEventStream;
+export interface RegisteredCustomApi {
+    stream: CustomStreamFn;
+    streamSimple: CustomStreamSimpleFn;
+    sourceId?: string;
+}
+/**
+ * Register a custom API streaming function.
+ */
+export declare function registerCustomApi(api: string, streamSimple: CustomStreamSimpleFn, sourceId?: string, stream?: CustomStreamFn): void;
+/**
+ * Get a custom API provider by API identifier.
+ */
+export declare function getCustomApi(api: string): RegisteredCustomApi | undefined;
+/**
+ * Remove all custom APIs registered by a specific source (e.g., extension path).
+ */
+export declare function unregisterCustomApis(sourceId: string): void;
+/**
+ * Clear all custom API registrations.
+ */
+export declare function clearCustomApis(): void;

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

@@ -0,0 +1,46 @@
+import type { AuthCredential } from "../auth-storage";
+import type { CredentialDisableResponse, CredentialRefreshResponse, CredentialUploadResponse, HealthzResponse, SnapshotResponse, UsageResponse } from "./types";
+export interface AuthBrokerClientOptions {
+    /** Base URL (e.g. `https://broker.tailnet:8765`). Trailing slashes are trimmed. */
+    url: string;
+    /** Bearer token used for everything except `healthz`. */
+    token: string;
+    /** Per-request timeout in milliseconds. Default 10s. */
+    timeoutMs?: number;
+    /** Retry connection errors this many times. Default 1. */
+    maxRetries?: number;
+    /** Override fetch (used in tests). Default global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+export declare class AuthBrokerError extends Error {
+    readonly status: number | undefined;
+    readonly body: string | undefined;
+    constructor(message: string, opts?: {
+        status?: number;
+        body?: string;
+        cause?: unknown;
+    });
+}
+export interface FetchSnapshotOptions {
+    ifGenerationGt?: number;
+    waitMs?: number;
+    signal?: AbortSignal;
+}
+export type FetchSnapshotResult = {
+    status: 200;
+    snapshot: SnapshotResponse;
+    generation: number;
+} | {
+    status: 304;
+    generation: number;
+};
+export declare class AuthBrokerClient {
+    #private;
+    constructor(opts: AuthBrokerClientOptions);
+    healthz(signal?: AbortSignal): Promise<HealthzResponse>;
+    fetchSnapshot(opts?: FetchSnapshotOptions): Promise<FetchSnapshotResult>;
+    fetchUsage(signal?: AbortSignal): Promise<UsageResponse>;
+    refreshCredential(id: number, signal?: AbortSignal): Promise<CredentialRefreshResponse>;
+    disableCredential(id: number, cause: string, signal?: AbortSignal): Promise<CredentialDisableResponse>;
+    uploadCredential(provider: string, credential: AuthCredential, signal?: AbortSignal): Promise<CredentialUploadResponse>;
+}

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

@@ -0,0 +1,5 @@
+export * from "./client";
+export * from "./refresher";
+export * from "./remote-store";
+export * from "./server";
+export * from "./types";

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

@@ -0,0 +1,25 @@
+import type { AuthStorage } from "../auth-storage";
+export interface AuthBrokerRefresherOptions {
+    storage: AuthStorage;
+    /** Refresh credentials expiring within this window. Default 5 min. */
+    refreshSkewMs?: number;
+    /** Loop cadence. Default 60s. */
+    refreshIntervalMs?: number;
+    /** Override clock (tests). */
+    now?: () => number;
+}
+export interface AuthBrokerRefresherSchedule {
+    enabled: boolean;
+    intervalMs: number;
+    skewMs: number;
+    nextSweepAt: number;
+}
+export declare class AuthBrokerRefresher {
+    #private;
+    constructor(opts: AuthBrokerRefresherOptions);
+    start(): void;
+    stop(): void;
+    getSchedule(): AuthBrokerRefresherSchedule;
+    /** Run one sweep. Exposed for tests. */
+    tick(): Promise<void>;
+}

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

@@ -0,0 +1,71 @@
+import { type AuthCredential, type AuthCredentialStore, type OAuthCredential, type StoredAuthCredential } from "../auth-storage";
+import type { Provider } from "../types";
+import type { UsageReport } from "../usage";
+import type { OAuthCredentials } from "../utils/oauth/types";
+import type { AuthBrokerClient } from "./client";
+import type { SnapshotResponse } from "./types";
+export interface RemoteAuthCredentialStoreOptions {
+    client: AuthBrokerClient;
+    /**
+     * Initial snapshot. When omitted, callers must call
+     * {@link RemoteAuthCredentialStore.refreshSnapshot} before the first read.
+     */
+    initialSnapshot?: SnapshotResponse;
+}
+export declare class RemoteAuthCredentialStore implements AuthCredentialStore {
+    #private;
+    constructor(opts: RemoteAuthCredentialStoreOptions);
+    get client(): AuthBrokerClient;
+    get snapshot(): SnapshotResponse;
+    /** Re-hydrate the in-memory snapshot from the broker. */
+    refreshSnapshot(): Promise<SnapshotResponse>;
+    listAuthCredentials(provider?: string): StoredAuthCredential[];
+    /**
+     * In-memory update from a successful refresh through the broker. AuthStorage
+     * calls this after `#replaceCredentialAt`; the broker already persisted the
+     * authoritative row, so we just mirror it.
+     */
+    updateAuthCredential(id: number, credential: AuthCredential): void;
+    deleteAuthCredential(id: number, disabledCause: string): void;
+    tryDisableAuthCredentialIfMatches(id: number, _expectedData: string, disabledCause: string): boolean;
+    waitForFreshSnapshot(maxWaitMs: number, opts?: {
+        signal?: AbortSignal;
+    }): Promise<boolean>;
+    prepareForRequest(credentialId: number, opts?: {
+        signal?: AbortSignal;
+    }): Promise<boolean>;
+    markCredentialSuspect(credentialId: number, opts?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    replaceAuthCredentialsForProvider(_provider: string, _credentials: AuthCredential[]): StoredAuthCredential[];
+    upsertAuthCredentialForProvider(_provider: string, _credential: AuthCredential): StoredAuthCredential[];
+    deleteAuthCredentialsForProvider(_provider: string, _disabledCause: string): void;
+    getCache(key: string): string | null;
+    setCache(key: string, value: string, expiresAtSec: number): void;
+    cleanExpiredCache(): void;
+    /**
+     * Store-level hook consumed by `AuthStorage` — routes refresh through the
+     * broker so the actual refresh token never leaves the broker host. Returns
+     * the broker-redacted credential with {@link REMOTE_REFRESH_SENTINEL} in
+     * the `refresh` slot.
+     */
+    refreshOAuthCredential(_provider: Provider, credentialId: number, _credential: OAuthCredential, signal?: AbortSignal): Promise<OAuthCredentials>;
+    /**
+     * Store-level hook consumed by `AuthStorage.fetchUsageReports()` — proxies
+     * to the broker's `/v1/usage` endpoint. The broker's egress IP isn't
+     * rate-limited by Anthropic's per-IP `/usage` cap the way a heavy
+     * residential laptop is, so all credentials surface every cycle.
+     */
+    fetchUsageReports(signal?: AbortSignal): Promise<UsageReport[] | null>;
+    /**
+     * Per-credential usage hook consumed by `AuthStorage.#getUsageReport`. Pulls
+     * the aggregate broker `/v1/usage` once and serves all callers from the
+     * same response (coalesced + cached), then matches the credential to a
+     * report by provider + identity (accountId / email / projectId).
+     *
+     * The broker already aggregates with its own 30s TTL on the server side; our
+     * 15s client TTL is below that so we usually re-use the broker's cache too.
+     */
+    getUsageReport(provider: Provider, credential: OAuthCredential, signal?: AbortSignal): Promise<UsageReport | null>;
+    close(): void;
+}

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

@@ -0,0 +1,26 @@
+import type { AuthStorage } from "../auth-storage";
+export interface AuthBrokerServerOptions {
+    /** Underlying credential storage (wraps the local SQLite store on the broker). */
+    storage: AuthStorage;
+    /** Listen address; accepts `host:port` or just `port`. */
+    bind?: string;
+    /** Accept any of these bearer tokens. Empty disables auth (loopback only). */
+    bearerTokens: string[];
+    /** Broker version string surfaced on `/v1/healthz`. */
+    version?: string;
+    /** Refresh credentials expiring within this window. Default 5 min. */
+    refreshSkewMs?: number;
+    /** Background refresh cadence. Default 60s. */
+    refreshIntervalMs?: number;
+    /** Disable the background refresher (e.g. for tests). */
+    disableRefresher?: boolean;
+}
+export interface AuthBrokerServerHandle {
+    /** Bound URL (`http://host:port`). */
+    url: string;
+    port: number;
+    hostname: string;
+    close(): Promise<void>;
+}
+/** Boot the broker. Caller owns lifecycle; `handle.close()` to stop. */
+export declare function startAuthBroker(opts: AuthBrokerServerOptions): AuthBrokerServerHandle;

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

@@ -0,0 +1,69 @@
+/**
+ * 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 } from "../auth-storage";
+import type { UsageReport } from "../usage";
+/** 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 SnapshotEntry = AuthCredentialSnapshotEntry & {
+    rotatesInMs: number | null;
+};
+/** 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[];
+}
+/** 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;
+}
+/**
+ * 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[];
+}
+/**
+ * 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";
+/** 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;