dexto 1.3.0 → 1.5.0

package/dist/cli/utils/api-key-verification.js

@@ -0,0 +1,211 @@
+// packages/cli/src/cli/utils/api-key-verification.ts
+import { logger } from '@dexto/core';
+/**
+ * Verify an API key by making a minimal test request to the provider.
+ * Uses provider-specific endpoints for efficient validation.
+ *
+ * @param provider - The LLM provider
+ * @param apiKey - The API key to verify
+ * @param model - Optional specific model to test with
+ * @returns Verification result
+ */
+export async function verifyApiKey(provider, apiKey, _model) {
+    try {
+        switch (provider) {
+            case 'openai':
+                return await verifyOpenAI(apiKey);
+            case 'anthropic':
+                return await verifyAnthropic(apiKey);
+            case 'google':
+                return await verifyGoogle(apiKey);
+            case 'groq':
+                return await verifyGroq(apiKey);
+            case 'xai':
+                return await verifyXAI(apiKey);
+            case 'cohere':
+                return await verifyCohere(apiKey);
+            case 'openrouter':
+                return await verifyOpenRouter(apiKey);
+            case 'glama':
+                return await verifyGlama(apiKey);
+            case 'openai-compatible':
+            case 'litellm':
+                // For custom endpoints, we can't verify without a baseURL
+                // Just do basic format check
+                return { success: true, modelUsed: 'custom' };
+            case 'vertex':
+            case 'bedrock':
+                // These use cloud credentials, not API keys
+                // Skip verification
+                return { success: true, modelUsed: 'cloud-auth' };
+            default:
+                // Unknown provider - skip verification
+                return { success: true, modelUsed: 'unknown' };
+        }
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        logger.debug(`API key verification failed for ${provider}: ${errorMessage}`);
+        return { success: false, error: errorMessage };
+    }
+}
+/**
+ * Verify OpenAI API key using the models endpoint
+ */
+async function verifyOpenAI(apiKey) {
+    const response = await fetch('https://api.openai.com/v1/models', {
+        method: 'GET',
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+        },
+    });
+    if (response.ok) {
+        return { success: true, modelUsed: 'models-list' };
+    }
+    const error = await parseErrorResponse(response);
+    return { success: false, error };
+}
+/**
+ * Verify Anthropic API key using a minimal messages request
+ */
+async function verifyAnthropic(apiKey) {
+    // Anthropic doesn't have a models endpoint, so we make a minimal request
+    // that will fail fast if the key is invalid
+    const response = await fetch('https://api.anthropic.com/v1/messages', {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'x-api-key': apiKey,
+            'anthropic-version': '2023-06-01',
+        },
+        body: JSON.stringify({
+            model: 'claude-3-5-haiku-20241022',
+            max_tokens: 1,
+            messages: [{ role: 'user', content: 'hi' }],
+        }),
+    });
+    // 200 = success, 400 = bad request (but key is valid), 401/403 = invalid key
+    if (response.ok || response.status === 400) {
+        return { success: true, modelUsed: 'claude-3-5-haiku-20241022' };
+    }
+    const error = await parseErrorResponse(response);
+    return { success: false, error };
+}
+/**
+ * Verify Google AI API key using the models endpoint
+ */
+async function verifyGoogle(apiKey) {
+    const response = await fetch(`https://generativelanguage.googleapis.com/v1/models?key=${apiKey}`, {
+        method: 'GET',
+    });
+    if (response.ok) {
+        return { success: true, modelUsed: 'models-list' };
+    }
+    const error = await parseErrorResponse(response);
+    return { success: false, error };
+}
+/**
+ * Verify Groq API key using the models endpoint
+ */
+async function verifyGroq(apiKey) {
+    const response = await fetch('https://api.groq.com/openai/v1/models', {
+        method: 'GET',
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+        },
+    });
+    if (response.ok) {
+        return { success: true, modelUsed: 'models-list' };
+    }
+    const error = await parseErrorResponse(response);
+    return { success: false, error };
+}
+/**
+ * Verify xAI API key using the models endpoint
+ */
+async function verifyXAI(apiKey) {
+    const response = await fetch('https://api.x.ai/v1/models', {
+        method: 'GET',
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+        },
+    });
+    if (response.ok) {
+        return { success: true, modelUsed: 'models-list' };
+    }
+    const error = await parseErrorResponse(response);
+    return { success: false, error };
+}
+/**
+ * Verify Cohere API key using a check-api-key endpoint or models list
+ */
+async function verifyCohere(apiKey) {
+    const response = await fetch('https://api.cohere.com/v2/models', {
+        method: 'GET',
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+        },
+    });
+    if (response.ok) {
+        return { success: true, modelUsed: 'models-list' };
+    }
+    const error = await parseErrorResponse(response);
+    return { success: false, error };
+}
+/**
+ * Verify OpenRouter API key using the auth endpoint
+ */
+async function verifyOpenRouter(apiKey) {
+    const response = await fetch('https://openrouter.ai/api/v1/auth/key', {
+        method: 'GET',
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+        },
+    });
+    if (response.ok) {
+        return { success: true, modelUsed: 'auth-check' };
+    }
+    const error = await parseErrorResponse(response);
+    return { success: false, error };
+}
+/**
+ * Verify Glama API key using the models endpoint
+ */
+async function verifyGlama(apiKey) {
+    const response = await fetch('https://glama.ai/api/gateway/openai/v1/models', {
+        method: 'GET',
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+        },
+    });
+    if (response.ok) {
+        return { success: true, modelUsed: 'models-list' };
+    }
+    const error = await parseErrorResponse(response);
+    return { success: false, error };
+}
+/**
+ * Parse error response from provider API
+ */
+async function parseErrorResponse(response) {
+    const status = response.status;
+    // Common status codes
+    if (status === 401) {
+        return 'Invalid API key - authentication failed';
+    }
+    if (status === 403) {
+        return 'API key does not have permission to access this resource';
+    }
+    if (status === 429) {
+        return 'Rate limit exceeded - but API key appears valid';
+    }
+    // Try to parse JSON error
+    try {
+        const json = await response.json();
+        const message = json.error?.message || json.message || json.detail || JSON.stringify(json);
+        return `API error (${status}): ${message}`;
+    }
+    catch {
+        return `API error (${status}): ${response.statusText}`;
+    }
+}

