@sayknow-cli/ai 0.4.2 → 0.4.3

package/dist/types/utils/fallback-transport.d.ts

@@ -0,0 +1,66 @@
+export type FallbackTriggerClass = "rate_limit" | "quota" | "auth" | "server" | "unknown" | "other";
+export interface FallbackTrigger {
+    class: FallbackTriggerClass;
+    retryAfterMs?: number;
+}
+export type TransportHeaders = Headers | Record<string, string | undefined>;
+/**
+ * Structured facts from an upstream HTTP or transport failure. Retry decisions
+ * must use these facts rather than provider- or application-owned error text.
+ *
+ * `headers` is always a plain record limited to the retained retry-signal
+ * entries: facts travel on persisted `AssistantMessage`s and through
+ * `structuredClone` snapshots (managed fallback attempt staging), so they must
+ * never carry a live `Headers` instance — cloning one throws `DataCloneError`
+ * ("The object can not be cloned.") and masks the real provider failure.
+ */
+export interface TransportFailureFacts {
+    kind: "transport";
+    status?: number;
+    /** Canonical provider error code used for fallback classification. */
+    providerCode?: string;
+    /** Anthropic's typed `error.type`, preserved separately at the transport boundary. */
+    anthropicErrorType?: string;
+    /** OpenAI's typed `error.code`, preserved separately at the transport boundary. */
+    openaiErrorCode?: string;
+    headers?: Record<string, string>;
+}
+/** Opaque per-invocation marker required by managed fallback transport calls. */
+export interface FallbackAttemptToken {
+    readonly modelKey: string;
+    readonly attemptId: string | number;
+}
+/**
+ * Marks a single outer fallback invocation. Accounting belongs to the caller;
+ * this token prevents managed transport calls from silently bypassing it.
+ */
+export declare function beginAttempt(modelKey: string, attemptId: string | number): FallbackAttemptToken;
+export declare function assertManagedAttempt(options: {
+    fallbackManaged?: boolean;
+    fallbackAttempt?: FallbackAttemptToken;
+} | undefined): void;
+/**
+ * Compatibility input for callers that have not yet wrapped their HTTP facts
+ * in the discriminated form. Only its structured fields are inspected.
+ */
+export interface FallbackTriggerInput {
+    status?: number;
+    providerCode?: string;
+    code?: string;
+    headers?: TransportHeaders;
+    response?: {
+        status?: number;
+        headers?: TransportHeaders;
+    };
+    error?: {
+        code?: string;
+        type?: string;
+    };
+}
+/** Extracts only explicit HTTP/transport metadata; it never parses error text. */
+export declare function transportFailureFacts(error: unknown, capturedResponse?: {
+    status?: number;
+    headers?: TransportHeaders;
+}): TransportFailureFacts | undefined;
+/** Classifies only typed upstream transport facts without consuming response bodies. */
+export declare function classifyFallbackTrigger(errorOrFacts: TransportFailureFacts | FallbackTriggerInput | unknown): FallbackTrigger;

package/dist/types/utils/fireworks-model-id.d.ts

@@ -0,0 +1,10 @@
+export declare function toFireworksPublicModelId(modelId: string): string;
+export declare function toFireworksWireModelId(modelId: string): string;
+/**
+ * Fire Pass exposes its Kimi K2.6 Turbo subscription through a dedicated router
+ * endpoint at `accounts/fireworks/routers/<id>` rather than the `models/` namespace.
+ * We keep a friendly public id (e.g. `kimi-k2.6-turbo`) in the catalog and translate
+ * to the wire form (`accounts/fireworks/routers/kimi-k2p6-turbo`) at request time.
+ */
+export declare function toFirepassPublicModelId(modelId: string): string;
+export declare function toFirepassWireModelId(modelId: string): string;

package/dist/types/utils/foundry.d.ts

@@ -0,0 +1 @@
+export declare function isFoundryEnabled(): boolean;

