@linxiraos/pi-ai 1.0.4 → 1.0.6

package/CHANGELOG.md

@@ -2,7 +2,38 @@
 
 ## [Unreleased]
 
-## [1.0.2] - 2026-08-15
+## [1.0.6] - 2026-08-17
+
+## [17.3.5] - 2026-08-16
+
+### Added
+
+- Added retryable oneshot completion support (`retryTransientCompletion`) so non-agent LLM calls correctly retry on transient provider failures (Anthropic overload/rate-limit errors, HTTP 429/500/502/503/529), honoring provider-supplied retry-after timing before giving up.
+
+### Fixed
+
+- Fixed xAI availability detection so paid-key-only setups correctly default to `xai/grok-4.5` instead of the free SuperGrok catalog; explicit `xai-oauth/…` selectors still work as before.
+- Fixed xAI Responses requests sending unsupported parameters (reasoning summary, presence/frequency penalties) that some models rejected.
+- Fixed Umans usage reporting incorrectly marking quota as exhausted based on raw request counts instead of actual weighted usage, and improved the usage display to show both a soft-cap warning and a hard exhaustion limit with an accurate countdown to reset.
+- Fixed `omp usage invalidate` to fully clear stale usage data and force a fresh refresh, so upgraded subscriptions no longer show outdated quota information.
+- Improved session recovery to correctly treat certain Cursor HTTP/2 connection errors as transient instead of ending the session.
+- Fixed OpenAI-compatible streams (e.g. DeepSeek) that are cut off mid-generation being silently treated as a completed response instead of being retried.
+- Fixed DeepSeek resource-exhaustion interruptions not being automatically retried.
+- Fixed tool-call IDs being lost during same-model replay, which could break correlation with custom gateways.
+- Fixed Kimi Code multi-account routing to prefer accounts with more available quota, respect usage-limit cooldowns, and keep consistent usage history across token refreshes.
+- Fixed Anthropic custom signing-proxy conversations losing tool-search results and thinking content during replay.
+- Fixed rare runaway response loops across model providers so they now fail gracefully instead of repeating indefinitely.
+- Fixed xAI rejecting entire turns due to certain MCP tool schema shapes, restoring compatibility while isolating any remaining incompatible tools rather than failing the whole request.
+- Fixed Alibaba DashScope/Bailian transient per-minute rate limits being misclassified as full quota exhaustion, causing unnecessary long backoffs instead of quick retries.
+- Fixed Anthropic-compatible streams dropping thinking content, which broke replay of prior reasoning.
+- Updated the Alibaba Coding Plan China login flow to point to the current Bailian API-key management console.
+
+## [17.3.4] - 2026-08-14
+
+### Fixed
+
+- Fixed `omp usage invalidate` to discard stale OAuth and API-key usage snapshots, then force a cache-bypassing, per-provider serialized refresh with a broker request budget sized for the full unfiltered account batch, so upgraded subscriptions do not silently retain pre-change quota data.
+- Fixed quota reporting and Cookie capture guidance for China (Beijing) Alibaba Token Plan credentials ([#8509](https://github.com/can1357/oh-my-pi/issues/8509)).
 
 ## [17.3.3] - 2026-08-14
 
@@ -4708,7 +4739,7 @@
 
 ### Changed
 
-- Forked to @oh-my-pi scope with unified versioning across all packages
+- Forked to @linxiraos scope with unified versioning across all packages
 
 ### Fixed
 
@@ -4716,17 +4747,17 @@
 
 ## [1.337.0] - 2026-01-02
 
-Initial release under @oh-my-pi scope. See previous releases at [badlogic/pi-mono](https://github.com/badlogic/pi-mono).
+Initial release under @linxiraos scope. See previous releases at [badlogic/pi-mono](https://github.com/badlogic/pi-mono).
 
 ## [1.0.1] - 2026-08-14
 
-- Reset the version to 1.0.0 and republished under the `@linxiraos/*` scope, breaking from the `@oh-my-pi` version lineage.
+- Reset the version to 1.0.0 and republished under the `@linxiraos/*` scope, breaking from the `@linxiraos` version lineage.
 
 ## [1.0.0] - 2026-08-13
 
 ### Changed
 
-- Reset the version to 1.0.0 and republished under the `@linxiraos/*` scope, breaking from the `@oh-my-pi` version lineage.
+- Reset the version to 1.0.0 and republished under the `@linxiraos/*` scope, breaking from the `@linxiraos` version lineage.
 
 ## [0.50.1] - 2026-01-26
 

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.js";
+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/sqlite-credential-store.d.ts

@@ -0,0 +1,115 @@
+/**
+ * SQLite-backed credential persistence for AuthStorage.
+ *
+ * The public AuthCredentialStore interface remains in ../auth-storage so local
+ * and remote stores share the same contract.
+ */
+import { Database } from "bun:sqlite";
+import type { AuthCredential, AuthCredentialStore, CredentialRefreshLeaseFence, DisabledCredentialSummary, StoredAuthCredential, StoredCredentialBlock } from "../auth-storage.js";
+import type { OAuthCredentials } from "../registry/oauth/types.js";
+import type { ClientUsageReport, ClientUsageSummary, UsageHistoryEntry, UsageHistoryQuery } from "../usage.js";
+export declare const USAGE_REPORT_TTL_MS: number;
+type SerializedCredentialRecord = {
+    credentialType: AuthCredential["type"];
+    data: string;
+    identityKey: string | null;
+};
+/**
+ * SQLite's busy result code family — base `SQLITE_BUSY` plus the extended
+ * variants `SQLITE_BUSY_RECOVERY` (concurrent WAL recovery), `SQLITE_BUSY_SNAPSHOT`,
+ * and `SQLITE_BUSY_TIMEOUT`. All warrant the same backoff-and-retry treatment.
+ */
+export declare function isSqliteBusyError(err: unknown): boolean;
+/**
+ * SQLite's unrecoverable-corruption result codes — the `SQLITE_CORRUPT` family
+ * (base plus extended variants like `SQLITE_CORRUPT_VTAB` / `SQLITE_CORRUPT_INDEX`)
+ * and `SQLITE_NOTADB` (the file header is not a database). Unlike
+ * {@link isSqliteBusyError}, these never clear by retrying: the store must be
+ * repaired or replaced, so callers latch and stop touching it.
+ */
+export declare function isSqliteCorruptionError(err: unknown): boolean;
+export declare function serializeCredential(provider: string, credential: AuthCredential): SerializedCredentialRecord | null;
+export declare function resolveCredentialIdentityKey(provider: string, credential: AuthCredential): string | null;
+/**
+ * Default SQLite-backed implementation of {@link AuthCredentialStore}.
+ *
+ * Used by the pi-ai CLI and as the default store for `AuthStorage.create()`.
+ * Also exposes convenience methods (`saveOAuth`, `getOAuth`, `saveApiKey`,
+ * `getApiKey`, `listProviders`, `deleteProvider`) that callers can use directly
+ * without going through `AuthStorage`.
+ */
+export declare class SqliteAuthCredentialStore implements AuthCredentialStore {
+    #private;
+    constructor(db: Database);
+    static open(dbPath?: string): Promise<SqliteAuthCredentialStore>;
+    listAuthCredentials(provider?: string): StoredAuthCredential[];
+    listDisabledCredentials(provider?: string): Promise<DisabledCredentialSummary[]>;
+    replaceAuthCredentialsForProvider(provider: string, credentials: AuthCredential[]): StoredAuthCredential[];
+    upsertAuthCredentialForProvider(provider: string, credential: AuthCredential): StoredAuthCredential[];
+    updateAuthCredential(id: number, credential: AuthCredential): void;
+    tryUpdateAuthCredentialIfMatches(id: number, expectedData: string, credential: AuthCredential, lease?: CredentialRefreshLeaseFence): boolean;
+    deleteAuthCredential(id: number, disabledCause: string): void;
+    /**
+     * CAS-style disable: only soft-deletes the row when its `data` column still
+     * matches `expectedData` and the row has not already been disabled. Used by
+     * the OAuth refresh-failure path to avoid clobbering a peer that rotated the
+     * row between our pre-check and the disable.
+     */
+    tryDisableAuthCredentialIfMatches(id: number, expectedData: string, disabledCause: string, lease?: CredentialRefreshLeaseFence): boolean;
+    deleteAuthCredentialsForProvider(provider: string, disabledCause: string): void;
+    getCache(key: string, options?: {
+        includeExpired?: boolean;
+    }): string | null;
+    setCache(key: string, value: string, expiresAtSec: number): void;
+    /** Drop all cache rows whose keys start with the supplied prefix. */
+    deleteCachePrefix(prefix: string): void;
+    cleanExpiredCache(): void;
+    getCredentialBlock(credentialId: number, providerKey: string, blockScope: string): number | undefined;
+    getCredentialBlockReconcileAfter(credentialId: number, providerKey: string, blockScope: string): number | undefined;
+    upsertCredentialBlock(block: StoredCredentialBlock): void;
+    deleteCredentialBlock(credentialId: number, providerKey: string, blockScope: string): void;
+    deleteCredentialBlocks(credentialId: number): void;
+    cleanExpiredCredentialBlocks(nowMs: number): void;
+    listCredentialBlocks(credentialIds: readonly number[]): StoredCredentialBlock[];
+    tryAcquireCredentialRefreshLease(credentialId: number, owner: string, expiresAtMs: number): boolean;
+    getCredentialRefreshLeaseExpiresAt(credentialId: number): number | undefined;
+    renewCredentialRefreshLease(credentialId: number, owner: string, expiresAtMs: number): boolean;
+    releaseCredentialRefreshLease(credentialId: number, owner: string): void;
+    recordUsageSnapshots(entries: UsageHistoryEntry[]): void;
+    listUsageHistory(query?: UsageHistoryQuery): UsageHistoryEntry[];
+    recordClientUsage(report: ClientUsageReport): void;
+    getClientUsageSummary(sinceMs: number): ClientUsageSummary;
+    /**
+     * Save OAuth credentials for a provider.
+     * Preserves unrelated identities and replaces only the matching credential.
+     */
+    saveOAuth(provider: string, credentials: OAuthCredentials): void;
+    /**
+     * Get OAuth credentials for a provider.
+     */
+    getOAuth(provider: string): OAuthCredentials | null;
+    /**
+     * Save API key for a provider (replaces existing).
+     */
+    saveApiKey(provider: string, apiKey: string): void;
+    /**
+     * Get API key for a provider.
+     */
+    getApiKey(provider: string): string | null;
+    /**
+     * List all providers with credentials.
+     */
+    listProviders(): string[];
+    /**
+     * Delete all credentials for a provider.
+     */
+    deleteProvider(provider: string): void;
+    /**
+     * SQLite increments `data_version` when another connection commits. Own
+     * writes leave it unchanged and already notify AuthStorage directly.
+     */
+    pollExternalChanges(): boolean;
+    acknowledgeLocalChanges(): void;
+    close(): void;
+}
+export {};

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

@@ -0,0 +1,100 @@
+/**
+ * HTTP client for the omp auth-broker server.
+ *
+ * Used by {@link RemoteAuthCredentialStore} (snapshot pulls) and by
+ * `omp auth-broker status` (liveness checks). All endpoints except
+ * `/v1/healthz` require a bearer token.
+ */
+import type { AuthCredential, DisabledCredentialSummary } from "../auth-storage.js";
+import type { ClientUsageReportRequest, ClientUsageReportResponse, ClientUsageSummaryResponse, CredentialBlockRequest, CredentialBlockResponse, CredentialBlocksDeleteResponse, CredentialDisableResponse, CredentialRefreshResponse, CredentialUploadResponse, HealthzResponse, SnapshotResponse, SnapshotStreamEvent, UsageHistoryResponse, UsageResponse, UsageStaleResponse } from "./types.js";
+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;
+    });
+}
+/**
+ * Thrown when a broker responds 404 to `GET /v1/snapshot/stream` — old
+ * brokers that predate the SSE endpoint. Callers (`RemoteAuthCredentialStore`)
+ * detect this sentinel to fall back to long-polling permanently.
+ */
+export declare class AuthBrokerStreamUnsupportedError extends AuthBrokerError {
+    constructor(message?: string);
+}
+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>;
+    /**
+     * Subscribe to the broker's SSE snapshot stream. The first frame is always
+     * a full `snapshot`; subsequent frames are `entry` upserts / refreshes or
+     * `removed` deletes. Caller controls lifecycle via `opts.signal`.
+     *
+     * Throws {@link AuthBrokerStreamUnsupportedError} when the broker responds
+     * 404 — older brokers predate this endpoint and the caller should fall back
+     * to long-polling for the remainder of its lifetime.
+     */
+    openSnapshotStream(opts?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<SnapshotStreamEvent>;
+    /**
+     * Fetch aggregate broker usage with a timeout sized for serialized
+     * same-provider account probes.
+     */
+    fetchUsage(options?: {
+        signal?: AbortSignal;
+        maxAccountsPerProvider?: number;
+    }): Promise<UsageResponse>;
+    /** Recorded usage-limit snapshots from the broker host, oldest first. */
+    fetchUsageHistory(query?: {
+        sinceMs?: number;
+        provider?: string;
+    }, signal?: AbortSignal): Promise<UsageHistoryResponse>;
+    /** Report this client's batched observed request usage for per-install burn tracking. */
+    reportClientUsage(report: ClientUsageReportRequest, signal?: AbortSignal): Promise<ClientUsageReportResponse>;
+    /** Per-client token burn aggregates recorded by the broker host. */
+    fetchClientUsageSummary(query?: {
+        sinceMs?: number;
+    }, signal?: AbortSignal): Promise<ClientUsageSummaryResponse>;
+    notifyUsageStale(signal?: AbortSignal): Promise<UsageStaleResponse>;
+    refreshCredential(id: number, signal?: AbortSignal): Promise<CredentialRefreshResponse>;
+    disableCredential(id: number, cause: string, signal?: AbortSignal): Promise<CredentialDisableResponse>;
+    /**
+     * Disabled-credential tombstones (identity + cause, no token material).
+     * Returns an empty list against brokers predating `GET
+     * /v1/credentials/disabled` (404).
+     */
+    listDisabledCredentials(provider?: string, signal?: AbortSignal): Promise<DisabledCredentialSummary[]>;
+    uploadCredential(provider: string, credential: AuthCredential, signal?: AbortSignal): Promise<CredentialUploadResponse>;
+    upsertCredentialBlock(id: number, block: CredentialBlockRequest, signal?: AbortSignal): Promise<CredentialBlockResponse>;
+    deleteCredentialBlocks(id: number, signal?: AbortSignal): Promise<CredentialBlocksDeleteResponse>;
+}

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

@@ -0,0 +1,39 @@
+import { AuthStorage } from "../auth-storage.js";
+import { type AuthBrokerAccountPool } from "./remote-store.js";
+export interface AuthBrokerClientConfig {
+    url: string;
+    token: string;
+}
+export interface ResolveAuthBrokerConfigOptions {
+    agentDir?: string;
+    configValueResolver?: (config: string) => Promise<string | undefined>;
+}
+export interface DiscoverAuthStorageOptions {
+    agentDir?: string;
+    configValueResolver?: (config: string) => Promise<string | undefined>;
+    cachePath?: string;
+    sourceLabel?: string;
+    /** Programmatic pool for SDK hosts. Takes precedence over the environment file. */
+    accountPool?: AuthBrokerAccountPool;
+}
+/** Path to the local bearer token file. Created by `omp auth-broker token`. */
+export declare function getAuthBrokerTokenFilePath(): string;
+export declare function loadAuthBrokerAccountPool(): Promise<AuthBrokerAccountPool | undefined>;
+/**
+ * Resolve broker connection configuration using the same precedence as the TUI:
+ *
+ * 1. `OMP_AUTH_BROKER_URL` / `OMP_AUTH_BROKER_TOKEN` env vars.
+ * 2. `auth.broker.url` / `auth.broker.token` in `<agentDir>/config.yml` or `<agentDir>/config.yaml`.
+ * 3. `<config-root>/auth-broker.token` file (paired with a URL from env/config).
+ *
+ * Returns `null` when no broker URL is configured — callers should fall back to
+ * the local SQLite store. Throws when a URL is configured but no token is
+ * available, matching the TUI behavior.
+ */
+export declare function resolveAuthBrokerConfig(options?: ResolveAuthBrokerConfigOptions): Promise<AuthBrokerClientConfig | null>;
+/**
+ * Create an AuthStorage instance, using the broker when configured and falling
+ * back to the local SQLite store otherwise. This is the single source of truth
+ * for the TUI and the catalog generator.
+ */
+export declare function discoverAuthStorage(options?: DiscoverAuthStorageOptions): Promise<AuthStorage>;

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

@@ -0,0 +1,7 @@
+export * from "./client.js";
+export * from "./discover.js";
+export * from "./refresher.js";
+export * from "./remote-store.js";
+export * from "./server.js";
+export * from "./snapshot-cache.js";
+export * from "./types.js";

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

@@ -0,0 +1,25 @@
+import { type AuthStorage } from "../auth-storage.js";
+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,136 @@
+import { type AuthCredential, type AuthCredentialStore, type DisabledCredentialSummary, type OAuthCredential, type StoredAuthCredential, type StoredCredentialBlock } from "../auth-storage.js";
+import type { OAuthCredentials } from "../registry/oauth/types.js";
+import type { Provider } from "../types.js";
+import type { ObservedUsageEntry, UsageReport } from "../usage.js";
+import { type AuthBrokerClient } from "./client.js";
+import type { SnapshotResponse } from "./types.js";
+/**
+ * Per-provider OAuth identities visible to this trusted broker client.
+ * Missing providers are unrestricted; an empty set excludes that provider's
+ * OAuth credentials. API keys are never filtered.
+ */
+export type AuthBrokerAccountPool = ReadonlyMap<string, ReadonlySet<string>>;
+export interface RemoteAuthCredentialStoreOptions {
+    client: AuthBrokerClient;
+    /**
+     * Initial snapshot. When omitted, callers must call
+     * {@link RemoteAuthCredentialStore.refreshSnapshot} before the first read.
+     */
+    initialSnapshot?: SnapshotResponse;
+    /**
+     * Subscribe to the broker's SSE snapshot stream when available. Falls back
+     * to long-poll permanently when the broker returns 404. Default `true`.
+     */
+    streamSnapshots?: boolean;
+    /**
+     * Called with each broker-sourced raw full snapshot after the filtered
+     * public view is applied. The constructor's initial snapshot intentionally
+     * does not trigger this hook.
+     */
+    onSnapshot?: (snapshot: SnapshotResponse, generation: number) => void;
+    /**
+     * OAuth identities visible through this store. This is a trusted-client
+     * routing policy, not broker authorization.
+     */
+    accountPool?: AuthBrokerAccountPool;
+    /** Flush cadence for batched observed-usage reports. Default 10s. */
+    observedUsageFlushMs?: number;
+}
+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[];
+    /** Broker-backed disabled tombstones; empty against brokers predating the endpoint. */
+    listDisabledCredentials(provider?: string, signal?: AbortSignal): Promise<DisabledCredentialSummary[]>;
+    getCredentialBlock(credentialId: number, providerKey: string, blockScope: string): number | undefined;
+    getCredentialBlockReconcileAfter(credentialId: number, providerKey: string, blockScope: string): number | undefined;
+    listCredentialBlocks(credentialIds: readonly number[]): StoredCredentialBlock[];
+    upsertCredentialBlock(block: StoredCredentialBlock): void;
+    deleteCredentialBlock(_credentialId: number, _providerKey: string, _blockScope: string): void;
+    deleteCredentialBlocks(credentialId: number): void;
+    cleanExpiredCredentialBlocks(nowMs: number): void;
+    /**
+     * 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;
+    deleteAuthCredentialRemote(id: number, disabledCause: string): Promise<boolean>;
+    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;
+    /**
+     * Upsert a single credential through the broker. The broker server is the
+     * canonical writer — see `POST /v1/credential`. The redacted snapshot
+     * entries returned by the server replace the provider's rows in our local
+     * snapshot, and the global snapshot is then refreshed in the background so
+     * any concurrent peer (refresh, generation bump) stays in sync.
+     */
+    upsertAuthCredentialRemote(provider: string, credential: AuthCredential): Promise<StoredAuthCredential[]>;
+    /**
+     * Replace-all semantics: disable every active credential for the provider,
+     * then upload each of the new credentials. Used by API-key login so a new
+     * key clobbers any previously stored key for the same provider.
+     */
+    replaceAuthCredentialsRemote(provider: string, credentials: AuthCredential[]): Promise<StoredAuthCredential[]>;
+    /**
+     * Logout: disable every active credential for the provider on the broker,
+     * then drop them from the local snapshot. Refresh fetches the authoritative
+     * post-state in the background.
+     */
+    deleteAuthCredentialsRemote(provider: string, disabledCause: string): Promise<void>;
+    getCache(key: string): string | null;
+    setCache(key: string, value: string, expiresAtSec: number): void;
+    /** Drop all cache rows whose keys start with the supplied prefix. */
+    deleteCachePrefix(prefix: string): void;
+    cleanExpiredCache(): void;
+    invalidateUsageCache(signal?: AbortSignal): Promise<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 overlays any client-observed
+     * header hints for the matching credential.
+     *
+     * 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>;
+    ingestUsageReport(provider: Provider, credential: OAuthCredential, report: UsageReport): boolean;
+    /**
+     * Fold locally observed request usage into the pending report and schedule
+     * a flush. One `POST /v1/usage/observed` at most per flush interval; on
+     * failure the batch is retained and retried with the next flush. A 404
+     * (pre-endpoint broker) disables reporting for the life of this store.
+     */
+    recordObservedUsage(entries: ObservedUsageEntry[]): void;
+    close(): void;
+}

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

