dexto 1.3.0 → 1.5.0

package/dist/index.js

@@ -3,7 +3,7 @@
 import { applyLayeredEnvironmentLoading } from './utils/env.js';
 // Apply layered environment loading before any other imports
 await applyLayeredEnvironmentLoading();
-import { existsSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
 import { createRequire } from 'module';
 import path from 'path';
 import { Command } from 'commander';
@@ -15,16 +15,14 @@ import { withAnalytics, safeExit, ExitSignal } from './analytics/wrapper.js';
 const require = createRequire(import.meta.url);
 const pkg = require('../package.json');
 import { logger, getProviderFromModel, getAllSupportedModels, DextoAgent, isPath, resolveApiKeyForProvider, getPrimaryApiKeyEnvVar, } from '@dexto/core';
-import { resolveAgentPath, getAgentRegistry, loadAgentConfig, globalPreferencesExist, loadGlobalPreferences, } from '@dexto/agent-management';
+import { resolveAgentPath, loadAgentConfig, globalPreferencesExist, loadGlobalPreferences, resolveBundledScript, } from '@dexto/agent-management';
 import { startHonoApiServer } from './api/server-hono.js';
-import { startDiscordBot } from './discord/bot.js';
-import { startTelegramBot } from './telegram/bot.js';
 import { validateCliOptions, handleCliOptionsError } from './cli/utils/options.js';
 import { validateAgentConfig } from './cli/utils/config-validation.js';
-import { applyCLIOverrides } from './config/cli-overrides.js';
+import { applyCLIOverrides, applyUserPreferences, checkAgentCompatibility, } from './config/cli-overrides.js';
 import { enrichAgentConfig } from '@dexto/agent-management';
 import { getPort } from './utils/port-utils.js';
-import { createDextoProject, createTsconfigJson, addDextoScriptsToPackageJson, postCreateDexto, initDexto, postInitDexto, getUserInputToInitDextoApp, } from './cli/commands/index.js';
+import { createDextoProject, createImage, getUserInputToInitDextoApp, initDexto, postInitDexto, } from './cli/commands/index.js';
 import { handleSetupCommand, handleInstallCommand, handleUninstallCommand, handleListAgentsCommand, handleWhichCommand, } from './cli/commands/index.js';
 import { handleSessionListCommand, handleSessionHistoryCommand, handleSessionDeleteCommand, handleSessionSearchCommand, } from './cli/commands/session-commands.js';
 import { requiresSetup } from './cli/utils/setup-utils.js';
@@ -36,6 +34,41 @@ import { initializeMcpToolAggregationServer } from './api/mcp/tool-aggregation-h
 const program = new Command();
 // Initialize analytics early (no-op if disabled)
 await initAnalytics({ appVersion: pkg.version });
+/**
+ * Recursively removes null values from an object.
+ * This handles YAML files that have explicit `apiKey: null` entries
+ * which would otherwise cause "Expected string, received null" validation errors.
+ */
+function cleanNullValues(obj) {
+    if (obj === null || obj === undefined)
+        return obj;
+    if (typeof obj !== 'object')
+        return obj;
+    if (Array.isArray(obj)) {
+        return obj.map((item) => typeof item === 'object' && item !== null
+            ? cleanNullValues(item)
+            : item);
+    }
+    const cleaned = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (value === null) {
+            // Skip null values - they become undefined (missing)
+            continue;
+        }
+        if (typeof value === 'object' && !Array.isArray(value)) {
+            cleaned[key] = cleanNullValues(value);
+        }
+        else if (Array.isArray(value)) {
+            cleaned[key] = value.map((item) => typeof item === 'object' && item !== null
+                ? cleanNullValues(item)
+                : item);
+        }
+        else {
+            cleaned[key] = value;
+        }
+    }
+    return cleaned;
+}
 // 1) GLOBAL OPTIONS
 program
     .name('dexto')
@@ -48,43 +81,28 @@ program
     .option('--no-interactive', 'Disable interactive prompts and API key setup')
     .option('--skip-setup', 'Skip global setup validation (useful for MCP mode, automation)')
     .option('-m, --model <model>', 'Specify the LLM model to use')