package/dist/types/utils/h2-fetch.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Patch `globalThis.fetch` to advertise HTTP/2 in TLS ALPN, with transparent
+ * HTTP/1.1 fallback when the server doesn't negotiate `h2`.
+ *
+ * Bun's HTTP/2 client is gated on `BUN_FEATURE_FLAG_EXPERIMENTAL_HTTP2_CLIENT`,
+ * read by the native runtime before any JS executes; assigning to
+ * `process.env` from inside JS is a no-op. Per-request `protocol: "http2"`
+ * activates h2 over TLS ALPN and rejects with `error.code === "HTTP2Unsupported"`
+ * if the server picks anything else, so we catch and retry without the hint.
+ *
+ * Some HTTPS endpoints (e.g. corporate API gateways behind reverse proxies)
+ * advertise h2 via ALPN but then refuse or reset the connection at the HTTP/2
+ * framing layer. Bun surfaces these as `ConnectionRefused`, `ConnectionReset`,
+ * or `ConnectionClosed` rather than `HTTP2Unsupported`, so we treat those
+ * codes as h2-fallback triggers as well.
+ *
+ * Bun negotiates h2 via ALPN over TLS only (no h2c), so plain `http://` URLs
+ * skip the attempt entirely — avoids the throw/retry round-trip for localhost.
+ *
+ * Idempotent.
+ */
+export declare function installH2Fetch(): void;

package/dist/types/utils/http-inspector.d.ts

@@ -0,0 +1,35 @@
+export type RawHttpRequestDump = {
+    provider: string;
+    api: string;
+    model: string;
+    method?: string;
+    url?: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+};
+export type CapturedHttpErrorResponse = {
+    status: number;
+    headers?: Headers;
+    bodyText?: string;
+    bodyJson?: unknown;
+};
+/** Whether `message` (from a 400 response) signals an unavailable/unknown model. */
+export declare function isModelUnavailableError(message: string, error: unknown): boolean;
+/** Actionable guidance for selecting an available model/provider. */
+export declare function formatModelUnavailableGuidance(dump: RawHttpRequestDump | undefined): string;
+export declare function appendRawHttpRequestDumpFor400(message: string, error: unknown, dump: RawHttpRequestDump | undefined): Promise<string>;
+export declare function finalizeErrorMessage(error: unknown, rawRequestDump: RawHttpRequestDump | undefined, capturedErrorResponse?: CapturedHttpErrorResponse): Promise<string>;
+export declare function withHttpStatus(error: unknown, status: number): Error;
+/**
+ * Rewrite error message for GitHub Copilot request failures.
+ * Must run AFTER finalizeErrorMessage since it replaces the message entirely.
+ *
+ * 400 `model_not_supported` = Copilot routing rollout gap for our OAuth client.
+ *        A preview model (gpt-5.3-OpenAI code backend, gpt-5.4*, ...) flaps between 200 and
+ *        400 because only some of Copilot's backends have the model. After the
+ *        in-request retry exhausts, surface guidance rather than the raw error.
+ * 401 = token invalid/expired → credential removal is safe, prompt re-login.
+ * 403 = token valid but access denied (plan, model policy, org restriction) →
+ *       do NOT reuse the auth-failed string (which triggers credential removal).
+ */
+export declare function rewriteCopilotError(errorMessage: string, error: unknown, provider: string): string;

