@phuetz/code-buddy 1.1.0 → 1.3.0

package/dist/channels/slash-parity.js

@@ -0,0 +1,185 @@
+/**
+ * Per-Platform Slash-Command Parity Manifest
+ *
+ * Defines the expected slash commands per messaging platform and
+ * compares them against the actual registered commands per adapter.
+ * Returns a machine-readable readiness report for each platform.
+ */
+import { getChannelManager } from './core.js';
+// ============================================================================
+// Expected Commands Manifest
+// ============================================================================
+/**
+ * The canonical set of slash commands expected on each platform.
+ *
+ * These represent the Code Buddy bot commands that users should be
+ * able to invoke from each messaging platform. The manifest is
+ * intentionally conservative — platforms may support additional
+ * commands beyond what is listed here.
+ */
+export const EXPECTED_SLASH_COMMANDS = {
+    discord: [
+        { name: 'ask', description: 'Ask Code Buddy a question' },
+        { name: 'status', description: 'Show bot and channel status' },
+        { name: 'clear', description: 'Clear conversation history' },
+        { name: 'help', description: 'Show available commands' },
+        { name: 'model', description: 'Switch or show current model' },
+        { name: 'think', description: 'Set reasoning depth', required: false },
+        { name: 'compact', description: 'Compact conversation context', required: false },
+        { name: 'repo', description: 'Show repository info', required: false },
+    ],
+    telegram: [
+        { name: 'ask', description: 'Ask Code Buddy a question' },
+        { name: 'status', description: 'Show bot and channel status' },
+        { name: 'clear', description: 'Clear conversation history' },
+        { name: 'help', description: 'Show available commands' },
+        { name: 'model', description: 'Switch or show current model' },
+        { name: 'yolo', description: 'Toggle YOLO mode', required: false },
+        { name: 'repo', description: 'Show repository info', required: false },
+        { name: 'branch', description: 'Show branch info', required: false },
+    ],
+    slack: [
+        { name: 'ask', description: 'Ask Code Buddy a question' },
+        { name: 'status', description: 'Show bot and channel status' },
+        { name: 'clear', description: 'Clear conversation history' },
+        { name: 'help', description: 'Show available commands' },
+        { name: 'model', description: 'Switch or show current model' },
+        { name: 'compact', description: 'Compact conversation context', required: false },
+        { name: 'think', description: 'Set reasoning depth', required: false },
+    ],
+    matrix: [
+        { name: 'ask', description: 'Ask Code Buddy a question' },
+        { name: 'status', description: 'Show bot and channel status' },
+        { name: 'clear', description: 'Clear conversation history' },
+        { name: 'help', description: 'Show available commands' },
+        { name: 'model', description: 'Switch or show current model', required: false },
+    ],
+};
+/**
+ * Check if a channel adapter implements SlashCommandProvider.
+ */
+function isSlashCommandProvider(channel) {
+    return typeof channel.getRegisteredCommands === 'function';
+}
+/**
+ * Extract the actual registered commands from a channel adapter.
+ *
+ * Uses the SlashCommandProvider interface if available, otherwise
+ * returns an empty array (no commands can be detected).
+ */
+export function extractActualCommands(channel) {
+    if (isSlashCommandProvider(channel)) {
+        return channel.getRegisteredCommands();
+    }
+    return [];
+}
+// ============================================================================
+// Parity Checking
+// ============================================================================
+/**
+ * Build a parity report for a single platform.
+ *
+ * @param platform - The platform channel type
+ * @param expectedCommands - The expected slash commands
+ * @param actualCommands - The actual registered commands
+ * @param adapterRegistered - Whether the adapter is in the ChannelManager
+ */
+export function buildPlatformParityReport(platform, expectedCommands, actualCommands, adapterRegistered) {
+    if (!adapterRegistered) {
+        return {
+            platform,
+            adapterRegistered: false,
+            expectedCount: expectedCommands.length,
+            presentCount: 0,
+            missingRequiredCount: expectedCommands.filter((c) => c.required !== false).length,
+            missingOptionalCount: expectedCommands.filter((c) => c.required === false).length,
+            commands: expectedCommands.map((cmd) => ({
+                name: cmd.name,
+                present: false,
+                required: cmd.required !== false,
+            })),
+            status: 'no-adapter',
+        };
+    }
+    const actualSet = new Set(actualCommands.map((c) => c.toLowerCase()));
+    const commands = expectedCommands.map((cmd) => ({
+        name: cmd.name,
+        present: actualSet.has(cmd.name.toLowerCase()),
+        required: cmd.required !== false,
+    }));
+    const presentCount = commands.filter((c) => c.present).length;
+    const missingRequiredCount = commands.filter((c) => !c.present && c.required).length;
+    const missingOptionalCount = commands.filter((c) => !c.present && !c.required).length;
+    let status;
+    if (presentCount === expectedCommands.length) {
+        status = 'full';
+    }
+    else if (presentCount > 0) {
+        status = 'partial';
+    }
+    else {
+        status = 'none';
+    }
+    return {
+        platform,
+        adapterRegistered: true,
+        expectedCount: expectedCommands.length,
+        presentCount,
+        missingRequiredCount,
+        missingOptionalCount,
+        commands,
+        status,
+    };
+}
+/**
+ * Build the full slash-command parity manifest across all tracked platforms.
+ *
+ * @param manager - Optional ChannelManager instance (defaults to singleton)
+ */
+export function buildSlashParityManifest(manager) {
+    const mgr = manager ?? getChannelManager();
+    const reports = [];
+    for (const [platformKey, expectedCmds] of Object.entries(EXPECTED_SLASH_COMMANDS)) {
+        const platform = platformKey;
+        const channel = mgr.getChannel(platform);
+        const adapterRegistered = !!channel;
+        const actualCommands = channel ? extractActualCommands(channel) : [];
+        reports.push(buildPlatformParityReport(platform, expectedCmds, actualCommands, adapterRegistered));
+    }
+    const fullParityCount = reports.filter((r) => r.status === 'full').length;
+    const partialParityCount = reports.filter((r) => r.status === 'partial' || r.status === 'none').length;
+    const noAdapterCount = reports.filter((r) => r.status === 'no-adapter').length;
+    return {
+        generatedAt: new Date().toISOString(),
+        ok: reports.every((r) => r.missingRequiredCount === 0),
+        totalPlatforms: reports.length,
+        fullParityCount,
+        partialParityCount,
+        noAdapterCount,
+        platforms: reports,
+    };
+}
+/**
+ * Render the parity manifest as a human-readable text report.
+ */
+export function renderSlashParityManifest(manifest) {
+    const lines = [
+        'Slash-command parity report:',
+        `  Status: ${manifest.ok ? 'ok' : 'needs attention'}`,
+        `  Platforms: ${manifest.totalPlatforms} (${manifest.fullParityCount} full, ${manifest.partialParityCount} partial, ${manifest.noAdapterCount} no-adapter)`,
+        '',
+    ];
+    for (const report of manifest.platforms) {
+        const missing = report.commands.filter((c) => !c.present);
+        const present = report.commands.filter((c) => c.present);
+        lines.push(`  ${report.platform}: ${report.status} (${report.presentCount}/${report.expectedCount})`);
+        if (present.length > 0) {
+            lines.push(`    Present: ${present.map((c) => c.name).join(', ')}`);
+        }
+        if (missing.length > 0) {
+            lines.push(`    Missing: ${missing.map((c) => `${c.name}${c.required ? ' (required)' : ''}`).join(', ')}`);
+        }
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=slash-parity.js.map

package/dist/channels/synology-chat/index.js

@@ -65,6 +65,9 @@ export class SynologyChatChannel extends BaseChannel {
     constructor(config) {
         super('synology-chat', config);
     }
+    // REST/webhook adapter — outbound via incoming webhooks, inbound via
+    // outgoing-webhook callbacks; no persistent connection is held open, so
+    // reconnection (ReconnectionManager) is N/A.
     async connect() {
         const cfg = this.config;
         this.adapter = new SynologyChatAdapter({

package/dist/channels/teams/index.d.ts

@@ -129,6 +129,9 @@ export declare class TeamsChannel extends BaseChannel {
     /**
      * Connect to Teams by validating the app credentials.
      * The actual message receiving happens via webhooks.
+     *
+     * REST/webhook adapter — no persistent connection is held open here, so
+     * reconnection (ReconnectionManager) is N/A.
      */
     connect(): Promise<void>;
     /**

package/dist/channels/teams/index.js

@@ -111,6 +111,9 @@ export class TeamsChannel extends BaseChannel {
     /**
      * Connect to Teams by validating the app credentials.
      * The actual message receiving happens via webhooks.
+     *
+     * REST/webhook adapter — no persistent connection is held open here, so
+     * reconnection (ReconnectionManager) is N/A.
      */
     async connect() {
         try {

package/dist/channels/telegram/client.d.ts

@@ -58,6 +58,15 @@ export declare class TelegramChannel extends BaseChannel {
      * Set bot commands
      */
     private setCommands;
+    /**
+     * Return the bot command names registered with this adapter.
+     *
+     * Implements {@link SlashCommandProvider} so the slash-parity checker can
+     * report real parity instead of falling back to an empty list. Names come
+     * from the configured `commands` (the same set pushed to Telegram via
+     * {@link setCommands}), normalized without a leading slash.
+     */
+    getRegisteredCommands(): string[];
     /**
      * Start polling for updates
      */

package/dist/channels/telegram/client.js

@@ -294,6 +294,18 @@ export class TelegramChannel extends BaseChannel {
         }));
         await this.apiRequest('setMyCommands', { commands });
     }
+    /**
+     * Return the bot command names registered with this adapter.
+     *
+     * Implements {@link SlashCommandProvider} so the slash-parity checker can
+     * report real parity instead of falling back to an empty list. Names come
+     * from the configured `commands` (the same set pushed to Telegram via
+     * {@link setCommands}), normalized without a leading slash.
+     */
+    getRegisteredCommands() {
+        const commands = this.telegramConfig.commands ?? [];
+        return commands.map((cmd) => cmd.command.replace(/^\//, ''));
+    }
     /**
      * Start polling for updates
      */

package/dist/channels/twilio-voice/index.js

@@ -94,6 +94,9 @@ export class TwilioVoiceChannel extends BaseChannel {
             webhookUrl: config.webhookUrl,
         });
     }
+    // REST/webhook adapter — calls are placed via the Twilio REST API and
+    // driven by TwiML webhook callbacks; no persistent connection is held open,
+    // so reconnection (ReconnectionManager) is N/A.
     async connect() {
         await this.adapter.start();
         this.status.connected = true;

package/dist/channels/webchat/index.d.ts

@@ -40,7 +40,13 @@ export declare class WebChatChannel extends BaseChannel {
     constructor(config: WebChatConfig);
     private get webChatConfig();
     /**
-     * Start the HTTP and WebSocket servers
+     * Start the HTTP and WebSocket servers.
+     *
+     * Server-side adapter — this hosts a WebSocket *server* that browsers
+     * connect *into*; it does not dial out to a remote endpoint that could
+     * drop, so there is nothing to reconnect to and ReconnectionManager is N/A.
+     * (Per-client socket drops are handled by the connections map, not by
+     * re-establishing an outbound link.)
      */
     connect(): Promise<void>;
     /**

package/dist/channels/webchat/index.js

@@ -46,7 +46,13 @@ export class WebChatChannel extends BaseChannel {
     // Lifecycle
     // ==========================================================================
     /**
-     * Start the HTTP and WebSocket servers
+     * Start the HTTP and WebSocket servers.
+     *
+     * Server-side adapter — this hosts a WebSocket *server* that browsers
+     * connect *into*; it does not dial out to a remote endpoint that could
+     * drop, so there is nothing to reconnect to and ReconnectionManager is N/A.
+     * (Per-client socket drops are handled by the connections map, not by
+     * re-establishing an outbound link.)
      */
     async connect() {
         let WebSocketModule;

package/dist/channels/wecom/index.js

@@ -97,6 +97,9 @@ export class WeComChannel extends BaseChannel {
             mentionedMobileList: config.mentionedMobileList,
         });
     }
+    // REST/webhook adapter — outbound messages are one-shot HTTPS POSTs to a
+    // WeCom group-robot webhook; no persistent connection is held open, so
+    // reconnection (ReconnectionManager) is N/A.
     async connect() {
         await this.adapter.start();
         this.status.connected = true;

package/dist/channels/weixin/index.js

@@ -93,6 +93,9 @@ export class WeixinChannel extends BaseChannel {
             kfAccount: config.kfAccount,
         });
     }
+    // REST/webhook adapter — outbound via the WeChat (Weixin) HTTP API, inbound
+    // via webhook callbacks; no persistent connection is held open, so
+    // reconnection (ReconnectionManager) is N/A.
     async connect() {
         await this.adapter.start();
         this.status.connected = true;

package/dist/channels/zalo/index.js

@@ -70,6 +70,9 @@ export class ZaloChannel extends BaseChannel {
             mode: config.mode,
         });
     }
+    // REST/webhook adapter — outbound via the Zalo API, inbound via webhook
+    // callbacks; no persistent connection is held open, so reconnection
+    // (ReconnectionManager) is N/A.
     async connect() {
         await this.adapter.start();
         this.status.connected = true;

package/dist/cli/config-loader.js

@@ -91,7 +91,7 @@ export async function saveCommandLineSettings(apiKey, baseURL) {
 export function validateConfig(config) {
     const errors = [];
     if (!config.apiKey) {
-        errors.push('API key required. Set GROK_API_KEY environment variable, use --api-key flag, or save to ~/.codebuddy/user-settings.json');
+        errors.push('API key required. Sign in free with `buddy login` (ChatGPT plan), set GROK_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY / GOOGLE_API_KEY, or use --api-key. Run `buddy doctor` to check your setup.');
     }
     return {
         valid: errors.length === 0,

package/dist/codebuddy/client.d.ts

@@ -1,5 +1,6 @@
 import type { ChatCompletionMessageParam, ChatCompletionChunk, ChatCompletionCreateParamsNonStreaming, ChatCompletionCreateParamsStreaming } from "openai/resources/chat";
 import type { CircuitBreakerConfig } from "../providers/circuit-breaker.js";
+import { type RuntimeFallbackProvider } from "../providers/provider-fallback.js";
 export { hasToolCalls } from './message-guards.js';
 export type { CodeBuddyMessageWithToolCalls } from './message-guards.js';
 /** Sentinel apiKey for the ChatGPT OAuth path — auto-detect chain in
@@ -78,6 +79,8 @@ export type GeminiThinkingLevel = 'minimal' | 'low' | 'medium' | 'high';
 export interface ChatOptions {
     model?: string;
     temperature?: number;
+    /** Optional per-call output-token cap. Providers fall back to their model default when omitted. */
+    maxTokens?: number;
     searchOptions?: SearchOptions;
     /** Optional request timeout override (ms) for Gemini native API calls */
     timeoutMs?: number;
@@ -95,6 +98,8 @@ export interface ChatOptions {
     responseFormat?: 'text' | 'json';
     /** tool_choice override for this request */
     tool_choice?: 'auto' | 'none' | 'required';
+    /** Disable Hermes-style cross-provider fallback for this one request. */
+    disableProviderFallback?: boolean;
     /**
      * Enable Gemini's native server-side Google Search grounding for this
      * request. Only affects the GeminiNativeProvider — ignored by the
@@ -129,6 +134,16 @@ export interface ChatOptions {
         maxDelayMs?: number;
     };
 }
+export interface CodeBuddyClientOptions {
+    /** Enable env-configured fallback providers. Default: true. */
+    enableFallbacks?: boolean;
+    /** Enable same-provider auth profile rotation before cross-provider fallback. Default: true. */
+    enableCredentialPool?: boolean;
+    /** Explicit same-provider credential pool candidates, mainly for tests and controlled embedding. */
+    credentialPoolProviders?: RuntimeFallbackProvider[];
+    /** Explicit fallback providers, mainly for tests and controlled embedding. */
+    fallbackProviders?: RuntimeFallbackProvider[];
+}
 export interface CodeBuddyResponse {
     choices: Array<{
         message: {
@@ -168,6 +183,10 @@ export declare class CodeBuddyClient {
     private geminiCliProvider;
     /** True when routed through the Gemini CLI subprocess. */
     private isGeminiCliProvider;
+    /** Same-provider auth profile candidates, tried before cross-provider fallback. */
+    private credentialPoolProviders;
+    /** Hermes-style cross-provider fallback candidates, tried per failed chat turn. */
+    private fallbackProviders;
     /**
      * Configure the circuit breaker for this client.
      * Once configured, calls with `circuitBreaker: true` in ChatOptions
@@ -184,8 +203,14 @@ export declare class CodeBuddyClient {
      */
     setDefaultGoogleSearch(enabled: boolean): void;
     setCircuitBreakerConfig(config: Partial<CircuitBreakerConfig>): void;
+    /**
+     * Override the cross-provider fallback list after construction. Used by the
+     * active-LLM registry to auto-populate failover from the user's live logins.
+     * `chatWithProviderFallback` reads this per-call, so it takes effect immediately.
+     */
+    setRuntimeFallbackProviders(providers: RuntimeFallbackProvider[]): void;
     private static isGeminiModelName;
-    constructor(apiKey: string, model?: string, baseURL?: string);
+    constructor(apiKey: string, model?: string, baseURL?: string, options?: CodeBuddyClientOptions);
     /**
      * Probe the model to check if it supports function calling
      * Makes a quick test request with a simple tool
@@ -226,6 +251,10 @@ export declare class CodeBuddyClient {
      */
     isGemini(): boolean;
     chat(messages: CodeBuddyMessage[], tools?: CodeBuddyTool[], options?: string | ChatOptions, searchOptions?: SearchOptions): Promise<CodeBuddyResponse>;
+    private dispatchChat;
+    private chatWithProviderFallback;
     chatStream(messages: CodeBuddyMessage[], tools?: CodeBuddyTool[], options?: string | ChatOptions, searchOptions?: SearchOptions): AsyncGenerator<ChatCompletionChunk, void, unknown>;
+    private dispatchChatStream;
+    private chatStreamWithProviderFallback;
     search(query: string, searchParameters?: SearchParameters): Promise<CodeBuddyResponse>;
 }

package/dist/codebuddy/client.js

@@ -7,6 +7,7 @@ import { OpenAICompatProvider } from "./providers/provider-openai-compat.js";
 import { ChatGptResponsesProvider } from "./providers/provider-chatgpt-responses.js";
 import { GeminiCliProvider } from "./providers/provider-gemini-cli.js";
 import { withStreamRetry } from "./stream-retry.js";
+import { recordRuntimeFallbackFailure, recordRuntimeFallbackSuccess, resolveRuntimeCredentialPoolProviders, resolveRuntimeFallbackProviders, } from "../providers/provider-fallback.js";
 export { hasToolCalls } from './message-guards.js';
 /** Sentinel apiKey for the ChatGPT OAuth path — auto-detect chain in
  *  `src/index.ts` passes this when `~/.codebuddy/codex-auth.json` exists. */
@@ -41,6 +42,10 @@ export class CodeBuddyClient {
     geminiCliProvider = null;
     /** True when routed through the Gemini CLI subprocess. */
     isGeminiCliProvider = false;
+    /** Same-provider auth profile candidates, tried before cross-provider fallback. */
+    credentialPoolProviders = [];
+    /** Hermes-style cross-provider fallback candidates, tried per failed chat turn. */
+    fallbackProviders = [];
     /**
      * Configure the circuit breaker for this client.
      * Once configured, calls with `circuitBreaker: true` in ChatOptions
@@ -68,10 +73,18 @@ export class CodeBuddyClient {
         this.circuitBreakerConfig = config;
         // Provider reads via getter at call-time, so no propagation needed.
     }
+    /**
+     * Override the cross-provider fallback list after construction. Used by the
+     * active-LLM registry to auto-populate failover from the user's live logins.
+     * `chatWithProviderFallback` reads this per-call, so it takes effect immediately.
+     */
+    setRuntimeFallbackProviders(providers) {
+        this.fallbackProviders = providers;
+    }
     static isGeminiModelName(model) {
         return model.toLowerCase().includes('gemini');
     }
-    constructor(apiKey, model, baseURL) {
+    constructor(apiKey, model, baseURL, options = {}) {
         // Validate API key
         if (!apiKey || typeof apiKey !== 'string') {
             throw new Error('API key is required and must be a non-empty string');
@@ -198,6 +211,24 @@ export class CodeBuddyClient {
                 logger.warn(`Model '${model}' is not officially supported. Using default token limits.`);
             }
         }
+        if (options.enableFallbacks !== false) {
+            if (options.enableCredentialPool !== false) {
+                this.credentialPoolProviders = options.credentialPoolProviders ?? resolveRuntimeCredentialPoolProviders({
+                    active: {
+                        apiKey: this.apiKey,
+                        baseURL: this.baseURL,
+                        model: this.currentModel,
+                    },
+                });
+            }
+            this.fallbackProviders = options.fallbackProviders ?? resolveRuntimeFallbackProviders({
+                active: {
+                    apiKey: this.apiKey,
+                    baseURL: this.baseURL,
+                    model: this.currentModel,
+                },
+            });
+        }
     }
     /**
      * Probe the model to check if it supports function calling
@@ -323,6 +354,14 @@ export class CodeBuddyClient {
             ? { model: options, searchOptions }
             : options || {};
         // Dispatch to the active strategy.
+        try {
+            return await this.dispatchChat(messages, tools, opts, searchOptions);
+        }
+        catch (error) {
+            return await this.chatWithProviderFallback(error, messages, tools, opts, searchOptions);
+        }
+    }
+    async dispatchChat(messages, tools, opts, searchOptions) {
         if (this.geminiProvider) {
             return this.geminiProvider.chat(messages, tools, opts);
         }
@@ -334,36 +373,144 @@ export class CodeBuddyClient {
         }
         return this.openaiCompatProvider.chat(messages, tools, opts, searchOptions);
     }
+    async chatWithProviderFallback(primaryError, messages, tools, opts, searchOptions) {
+        const fallbackCandidates = [
+            ...this.credentialPoolProviders,
+            ...this.fallbackProviders,
+        ];
+        if (opts.disableProviderFallback || fallbackCandidates.length === 0) {
+            throw primaryError;
+        }
+        const fallbackOptsBase = {
+            ...opts,
+            disableProviderFallback: true,
+        };
+        for (const fallback of fallbackCandidates) {
+            try {
+                logger.warn('Primary provider failed; trying fallback provider', {
+                    source: 'CodeBuddyClient',
+                    primaryProvider: this.getProviderName(),
+                    fallbackProvider: fallback.provider,
+                    fallbackModel: fallback.model,
+                    fallbackSource: fallback.fallbackSource,
+                    profileId: fallback.profileId,
+                    error: primaryError instanceof Error ? primaryError.message : String(primaryError),
+                });
+                const fallbackClient = new CodeBuddyClient(fallback.apiKey, fallback.model, fallback.baseURL, { enableFallbacks: false });
+                if (this.circuitBreakerConfig) {
+                    fallbackClient.setCircuitBreakerConfig(this.circuitBreakerConfig);
+                }
+                const response = await fallbackClient.chat(messages, tools, {
+                    ...fallbackOptsBase,
+                    model: fallback.model,
+                }, searchOptions);
+                recordRuntimeFallbackSuccess(fallback);
+                return response;
+            }
+            catch (fallbackError) {
+                recordRuntimeFallbackFailure(fallback, fallbackError);
+                logger.warn('Fallback provider failed', {
+                    source: 'CodeBuddyClient',
+                    fallbackProvider: fallback.provider,
+                    fallbackModel: fallback.model,
+                    fallbackSource: fallback.fallbackSource,
+                    profileId: fallback.profileId,
+                    error: fallbackError instanceof Error ? fallbackError.message : String(fallbackError),
+                });
+            }
+        }
+        throw primaryError;
+    }
     async *chatStream(messages, tools, options, searchOptions) {
         // Support both old signature (model as string) and new signature (options object)
         const opts = typeof options === "string"
             ? { model: options, searchOptions }
             : options || {};
-        // Dispatch to the active strategy. Wrapped in a factory so we can
-        // re-invoke it inside `withStreamRetry` when opt-in retry is enabled.
-        const factory = () => {
-            if (this.geminiProvider) {
-                return this.geminiProvider.chatStream(messages, tools, opts);
-            }
-            if (this.chatgptProvider) {
-                return this.chatgptProvider.chatStream(messages, tools, opts);
-            }
-            if (this.geminiCliProvider) {
-                return this.geminiCliProvider.chatStream(messages, tools, opts);
-            }
-            return this.openaiCompatProvider.chatStream(messages, tools, opts, searchOptions);
-        };
         // Resolve retry opt-in. Per-call `streamRetry` wins over env var when
         // explicitly set (including `false`, which forces no retry).
         const envOptIn = process.env.CODEBUDDY_STREAM_RETRY === '1';
         const callOptIn = opts.streamRetry;
         const retryEnabled = callOptIn !== undefined ? !!callOptIn : envOptIn;
-        if (!retryEnabled) {
-            yield* factory();
-            return;
-        }
         const retryOpts = typeof callOptIn === 'object' && callOptIn !== null ? callOptIn : {};
-        yield* withStreamRetry(factory, retryOpts);
+        const primaryFactory = () => this.dispatchChatStream(messages, tools, opts, searchOptions);
+        const primaryStream = retryEnabled
+            ? withStreamRetry(primaryFactory, retryOpts)
+            : primaryFactory();
+        let yieldedAnyChunk = false;
+        try {
+            for await (const chunk of primaryStream) {
+                yieldedAnyChunk = true;
+                yield chunk;
+            }
+        }
+        catch (error) {
+            if (yieldedAnyChunk) {
+                throw error;
+            }
+            yield* this.chatStreamWithProviderFallback(error, messages, tools, opts, searchOptions);
+        }
+    }
+    dispatchChatStream(messages, tools, opts, searchOptions) {
+        if (this.geminiProvider) {
+            return this.geminiProvider.chatStream(messages, tools, opts);
+        }
+        if (this.chatgptProvider) {
+            return this.chatgptProvider.chatStream(messages, tools, opts);
+        }
+        if (this.geminiCliProvider) {
+            return this.geminiCliProvider.chatStream(messages, tools, opts);
+        }
+        return this.openaiCompatProvider.chatStream(messages, tools, opts, searchOptions);
+    }
+    async *chatStreamWithProviderFallback(primaryError, messages, tools, opts, searchOptions) {
+        const fallbackCandidates = [
+            ...this.credentialPoolProviders,
+            ...this.fallbackProviders,
+        ];
+        if (opts.disableProviderFallback || fallbackCandidates.length === 0) {
+            throw primaryError;
+        }
+        const fallbackOptsBase = {
+            ...opts,
+            disableProviderFallback: true,
+        };
+        for (const fallback of fallbackCandidates) {
+            try {
+                logger.warn('Primary provider stream failed before first chunk; trying fallback provider', {
+                    source: 'CodeBuddyClient',
+                    primaryProvider: this.getProviderName(),
+                    fallbackProvider: fallback.provider,
+                    fallbackModel: fallback.model,
+                    fallbackSource: fallback.fallbackSource,
+                    profileId: fallback.profileId,
+                    error: primaryError instanceof Error ? primaryError.message : String(primaryError),
+                });
+                const fallbackClient = new CodeBuddyClient(fallback.apiKey, fallback.model, fallback.baseURL, { enableFallbacks: false });
+                if (this.circuitBreakerConfig) {
+                    fallbackClient.setCircuitBreakerConfig(this.circuitBreakerConfig);
+                }
+                for await (const chunk of fallbackClient.chatStream(messages, tools, {
+                    ...fallbackOptsBase,
+                    model: fallback.model,
+                }, searchOptions)) {
+                    yield chunk;
+                }
+                recordRuntimeFallbackSuccess(fallback);
+                return;
+            }
+            catch (fallbackError) {
+                recordRuntimeFallbackFailure(fallback, fallbackError);
+                logger.warn('Fallback provider stream failed', {
+                    source: 'CodeBuddyClient',
+                    fallbackProvider: fallback.provider,
+                    fallbackModel: fallback.model,
+                    fallbackSource: fallback.fallbackSource,
+                    profileId: fallback.profileId,
+                    error: fallbackError instanceof Error ? fallbackError.message : String(fallbackError),
+                });
+            }
+        }
+        throw primaryError;
     }
     async search(query, searchParameters) {
         const searchMessage = {