-    .option('--router <router>', 'Specify the LLM router to use (vercel or in-built)')
     .option('--auto-approve', 'Always approve tool executions without confirmation prompts')
     .option('-c, --continue', 'Continue most recent session (requires -p/prompt)')
     .option('-r, --resume <sessionId>', 'Resume specific session (requires -p/prompt)')
-    .option('--mode <mode>', 'The application in which dexto should talk to you - web | cli | server | discord | telegram | mcp', 'web')
+    .option('--mode <mode>', 'The application in which dexto should talk to you - web | cli | server | mcp', 'web')
     .option('--port <port>', 'port for the server (default: 3000 for web, 3001 for server mode)')
     .option('--no-auto-install', 'Disable automatic installation of missing agents from registry')
+    .option('--image <package>', 'Image package to load (e.g., @dexto/image-local). Overrides config image field.')
     .enablePositionalOptions();
 // 2) `create-app` SUB-COMMAND
 program
-    .command('create-app')
-    .description('Scaffold a new Dexto Typescript app')
-    .action(withAnalytics('create-app', async () => {
+    .command('create-app [name]')
+    .description('Create a Dexto application (CLI, web, bot, etc.)')
+    .option('--from-image <package>', 'Use existing image (e.g., @dexto/image-local)')
+    .option('--extend-image <package>', 'Extend image with custom providers')
+    .option('--from-core', 'Build from @dexto/core (advanced)')
+    .option('--type <type>', 'App type: script, webapp (default: script)')
+    .action(withAnalytics('create-app', async (name, options) => {
     try {
-        p.intro(chalk.inverse('Dexto Create App'));
-        // first setup the initial files in the project and get the project path
-        const appPath = await createDextoProject();
-        // then get user inputs for directory, llm etc.
-        const userInput = await getUserInputToInitDextoApp();
-        try {
-            capture('dexto_create', {
-                provider: userInput.llmProvider,
-                providedKey: Boolean(userInput.llmApiKey),
-            });
-        }
-        catch {
-            // Analytics failures should not block CLI execution.
-        }
-        // move to project directory, then add the dexto scripts to the package.json and create the tsconfig.json
-        process.chdir(appPath);
-        await addDextoScriptsToPackageJson(userInput.directory, appPath);
-        await createTsconfigJson(appPath, userInput.directory);
-        // then initialize the other parts of the project
-        await initDexto(userInput.directory, userInput.createExampleFile, userInput.llmProvider, userInput.llmApiKey);
-        p.outro(chalk.greenBright('Dexto app created and initialized successfully!'));
-        // add notes for users to get started with their newly created Dexto project
-        await postCreateDexto(appPath, userInput.directory);
+        p.intro(chalk.inverse('Create Dexto App'));
+        // Create the app project structure (fully self-contained)
+        await createDextoProject(name, options);
+        p.outro(chalk.greenBright('Dexto app created successfully!'));
         safeExit('create-app', 0);
     }
     catch (err) {
@@ -94,7 +112,26 @@ program
         safeExit('create-app', 1, 'error');
     }
 }));
-// 3) `init-app` SUB-COMMAND
+// 3) `create-image` SUB-COMMAND
+program
+    .command('create-image [name]')
+    .description('Create a Dexto image - a distributable agent harness package')
+    .action(withAnalytics('create-image', async (name) => {
+    try {
+        p.intro(chalk.inverse('Create Dexto Image'));
+        // Create the image project structure
+        const projectPath = await createImage(name);
+        p.outro(chalk.greenBright(`Dexto image created successfully at ${projectPath}!`));
+        safeExit('create-image', 0);
+    }
+    catch (err) {
+        if (err instanceof ExitSignal)
+            throw err;
+        console.error(`❌ dexto create-image command failed: ${err}`);
+        safeExit('create-image', 1, 'error');
+    }
+}));
+// 4) `init-app` SUB-COMMAND
 program
     .command('init-app')
     .description('Initialize an existing Typescript app with Dexto')
@@ -133,13 +170,13 @@ program
         safeExit('init-app', 1, 'error');
     }
 }));
-// 4) `setup` SUB-COMMAND
+// 5) `setup` SUB-COMMAND
 program
     .command('setup')
     .description('Configure global Dexto preferences')
     .option('--provider <provider>', 'LLM provider (openai, anthropic, google, groq)')
     .option('--model <model>', 'Model name (uses provider default if not specified)')