package/dist/cli/utils/config-validation.d.ts

@@ -1,8 +1,28 @@
-import { type AgentConfig, type ValidatedAgentConfig } from '@dexto/core';
+import { type AgentConfig, type ValidatedAgentConfig, type LLMValidationOptions } from '@dexto/core';
+export interface ValidationResult {
+    success: boolean;
+    config?: ValidatedAgentConfig;
+    errors?: string[];
+    skipped?: boolean;
+}
 /**
  * Validates agent config with optional interactive fixes for user experience.
  * Uses schema parsing to detect API key issues and provides targeted setup.
  * Returns validated config with all defaults applied.
+ *
+ * IMPORTANT: This function NEVER exits the process. It always returns a result
+ * that allows the caller to decide what to do next.
+ *
+ * @param config - The agent configuration to validate
+ * @param interactive - Whether to allow interactive prompts to fix issues
+ * @param validationOptions - Validation strictness options
+ * @param validationOptions.strict - When true (default), enforces API key requirements.
+ *                                   When false, allows missing credentials for interactive config.
  */
-export declare function validateAgentConfig(config: AgentConfig, interactive?: boolean): Promise<ValidatedAgentConfig>;
+export declare function validateAgentConfig(config: AgentConfig, interactive?: boolean, validationOptions?: LLMValidationOptions): Promise<ValidationResult>;
+/**
+ * Legacy function for backwards compatibility
+ * @deprecated Use validateAgentConfig with result handling instead
+ */
+export declare function validateAgentConfigOrExit(config: AgentConfig, interactive?: boolean): Promise<ValidatedAgentConfig>;
 //# sourceMappingURL=config-validation.d.ts.map