package/dist/types/utils/idle-iterator.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Returns the idle timeout used for provider streaming transports.
+ *
+ * `PI_OPENAI_STREAM_IDLE_TIMEOUT_MS` is accepted as a backward-compatible alias.
+ * Set `PI_STREAM_IDLE_TIMEOUT_MS=0` to disable the watchdog.
+ *
+ * Providers that legitimately stream much slower than the global default can pass
+ * `fallbackMs` to widen the floor used when neither env var nor caller option is set.
+ * Caller options still take precedence; env overrides still trump the fallback.
+ */
+export declare function getStreamIdleTimeoutMs(fallbackMs?: number): number | undefined;
+/**
+ * Returns the idle timeout used for OpenAI-family streaming transports.
+ *
+ * Set `PI_OPENAI_STREAM_IDLE_TIMEOUT_MS=0` to disable the watchdog.
+ */
+export declare function getOpenAIStreamIdleTimeoutMs(): number | undefined;
+/**
+ * Returns the timeout used while waiting for the first stream event.
+ * The first token can legitimately take longer than later inter-event gaps,
+ * so the default never undershoots the steady-state idle timeout.
+ *
+ * Set `PI_STREAM_FIRST_EVENT_TIMEOUT_MS=0` to disable the watchdog.
+ *
+ * Providers whose first response can legitimately take longer (heavy reasoning,
+ * slow cold-start proxies) can pass `fallbackMs` to widen the floor used when
+ * neither env var nor caller option is set. Caller options still take precedence;
+ * env overrides still trump the fallback.
+ */
+export declare function getStreamFirstEventTimeoutMs(idleTimeoutMs?: number, fallbackMs?: number): number | undefined;
+export type Watchdog = NodeJS.Timeout | undefined;
+/**
+ * Starts a watchdog that aborts a request if no first stream event arrives in time.
+ * Call `markFirstEventReceived()` as soon as the first event is observed.
+ */
+export declare function createWatchdog(timeoutMs: number | undefined, onTimeout: () => void): Watchdog;
+export interface IdleTimeoutIteratorOptions {
+    watchdog?: Watchdog;
+    idleTimeoutMs?: number;
+    firstItemTimeoutMs?: number;
+    errorMessage: string;
+    firstItemErrorMessage?: string;
+    onIdle?: () => void;
+    onFirstItemTimeout?: () => void;
+    /**
+     * Optional semantic-progress predicate. Non-progress items are still yielded,
+     * but they do not reset the idle deadline. This prevents provider
+     * keepalive/no-op events from keeping a stalled tool call alive forever.
+     */
+    isProgressItem?: (item: unknown) => boolean;
+    /**
+     * Cancel iteration as soon as this signal aborts. Required for caller-driven
+     * cancellation (ESC) when the underlying transport does not surface signal
+     * aborts to the iterator (HTTP/2 proxies, native sockets, mocked fetch).
+     * Without this, the consumer sleeps on iterator.next() until the idle/first
+     * -event watchdog fires — observable as the issue #912 "Working… forever"
+     * symptom on the github-copilot provider.
+     */
+    abortSignal?: AbortSignal;
+}
+/**
+ * Yields items from an async iterable while enforcing a maximum idle gap between items.
+ *
+ * The first item may use a shorter timeout so stuck requests can be aborted and retried
+ * before any user-visible content has streamed.
+ */
+export declare function iterateWithIdleTimeout<T>(iterable: AsyncIterable<T>, options: IdleTimeoutIteratorOptions): AsyncGenerator<T>;

package/dist/types/utils/json-parse.d.ts

@@ -0,0 +1,18 @@
+export declare function repairJson(json: string): string;
+export declare function parseJsonWithRepair<T>(json: string): T;
+/**
+ * Attempts to parse potentially incomplete JSON during streaming.
+ * Always returns a valid object, even if the JSON is incomplete.
+ *
+ * @param partialJson The partial JSON string from streaming
+ * @returns Parsed object or empty object if parsing fails
+ */
+export declare function parseStreamingJson<T = Record<string, unknown>>(partialJson: string | undefined): T;
+/**
+ * Whether a string is a complete, well-formed JSON document (strict parse, no
+ * repair). Used to distinguish a tool-call argument blob that finished cleanly
+ * from one that was cut off mid-stream (truncation). An empty / whitespace-only
+ * string is treated as complete: a tool invoked with no arguments legitimately
+ * streams an empty buffer and must not be flagged as truncated.
+ */
+export declare function isCompleteJson(text: string | undefined): boolean;