-    .option('--default-agent <agent>', 'Default agent name (default: default-agent)')
+    .option('--default-agent <agent>', 'Default agent name (default: coding-agent)')
     .option('--no-interactive', 'Skip interactive prompts and API key setup')
     .option('--force', 'Overwrite existing setup without confirmation')
     .action(withAnalytics('setup', async (options) => {
@@ -154,7 +191,7 @@ program
         safeExit('setup', 1, 'error');
     }
 }));
-// 5) `install` SUB-COMMAND
+// 6) `install` SUB-COMMAND
 program
     .command('install [agents...]')
     .description('Install agents from registry or custom YAML files/directories')
@@ -163,7 +200,7 @@ program
     .option('--force', 'Force reinstall even if agent is already installed')
     .addHelpText('after', `
 Examples:
-  $ dexto install default-agent              Install agent from registry
+  $ dexto install coding-agent               Install agent from registry
   $ dexto install agent1 agent2              Install multiple registry agents
   $ dexto install --all                      Install all available registry agents
   $ dexto install ./my-agent.yml             Install custom agent from YAML file
@@ -180,12 +217,12 @@ Examples:
         safeExit('install', 1, 'error');
     }
 }));
-// 6) `uninstall` SUB-COMMAND
+// 7) `uninstall` SUB-COMMAND
 program
     .command('uninstall [agents...]')
     .description('Uninstall agents from the local installation')
     .option('--all', 'Uninstall all installed agents')
-    .option('--force', 'Force uninstall even if agent is protected (e.g., default-agent)')
+    .option('--force', 'Force uninstall even if agent is protected (e.g., coding-agent)')
     .action(withAnalytics('uninstall', async (agents, options) => {
     try {
         await handleUninstallCommand(agents, options);
@@ -198,7 +235,7 @@ program
         safeExit('uninstall', 1, 'error');
     }
 }));
-// 7) `list-agents` SUB-COMMAND
+// 8) `list-agents` SUB-COMMAND
 program
     .command('list-agents')
     .description('List available and installed agents')
@@ -217,7 +254,7 @@ program
         safeExit('list-agents', 1, 'error');
     }
 }));
-// 8) `which` SUB-COMMAND
+// 9) `which` SUB-COMMAND
 program
     .command('which <agent>')
     .description('Show the path to an agent')
@@ -236,21 +273,43 @@ program
 // Helper to bootstrap a minimal agent for non-interactive session/search ops
 async function bootstrapAgentFromGlobalOpts() {
     const globalOpts = program.opts();
-    const resolvedPath = await resolveAgentPath(globalOpts.agent, globalOpts.autoInstall !== false, true);
+    const resolvedPath = await resolveAgentPath(globalOpts.agent, globalOpts.autoInstall !== false);
     const rawConfig = await loadAgentConfig(resolvedPath);
     const mergedConfig = applyCLIOverrides(rawConfig, globalOpts);
-    const enrichedConfig = enrichAgentConfig(mergedConfig, resolvedPath);
+    const enrichedConfig = enrichAgentConfig(mergedConfig, resolvedPath, {
+        logLevel: 'info', // CLI uses info-level logging for visibility
+    });
+    // Load image dynamically if specified (same priority as main command)
+    // Priority: CLI flag > Agent config > Environment variable > Default
+    // Images are optional, but default to image-local for convenience
+    const imageName = globalOpts.image || // --image flag
+        enrichedConfig.image || // image field in agent config
+        process.env.DEXTO_IMAGE || // DEXTO_IMAGE env var
+        '@dexto/image-local'; // Default for convenience
+    try {
+        await import(imageName);
+    }
+    catch (_err) {
+        console.error(`❌ Failed to load image '${imageName}'`);
+        console.error(`💡 Install it with: ${existsSync('package.json') ? 'npm install' : 'npm install -g'} ${imageName}`);
+        safeExit('bootstrap', 1, 'image-load-failed');
+    }
     // Override approval config for read-only commands (never run conversations)
     // This avoids needing to set up unused approval handlers
     enrichedConfig.toolConfirmation = {
         mode: 'auto-approve',
-        timeout: enrichedConfig.toolConfirmation?.timeout ?? 120000,
+        ...(enrichedConfig.toolConfirmation?.timeout !== undefined && {
+            timeout: enrichedConfig.toolConfirmation.timeout,
+        }),
     };
     enrichedConfig.elicitation = {
         enabled: false,
-        timeout: enrichedConfig.elicitation?.timeout ?? 120000,
+        ...(enrichedConfig.elicitation?.timeout !== undefined && {
+            timeout: enrichedConfig.elicitation.timeout,
+        }),
     };
-    const agent = new DextoAgent(enrichedConfig, resolvedPath);
+    // Use relaxed validation for session commands - they don't need LLM calls
+    const agent = new DextoAgent(enrichedConfig, resolvedPath, { strict: false });
     await agent.start();
     // Register graceful shutdown
     const shutdown = async () => {
@@ -289,7 +348,7 @@ async function getMostRecentSessionId(agent, includeHeadless = false) {
     }
     return mostRecentId;
 }
-// 9) `session` SUB-COMMAND
+// 10) `session` SUB-COMMAND
 const sessionCommand = program.command('session').description('Manage chat sessions');
 sessionCommand
     .command('list')
@@ -344,7 +403,7 @@ sessionCommand
         safeExit('session delete', 1, 'error');
     }
 }));
-// 10) `search` SUB-COMMAND
+// 11) `search` SUB-COMMAND
 program
     .command('search')
     .description('Search session history')
@@ -386,7 +445,7 @@ program
         safeExit('search', 1, 'error');
     }
 }));
-// 11) `mcp` SUB-COMMAND
+// 12) `mcp` SUB-COMMAND
 // For now, this mode simply aggregates and re-expose tools from configured MCP servers (no agent)
 // dexto --mode mcp will be moved to this sub-command in the future
 program
@@ -409,7 +468,7 @@ program
         // Get the global agent option from the main program
         const globalOpts = program.opts();
         const nameOrPath = globalOpts.agent;
-        const configPath = await resolveAgentPath(nameOrPath, globalOpts.autoInstall !== false, true);
+        const configPath = await resolveAgentPath(nameOrPath, globalOpts.autoInstall !== false);
         console.log(`📄 Loading Dexto config from: ${configPath}`);
         const config = await loadAgentConfig(configPath);
         logger.info(`Validating MCP servers...`);
@@ -439,7 +498,7 @@ program
         safeExit('mcp', 1, 'mcp-agg-failed');
     }
 }, { timeoutMs: 0 }));
-// 10) Main dexto CLI - Interactive/One shot (CLI/HEADLESS) or run in other modes (--mode web/discord/telegram)
+// 13) Main dexto CLI - Interactive/One shot (CLI/HEADLESS) or run in other modes (--mode web/server/mcp)
 program
     .argument('[prompt...]', 'Natural-language prompt to run once. If not passed, dexto will start as an interactive CLI')
     // Main customer facing description
@@ -469,8 +528,6 @@ program
     '  dexto --auto-approve     Auto-approve all tool executions\n\n' +
     'Advanced Modes:\n' +
     '  dexto --mode server      Run as API server\n' +
-    '  dexto --mode discord     Run as Discord bot\n' +
-    '  dexto --mode telegram    Run as Telegram bot\n' +
     '  dexto --mode mcp         Run as MCP server\n\n' +
     'See https://docs.dexto.ai for documentation and examples')
     .action(withAnalytics('main', async (prompt = []) => {
@@ -564,28 +621,42 @@ program
     // ——— ENHANCED PREFERENCE-AWARE CONFIG LOADING ———
     let validatedConfig;
     let resolvedPath;
+    // Determine validation mode early - used throughout config loading and agent creation
+    // Use relaxed validation for interactive modes (web/cli) where users can configure later
+    // Use strict validation for headless modes (server/mcp) that need full config upfront
+    const isInteractiveMode = opts.mode === 'web' || opts.mode === 'cli';
     try {
         // Case 1: File path - skip all validation and setup
         if (opts.agent && isPath(opts.agent)) {
-            resolvedPath = await resolveAgentPath(opts.agent, opts.autoInstall !== false, true);
+            resolvedPath = await resolveAgentPath(opts.agent, opts.autoInstall !== false);
         }
         // Cases 2 & 3: Default agent or registry agent
         else {
             // Early registry validation for named agents
             if (opts.agent) {
-                const registry = getAgentRegistry();
-                if (!registry.hasAgent(opts.agent)) {
-                    console.error(`❌ Agent '${opts.agent}' not found in registry`);
-                    // Show available agents
-                    const available = Object.keys(registry.getAvailableAgents());
-                    if (available.length > 0) {
-                        console.log(`📋 Available agents: ${available.join(', ')}`);
-                    }
-                    else {
-                        console.log('📋 No agents available in registry');
+                // Load bundled registry to check if agent exists
+                try {
+                    const bundledRegistryPath = resolveBundledScript('agents/agent-registry.json');
+                    const registryContent = readFileSync(bundledRegistryPath, 'utf-8');
+                    const bundledRegistry = JSON.parse(registryContent);
+                    // Check if agent exists in bundled registry
+                    if (!(opts.agent in bundledRegistry.agents)) {
+                        console.error(`❌ Agent '${opts.agent}' not found in registry`);
+                        // Show available agents
+                        const available = Object.keys(bundledRegistry.agents);
+                        if (available.length > 0) {
+                            console.log(`📋 Available agents: ${available.join(', ')}`);
+                        }
+                        else {
+                            console.log('📋 No agents available in registry');
+                        }
+                        safeExit('main', 1, 'agent-not-in-registry');
+                        return;
                     }
-                    safeExit('main', 1, 'agent-not-in-registry');
-                    return;
+                }
+                catch (error) {
+                    logger.warn(`Could not validate agent against registry: ${error instanceof Error ? error.message : String(error)}`);
+                    // Continue anyway - resolver will handle it
                 }
             }
             // Check setup state and auto-trigger if needed
@@ -597,20 +668,190 @@ program
                     safeExit('main', 1, 'setup-required-non-interactive');
                 }
                 await handleSetupCommand({ interactive: true });
+                // Reload preferences after setup to get the newly selected default mode
+                // (setup may have just saved a different mode than the default 'web')
+                try {
+                    const newPreferences = await loadGlobalPreferences();
+                    if (newPreferences.defaults?.defaultMode) {
+                        opts.mode = newPreferences.defaults.defaultMode;
+                        logger.debug(`Updated mode from setup preferences: ${opts.mode}`);
+                    }
+                }
+                catch {
+                    // Ignore errors - will use default mode
+                }
             }
-            // Now resolve agent (will auto-install with preferences since setup is complete)
-            resolvedPath = await resolveAgentPath(opts.agent, opts.autoInstall !== false, true);
+            // Now resolve agent (will auto-install since setup is complete)
+            resolvedPath = await resolveAgentPath(opts.agent, opts.autoInstall !== false);
         }
         // Load raw config and apply CLI overrides
         const rawConfig = await loadAgentConfig(resolvedPath);
-        const mergedConfig = applyCLIOverrides(rawConfig, opts);
+        let mergedConfig = applyCLIOverrides(rawConfig, opts);
+        // ——— PREFERENCE-AWARE CONFIG HANDLING ———
+        // For coding-agent (no explicit agent specified): Apply user preferences
+        // For specific agents: Check compatibility and warn if needed
+        const isDefaultAgent = !opts.agent;
+        let preferences = null;
+        if (globalPreferencesExist()) {
+            try {
+                preferences = await loadGlobalPreferences();
+            }
+            catch {
+                // Preferences exist but couldn't load - continue without them
+                logger.debug('Could not load preferences, continuing without them');
+            }
+        }
+        // Check for pending API key setup (user skipped during initial setup)
+        if (isDefaultAgent &&
+            preferences?.setup?.apiKeyPending &&
+            opts.interactive !== false) {
+            // Check if API key is still missing (user may have set it manually)
+            const configuredApiKey = resolveApiKeyForProvider(preferences.llm.provider);
+            if (!configuredApiKey) {
+                const { promptForPendingApiKey } = await import('./cli/utils/api-key-setup.js');
+                const { updateGlobalPreferences } = await import('@dexto/agent-management');
+                const result = await promptForPendingApiKey(preferences.llm.provider, preferences.llm.model);
+                if (result.action === 'cancel') {
+                    safeExit('main', 0, 'pending-api-key-cancelled');
+                }
+                if (result.action === 'setup' && result.apiKey) {
+                    // API key was configured - update preferences to clear pending flag
+                    await updateGlobalPreferences({
+                        setup: { apiKeyPending: false },
+                    });
+                    // Update the merged config with the new API key
+                    mergedConfig.llm.apiKey = result.apiKey;
+                    logger.debug('API key configured, pending flag cleared');
+                }
+                // If 'skip', continue without API key (user chose to proceed)
+            }
+            else {
+                // API key exists (user set it manually) - clear the pending flag
+                const { updateGlobalPreferences } = await import('@dexto/agent-management');
+                await updateGlobalPreferences({
+                    setup: { apiKeyPending: false },
+                });
+                logger.debug('API key found in environment, cleared pending flag');
+            }
+        }
+        if (isDefaultAgent && preferences) {
+            // Default-agent: Apply user's LLM preferences at runtime
+            // This ensures the base agent always uses user's preferred model/provider
+            mergedConfig = applyUserPreferences(mergedConfig, preferences);
+            logger.debug('Applied user preferences to coding-agent', {
+                provider: preferences.llm.provider,
+                model: preferences.llm.model,
+            });
+        }
+        else if (!isDefaultAgent && mergedConfig.llm) {
+            // Specific agent: Check if user has the required provider configured
+            const agentProvider = mergedConfig.llm.provider;
+            const resolvedApiKey = resolveApiKeyForProvider(agentProvider);
+            const compatibility = checkAgentCompatibility(mergedConfig, preferences, resolvedApiKey);
+            if (!compatibility.compatible && opts.interactive !== false) {
+                // User is missing API key for the agent's provider
+                if (!compatibility.userHasApiKey &&
+                    preferences?.llm?.provider &&
+                    preferences?.llm?.model) {
+                    // User has a default LLM configured - offer choice
+                    const { promptForMissingAgentApiKey } = await import('./cli/utils/api-key-setup.js');
+                    const result = await promptForMissingAgentApiKey(compatibility.agentProvider, compatibility.agentModel, preferences.llm.provider, preferences.llm.model);
+                    if (result.action === 'cancel') {
+                        safeExit('main', 0, 'agent-api-key-cancelled');
+                    }
+                    if (result.action === 'use-default') {
+                        // Apply user's default LLM to the agent config
+                        mergedConfig = applyUserPreferences(mergedConfig, preferences);
+                        // Also resolve the actual API key from environment
+                        // (preferences store env var reference like $GOOGLE_API_KEY, not the actual key)
+                        const userApiKey = resolveApiKeyForProvider(preferences.llm.provider);
+                        if (userApiKey) {
+                            mergedConfig.llm.apiKey = userApiKey;
+                        }
+                        logger.debug('Applied user preferences to agent (user chose default)', {
+                            provider: preferences.llm.provider,
+                            model: preferences.llm.model,
+                        });
+                    }
+                    if (result.action === 'add-key' && result.apiKey) {
+                        // User added the API key - update the config
+                        mergedConfig.llm.apiKey = result.apiKey;
+                        logger.debug('Applied new API key to agent config');
+                    }
+                }
+                else {
+                    // No default LLM to fall back to - show warnings only
+                    console.log(chalk.yellow('\n⚠️  Agent Compatibility Notice:'));
+                    for (const warning of compatibility.warnings) {
+                        console.log(chalk.yellow(`   ${warning}`));
+                    }
+                    if (compatibility.instructions.length > 0) {
+                        console.log(chalk.dim('\n   To fix:'));
+                        for (const instruction of compatibility.instructions) {
+                            console.log(chalk.dim(`   ${instruction}`));
+                        }
+                    }
+                    console.log(''); // Empty line for spacing
+                }
+            }
+        }
+        // Clean up null values from config (can happen from YAML files with explicit nulls)
+        // This prevents "Expected string, received null" errors for optional fields
+        const cleanedConfig = cleanNullValues(mergedConfig);
         // Enrich config with per-agent paths BEFORE validation
         // Enrichment adds filesystem paths to storage (schema has in-memory defaults)
         // Interactive CLI mode: only log to file (console would interfere with chat UI)
         const isInteractiveCli = opts.mode === 'cli' && !headlessInput;
-        const enrichedConfig = enrichAgentConfig(mergedConfig, resolvedPath, isInteractiveCli);
+        const enrichedConfig = enrichAgentConfig(cleanedConfig, resolvedPath, {
+            isInteractiveCli,
+            logLevel: 'info', // CLI uses info-level logging for visibility
+        });
         // Validate enriched config with interactive setup if needed (for API key issues)
-        validatedConfig = await validateAgentConfig(enrichedConfig, opts.interactive !== false);
+        // isInteractiveMode is defined above the try block
+        const validationResult = await validateAgentConfig(enrichedConfig, opts.interactive !== false, { strict: !isInteractiveMode });
+        if (validationResult.success && validationResult.config) {
+            validatedConfig = validationResult.config;
+        }
+        else if (validationResult.skipped) {
+            // User chose to continue despite validation errors
+            // SAFETY: This cast is intentionally unsafe - it's an escape hatch for users
+            // when validation is overly strict or incorrect. Runtime errors will surface
+            // if the config truly doesn't work. Future: explicit `allowUnvalidated` mode.
+            logger.warn('Starting with validation warnings - some features may not work');
+            validatedConfig = enrichedConfig;
+        }
+        else {
+            // Validation failed and user didn't skip - show next steps and exit
+            safeExit('main', 1, 'config-validation-failed');
+        }
+        // ——— LOAD IMAGE DYNAMICALLY (if specified) ———
+        // Priority: CLI flag > Agent config > Environment variable > Default
+        // Images are optional, but default to image-local for convenience
+        const imageName = opts.image || // --image flag
+            validatedConfig.image || // image field in agent config
+            process.env.DEXTO_IMAGE || // DEXTO_IMAGE env var
+            '@dexto/image-local'; // Default for convenience
+        try {
+            await import(imageName);
+            logger.debug(`Loaded image: ${imageName}`);
+        }
+        catch (err) {
+            console.error(`❌ Failed to load image '${imageName}'`);
+            console.error(`💡 Install it with: ${existsSync('package.json') ? 'npm install' : 'npm install -g'} ${imageName}`);
+            if (err instanceof Error) {
+                logger.debug(`Image load error: ${err.message}`);
+            }
+            safeExit('main', 1, 'image-load-failed');
+        }
+        // Validate that if config specifies an image, it matches what was loaded
+        // Skip this check if user explicitly provided --image flag (intentional override)
+        if (!opts.image &&
+            validatedConfig.image &&
+            validatedConfig.image !== imageName) {
+            console.error(`❌ Config specifies image '${validatedConfig.image}' but '${imageName}' was loaded instead`);
+            console.error(`💡 Either remove 'image' from config or ensure it matches the loaded image`);
+            safeExit('main', 1, 'image-mismatch');
+        }
     }
     catch (err) {
         if (err instanceof ExitSignal)
@@ -663,7 +904,10 @@ program
         }
         // Config is already enriched and validated - ready for agent creation
         // DextoAgent will parse/validate again (parse-twice pattern)
-        agent = new DextoAgent(validatedConfig, resolvedPath);
+        // isInteractiveMode is already defined above for validateAgentConfig
+        agent = new DextoAgent(validatedConfig, resolvedPath, {
+            strict: !isInteractiveMode,
+        });
         // Start the agent (initialize async services)
         // - web/server modes: initializeHonoApi will set approval handler and start the agent
         // - cli mode: handles its own approval setup in the case block
@@ -704,6 +948,15 @@ program
                 const approvalCoordinator = new ApprovalCoordinator();
                 const handler = createManualApprovalHandler(approvalCoordinator);
                 agent.setApprovalHandler(handler);
+                // Bridge approval events between coordinator and agent event bus for Ink CLI
+                // Forward requests from coordinator to event bus (for UI to receive)
+                approvalCoordinator.on('approval:request', (request) => {
+                    agent.agentEventBus.emit('approval:request', request);
+                });
+                // Forward responses from event bus to coordinator (for handler to receive)
+                agent.agentEventBus.on('approval:response', (response) => {
+                    approvalCoordinator.emitResponse(response);
+                });
                 logger.debug('Event-based approval handler configured for Ink CLI');
             }
             // Start the agent now that approval handler is configured
@@ -799,8 +1052,41 @@ program
             else {
                 // Interactive mode - session management handled via /resume command
                 // Note: -c and -r flags are validated to require a prompt (headless mode only)
-                // Defer session creation until first message is sent to prevent stale empty sessions
-                const cliSessionId = null;
+                // Check if API key is configured before trying to create session
+                // Session creation triggers LLM service init which requires API key
+                const llmConfig = agent.getCurrentLLMConfig();
+                const { requiresApiKey } = await import('@dexto/core');
+                if (requiresApiKey(llmConfig.provider) && !llmConfig.apiKey?.trim()) {
+                    // Offer interactive API key setup instead of just exiting
+                    const { interactiveApiKeySetup } = await import('./cli/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) {
+                        await agent.stop().catch(() => { });
+                        safeExit('main', 0, 'api-key-setup-cancelled');
+                    }
+                    if (setupResult.skipped) {
+                        // User chose to skip - exit with instructions
+                        await agent.stop().catch(() => { });
+                        safeExit('main', 0, 'api-key-pending');
+                    }
+                    if (setupResult.success && setupResult.apiKey) {
+                        // API key was entered and saved - reload config and continue
+                        // Update the agent's LLM config with the new API key
+                        await agent.switchLLM({
+                            provider: llmConfig.provider,
+                            model: llmConfig.model,
+                            apiKey: setupResult.apiKey,
+                        });
+                        logger.info('API key configured successfully, continuing...');
+                    }
+                }
+                // Create session eagerly so slash commands work immediately
+                const session = await agent.createSession();
+                const cliSessionId = session.id;
                 // Interactive mode - use Ink CLI with session support
                 // Suppress console output before starting Ink UI
                 const originalConsole = {
@@ -849,8 +1135,8 @@ program
                 }
                 safeExit('main', 0);
             }
-            break;
         }
+        // falls through - safeExit returns never, but eslint doesn't know that
         case 'web': {
             // Default to 3000 for web mode
             const defaultPort = opts.port ? parseInt(opts.port, 10) : 3000;
@@ -903,26 +1189,6 @@ program
             console.log('  SSE support available for real-time events');
             break;
         }
-        case 'discord':
-            console.log('🤖 Starting Discord bot…');
-            try {
-                startDiscordBot(agent);
-            }
-            catch (err) {
-                console.error('❌ Discord startup failed:', err);
-                safeExit('main', 1, 'discord-startup-failed');
-            }
-            break;
-        case 'telegram':
-            console.log('🤖 Starting Telegram bot…');
-            try {
-                startTelegramBot(agent);
-            }
-            catch (err) {
-                console.error('❌ Telegram startup failed:', err);
-                safeExit('main', 1, 'telegram-startup-failed');
-            }
-            break;
         // TODO: Remove if server mode is stable and supports mcp
         // Starts dexto as a local mcp server
         // Use `dexto --mode mcp` to start dexto as a local mcp server
@@ -953,9 +1219,23 @@ program
             break;
         }
         default:
-            console.error(`❌ Unknown mode '${opts.mode}'. Use web, cli, server, discord, telegram, or mcp.`);
+            if (opts.mode === 'discord' || opts.mode === 'telegram') {
+                console.error(`❌ Error: '${opts.mode}' mode has been moved to examples`);
+                console.error('');
+                console.error(`The ${opts.mode} bot is now a standalone example that you can customize.`);
+                console.error('');
+                console.error(`📖 See: examples/${opts.mode}-bot/README.md`);
+                console.error('');
+                console.error(`To run it:`);
+                console.error(`  cd examples/${opts.mode}-bot`);
+                console.error(`  pnpm install`);
+                console.error(`  pnpm start`);
+            }
+            else {
+                console.error(`❌ Unknown mode '${opts.mode}'. Use web, cli, server, or mcp.`);
+            }
             safeExit('main', 1, 'unknown-mode');
     }
 }, { timeoutMs: 0 }));
-// 11) PARSE & EXECUTE
+// 14) PARSE & EXECUTE
 program.parseAsync(process.argv);