@gajae-code/ai 0.1.1

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-Anthropic model-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,66 @@
+import type { AuthCredential } from "../auth-storage";
+import type { CredentialDisableResponse, CredentialRefreshResponse, CredentialUploadResponse, HealthzResponse, SnapshotResponse, SnapshotStreamEvent, 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;
+    });
+}
+/**
+ * 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>;
+    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,96 @@
+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;
+    /**
+     * 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;
+}
+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;
+    /**
+     * 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;
+    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,32 @@
+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;
+    /**
+     * 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;
+}
+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,105 @@
+/**
+ * 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[];
+}
+/**
+ * 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";
+/** 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;
+/** 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;