dexto 1.1.10 → 1.2.0

package/dist/index.js

@@ -5,6 +5,7 @@ import { applyLayeredEnvironmentLoading } from '@dexto/core';
 await applyLayeredEnvironmentLoading();
 import { existsSync } from 'fs';
 import { createRequire } from 'module';
+import path from 'path';
 import { Command } from 'commander';
 import * as p from '@clack/prompts';
 import chalk from 'chalk';
@@ -13,8 +14,8 @@ import { withAnalytics, safeExit, ExitSignal } from './analytics/wrapper.js';
 // Use createRequire to import package.json without experimental warning
 const require = createRequire(import.meta.url);
 const pkg = require('../package.json');
-import { logger, getProviderFromModel, getAllSupportedModels, DextoAgent, loadAgentConfig, } from '@dexto/core';
-import { resolveAgentPath, getAgentRegistry, isPath, resolveApiKeyForProvider } from '@dexto/core';
+import { logger, getProviderFromModel, getAllSupportedModels, DextoAgent, loadAgentConfig, globalPreferencesExist, loadGlobalPreferences, } from '@dexto/core';
+import { resolveAgentPath, getAgentRegistry, isPath, resolveApiKeyForProvider, getPrimaryApiKeyEnvVar, } from '@dexto/core';
 import { startAiCli, startHeadlessCli, loadMostRecentSession } from './cli/cli.js';
 import { startApiServer } from './api/server.js';
 import { startDiscordBot } from './discord/bot.js';
@@ -40,7 +41,7 @@ program
     .name('dexto')
     .description('AI-powered CLI and WebUI for interacting with MCP servers')
     .version(pkg.version, '-v, --version', 'output the current version')
-    .option('-a, --agent <name|path>', 'Agent name or path to agent config file')
+    .option('-a, --agent <id|path>', 'Agent ID or path to agent config file')
     .option('-p, --prompt <text>', 'Run prompt and exit. Alternatively provide a single quoted string as positional argument.')
     .option('-s, --strict', 'Require all server connections to succeed')
     .option('--no-verbose', 'Disable verbose output')
@@ -51,8 +52,9 @@ program
     .option('--auto-approve', 'Always approve tool executions without confirmation prompts')
     .option('-c, --continue', 'Continue most recent conversation')
     .option('-r, --resume <sessionId>', 'Resume session by ID')
-    .option('--mode <mode>', 'The application in which dexto should talk to you - cli | web | server | discord | telegram | mcp', 'cli')
-    .option('--web-port <port>', 'optional port for the web UI', '3000')
+    .option('--mode <mode>', 'The application in which dexto should talk to you - web | cli | server | discord | telegram | mcp', 'web')
+    .option('--web-port <port>', 'port for the web UI (default: 3000)', '3000')
+    .option('--api-port <port>', 'port for the API server (default: web-port + 1)')
     .option('--no-auto-install', 'Disable automatic installation of missing agents from registry')
     .enablePositionalOptions();
 // 2) `create-app` SUB-COMMAND
@@ -156,10 +158,17 @@ program
 // 5) `install` SUB-COMMAND
 program
     .command('install [agents...]')
-    .description('Install agents from the registry')
+    .description('Install agents from registry or custom YAML files/directories')
     .option('--all', 'Install all available agents from registry')
     .option('--no-inject-preferences', 'Skip injecting global preferences into installed agents')
     .option('--force', 'Force reinstall even if agent is already installed')