package/dist/types/utils/oauth/alibaba-coding-plan.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Alibaba Coding Plan login flow.
+ *
+ * Alibaba Coding Plan provides OpenAI-compatible models via https://coding-intl.dashscope.aliyuncs.com/v1.
+ *
+ * This is not OAuth - it's a simple API key flow:
+ * 1. Open browser to Alibaba Cloud DashScope API key settings
+ * 2. User copies their API key
+ * 3. User pastes the API key into the CLI
+ */
+import type { OAuthController } from "./types";
+/**
+ * Login to Alibaba Coding Plan.
+ *
+ * Opens browser to API keys page, prompts user to paste their API key.
+ * Returns the API key directly (not OAuthCredentials - this isn't OAuth).
+ */
+export declare function loginAlibabaCodingPlan(options: OAuthController): Promise<string>;

package/dist/types/utils/oauth/anthropic.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Anthropic OAuth flow (Anthropic model Pro/Max)
+ */
+import { OAuthCallbackFlow } from "./callback-server";
+import type { OAuthController, OAuthCredentials } from "./types";
+export declare class AnthropicOAuthFlow extends OAuthCallbackFlow {
+    #private;
+    constructor(ctrl: OAuthController);
+    generateAuthUrl(state: string, redirectUri: string): Promise<{
+        url: string;
+        instructions?: string;
+    }>;
+    exchangeToken(code: string, state: string, redirectUri: string): Promise<OAuthCredentials>;
+}
+/**
+ * Login with Anthropic OAuth
+ */
+export declare function loginAnthropic(ctrl: OAuthController): Promise<OAuthCredentials>;
+/**
+ * Refresh Anthropic OAuth token
+ */
+export declare function refreshAnthropicToken(refreshToken: string): Promise<OAuthCredentials>;

package/dist/types/utils/oauth/api-key-login.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared factory for API-key-paste "login" flows.
+ *
+ * Several providers (Cerebras, Synthetic, Moonshot, Together, NanoGPT, ZenMux)
+ * don't actually implement OAuth — they just ask the user to paste an API key,
+ * optionally validate it, and return the trimmed key.
+ */
+import type { OAuthController } from "./types";
+type ChatCompletionsValidation = {
+    kind: "chat-completions";
+    provider: string;
+    baseUrl: string;
+    model: string;
+};
+type ModelsEndpointValidation = {
+    kind: "models-endpoint";
+    provider: string;
+    modelsUrl: string;
+};
+export type ApiKeyLoginConfig = {
+    /** Display name used in error messages, e.g. "Cerebras", "NanoGPT". */
+    providerLabel: string;
+    /** URL opened in browser for the user to grab their key. */
+    authUrl: string;
+    /** Instructions shown with the onAuth callback. */
+    instructions: string;
+    /** Prompt message shown when asking for the key paste. */
+    promptMessage: string;
+    /** Placeholder string for the prompt (e.g. "sk-...", "csk-..."). */
+    placeholder: string;
+    /** Validation strategy, or `null` to skip validation. */
+    validation: ChatCompletionsValidation | ModelsEndpointValidation | null;
+};
+export declare function createApiKeyLogin(config: ApiKeyLoginConfig): (options: OAuthController) => Promise<string>;
+export {};

package/dist/types/utils/oauth/api-key-validation.d.ts

@@ -0,0 +1,27 @@
+type OpenAICompatibleValidationOptions = {
+    provider: string;
+    apiKey: string;
+    baseUrl: string;
+    model: string;
+    signal?: AbortSignal;
+};
+type ModelListValidationOptions = {
+    provider: string;
+    apiKey: string;
+    modelsUrl: string;
+    signal?: AbortSignal;
+};
+/**
+ * Validate an API key against an OpenAI-compatible chat completions endpoint.
+ *
+ * Performs a minimal request to verify credentials and endpoint access.
+ */
+export declare function validateOpenAICompatibleApiKey(options: OpenAICompatibleValidationOptions): Promise<void>;
+/**
+ * Validate an API key against a provider models endpoint.
+ *
+ * Useful for providers where access to specific models may vary by plan and
+ * should not block key validation.
+ */
+export declare function validateApiKeyAgainstModelsEndpoint(options: ModelListValidationOptions): Promise<void>;
+export {};

package/dist/types/utils/oauth/callback-server.d.ts

