dexto 1.6.20 → 1.6.21

package/README.md

@@ -116,7 +116,7 @@ Upgrade/uninstall and migration troubleshooting live in docs:
 ### Run
 
 ```bash
-# Start Dexto (launches setup wizard on first run)
+# Start Dexto
 dexto
 ```
 
@@ -132,6 +132,8 @@ dexto --help                                       # Explore all options
 
 **Inside the interactive CLI**, type `/` to explore commands—switch models, manage sessions, configure tools, and more.
 
+If Dexto has not been set up yet, the first interactive launch opens the generic `dexto setup` flow before starting. Existing provider keys in your environment are detected there, so you can keep startup simple without inheriting the wrong bundled provider by accident.
+
 ### Manage Settings
 
 ```bash
@@ -595,9 +597,8 @@ Test tools before deploying:
 Usage: dexto [options] [command] [prompt...]
 
 Basic Usage:
-  dexto                    Start web UI (default)
-  dexto "query"            Run one-shot query
-  dexto --mode cli         Interactive CLI
+  dexto or dexto --mode cli  Start interactive CLI (default)
+  dexto "query"              Run one-shot query
 
 Session Management:
   dexto -c                 Continue last conversation

package/dist/cli/commands/setup.d.ts

@@ -5,6 +5,7 @@ declare const SetupCommandSchema: z.ZodEffects<z.ZodObject<{
     defaultAgent: z.ZodDefault<z.ZodString>;
     interactive: z.ZodDefault<z.ZodBoolean>;
     force: z.ZodDefault<z.ZodBoolean>;
+    defaultMode: z.ZodOptional<z.ZodEnum<["cli", "web", "server", "discord", "telegram", "mcp"]>>;
     quickStart: z.ZodDefault<z.ZodBoolean>;
 }, "strict", z.ZodTypeAny, {
     interactive: boolean;
@@ -13,12 +14,14 @@ declare const SetupCommandSchema: z.ZodEffects<z.ZodObject<{
     quickStart: boolean;
     provider?: "dexto-nova" | "openai" | "openai-compatible" | "anthropic" | "google" | "groq" | "xai" | "cohere" | "minimax" | "glm" | "openrouter" | "litellm" | "glama" | "vertex" | "bedrock" | "local" | "ollama" | undefined;
     model?: string | undefined;
+    defaultMode?: "cli" | "web" | "server" | "discord" | "telegram" | "mcp" | undefined;
 }, {
     interactive?: boolean | undefined;
     provider?: "dexto-nova" | "openai" | "openai-compatible" | "anthropic" | "google" | "groq" | "xai" | "cohere" | "minimax" | "glm" | "openrouter" | "litellm" | "glama" | "vertex" | "bedrock" | "local" | "ollama" | undefined;
     model?: string | undefined;
     force?: boolean | undefined;
     defaultAgent?: string | undefined;
+    defaultMode?: "cli" | "web" | "server" | "discord" | "telegram" | "mcp" | undefined;
     quickStart?: boolean | undefined;
 }>, {
     interactive: boolean;
@@ -27,12 +30,14 @@ declare const SetupCommandSchema: z.ZodEffects<z.ZodObject<{
     quickStart: boolean;
     provider?: "dexto-nova" | "openai" | "openai-compatible" | "anthropic" | "google" | "groq" | "xai" | "cohere" | "minimax" | "glm" | "openrouter" | "litellm" | "glama" | "vertex" | "bedrock" | "local" | "ollama" | undefined;
     model?: string | undefined;
+    defaultMode?: "cli" | "web" | "server" | "discord" | "telegram" | "mcp" | undefined;
 }, {
     interactive?: boolean | undefined;
     provider?: "dexto-nova" | "openai" | "openai-compatible" | "anthropic" | "google" | "groq" | "xai" | "cohere" | "minimax" | "glm" | "openrouter" | "litellm" | "glama" | "vertex" | "bedrock" | "local" | "ollama" | undefined;
     model?: string | undefined;
     force?: boolean | undefined;
     defaultAgent?: string | undefined;
+    defaultMode?: "cli" | "web" | "server" | "discord" | "telegram" | "mcp" | undefined;
     quickStart?: boolean | undefined;
 }>;
 export type CLISetupOptions = z.output<typeof SetupCommandSchema>;

package/dist/cli/commands/setup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/setup.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA+DxB,QAAA,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0ClB,CAAC;AAEP,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAClE,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAqKtE;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,OAAO,CAAC,oBAAoB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAmC9F"}
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/setup.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA+DxB,QAAA,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8ClB,CAAC;AAEP,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAClE,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAsKtE;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,OAAO,CAAC,oBAAoB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAsC9F"}

package/dist/cli/commands/setup.js

@@ -39,6 +39,10 @@ const SetupCommandSchema = z
         .boolean()
         .default(false)
         .describe('Overwrite existing setup when already configured'),
+    defaultMode: z
+        .enum(['cli', 'web', 'server', 'discord', 'telegram', 'mcp'])
+        .optional()
+        .describe('Preferred default mode for interactive setup flows'),
     quickStart: z
         .boolean()
         .default(false)
@@ -189,7 +193,10 @@ export async function handleSetupCommand(options) {
     }
     // Handle quick start
     if (validated.quickStart) {
-        await handleQuickStart({ onCancel: 'exit' });
+        await handleQuickStart({
+            onCancel: 'exit',
+            preferredDefaultMode: validated.defaultMode,
+        });
         return;
     }
     // Handle interactive full setup
@@ -260,7 +267,9 @@ async function handleQuickStart(options = { onCancel: 'exit' }) {
                 }
                 continue;
             }
-            const defaultMode = useCli ? 'cli' : await selectDefaultMode();
+            const defaultMode = useCli
+                ? 'cli'
+                : await selectDefaultMode(options.preferredDefaultMode);
             if (defaultMode === null) {
                 if (options.onCancel === 'exit') {
                     p.cancel('Setup cancelled');
@@ -383,7 +392,7 @@ async function handleQuickStart(options = { onCancel: 'exit' }) {
             }
             continue;
         }
-        const defaultMode = useCli ? 'cli' : await selectDefaultMode();
+        const defaultMode = useCli ? 'cli' : await selectDefaultMode(options.preferredDefaultMode);
         // Handle cancellation
         if (defaultMode === null) {
             if (options.onCancel === 'exit') {
@@ -934,11 +943,14 @@ async function getCreditsBalance() {
  * Full interactive setup flow with wizard navigation.
  * Users can go back to previous steps to change their selections.
  */
-async function handleInteractiveSetup(_options) {
+async function handleInteractiveSetup(options) {
     console.log(chalk.cyan('\nDexto Setup\n'));
     p.intro(chalk.cyan("Let's configure your AI agent"));
     // Initialize wizard state
-    let state = { step: 'setupType' };
+    let state = {
+        step: 'setupType',
+        preferredDefaultMode: options.defaultMode,
+    };
     // Wizard loop - process steps until complete
     while (state.step !== 'complete') {
         switch (state.step) {
@@ -1016,7 +1028,10 @@ async function wizardStepSetupType(state) {
     }
     if (setupType === 'quick') {
         // Quick start bypasses the wizard - handle it directly
-        const result = await handleQuickStart({ onCancel: 'back' });
+        const result = await handleQuickStart({
+            onCancel: 'back',
+            preferredDefaultMode: state.preferredDefaultMode,
+        });
         if (result === 'cancelled') {
             return { ...state, step: 'setupType' };
         }
@@ -1161,7 +1176,7 @@ async function wizardStepMode(state) {
     const isLocalProvider = provider === 'local' || provider === 'ollama';
     const hasReasoningStep = getReasoningProfile(provider, model).capable;
     showStepProgress('mode', provider, model);
-    const mode = await selectDefaultModeWithBack();
+    const mode = await selectDefaultModeWithBack(state.preferredDefaultMode);
     if (mode === '_back') {
         // Go back to the previous *interactive* step. Some steps (like apiKey) may be
         // auto-skipped when not required or already configured, so "back" from mode
@@ -1550,7 +1565,7 @@ async function promptCustomModelValues(initialModel, providerOverride) {
         ...(reasoningPreset ? { reasoningPreset } : {}),
     };
 }
-async function selectDefaultModeWithBack() {
+async function selectDefaultModeWithBack(preferredDefaultMode) {
     const result = await p.select({
         message: 'How do you want to use Dexto by default?',
         options: [
@@ -1571,6 +1586,7 @@ async function selectDefaultModeWithBack() {
             },
             { value: '_back', label: chalk.gray('← Back'), hint: 'Go to previous step' },
         ],
+        ...(preferredDefaultMode ? { initialValue: preferredDefaultMode } : {}),
     });
     if (p.isCancel(result)) {
         return '_back';
@@ -1645,13 +1661,17 @@ async function handleNonInteractiveSetup(options) {
     }
     const apiKeyVar = getProviderEnvVar(provider);
     const hadApiKeyBefore = Boolean(resolveApiKeyForProvider(provider));
-    const preferences = createInitialPreferences({
+    const preferencesOptions = {
         provider,
         model,
         apiKeyVar,
         defaultAgent: options.defaultAgent,
         setupCompleted: true,
-    });
+    };
+    if (options.defaultMode) {
+        preferencesOptions.defaultMode = options.defaultMode;
+    }
+    const preferences = createInitialPreferences(preferencesOptions);
     await saveGlobalPreferences(preferences);
     // For local provider, sync the active model in state.json
     if (provider === 'local') {
@@ -1733,7 +1753,7 @@ async function showSettingsMenu() {
             {
                 value: 'mode',
                 label: 'Change default mode',
-                hint: `Currently: ${currentPrefs?.defaults.defaultMode || 'web'}`,
+                hint: `Currently: ${currentPrefs?.defaults.defaultMode || 'cli'}`,
             },
             {
                 value: 'auth',
@@ -2090,7 +2110,7 @@ function showPreferencesFilePath() {
  * Select default mode interactively
  * Returns null if user cancels
  */
-async function selectDefaultMode() {
+async function selectDefaultMode(preferredDefaultMode) {
     const mode = await p.select({
         message: 'How do you want to use Dexto by default?',
         options: [
@@ -2110,6 +2130,7 @@ async function selectDefaultMode() {
                 hint: 'REST API for integrations',
             },
         ],
+        ...(preferredDefaultMode ? { initialValue: preferredDefaultMode } : {}),
     });
     if (p.isCancel(mode)) {
         return null;

package/dist/cli/modes/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../../src/cli/modes/cli.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAuBpD,wBAAsB,UAAU,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAgLxE"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../../src/cli/modes/cli.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAuBpD,wBAAsB,UAAU,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAuQxE"}

package/dist/cli/modes/cli.js

@@ -1,6 +1,8 @@
 import chalk from 'chalk';
+import * as p from '@clack/prompts';
 import { logger } from '@dexto/core';
 import { safeExit, ExitSignal } from '../../analytics/wrapper.js';
+import { hasUsableCredentials } from '../../config/cli-overrides.js';
 import { applyWorkspaceToAgent } from '../../utils/workspace.js';
 async function getMostRecentSessionId(agent) {
     const sessionIds = await agent.listSessions();
@@ -31,27 +33,99 @@ export async function runCliMode(context) {
         await agent.start();
         await applyWorkspaceToAgent(agent, workspaceRoot);
         const llmConfig = agent.getCurrentLLMConfig();
-        const { requiresApiKey } = await import('@dexto/core');
-        if (requiresApiKey(llmConfig.provider) && !llmConfig.apiKey?.trim()) {
+        if (!hasUsableCredentials(llmConfig.provider, llmConfig)) {
+            const { globalPreferencesExist, loadGlobalPreferences } = await import('@dexto/agent-management');
             const { interactiveApiKeySetup } = await import('../utils/api-key-setup.js');
-            console.log(chalk.yellow(`\n⚠️  API key required for provider '${llmConfig.provider}'\n`));
-            const setupResult = await interactiveApiKeySetup(llmConfig.provider, {
-                exitOnCancel: false,
-                model: llmConfig.model,
-            });
-            if (setupResult.cancelled) {
-                safeExit('main', 0, 'api-key-setup-cancelled');
+            const { getProviderDisplayName, getProviderEnvVar } = await import('../utils/provider-setup.js');
+            let hasCompletedSetup = false;
+            if (globalPreferencesExist()) {
+                try {
+                    const preferences = await loadGlobalPreferences();
+                    hasCompletedSetup = preferences.setup.completed;
+                }
+                catch {
+                    hasCompletedSetup = false;
+                }
             }
-            if (setupResult.skipped) {
-                safeExit('main', 0, 'api-key-pending');
+            console.log(chalk.yellow(`\n⚠️  API key required for provider '${getProviderDisplayName(llmConfig.provider)}'\n`));
+            if (!hasCompletedSetup) {
+                console.log(chalk.gray(`Dexto started with the bundled coding-agent defaults. ` +
+                    `Set ${getProviderEnvVar(llmConfig.provider)} or run ${chalk.cyan('dexto setup')} to choose a different provider.`));
             }
-            if (setupResult.success && setupResult.apiKey) {
-                await agent.switchLLM({
-                    provider: llmConfig.provider,
+            const runProviderKeySetup = async () => {
+                const setupResult = await interactiveApiKeySetup(llmConfig.provider, {
+                    exitOnCancel: false,
                     model: llmConfig.model,
-                    apiKey: setupResult.apiKey,
                 });
-                logger.info('API key configured successfully, continuing...');
+                if (setupResult.cancelled) {
+                    safeExit('main', 0, 'api-key-setup-cancelled');
+                }
+                if (setupResult.skipped) {
+                    safeExit('main', 0, 'api-key-pending');
+                }
+                if (setupResult.success && setupResult.apiKey) {
+                    await agent.switchLLM({
+                        provider: llmConfig.provider,
+                        model: llmConfig.model,
+                        apiKey: setupResult.apiKey,
+                    });
+                    logger.info('API key configured successfully, continuing...');
+                }
+            };
+            if (hasCompletedSetup) {
+                await runProviderKeySetup();
+            }
+            else {
+                const action = await p.select({
+                    message: 'How would you like to continue?',
+                    options: [
+                        {
+                            value: 'key',
+                            label: `Paste a ${getProviderDisplayName(llmConfig.provider)} key`,
+                            hint: 'Continue in this session',
+                        },
+                        {
+                            value: 'setup',
+                            label: 'Run dexto setup',
+                            hint: 'Choose a different provider or save defaults',
+                        },
+                        {
+                            value: 'exit',
+                            label: 'Exit',
+                            hint: 'Configure later',
+                        },
+                    ],
+                });
+                if (p.isCancel(action) || action === 'exit') {
+                    safeExit('main', 0, 'api-key-setup-cancelled');
+                }
+                if (action === 'setup') {
+                    const { handleSetupCommand } = await import('../commands/setup.js');
+                    await handleSetupCommand({ interactive: true, force: true });
+                    let preferences;
+                    try {
+                        preferences = await loadGlobalPreferences();
+                    }
+                    catch {
+                        safeExit('main', 0, 'setup-incomplete');
+                    }
+                    if (!preferences.setup.completed) {
+                        safeExit('main', 0, 'setup-incomplete');
+                    }
+                    if (preferences.setup.apiKeyPending) {
+                        safeExit('main', 0, 'api-key-pending');
+                    }
+                    await agent.switchLLM({
+                        provider: preferences.llm.provider,
+                        model: preferences.llm.model,
+                        ...(preferences.llm.apiKey && { apiKey: preferences.llm.apiKey }),
+                        ...(preferences.llm.baseURL && { baseURL: preferences.llm.baseURL }),
+                    });
+                    logger.info('Provider configured successfully, continuing...');
+                }
+                else {
+                    await runProviderKeySetup();
+                }
             }
         }
         let cliSessionId;

package/dist/cli/utils/setup-utils.d.ts

@@ -23,9 +23,8 @@ export declare function getSetupState(): Promise<SetupState>;
  * Check if user requires setup (missing, corrupted, or incomplete preferences)
  * Context-aware:
  * - Dev mode (source + DEXTO_DEV_MODE): Skip setup, uses repo configs
- * - Project context: Skip setup (might have project-local config)
- * - First-time user (source/global-cli): Require setup
- * - Has preferences (source/global-cli): Validate them
+ * - First-time user: Require setup
+ * - Has preferences: Validate them
  * @returns true if setup is required
  */
 export declare function requiresSetup(): Promise<boolean>;

package/dist/cli/utils/setup-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup-utils.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/setup-utils.ts"],"names":[],"mappings":"AAEA,OAAO,EAGH,KAAK,iBAAiB,EACzB,MAAM,yBAAyB,CAAC;AAGjC;;;GAGG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACvB,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,EAAE,OAAO,CAAC;IACvB,cAAc,EAAE,OAAO,CAAC;IACxB,WAAW,EAAE,iBAAiB,GAAG,IAAI,CAAC;CACzC;AAED;;;GAGG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,UAAU,CAAC,CAgFzD;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC,CAGtD;AAED;;GAEG;AACH,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,MAAM,CAAC,CAqB/D"}
+{"version":3,"file":"setup-utils.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/setup-utils.ts"],"names":[],"mappings":"AAEA,OAAO,EAKH,KAAK,iBAAiB,EACzB,MAAM,yBAAyB,CAAC;AAgBjC;;;GAGG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACvB,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,EAAE,OAAO,CAAC;IACvB,cAAc,EAAE,OAAO,CAAC;IACxB,WAAW,EAAE,iBAAiB,GAAG,IAAI,CAAC;CACzC;AAaD;;;GAGG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,UAAU,CAAC,CAkFzD;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC,CAGtD;AAED;;GAEG;AACH,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,MAAM,CAAC,CAqB/D"}

package/dist/cli/utils/setup-utils.js

@@ -1,6 +1,18 @@
 // packages/cli/src/cli/utils/setup-utils.ts
-import { globalPreferencesExist, loadGlobalPreferences, } from '@dexto/agent-management';
+import { findDextoProjectRoot, findProjectRegistryPathSync, globalPreferencesExist, loadGlobalPreferences, } from '@dexto/agent-management';
 import { getExecutionContext } from '@dexto/core';
+import { existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+const PROJECT_LOCAL_CODING_AGENT_RELATIVE_PATHS = [
+    path.join('agents', 'coding-agent', 'coding-agent.yml'),
+    path.join('agents', 'coding-agent', 'coding-agent.yaml'),
+    'coding-agent.yml',
+    'coding-agent.yaml',
+    path.join('agents', 'coding-agent.yml'),
+    path.join('agents', 'coding-agent.yaml'),
+    path.join('src', 'dexto', 'agents', 'coding-agent.yml'),
+    path.join('src', 'dexto', 'agents', 'coding-agent.yaml'),
+];
 /**
  * Check if this is a first-time user (no preferences file exists)
  * @returns true if user has never run setup
@@ -8,6 +20,15 @@ import { getExecutionContext } from '@dexto/core';
 export function isFirstTimeUser() {
     return !globalPreferencesExist();
 }
+function hasProjectLocalStartupConfig(projectRoot) {
+    if (findProjectRegistryPathSync(projectRoot)) {
+        return true;
+    }
+    return PROJECT_LOCAL_CODING_AGENT_RELATIVE_PATHS.some((relativePath) => {
+        const absolutePath = path.join(projectRoot, relativePath);
+        return existsSync(absolutePath) && statSync(absolutePath).isFile();
+    });
+}
 /**
  * Get detailed setup state including pending items
  * @returns Setup state with detailed flags
@@ -24,15 +45,17 @@ export async function getSetupState() {
             preferences: null,
         };
     }
-    // Project context: skip (might have project-local config)
     if (context === 'dexto-project') {
-        return {
-            needsSetup: false,
-            isFirstTime: false,
-            apiKeyPending: false,
-            baseURLPending: false,
-            preferences: null,
-        };
+        const projectRoot = findDextoProjectRoot();
+        if (projectRoot && hasProjectLocalStartupConfig(projectRoot)) {
+            return {
+                needsSetup: false,
+                isFirstTime: false,
+                apiKeyPending: false,
+                baseURLPending: false,
+                preferences: null,
+            };
+        }
     }
     // First-time user (no preferences)
     if (isFirstTimeUser()) {
@@ -91,9 +114,8 @@ export async function getSetupState() {
  * Check if user requires setup (missing, corrupted, or incomplete preferences)
  * Context-aware:
  * - Dev mode (source + DEXTO_DEV_MODE): Skip setup, uses repo configs
- * - Project context: Skip setup (might have project-local config)
- * - First-time user (source/global-cli): Require setup
- * - Has preferences (source/global-cli): Validate them
+ * - First-time user: Require setup
+ * - Has preferences: Validate them
  * @returns true if setup is required
  */
 export async function requiresSetup() {

package/dist/config/cli-overrides.d.ts

@@ -19,7 +19,7 @@
  * - Merge strategy configuration for non-LLM fields
  */
 import type { AgentConfig } from '@dexto/agent-config';
-import type { LLMConfig, LLMProvider } from '@dexto/core';
+import { type LLMConfig, type LLMProvider } from '@dexto/core';
 import type { GlobalPreferences } from '@dexto/agent-management';
 /**
  * CLI config override type for fields that can be overridden via CLI
@@ -30,6 +30,12 @@ export interface CLIConfigOverrides extends Partial<Pick<LLMConfig, 'provider' |
     /** When false (via --no-elicitation), disables elicitation */
     elicitation?: boolean;
 }
+export interface StartupLLMFallbackOptions {
+    hasCompletedSetup: boolean;
+    hasExplicitProviderOverride: boolean;
+    hasExplicitModelOverride: boolean;
+    hasExplicitApiKeyOverride: boolean;
+}
 /**
  * Applies CLI overrides to an agent configuration
  * This merges CLI arguments into the base config without validation.
@@ -52,6 +58,8 @@ export declare function applyCLIOverrides(baseConfig: AgentConfig, cliOverrides?
  * @returns Merged configuration with user preferences applied
  */
 export declare function applyUserPreferences(baseConfig: AgentConfig, preferences: Partial<GlobalPreferences>): AgentConfig;
+export declare function applyStartupLLMFallback(baseConfig: AgentConfig, options: StartupLLMFallbackOptions): AgentConfig;
+export declare function hasUsableCredentials(provider: LLMProvider, llmConfig?: Pick<AgentConfig['llm'], 'apiKey' | 'baseURL'>): boolean;
 /**
  * Result of agent compatibility check
  */

package/dist/config/cli-overrides.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-overrides.d.ts","sourceRoot":"","sources":["../../src/config/cli-overrides.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEjE;;;GAGG;AACH,MAAM,WAAW,kBACb,SAAQ,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC,CAAC;IACjE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,8DAA8D;IAC9D,WAAW,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC7B,UAAU,EAAE,WAAW,EACvB,YAAY,CAAC,EAAE,kBAAkB,GAClC,WAAW,CAuCb;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAChC,UAAU,EAAE,WAAW,EACvB,WAAW,EAAE,OAAO,CAAC,iBAAiB,CAAC,GACxC,WAAW,CAwBb;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACrC,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,aAAa,EAAE,WAAW,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,WAAW,GAAG,SAAS,CAAC;IACtC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,aAAa,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACnC,WAAW,EAAE,WAAW,EACxB,WAAW,EAAE,iBAAiB,GAAG,IAAI,EACrC,cAAc,EAAE,MAAM,GAAG,SAAS,GACnC,wBAAwB,CAwC1B"}
+{"version":3,"file":"cli-overrides.d.ts","sourceRoot":"","sources":["../../src/config/cli-overrides.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAOH,KAAK,SAAS,EACd,KAAK,WAAW,EACnB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEjE;;;GAGG;AACH,MAAM,WAAW,kBACb,SAAQ,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC,CAAC;IACjE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,8DAA8D;IAC9D,WAAW,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,yBAAyB;IACtC,iBAAiB,EAAE,OAAO,CAAC;IAC3B,2BAA2B,EAAE,OAAO,CAAC;IACrC,wBAAwB,EAAE,OAAO,CAAC;IAClC,yBAAyB,EAAE,OAAO,CAAC;CACtC;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC7B,UAAU,EAAE,WAAW,EACvB,YAAY,CAAC,EAAE,kBAAkB,GAClC,WAAW,CAuCb;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAChC,UAAU,EAAE,WAAW,EACvB,WAAW,EAAE,OAAO,CAAC,iBAAiB,CAAC,GACxC,WAAW,CAwBb;AAED,wBAAgB,uBAAuB,CACnC,UAAU,EAAE,WAAW,EACvB,OAAO,EAAE,yBAAyB,GACnC,WAAW,CAyCb;AAcD,wBAAgB,oBAAoB,CAChC,QAAQ,EAAE,WAAW,EACrB,SAAS,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC,GAC3D,OAAO,CAgBT;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACrC,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,aAAa,EAAE,WAAW,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,WAAW,GAAG,SAAS,CAAC;IACtC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,aAAa,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACnC,WAAW,EAAE,WAAW,EACxB,WAAW,EAAE,iBAAiB,GAAG,IAAI,EACrC,cAAc,EAAE,MAAM,GAAG,SAAS,GACnC,wBAAwB,CAwC1B"}

package/dist/config/cli-overrides.js

@@ -18,6 +18,7 @@
  * - Agent capability requirements (requires: { vision: true, toolUse: true })
  * - Merge strategy configuration for non-LLM fields
  */
+import { EnvExpandedString, LLM_PROVIDERS, getDefaultModelForProvider, requiresApiKey, requiresBaseURL, resolveApiKeyForProvider, } from '@dexto/core';
 /**
  * Applies CLI overrides to an agent configuration
  * This merges CLI arguments into the base config without validation.
@@ -96,6 +97,62 @@ export function applyUserPreferences(baseConfig, preferences) {
     }
     return mergedConfig;
 }
+export function applyStartupLLMFallback(baseConfig, options) {
+    const mergedConfig = JSON.parse(JSON.stringify(baseConfig));
+    if (options.hasCompletedSetup ||
+        options.hasExplicitProviderOverride ||
+        options.hasExplicitModelOverride ||
+        options.hasExplicitApiKeyOverride) {
+        return mergedConfig;
+    }
+    if (hasUsableCredentials(mergedConfig.llm.provider, mergedConfig.llm)) {
+        return mergedConfig;
+    }
+    for (const provider of LLM_PROVIDERS) {
+        if (!hasExplicitStartupFallbackConfiguration(provider)) {
+            continue;
+        }
+        const model = getDefaultModelForProvider(provider);
+        if (!model) {
+            continue;
+        }
+        mergedConfig.llm.provider = provider;
+        mergedConfig.llm.model = model;
+        delete mergedConfig.llm.baseURL;
+        const apiKey = resolveApiKeyForProvider(provider);
+        if (apiKey) {
+            mergedConfig.llm.apiKey = apiKey;
+        }
+        else {
+            delete mergedConfig.llm.apiKey;
+        }
+        return mergedConfig;
+    }
+    return mergedConfig;
+}
+function hasExplicitStartupFallbackConfiguration(provider) {
+    if (resolveApiKeyForProvider(provider)?.trim()) {
+        return true;
+    }
+    if (requiresBaseURL(provider) && process.env.OPENAI_BASE_URL?.trim()) {
+        return true;
+    }
+    return false;
+}
+export function hasUsableCredentials(provider, llmConfig) {
+    const baseURL = llmConfig?.baseURL ? EnvExpandedString().parse(llmConfig.baseURL) : undefined;
+    if (requiresBaseURL(provider) && !baseURL?.trim()) {
+        return false;
+    }
+    if (!requiresApiKey(provider)) {
+        return true;
+    }
+    const inlineApiKey = llmConfig?.apiKey ? EnvExpandedString().parse(llmConfig.apiKey) : '';
+    if (inlineApiKey.trim()) {
+        return true;
+    }
+    return Boolean(resolveApiKeyForProvider(provider)?.trim());
+}
 /**
  * Check if user's current setup is compatible with an agent's requirements.
  * Used when switching to non-default agents to warn users about potential issues.