@@ -0,0 +1,48 @@
+/**
+ * Auth broker HTTP server.
+ *
+ * Wraps an {@link AuthStorage} (backed by a SQLite store on the broker host)
+ * and exposes a minimal REST API for snapshot pulls and explicit refresh /
+ * disable operations. Background refresh of expiring credentials lives in
+ * {@link AuthBrokerRefresher}.
+ *
+ * Transport security is delegated to the operator (Tailscale / Wireguard);
+ * the server only checks a bearer token against an allow-list per request.
+ */
+import type { AuthStorage } from "../auth-storage.js";
+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;
+    /**
+     * Override SSE keepalive cadence in milliseconds for `/v1/snapshot/stream`.
+     * Internal-only — tests use a short interval so they can assert heartbeats
+     * without long sleeps. Default {@link DEFAULT_STREAM_KEEPALIVE_MS}.
+     */
+    streamKeepaliveMs?: number;
+    /**
+     * Override cross-process SQLite change polling in milliseconds.
+     * Internal-only — tests use a short interval. Default 250ms.
+     */
+    externalChangePollMs?: number;
+}
+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/snapshot-cache.d.ts

@@ -0,0 +1,17 @@
+import type { SnapshotResponse } from "./types.js";
+export interface ReadAuthBrokerSnapshotCacheOptions {
+    path: string;
+    token: string;
+    url: string;
+    ttlMs: number;
+    /** Override clock for deterministic tests. */
+    now?: () => number;
+}
+export interface WriteAuthBrokerSnapshotCacheOptions {
+    path: string;
+    token: string;
+    url: string;
+    snapshot: SnapshotResponse;
+}
+export declare function readAuthBrokerSnapshotCache(opts: ReadAuthBrokerSnapshotCacheOptions): Promise<SnapshotResponse | null>;
+export declare function writeAuthBrokerSnapshotCache(opts: WriteAuthBrokerSnapshotCacheOptions): Promise<void>;