@@ -0,0 +1,60 @@
+import type { OAuthController, OAuthCredentials } from "./types";
+export type CallbackResult = {
+    code: string;
+    state: string;
+};
+export interface OAuthCallbackFlowOptions {
+    preferredPort: number;
+    callbackPath?: string;
+    callbackHostname?: string;
+    /** Local listener hostname; defaults to callbackHostname when omitted. */
+    callbackBindHostname?: string;
+    /** Exact redirect URI advertised to the provider; disables port fallback. */
+    redirectUri?: string;
+}
+/**
+ * Abstract base class for OAuth flows with local callback servers.
+ */
+export declare abstract class OAuthCallbackFlow {
+    #private;
+    ctrl: OAuthController;
+    preferredPort: number;
+    callbackPath: string;
+    callbackHostname: string;
+    callbackBindHostname: string;
+    redirectUri?: string;
+    constructor(ctrl: OAuthController, preferredPortOrOptions: number | OAuthCallbackFlowOptions, callbackPath?: string);
+    /**
+     * Generate provider-specific authorization URL.
+     * @param state - CSRF state token
+     * @param redirectUri - The actual redirect URI to use (may differ from expected if port fallback occurred)
+     * @returns Authorization URL and optional instructions
+     */
+    abstract generateAuthUrl(state: string, redirectUri: string): Promise<{
+        url: string;
+        instructions?: string;
+    }>;
+    /**
+     * Exchange authorization code for OAuth tokens.
+     * @param code - Authorization code from callback
+     * @param state - CSRF state token
+     * @param redirectUri - The actual redirect URI used (must match authorization request)
+     * @returns OAuth credentials
+     */
+    abstract exchangeToken(code: string, state: string, redirectUri: string): Promise<OAuthCredentials>;
+    /**
+     * Generate CSRF state token. Override if provider needs custom state generation.
+     */
+    generateState(): string;
+    /**
+     * Execute the OAuth login flow.
+     */
+    login(): Promise<OAuthCredentials>;
+}
+/**
+ * Parse a redirect URL or code string to extract code and state.
+ */
+export declare function parseCallbackInput(input: string): {
+    code?: string;
+    state?: string;
+};

package/dist/types/utils/oauth/cerebras.d.ts

@@ -0,0 +1 @@
+export declare const loginCerebras: (options: import("./types").OAuthController) => Promise<string>;

package/dist/types/utils/oauth/cloudflare-ai-gateway.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Cloudflare AI Gateway login flow.
+ *
+ * Cloudflare AI Gateway proxies upstream model providers.
+ *
+ * This is not OAuth - it's a simple API key flow:
+ * 1. Open Cloudflare AI Gateway docs/dashboard
+ * 2. User copies their Cloudflare AI Gateway token/API key
+ * 3. User pastes the API key into the CLI
+ */
+import type { OAuthController } from "./types";
+/**
+ * Login to Cloudflare AI Gateway.
+ *
+ * Opens browser to Cloudflare AI Gateway authentication docs and prompts for a gateway token/API key.
+ * Returns the API key directly (not OAuthCredentials - this isn't OAuth).
+ */
+export declare function loginCloudflareAiGateway(options: OAuthController): Promise<string>;

package/dist/types/utils/oauth/cursor.d.ts

@@ -0,0 +1,15 @@
+import type { OAuthCredentials } from "./types";
+export interface CursorAuthParams {
+    verifier: string;
+    challenge: string;
+    uuid: string;
+    loginUrl: string;
+}
+export declare function generateCursorAuthParams(): Promise<CursorAuthParams>;
+export declare function pollCursorAuth(uuid: string, verifier: string): Promise<{
+    accessToken: string;
+    refreshToken: string;
+}>;
+export declare function loginCursor(onAuthUrl: (url: string) => void, onPollStart?: () => void): Promise<OAuthCredentials>;
+export declare function refreshCursorToken(apiKeyOrRefreshToken: string): Promise<OAuthCredentials>;
+export declare function isCursorTokenExpiringSoon(token: string, thresholdSeconds?: number): boolean;

package/dist/types/utils/oauth/deepinfra.d.ts