package/dist/cli/utils/config-validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config-validation.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/config-validation.ts"],"names":[],"mappings":"AAEA,OAAO,EAAqB,KAAK,WAAW,EAAE,KAAK,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAM7F;;;;GAIG;AACH,wBAAsB,mBAAmB,CACrC,MAAM,EAAE,WAAW,EACnB,WAAW,GAAE,OAAe,GAC7B,OAAO,CAAC,oBAAoB,CAAC,CAiC/B"}
+{"version":3,"file":"config-validation.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/config-validation.ts"],"names":[],"mappings":"AAGA,OAAO,EAGH,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EAC5B,MAAM,aAAa,CAAC;AAWrB,MAAM,WAAW,gBAAgB;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CACrC,MAAM,EAAE,WAAW,EACnB,WAAW,GAAE,OAAe,EAC5B,iBAAiB,CAAC,EAAE,oBAAoB,GACzC,OAAO,CAAC,gBAAgB,CAAC,CAyC3B;AAwZD;;;GAGG;AACH,wBAAsB,yBAAyB,CAC3C,MAAM,EAAE,WAAW,EACnB,WAAW,GAAE,OAAe,GAC7B,OAAO,CAAC,oBAAoB,CAAC,CAgC/B"}

package/dist/cli/utils/config-validation.js

@@ -1,37 +1,312 @@
 import chalk from 'chalk';
-import { AgentConfigSchema } from '@dexto/core';
+import * as p from '@clack/prompts';
+import { AgentConfigSchema, createAgentConfigSchema, } from '@dexto/core';
 import { interactiveApiKeySetup } from './api-key-setup.js';
 import { LLMErrorCode } from '@dexto/core';
 import { logger } from '@dexto/core';
+import { getGlobalPreferencesPath, loadGlobalPreferences, saveGlobalPreferences, } from '@dexto/agent-management';
 /**
  * Validates agent config with optional interactive fixes for user experience.
  * Uses schema parsing to detect API key issues and provides targeted setup.
  * Returns validated config with all defaults applied.
+ *
+ * IMPORTANT: This function NEVER exits the process. It always returns a result
+ * that allows the caller to decide what to do next.
+ *
+ * @param config - The agent configuration to validate
+ * @param interactive - Whether to allow interactive prompts to fix issues
+ * @param validationOptions - Validation strictness options
+ * @param validationOptions.strict - When true (default), enforces API key requirements.
+ *                                   When false, allows missing credentials for interactive config.
  */