+    .addHelpText('after', `
+Examples:
+  $ dexto install default-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
+  $ dexto install ./my-agent-dir/            Install custom agent from directory (interactive)`)
     .action(withAnalytics('install', async (agents = [], options) => {
     try {
         await handleInstallCommand(agents, options);
@@ -231,7 +240,7 @@ async function bootstrapAgentFromGlobalOpts() {
     const resolvedPath = await resolveAgentPath(globalOpts.agent, globalOpts.autoInstall !== false, true);
     const rawConfig = await loadAgentConfig(resolvedPath);
     const mergedConfig = applyCLIOverrides(rawConfig, globalOpts);
-    const agent = new DextoAgent(mergedConfig, globalOpts.agent);
+    const agent = new DextoAgent(mergedConfig, resolvedPath);
     await agent.start();
     // Register graceful shutdown
     const shutdown = async () => {
@@ -402,31 +411,55 @@ program
     // Main customer facing description
     .description('Dexto CLI - AI-powered assistant with session management\n\n' +
     'Basic Usage:\n' +
-    '  dexto                    Start interactive REPL\n' +
-    '  dexto "query"            Start REPL with initial prompt\n' +
-    '  dexto -p "query"         Run query, then exit\n' +
+    '  dexto                    Start web UI (default)\n' +
+    '  dexto "query"            Run one-shot query (auto-uses CLI mode)\n' +
+    '  dexto -p "query"         Run one-shot query, then exit\n' +
     '  cat file | dexto -p "query"  Process piped content\n\n' +
+    'CLI Mode:\n' +
+    '  dexto --mode cli         Start interactive CLI REPL\n\n' +
     'Session Management:\n' +
     '  dexto -c                 Continue most recent conversation\n' +
-    '  dexto -c -p "query"      Continue conversation, then exit\n' +
-    '  dexto -r "<session-id>" "query"  Resume session by ID\n\n' +
+    '  dexto -c -p "query"      Continue with one-shot query, then exit\n' +
+    '  dexto -r "<session-id>" "query"  Resume with one-shot query\n\n' +
     'Tool Confirmation:\n' +
     '  dexto --auto-approve     Auto-approve all tool executions\n\n' +
+    'Agent Selection:\n' +
+    '  dexto --agent coding-agent       Use installed agent by name\n' +
+    '  dexto --agent ./my-agent.yml     Use agent from file path\n' +
+    '  dexto -a agents/custom.yml       Short form with relative path\n\n' +
     'Advanced Modes:\n' +
-    '  dexto --mode web         Run web UI\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' +
     'Session Commands: dexto session list|history|delete • search\n' +
     'Search: dexto search <query> [--session <id>] [--role <role>]\n\n' +
-    'See https://github.com/truffle-ai/dexto for more examples and documentation')
+    'See https://docs.dexto.ai for documentation and examples')
     .action(withAnalytics('main', async (prompt = []) => {
     // ——— ENV CHECK (optional) ———
     if (!existsSync('.env')) {
         logger.debug('WARNING: .env file not found; copy .env.example and set your API keys.');
     }
     const opts = program.opts();
+    // ——— LOAD DEFAULT MODE FROM PREFERENCES ———
+    // If --mode was not explicitly provided on CLI, use defaultMode from preferences
+    const modeSource = program.getOptionValueSource('mode');
+    const explicitModeProvided = modeSource === 'cli';
+    if (!explicitModeProvided) {
+        try {
+            if (globalPreferencesExist()) {
+                const preferences = await loadGlobalPreferences();
+                if (preferences.defaults?.defaultMode) {
+                    opts.mode = preferences.defaults.defaultMode;
+                    logger.debug(`Using default mode from preferences: ${opts.mode}`);
+                }
+            }
+        }
+        catch (error) {
+            // Silently fall back to hardcoded default if preferences loading fails
+            logger.debug(`Failed to load default mode from preferences: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
     let headlessInput = undefined;
     // Prefer explicit -p/--prompt for headless one-shot
     if (opts.prompt !== undefined && String(opts.prompt).trim() !== '') {
@@ -449,6 +482,13 @@ program
     }
     // Note: Agent selection must be passed via -a/--agent. We no longer interpret
     // the first positional argument as an agent name to avoid ambiguity with prompts.
+    // ——— FORCE CLI MODE FOR HEADLESS PROMPTS ———
+    // If a prompt was provided via -p or positional args, force CLI mode
+    if (headlessInput && opts.mode !== 'cli') {
+        console.log(`ℹ️  Prompt detected via -p or positional argument. Forcing CLI mode for one-shot execution.`);
+        console.log(`   Original mode: ${opts.mode} → Overridden to: cli`);
+        opts.mode = 'cli';
+    }
     // ——— Infer provider & API key from model ———
     if (opts.model) {
         let provider;
@@ -462,7 +502,8 @@ program
         }
         const apiKey = resolveApiKeyForProvider(provider);
         if (!apiKey) {
-            console.error(`❌ Missing API key for provider '${provider}' - please set the appropriate environment variable`);
+            const envVar = getPrimaryApiKeyEnvVar(provider);
+            console.error(`❌ Missing API key for provider '${provider}' - please set $${envVar}`);
             safeExit('main', 1, 'missing-api-key');
         }
         opts.provider = provider;
@@ -529,6 +570,7 @@ program
     }
     // ——— CREATE AGENT ———
     let agent;
+    let derivedAgentId;
     try {
         console.log(`🚀 Initializing Dexto with config: ${resolvedPath}`);
         // Set run mode for tool confirmation provider
@@ -541,51 +583,14 @@ program
             }
         }
         // DextoAgent will parse/validate again (parse-twice pattern)
-        agent = new DextoAgent(validatedConfig, opts.agent);
+        agent = new DextoAgent(validatedConfig, resolvedPath);
         // Start the agent (initialize async services)
         await agent.start();
-        // Handle session options - simplified logic
-        if (opts.resume) {
-            try {
-                // Resume specific session by ID
-                await agent.loadSessionAsDefault(opts.resume);
-                logger.info(`Resumed session: ${opts.resume}`, null, 'cyan');
-            }
-            catch (err) {
-                console.error(`❌ Failed to resume session '${opts.resume}': ${err instanceof Error ? err.message : String(err)}`);
-                console.error('💡 Use `dexto session list` to see available sessions');
-                safeExit('main', 1, 'resume-failed');
-            }
-        }
-        else if (opts.continue) {
-            try {
-                // Continue from most recent session
-                await loadMostRecentSession(agent);
-                // If no sessions existed, create a new one to honor default-new invariant
-                const sessionsAfter = await agent.listSessions();
-                if (sessionsAfter.length === 0) {
-                    const session = await agent.createSession();
-                    await agent.loadSessionAsDefault(session.id);
-                    logger.info(`Created new session: ${session.id}`, null, 'green');
-                }
-            }
-            catch (err) {
-                console.error(`❌ Failed to continue session: ${err instanceof Error ? err.message : String(err)}`);
-                safeExit('main', 1, 'continue-failed');
-            }
-        }
-        else {
-            // Default behavior: create new session
-            try {
-                const session = await agent.createSession();
-                await agent.loadSessionAsDefault(session.id);
-                logger.info(`Created new session: ${session.id}`, null, 'green');
-            }
-            catch (err) {
-                console.error(`❌ Failed to create new session: ${err instanceof Error ? err.message : String(err)}`);
-                safeExit('main', 1, 'create-session-failed');
-            }
-        }
+        // Derive a concise agent ID for display purposes (used by API/UI)
+        // Prefer agentCard.name, otherwise extract from filename
+        derivedAgentId =
+            validatedConfig.agentCard?.name ||
+                path.basename(resolvedPath, path.extname(resolvedPath));
     }
     catch (err) {
         if (err instanceof ExitSignal)
@@ -597,6 +602,48 @@ program
     // ——— Dispatch based on --mode ———
     switch (opts.mode) {
         case 'cli': {
+            // Handle session options - only for CLI mode
+            if (opts.resume) {
+                try {
+                    // Resume specific session by ID
+                    await agent.loadSessionAsDefault(opts.resume);
+                    logger.info(`Resumed session: ${opts.resume}`, null, 'cyan');
+                }
+                catch (err) {
+                    console.error(`❌ Failed to resume session '${opts.resume}': ${err instanceof Error ? err.message : String(err)}`);
+                    console.error('💡 Use `dexto session list` to see available sessions');
+                    safeExit('main', 1, 'resume-failed');
+                }
+            }
+            else if (opts.continue) {
+                try {
+                    // Continue from most recent session
+                    await loadMostRecentSession(agent);
+                    // If no sessions existed, create a new one to honor default-new invariant
+                    const sessionsAfter = await agent.listSessions();
+                    if (sessionsAfter.length === 0) {
+                        const session = await agent.createSession();
+                        await agent.loadSessionAsDefault(session.id);
+                        logger.info(`Created new session: ${session.id}`, null, 'green');
+                    }
+                }
+                catch (err) {
+                    console.error(`❌ Failed to continue session: ${err instanceof Error ? err.message : String(err)}`);
+                    safeExit('main', 1, 'continue-failed');
+                }
+            }
+            else {
+                // Default behavior: create new session for CLI mode
+                try {
+                    const session = await agent.createSession();
+                    await agent.loadSessionAsDefault(session.id);
+                    logger.info(`Created new session: ${session.id}`, null, 'green');
+                }
+                catch (err) {
+                    console.error(`❌ Failed to create new session: ${err instanceof Error ? err.message : String(err)}`);
+                    safeExit('main', 1, 'create-session-failed');
+                }
+            }
             const toolConfirmationMode = agent.getEffectiveConfig().toolConfirmation?.mode ?? 'event-based';
             if (toolConfirmationMode === 'event-based') {
                 // Set up CLI tool confirmation subscriber
@@ -621,11 +668,15 @@ program
         case 'web': {
             const webPort = parseInt(opts.webPort, 10);
             const frontPort = getPort(process.env.FRONTEND_PORT, webPort, 'FRONTEND_PORT');
-            const apiPort = getPort(process.env.API_PORT, webPort + 1, 'API_PORT');
+            // Use explicit --api-port if provided, otherwise default to webPort + 1
+            const defaultApiPort = opts.apiPort
+                ? parseInt(opts.apiPort, 10)
+                : webPort + 1;
+            const apiPort = getPort(process.env.API_PORT, defaultApiPort, 'API_PORT');
             const apiUrl = process.env.API_URL ?? `http://localhost:${apiPort}`;
             const nextJSserverURL = process.env.FRONTEND_URL ?? `http://localhost:${frontPort}`;
             // Start API server
-            await startApiServer(agent, apiPort, agent.getEffectiveConfig().agentCard || {}, opts.agent);
+            await startApiServer(agent, apiPort, agent.getEffectiveConfig().agentCard || {}, derivedAgentId);
             // Start Next.js web server
             const webServerStarted = await startNextJsWebServer(apiUrl, frontPort, nextJSserverURL);
             // Open WebUI in browser if server started successfully
@@ -646,10 +697,12 @@ program
         case 'server': {
             // Start server with REST APIs and WebSockets only
             const agentCard = agent.getEffectiveConfig().agentCard ?? {};
-            const apiPort = getPort(process.env.API_PORT, 3001, 'API_PORT');
+            // Use explicit --api-port if provided, otherwise default to 3001
+            const defaultApiPort = opts.apiPort ? parseInt(opts.apiPort, 10) : 3001;
+            const apiPort = getPort(process.env.API_PORT, defaultApiPort, 'API_PORT');
             const apiUrl = process.env.API_URL ?? `http://localhost:${apiPort}`;
             console.log('🌐 Starting server (REST APIs + WebSockets)...');
-            await startApiServer(agent, apiPort, agentCard, opts.agent);
+            await startApiServer(agent, apiPort, agentCard, derivedAgentId);
             console.log(`✅ Server running at ${apiUrl}`);
             console.log('Available endpoints:');
             console.log('  POST /api/message - Send async message');
@@ -699,7 +752,7 @@ program
                 );
                 // Use stdio transport in mcp mode
                 const mcpTransport = await createMcpTransport('stdio');
-                await initializeMcpServer(agent, agentCardData, mcpTransport);
+                await initializeMcpServer(() => agent, () => agentCardData, mcpTransport);
             }
             catch (err) {
                 // Write to stderr instead of stdout to avoid interfering with MCP protocol
@@ -709,7 +762,7 @@ program
             break;
         }
         default:
-            console.error(`❌ Unknown mode '${opts.mode}'. Use cli, web, server, discord, telegram, or mcp.`);
+            console.error(`❌ Unknown mode '${opts.mode}'. Use web, cli, server, discord, telegram, or mcp.`);
             safeExit('main', 1, 'unknown-mode');
     }
 }, { timeoutMs: 0 }));