@@ -0,0 +1 @@
+export declare const loginDeepInfra: (options: import("./types").OAuthController) => Promise<string>;

package/dist/types/utils/oauth/deepseek.d.ts

@@ -0,0 +1,10 @@
+import type { OAuthController } from "./types";
+/**
+ * Normalize a pasted DeepSeek API key.
+ *
+ * Users frequently copy keys out of `curl` snippets that include the
+ * `Authorization: Bearer …` prefix. Strip it so validation does not fail
+ * with a confusing 401, and reject obviously empty input early.
+ */
+export declare function normalizeDeepSeekApiKey(raw: string): string;
+export declare const loginDeepSeek: (options: OAuthController) => Promise<string>;

package/dist/types/utils/oauth/firepass.d.ts

@@ -0,0 +1 @@
+export declare const loginFirepass: (options: import("./types").OAuthController) => Promise<string>;

package/dist/types/utils/oauth/fireworks.d.ts

@@ -0,0 +1 @@
+export declare const loginFireworks: (options: import("./types").OAuthController) => Promise<string>;

package/dist/types/utils/oauth/fugu.d.ts

@@ -0,0 +1 @@
+export declare const loginFugu: (options: import("./types").OAuthController) => Promise<string>;

package/dist/types/utils/oauth/github-copilot.d.ts

@@ -0,0 +1,38 @@
+import type { OAuthCredentials } from "./types";
+export declare const COPILOT_USER_AGENT: "opencode/1.3.15";
+export declare const OPENCODE_HEADERS: {
+    readonly "User-Agent": "opencode/1.3.15";
+};
+export type ParsedGitHubCopilotApiKey = {
+    accessToken: string;
+    enterpriseUrl?: string;
+};
+export declare function normalizeGitHubCopilotEnterpriseDomain(input: string | undefined): string | undefined;
+export declare function parseGitHubCopilotApiKey(apiKeyRaw: string): ParsedGitHubCopilotApiKey;
+export declare function normalizeDomain(input: string): string | null;
+export declare function getGitHubCopilotBaseUrl(enterpriseDomain?: string): string;
+/**
+ * Refresh GitHub Copilot token.
+ * With the opencode OAuth flow, the GitHub token is used directly — no JWT exchange needed.
+ */
+export declare function refreshGitHubCopilotToken(refreshToken: string, enterpriseDomain?: string): OAuthCredentials;
+/**
+ * Login with GitHub Copilot OAuth (device code flow)
+ *
+ * @param options.onAuth - Callback with URL and optional instructions (user code)
+ * @param options.onPrompt - Callback to prompt user for input
+ * @param options.onProgress - Optional progress callback
+ * @param options.signal - Optional AbortSignal for cancellation
+ */
+export declare function loginGitHubCopilot(options: {
+    onAuth: (url: string, instructions?: string) => void;
+    onPrompt: (prompt: {
+        message: string;
+        placeholder?: string;
+        allowEmpty?: boolean;
+    }) => Promise<string>;
+    onProgress?: (message: string) => void;
+    signal?: AbortSignal;
+    pollIntervalFloorMs?: number;
+    pollIntervalScaleMs?: number;
+}): Promise<OAuthCredentials>;

package/dist/types/utils/oauth/gitlab-duo.d.ts

