@phuetz/code-buddy 1.1.0 → 1.2.0

package/dist/providers/provider-fallback.d.ts

@@ -0,0 +1,35 @@
+import { type ResolvedRuntimeProvider } from './provider-catalog.js';
+import type { AuthProfile } from '../auth/profile-manager.js';
+type EnvLike = Record<string, string | undefined>;
+export type RuntimeFallbackSource = 'environment' | 'auth-profile';
+export interface RuntimeAuthProfilePool {
+    getHealthyProfiles(): AuthProfile[];
+    markFailed(profileId: string, error: string, isBilling?: boolean): void;
+    markSuccess(profileId: string): void;
+}
+export interface RuntimeFallbackProvider extends ResolvedRuntimeProvider {
+    model: string;
+    rawSpec: string;
+    fallbackSource: RuntimeFallbackSource;
+    profileId?: string;
+    profileManager?: RuntimeAuthProfilePool;
+}
+export interface RuntimeFallbackResolveOptions {
+    env?: EnvLike;
+    hasChatGptOAuth?: boolean;
+    active?: {
+        provider?: string;
+        apiKey?: string;
+        baseURL?: string;
+        model?: string;
+    };
+}
+export interface RuntimeCredentialPoolResolveOptions {
+    active?: RuntimeFallbackResolveOptions['active'];
+    authProfileManager?: RuntimeAuthProfilePool;
+}
+export declare function resolveRuntimeFallbackProviders(options?: RuntimeFallbackResolveOptions): RuntimeFallbackProvider[];
+export declare function resolveRuntimeCredentialPoolProviders(options?: RuntimeCredentialPoolResolveOptions): RuntimeFallbackProvider[];
+export declare function recordRuntimeFallbackSuccess(fallback: RuntimeFallbackProvider): void;
+export declare function recordRuntimeFallbackFailure(fallback: RuntimeFallbackProvider, error: unknown): void;
+export {};

package/dist/providers/provider-fallback.js