-export async function validateAgentConfig(config, interactive = false) {
+export async function validateAgentConfig(config, interactive = false, validationOptions) {
+    // Use appropriate schema based on validation options
+    // Default to strict validation unless explicitly relaxed
+    const schema = validationOptions?.strict === false
+        ? createAgentConfigSchema({ strict: false })
+        : AgentConfigSchema;
     // Parse with schema to detect issues
-    const parseResult = AgentConfigSchema.safeParse(config);
-    if (!parseResult.success) {
-        // Check for API key validation errors using raw Zod error (preserves params)
-        logger.error(`Agent config validation error: ${JSON.stringify(parseResult.error)}`);
-        const apiKeyError = findApiKeyError(parseResult.error, config);
-        if (apiKeyError && interactive) {
-            logger.debug(`API key error found for ${apiKeyError.provider} provider, retriggering interactive setup`);
-            console.log(chalk.yellow(`\n🔑 API key required for ${apiKeyError.provider} provider\n`));
-            // Run interactive setup for the specific provider that failed
-            // Function will exit process if user cancels, otherwise continues
-            // Environment variables are automatically reloaded after API key setup
-            await interactiveApiKeySetup(apiKeyError.provider);
-            // Same config, but EnvExpandedString will now find the API key
-            return validateAgentConfig(config, interactive);
+    const parseResult = schema.safeParse(config);
+    if (parseResult.success) {
+        return { success: true, config: parseResult.data };
+    }
+    // Validation failed - handle based on mode
+    logger.debug(`Agent config validation error: ${JSON.stringify(parseResult.error)}`);
+    const errors = formatZodErrors(parseResult.error);
+    if (!interactive) {
+        // Non-interactive mode: show errors and next steps, but don't exit
+        showValidationErrors(errors);
+        showNextSteps();
+        return { success: false, errors };
+    }
+    // Interactive mode: try to help the user fix the issue
+    // Check for API key errors first
+    const apiKeyError = findApiKeyError(parseResult.error, config);
+    if (apiKeyError) {
+        return await handleApiKeyError(apiKeyError.provider, config, errors, validationOptions);
+    }
+    // Check for baseURL errors next
+    const baseURLError = findBaseURLError(parseResult.error, config);
+    if (baseURLError) {
+        return await handleBaseURLError(baseURLError.provider, config, errors, validationOptions);
+    }
+    // Other validation errors - show options
+    return await handleOtherErrors(errors);
+}
+/**
+ * Handle API key validation errors interactively
+ */
+async function handleApiKeyError(provider, config, errors, validationOptions) {
+    console.log(chalk.rgb(255, 165, 0)(`\n🔑 API key issue detected for ${provider} provider\n`));
+    const action = await p.select({
+        message: 'How would you like to proceed?',
+        options: [
+            {
+                value: 'setup',
+                label: 'Set up API key now',
+                hint: 'Configure the API key interactively',
+            },
+            {
+                value: 'skip',
+                label: 'Continue anyway',
+                hint: 'Try to start without fixing (may fail)',
+            },
+            {
+                value: 'edit',
+                label: 'Edit configuration manually',
+                hint: 'Show file path and instructions',
+            },
+        ],
+    });
+    if (p.isCancel(action)) {
+        showNextSteps();
+        return { success: false, errors, skipped: true };
+    }
+    if (action === 'setup') {
+        const result = await interactiveApiKeySetup(provider, { exitOnCancel: false });
+        if (result.success && !result.skipped) {
+            // Retry validation after API key setup
+            return validateAgentConfig(config, true, validationOptions);
         }
-        // API key error in non-interactive mode or other validation errors
-        console.error(chalk.red('❌ Configuration Error:'));
-        formatZodError(parseResult.error);
-        process.exit(1);
+        // Setup was skipped or cancelled - let them continue anyway
+        return { success: false, errors, skipped: true };
+    }
+    if (action === 'edit') {
+        showManualEditInstructions();
+        return { success: false, errors, skipped: true };
+    }
+    // 'skip' - continue anyway
+    p.log.warn('Continuing with validation errors - some features may not work correctly');
+    return { success: false, errors, skipped: true };
+}
+/**
+ * Handle baseURL validation errors interactively
+ */
+async function handleBaseURLError(provider, config, errors, validationOptions) {
+    console.log(chalk.rgb(255, 165, 0)(`\n🌐 Base URL required for ${provider} provider\n`));
+    const providerExamples = {
+        'openai-compatible': 'http://localhost:11434/v1 (Ollama)',
+        litellm: 'http://localhost:4000 (LiteLLM proxy)',
+    };
+    const example = providerExamples[provider] || 'http://localhost:8080/v1';
+    p.note([
+        `The ${provider} provider requires a base URL to connect to your`,
+        `local or custom LLM endpoint.`,
+        ``,
+        `${chalk.gray('Example:')} ${example}`,
+    ].join('\n'), 'Base URL Required');
+    const action = await p.select({
+        message: 'How would you like to proceed?',
+        options: [
+            {
+                value: 'setup',
+                label: 'Enter base URL now',
+                hint: 'Configure the base URL interactively',
+            },
+            {
+                value: 'skip',
+                label: 'Continue anyway',
+                hint: 'Try to start without fixing (may fail)',
+            },
+            {
+                value: 'edit',
+                label: 'Edit configuration manually',
+                hint: 'Show file path and instructions',
+            },
+        ],
+    });
+    if (p.isCancel(action)) {
+        showNextSteps();
+        return { success: false, errors, skipped: true };
+    }
+    if (action === 'setup') {
+        const result = await interactiveBaseURLSetup(provider, config.llm?.baseURL);
+        if (result.success && !result.skipped && result.baseURL && config.llm) {
+            // Update config with the new baseURL for retry validation
+            const updatedConfig = {
+                ...config,
+                llm: { ...config.llm, baseURL: result.baseURL },
+            };
+            // Retry validation after baseURL setup
+            return validateAgentConfig(updatedConfig, true, validationOptions);
+        }
+        // Setup was skipped or cancelled
+        return { success: false, errors, skipped: true };
+    }
+    if (action === 'edit') {
+        showManualEditInstructions();
+        return { success: false, errors, skipped: true };
+    }
+    // 'skip' - continue anyway
+    p.log.warn('Continuing with validation errors - some features may not work correctly');
+    return { success: false, errors, skipped: true };
+}
+/**
+ * Interactive baseURL setup
+ */
+async function interactiveBaseURLSetup(provider, existingBaseURL) {
+    const providerDefaults = {
+        'openai-compatible': 'http://localhost:11434/v1',
+        litellm: 'http://localhost:4000',
+    };
+    // Use existing baseURL if available, otherwise fall back to provider defaults
+    const defaultURL = existingBaseURL || providerDefaults[provider] || '';
+    const baseURL = await p.text({
+        message: `Enter base URL for ${provider}`,
+        placeholder: defaultURL,
+        initialValue: defaultURL,
+        validate: (value) => {
+            if (!value.trim()) {
+                return 'Base URL is required';
+            }
+            try {
+                new URL(value.trim());
+                return undefined;
+            }
+            catch {
+                return 'Please enter a valid URL (e.g., http://localhost:11434/v1)';
+            }
+        },
+    });
+    if (p.isCancel(baseURL)) {
+        p.log.warn('Skipping base URL setup. You can configure it later with: dexto setup');
+        return { success: false, skipped: true };
+    }
+    const trimmedURL = baseURL.trim();
+    // Save to preferences
+    const spinner = p.spinner();
+    spinner.start('Saving base URL to preferences...');
+    try {
+        const preferences = await loadGlobalPreferences();
+        // Update the LLM section with baseURL (complete replacement as per schema design)
+        const updatedPreferences = {
+            ...preferences,
+            llm: {
+                ...preferences.llm,
+                baseURL: trimmedURL,
+            },
+        };
+        await saveGlobalPreferences(updatedPreferences);
+        spinner.stop(chalk.green('✓ Base URL saved to preferences'));
+        return { success: true, baseURL: trimmedURL };
+    }
+    catch (error) {
+        spinner.stop(chalk.red('✗ Failed to save base URL'));
+        logger.error(`Failed to save baseURL: ${error instanceof Error ? error.message : String(error)}`);
+        // Show manual instructions
+        p.note([
+            `Add this to your preferences file:`,
+            ``,
+            `  ${chalk.cyan('baseURL:')} ${trimmedURL}`,
+            ``,
+            `File: ${getGlobalPreferencesPath()}`,
+        ].join('\n'), chalk.rgb(255, 165, 0)('Manual Setup Required'));
+        // Still return success with the URL for in-memory use
+        return { success: true, baseURL: trimmedURL, skipped: true };
+    }
+}
+/**
+ * Handle non-API-key validation errors interactively
+ */
+async function handleOtherErrors(errors) {
+    console.log(chalk.rgb(255, 165, 0)('\n⚠️  Configuration issues detected:\n'));
+    for (const error of errors) {
+        console.log(chalk.red(`  • ${error}`));
+    }
+    console.log('');
+    const action = await p.select({
+        message: 'How would you like to proceed?',
+        options: [
+            {
+                value: 'skip',
+                label: 'Continue anyway',
+                hint: 'Try to start despite errors (may fail)',
+            },
+            {
+                value: 'edit',
+                label: 'Edit configuration manually',
+                hint: 'Show file path and instructions',
+            },
+            {
+                value: 'setup',
+                label: 'Run setup again',
+                hint: 'Reconfigure from scratch',
+            },
+        ],
+    });
+    if (p.isCancel(action)) {
+        showNextSteps();
+        return { success: false, errors, skipped: true };
+    }
+    if (action === 'edit') {
+        showManualEditInstructions();
+        return { success: false, errors, skipped: true };
     }
-    // Return the validated config
-    return parseResult.data;
+    if (action === 'setup') {
+        p.log.info('Run: dexto setup --force');
+        return { success: false, errors, skipped: true };
+    }
+    // 'skip' - continue anyway
+    p.log.warn('Continuing with validation errors - some features may not work correctly');
+    return { success: false, errors, skipped: true };
+}
+/**
+ * Show validation errors in a user-friendly way
+ */
+function showValidationErrors(errors) {
+    console.log(chalk.rgb(255, 165, 0)('\n⚠️  Configuration issues detected:\n'));
+    for (const error of errors) {
+        console.log(chalk.red(`  • ${error}`));
+    }
+    console.log('');
+}
+/**
+ * Show next steps after validation failure
+ */
+function showNextSteps() {
+    const prefsPath = getGlobalPreferencesPath();
+    console.log(chalk.bold('\nNext steps:'));
+    console.log(`  • Run ${chalk.cyan('dexto setup')} to reconfigure interactively`);
+    console.log(`  • Edit ${chalk.cyan(prefsPath)} directly`);
+    console.log(`  • Check your environment variables\n`);
+}
+/**
+ * Show manual edit instructions
+ */
+function showManualEditInstructions() {
+    const prefsPath = getGlobalPreferencesPath();
+    p.note([
+        `Your configuration files:`,
+        ``,
+        `  ${chalk.cyan('Global preferences:')} ${prefsPath}`,
+        `  ${chalk.cyan('Agent configs:')} ~/.dexto/agents/*/`,
+        ``,
+        `Edit the appropriate file and run dexto again.`,
+        ``,
+        chalk.gray('Example commands:'),
+        chalk.gray(`  code ${prefsPath}     # Open in VS Code`),
+        chalk.gray(`  nano ${prefsPath}     # Edit in terminal`),
+    ].join('\n'), 'Manual Configuration');
 }
 /**
  * Extract API key error details from Zod validation error
@@ -56,6 +331,28 @@ function findApiKeyError(error, configData) {
     }
     return null;
 }
+/**
+ * Extract baseURL error details from Zod validation error
+ */
+function findBaseURLError(error, configData) {
+    for (const issue of error.issues) {
+        // Check for our custom BASE_URL_MISSING error code in params
+        if (issue.code === 'custom' && hasErrorCode(issue.params, LLMErrorCode.BASE_URL_MISSING)) {
+            const provider = getProviderFromParams(issue.params) || configData.llm?.provider;
+            if (provider) {
+                return { provider };
+            }
+        }
+        // Fallback: check for baseURL path errors
+        if (issue.path.includes('baseURL') && issue.message.includes('requires')) {
+            const provider = configData.llm?.provider;
+            if (provider) {
+                return { provider };
+            }
+        }
+    }
+    return null;
+}
 /**
  * Type guard to check if params contains the expected error code
  */
@@ -80,9 +377,41 @@ function getProviderFromParams(params) {
 /**
  * Format Zod validation errors in a user-friendly way
  */
-function formatZodError(error) {
-    for (const issue of error.issues) {
+function formatZodErrors(error) {
+    return error.issues.map((issue) => {
         const path = issue.path.length > 0 ? issue.path.join('.') : 'config';
-        console.error(chalk.red(`  • ${path}: ${issue.message}`));
+        return `${path}: ${issue.message}`;
+    });
+}
+/**
+ * Legacy function for backwards compatibility
+ * @deprecated Use validateAgentConfig with result handling instead
+ */
+export async function validateAgentConfigOrExit(config, interactive = false) {
+    const result = await validateAgentConfig(config, interactive);
+    if (result.success && result.config) {
+        return result.config;
+    }
+    // If validation failed but was skipped, return config as-is with defaults applied
+    // This allows the app to launch in a limited capacity (e.g., web UI for configuration)
+    // Runtime errors will occur when actually trying to use the LLM
+    if (result.skipped) {
+        logger.warn('Starting with validation warnings - some features may not work');
+        // Apply defaults manually without strict validation
+        // This allows launching web UI for interactive configuration
+        // Use unknown cast to bypass branded type checking since we're intentionally
+        // returning a partially valid config that the user acknowledged
+        const configWithDefaults = {
+            ...config,
+            llm: {
+                ...config.llm,
+                maxIterations: config.llm?.maxIterations ?? 50,
+            },
+        };
+        return configWithDefaults;
     }
+    // Last resort: exit with helpful message
+    console.log(chalk.rgb(255, 165, 0)('\nUnable to start with current configuration.'));
+    showNextSteps();
+    process.exit(1);
 }