@@ -0,0 +1,3 @@
+import type { OAuthCredentials, OAuthLoginCallbacks } from "./types";
+export declare function loginGitLabDuo(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials>;
+export declare function refreshGitLabDuoToken(credentials: OAuthCredentials): Promise<OAuthCredentials>;

package/dist/types/utils/oauth/glm-zcode.d.ts

@@ -0,0 +1,71 @@
+/**
+ * GLM ZCode OAuth flow (UNOFFICIAL, opt-in).
+ *
+ * Replicates how the ZCode desktop app turns a Z.AI login into usable GLM model
+ * access. This is NOT an official Z.AI OAuth client: it reuses ZCode's authorize
+ * page, broker, and a custom-protocol redirect. It may break at any time and may
+ * violate ZCode/Z.AI Terms of Service. Endpoints/client id are overridable via
+ * `ZCODE_OAUTH_*` environment variables.
+ *
+ * Verified end-to-end against the ZCode host bundle (`resolveZaiApiKey` /
+ * `resolveBizApiKey`) and live traffic:
+ *   1. Authorize: GET {authorize}?redirect_uri=zcode://oauth/callback&response_type=code&client_id=...&state=...
+ *      (custom-protocol redirect → a CLI cannot catch it, so the user pastes the code/redirect URL)
+ *   2. Broker:    POST {broker} { provider:"zai", code, redirect_uri, state }
+ *                  → { data: { token: <ZCode JWT>, zai: { access_token: <upstream Z.AI token> } } }
+ *   3. Business:  POST {z/login} { token: <upstream Z.AI token> } → { data: { access_token: <business token> } }
+ *   4. Provision: with the business token, GET getCustomerInfo → default org/project,
+ *      GET/POST .../api_keys (find/create a key named "zcode-api-key"),
+ *      GET .../api_keys/copy/{id} → secretKey ⇒ a real Z.AI API key "{id}.{secret}".
+ *
+ * Credential mapping:
+ *   - `access`  = the provisioned **Z.AI API key** ("{id}.{secret}"). Model requests go to
+ *                 `https://api.z.ai/api/anthropic/v1/messages` with `Authorization: Bearer <key>`
+ *                 (exactly like a dashboard key) — NO zcode.z.ai gateway, NO captcha.
+ *   - `refresh` = the upstream Z.AI OAuth access token (used to re-provision the key).
+ * The API key is long-lived, so `expires` is set far in the future.
+ *
+ * This provider must NEVER force `isOAuth=true`: the key is a plain Z.AI API key, and
+ * api.z.ai is not api.anthropic.com, so the Anthropic path already emits a plain bearer.
+ */
+import { OAuthCallbackFlow } from "./callback-server";
+import type { OAuthController, OAuthCredentials } from "./types";
+export declare const GLM_ZCODE_REFRESH_SKEW_MS: number;
+/** Default endpoints / client id. Override via the matching `ZCODE_OAUTH_*` env vars. */
+export declare const GLM_ZCODE_OAUTH_AUTHORIZE_URL = "https://chat.z.ai/api/oauth/authorize";
+export declare const GLM_ZCODE_OAUTH_CLIENT_ID = "client_P8X5CMWmlaRO9gyO-KSqtg";
+export declare const GLM_ZCODE_OAUTH_REDIRECT_URI = "zcode://oauth/callback";
+export declare const GLM_ZCODE_OAUTH_BROKER_TOKEN_URL = "https://zcode.z.ai/api/v1/oauth/token";
+export declare const GLM_ZCODE_ZAI_LOGIN_URL = "https://api.z.ai/api/auth/z/login";
+export declare const GLM_ZCODE_USERINFO_URL = "https://chat.z.ai/api/oauth/userinfo";
+/** Z.AI business API base (customer/org/project/api-key management). */
+export declare const GLM_ZCODE_ZAI_API_BASE = "https://api.z.ai";
+/** Model API base — the provisioned key is used here, exactly like a dashboard key. */
+export declare const GLM_ZCODE_ANTHROPIC_BASE_URL = "https://api.z.ai/api/anthropic";
+type FetchImpl = typeof globalThis.fetch;
+/** Configured whenever a client id is available; the real ZCode client id ships as default. */
+export declare function isGlmZcodeOAuthConfigured(): boolean;
+export interface GlmZcodeOAuthFlowOptions {
+    fetch?: FetchImpl;
+}
+export declare class GlmZcodeOAuthFlow extends OAuthCallbackFlow {
+    #private;
+    constructor(ctrl: OAuthController, options?: GlmZcodeOAuthFlowOptions);
+    generateAuthUrl(state: string, redirectUri: string): Promise<{
+        url: string;
+        instructions?: string;
+    }>;
+    exchangeToken(code: string, state: string, redirectUri: string): Promise<OAuthCredentials>;
+}
+export declare function loginGlmZcode(ctrl: OAuthController, options?: GlmZcodeOAuthFlowOptions): Promise<OAuthCredentials>;
+export interface GlmZcodeRefreshOptions {
+    signal?: AbortSignal;
+    fetch?: FetchImpl;
+}
+/**
+ * Re-provision the Z.AI API key from the stored upstream token. The key itself is
+ * long-lived, so this is rarely needed; if the upstream token has expired it fails
+ * loudly and the user must re-login.
+ */
+export declare function refreshGlmZcodeToken(credentials: OAuthCredentials, options?: AbortSignal | GlmZcodeRefreshOptions): Promise<OAuthCredentials>;
+export {};

package/dist/types/utils/oauth/google-antigravity.d.ts

@@ -0,0 +1,11 @@
+import type { OAuthController, OAuthCredentials } from "./types";
+export declare const ANTIGRAVITY_LOAD_CODE_ASSIST_METADATA: Readonly<{
+    ideType: "ANTIGRAVITY";
+    platform: "PLATFORM_UNSPECIFIED";
+    pluginType: "GEMINI";
+}>;
+export declare function loginAntigravity(ctrl: OAuthController): Promise<OAuthCredentials>;
+/**
+ * Refresh Antigravity token
+ */
+export declare function refreshAntigravityToken(refreshToken: string, projectId: string): Promise<OAuthCredentials>;

package/dist/types/utils/oauth/google-gemini-cli.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Gemini CLI OAuth flow (Google Cloud Code Assist)
+ * Standard Gemini models only (gemini-2.0-flash, gemini-2.5-*)
+ */
+import type { OAuthController, OAuthCredentials } from "./types";
+export declare function loginGeminiCli(ctrl: OAuthController): Promise<OAuthCredentials>;
+/**
+ * Refresh Google Cloud Code Assist token
+ */
+export declare function refreshGoogleCloudToken(refreshToken: string, projectId: string): Promise<OAuthCredentials>;

package/dist/types/utils/oauth/google-oauth-shared.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared OAuth flow for Google-style providers (Gemini CLI, Antigravity).
+ *
+ * Both providers use the same authorization-code flow shape; only the client
+ * credentials, scopes, endpoint constants, and project-discovery logic differ.
+ */
+import { OAuthCallbackFlow } from "./callback-server";
+import type { OAuthController, OAuthCredentials } from "./types";
+export interface GoogleOAuthFlowConfig {
+    clientId: string;
+    clientSecret: string;
+    authUrl: string;
+    tokenUrl: string;
+    scopes: string[];
+    callbackPort: number;
+    callbackPath: string;
+    discoverProject: (accessToken: string, onProgress?: (message: string) => void) => Promise<string>;
+}
+export declare class GoogleOAuthFlow extends OAuthCallbackFlow {
+    private readonly config;
+    constructor(ctrl: OAuthController, config: GoogleOAuthFlowConfig);
+    generateAuthUrl(state: string, redirectUri: string): Promise<{
+        url: string;
+        instructions?: string;
+    }>;
+    exchangeToken(code: string, _state: string, redirectUri: string): Promise<OAuthCredentials>;
+}
+export declare function runGoogleOAuthLogin(ctrl: OAuthController, config: GoogleOAuthFlowConfig): Promise<OAuthCredentials>;

package/dist/types/utils/oauth/huggingface.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Hugging Face Inference login flow.
+ *
+ * Hugging Face Inference Providers expose an OpenAI-compatible endpoint via
+ * https://router.huggingface.co/v1.
+ *
+ * This is an API key flow:
+ * 1. Open browser to Hugging Face token settings
+ * 2. User creates/copies a token with Inference Providers permission
+ * 3. User pastes the token into the CLI
+ */
+import type { OAuthController } from "./types";
+/**
+ * Login to Hugging Face Inference Providers.
+ *
+ * Opens browser to token settings, prompts user to paste their API key.
+ * Returns the API key directly (not OAuthCredentials - this isn't OAuth).
+ */
+export declare function loginHuggingface(options: OAuthController): Promise<string>;