@@ -0,0 +1,171 @@
+import { hasCodexCredentials } from './codex-oauth.js';
+import { findRuntimeProvider, getDirectRuntimeProviderCatalog, resolveProviderFromCatalog, } from './provider-catalog.js';
+import { getAuthProfileManager } from '../auth/profile-manager.js';
+export function resolveRuntimeFallbackProviders(options = {}) {
+    const env = options.env ?? process.env;
+    const specs = parseFallbackSpecs(env);
+    if (specs.length === 0)
+        return [];
+    const hasOAuth = options.hasChatGptOAuth ?? hasCodexCredentials();
+    const activeBaseURL = options.active?.baseURL?.replace(/\/+$/, '');
+    const activeModel = options.active?.model;
+    const seen = new Set();
+    const resolved = [];
+    for (const spec of specs) {
+        const provider = resolveProviderFromCatalog({
+            providerOverride: spec.provider,
+            env,
+            hasChatGptOAuth: hasOAuth,
+            requireConfigured: true,
+        });
+        if (!provider)
+            continue;
+        const model = spec.model || provider.defaultModel;
+        const baseURL = provider.baseURL.replace(/\/+$/, '');
+        if (activeBaseURL === baseURL && activeModel === model)
+            continue;
+        const key = `${provider.provider}:${baseURL}:${model}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        resolved.push({
+            ...provider,
+            model,
+            rawSpec: spec.rawSpec,
+            fallbackSource: 'environment',
+        });
+    }
+    return resolved;
+}
+export function resolveRuntimeCredentialPoolProviders(options = {}) {
+    const manager = options.authProfileManager ?? getAuthProfileManager();
+    const activeProvider = canonicalProviderId(options.active?.provider ?? inferRuntimeProviderIdFromBaseURL(options.active?.baseURL));
+    if (!activeProvider)
+        return [];
+    const activeApiKey = options.active?.apiKey;
+    const seen = new Set();
+    const resolved = [];
+    for (const profile of manager.getHealthyProfiles()) {
+        const profileProvider = canonicalProviderId(profile.provider);
+        if (profileProvider !== activeProvider)
+            continue;
+        const provider = resolveProfileProvider(profile);
+        if (!provider)
+            continue;
+        const model = profile.metadata.model || provider.defaultModel;
+        const baseURL = (profile.metadata.baseURL || provider.baseURL).replace(/\/+$/, '');
+        const apiKey = profile.credentials.apiKey || profile.credentials.accessToken || provider.apiKey;
+        if (!apiKey)
+            continue;
+        if (activeApiKey && apiKey === activeApiKey)
+            continue;
+        const key = `${provider.provider}:${baseURL}:${model}:${profile.id}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        resolved.push({
+            ...provider,
+            apiKey,
+            baseURL,
+            defaultModel: model,
+            model,
+            rawSpec: `auth-profile:${profile.id}`,
+            fallbackSource: 'auth-profile',
+            profileId: profile.id,
+            profileManager: manager,
+        });
+    }
+    return resolved;
+}
+export function recordRuntimeFallbackSuccess(fallback) {
+    if (fallback.fallbackSource !== 'auth-profile' || !fallback.profileId)
+        return;
+    fallback.profileManager?.markSuccess(fallback.profileId);
+}
+export function recordRuntimeFallbackFailure(fallback, error) {
+    if (fallback.fallbackSource !== 'auth-profile' || !fallback.profileId)
+        return;
+    fallback.profileManager?.markFailed(fallback.profileId, error instanceof Error ? error.message : String(error), isBillingLikeProviderError(error));
+}
+function parseFallbackSpecs(env) {
+    const specs = [];
+    const list = env.CODEBUDDY_FALLBACK_PROVIDERS?.trim();
+    if (list) {
+        specs.push(...list.split(','));
+    }
+    const singleProvider = env.CODEBUDDY_FALLBACK_PROVIDER?.trim();
+    if (singleProvider) {
+        const singleModel = env.CODEBUDDY_FALLBACK_MODEL?.trim();
+        specs.push(singleModel ? `${singleProvider}:${singleModel}` : singleProvider);
+    }
+    return specs
+        .map(parseFallbackSpec)
+        .filter((spec) => spec !== null);
+}
+function parseFallbackSpec(spec) {
+    const rawSpec = spec.trim();
+    if (!rawSpec)
+        return null;
+    const separator = rawSpec.indexOf(':');
+    if (separator === -1) {
+        return { provider: rawSpec, rawSpec };
+    }
+    const provider = rawSpec.slice(0, separator).trim();
+    const model = rawSpec.slice(separator + 1).trim();
+    if (!provider)
+        return null;
+    return {
+        provider,
+        model: model || undefined,
+        rawSpec,
+    };
+}
+function resolveProfileProvider(profile) {
+    const entry = findRuntimeProvider(profile.provider);
+    if (!entry || entry.runtimeSupport !== 'direct')
+        return null;
+    return {
+        provider: entry.id,
+        label: entry.label,
+        apiMode: entry.apiMode,
+        authMode: entry.authMode,
+        apiKey: profile.credentials.apiKey || profile.credentials.accessToken || entry.apiKeyPlaceholder || '',
+        baseURL: profile.metadata.baseURL || entry.defaultBaseURL,
+        defaultModel: profile.metadata.model || entry.defaultModel,
+        source: 'override',
+    };
+}
+function canonicalProviderId(provider) {
+    if (!provider)
+        return undefined;
+    return findRuntimeProvider(provider)?.id ?? provider.trim().toLowerCase();
+}
+function inferRuntimeProviderIdFromBaseURL(baseURL) {
+    if (!baseURL)
+        return undefined;
+    const normalized = baseURL.replace(/\/+$/, '').toLowerCase();
+    const directCatalog = getDirectRuntimeProviderCatalog();
+    const exact = directCatalog.find((entry) => normalizeEntryBaseURL(entry) === normalized);
+    if (exact)
+        return exact.id;
+    const host = safeHost(normalized);
+    if (!host)
+        return undefined;
+    return directCatalog.find((entry) => safeHost(normalizeEntryBaseURL(entry)) === host)?.id;
+}
+function normalizeEntryBaseURL(entry) {
+    return entry.defaultBaseURL.replace(/\/+$/, '').toLowerCase();
+}
+function safeHost(value) {
+    try {
+        return new URL(value).host;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isBillingLikeProviderError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /\b(billing|quota|insufficient[_\s-]?credits?|payment|required balance)\b/i.test(message);
+}
+//# sourceMappingURL=provider-fallback.js.map

package/dist/providers/xai-oauth.d.ts

@@ -0,0 +1,128 @@
+/**
+ * xAI / Grok OAuth — Authorization Code + PKCE flow (subscription login).
+ *
+ * Lets a SuperGrok / xAI subscriber use their plan as the brain of Code
+ * Buddy via a one-time browser login — no `XAI_API_KEY`, no per-token API
+ * metering — mirroring the ChatGPT `buddy login` path (`codex-oauth.ts`).
+ *
+ * Flow (RFC 7636 PKCE + loopback redirect, per RFC 8252):
+ *   1. Fetch OIDC discovery (`https://auth.x.ai/.well-known/openid-configuration`)
+ *      → `authorization_endpoint` + `token_endpoint` (validated to be on *.x.ai).
+ *   2. Generate a 64-byte `code_verifier` → SHA-256 `code_challenge` (S256).
+ *   3. Spin a callback server on `127.0.0.1:56121` (fallback ephemeral).
+ *   4. Open the authorize URL in the browser; the user consents.
+ *   5. Browser redirects to `http://127.0.0.1:<port>/callback?code=...&state=...`.
+ *   6. Exchange the code (form-encoded, with `code_challenge` re-sent — an xAI
+ *      defense-in-depth quirk) for `{access_token, refresh_token, ...}`.
+ *   7. Tokens land under `~/.codebuddy/xai-auth.json` (0600).
+ *
+ * Inference: the `access_token` is sent **directly** as `Authorization:
+ * Bearer` to `https://api.x.ai/v1` (`/chat/completions` or `/responses`).
+ * There is NO key-exchange / management API step — the OAuth token is the
+ * inference credential. (Verified against the Hermes Agent reference impl.)
+ *
+ * Client id `b1a00492-…` is xAI's first-party Grok CLI public OAuth client
+ * (paired with PKCE, not a secret) — the same reuse pattern as the ChatGPT
+ * Codex CLI client id in `codex-oauth.ts`.
+ */
+/** Default inference base URL for the xAI OAuth path. */
+export declare const XAI_OAUTH_BASE_URL = "https://api.x.ai/v1";
+/** Minimal auth summary returned to callers after login. */
+export interface XaiAuth {
+    access_token: string;
+    email?: string;
+    /** Seconds until the access token expires, when derivable from the JWT. */
+    expires_in_seconds?: number;
+}
+/** Remove cached tokens. `buddy logout xai` calls this. */
+export declare function clearXaiCredentials(): void;
+/** Whether a non-empty auth file with an access token exists. Used for
+ *  provider auto-detection (no token loading, just presence). */
+export declare function hasXaiCredentials(): boolean;
+/** Absolute path to the auth file. Exposed for doctor / debug. */
+export declare function getXaiAuthFilePath(): string;
+declare function base64URLEncode(buffer: Buffer): string;
+interface PkceCodes {
+    code_verifier: string;
+    code_challenge: string;
+}
+/** Generate a fresh PKCE pair (64 bytes of entropy, S256). */
+declare function generatePkce(): PkceCodes;
+interface JwtClaims {
+    exp?: number;
+    email?: string;
+    [key: string]: unknown;
+}
+/** Decode a JWT payload (no signature verification — the IdP vouched for it).
+ *  Returns null for opaque (non-JWT) tokens. */
+declare function decodeJwtClaims(token: string): JwtClaims | null;
+/** Seconds until the access token expires, or null when not derivable
+ *  (opaque token, or missing `exp`). */
+declare function accessTokenTtlSeconds(accessToken: string): number | null;
+/** True when the token is a JWT expiring within the refresh skew window.
+ *  Opaque tokens (no `exp`) are treated as NOT-expiring → refreshed only
+ *  reactively on a 401. */
+declare function isAccessTokenExpiring(accessToken: string): boolean;
+/** Validate an endpoint is HTTPS on the `*.x.ai` origin — prevents a
+ *  poisoned discovery doc from redirecting credentials elsewhere. */
+declare function isXaiHttpsEndpoint(url: string): boolean;
+declare function buildAuthorizeUrl(authorizeEndpoint: string, redirectUri: string, codeChallenge: string, state: string, nonce: string): string;
+/** Parse what the user pastes back from the browser. xAI's current consent
+ *  screen shows the bare authorization code in-page (rather than redirecting
+ *  to the loopback), so accept either a bare code, a full callback URL, or a
+ *  `?code=...&state=...` fragment. Returns null when no code is found. */
+declare function parsePastedCallback(raw: string): {
+    code: string;
+    state?: string;
+} | null;
+/**
+ * Begin a login: run discovery, generate PKCE, persist the pending material,
+ * and return the authorize URL to open. Does NOT block — the caller opens the
+ * browser and later calls `completeLogin(code)` with the in-page code.
+ */
+export declare function beginLogin(): Promise<{
+    authorizeUrl: string;
+    redirectUri: string;
+}>;
+/**
+ * Complete a login started by `beginLogin()`: exchange the authorization code
+ * (bare code or a pasted callback URL) for tokens, persist them, and clear the
+ * pending file. Throws when there's no pending login or the exchange fails.
+ */
+export declare function completeLogin(rawCode: string): Promise<XaiAuth>;
+/**
+ * Run the interactive login flow. Because xAI's consent screen currently
+ * shows the authorization code **in-page** (rather than redirecting to the
+ * loopback), this races two completion paths:
+ *   - a loopback callback server on 127.0.0.1:56121 (used if xAI redirects), and
+ *   - a stdin prompt where the user pastes the in-page code.
+ * Whichever resolves first wins. The `redirect_uri` stays byte-identical in
+ * the authorize URL and the token exchange (xAI cross-checks it). Returns a
+ * minimal `XaiAuth`. Rejects on failure / timeout (5 minutes).
+ */
+export declare function loginInteractive(openUrl?: (url: string) => void | Promise<void>): Promise<XaiAuth>;
+/**
+ * Returns a valid xAI access token for inference, refreshing it when the
+ * JWT is within the skew window (or when `forceRefresh` is set, e.g. after a
+ * 401). Returns null when no credentials are on disk, or when a refresh
+ * fails (token revoked / entitlement lost) — the caller should re-login.
+ */
+export declare function getValidXaiAccessToken(forceRefresh?: boolean): Promise<string | null>;
+export declare const __test: {
+    buildAuthorizeUrl: typeof buildAuthorizeUrl;
+    generatePkce: typeof generatePkce;
+    decodeJwtClaims: typeof decodeJwtClaims;
+    accessTokenTtlSeconds: typeof accessTokenTtlSeconds;
+    isAccessTokenExpiring: typeof isAccessTokenExpiring;
+    isXaiHttpsEndpoint: typeof isXaiHttpsEndpoint;
+    parsePastedCallback: typeof parsePastedCallback;
+    base64URLEncode: typeof base64URLEncode;
+    CLIENT_ID: string;
+    SCOPES: string;
+    ISSUER: string;
+    FALLBACK_TOKEN_ENDPOINT: string;
+    FALLBACK_AUTHORIZE_ENDPOINT: string;
+    CALLBACK_PORT: number;
+    CALLBACK_PATH: string;
+};
+export {};