dexto 1.1.11 → 1.2.1

package/dist/api/middleware/errorHandler.js

@@ -14,6 +14,8 @@ const mapErrorTypeToStatus = (type) => {
             return 403;
         case ErrorType.TIMEOUT:
             return 408;
+        case ErrorType.CONFLICT:
+            return 409;
         case ErrorType.RATE_LIMIT:
             return 429;
         case ErrorType.SYSTEM:

package/dist/api/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/api/server.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAY,MAAM,SAAS,CAAC;AACjD,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,IAAI,CAAC;AAErC,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAEjE,OAAO,EAAkD,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAS7F,OAAO,EAA0B,UAAU,EAAY,MAAM,aAAa,CAAC;AA8D3E,wBAAsB,aAAa,CAC/B,KAAK,EAAE,UAAU,EACjB,iBAAiB,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,EACtC,UAAU,CAAC,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC;IACP,GAAG,EAAE,OAAO,CAAC;IACb,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC;IACpB,GAAG,EAAE,eAAe,CAAC;IACrB,aAAa,EAAE,wBAAwB,CAAC;IACxC,iBAAiB,EAAE,sBAAsB,CAAC;CAC7C,CAAC,CA2nED;AAED,wBAAsB,cAAc,CAChC,KAAK,EAAE,UAAU,EACjB,IAAI,SAAO,EACX,iBAAiB,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,EACtC,OAAO,CAAC,EAAE,MAAM;;;;;GA6BnB"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/api/server.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAY,MAAM,SAAS,CAAC;AACjD,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,IAAI,CAAC;AAErC,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAEjE,OAAO,EAAkD,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAS7F,OAAO,EAA0B,UAAU,EAAmB,MAAM,aAAa,CAAC;AA8DlF,wBAAsB,aAAa,CAC/B,KAAK,EAAE,UAAU,EACjB,iBAAiB,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,EACtC,UAAU,CAAC,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC;IACP,GAAG,EAAE,OAAO,CAAC;IACb,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC;IACpB,GAAG,EAAE,eAAe,CAAC;IACrB,aAAa,EAAE,wBAAwB,CAAC;IACxC,iBAAiB,EAAE,sBAAsB,CAAC;CAC7C,CAAC,CAmxED;AAED,wBAAsB,cAAc,CAChC,KAAK,EAAE,UAAU,EACjB,IAAI,SAAO,EACX,iBAAiB,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,EACtC,OAAO,CAAC,EAAE,MAAM;;;;;GA6BnB"}

package/dist/api/server.js

@@ -7,7 +7,7 @@ import { logger, redactSensitiveData, deriveDisplayName } from '@dexto/core';
 import { setupA2ARoutes } from './a2a.js';
 import { setupMemoryRoutes } from './memory/memory-handler.js';
 import { createMcpTransport, initializeMcpServer, initializeMcpServerApiEndpoints, } from './mcp/mcp_handler.js';
-import { createAgentCard, Dexto, getDexto } from '@dexto/core';
+import { createAgentCard, Dexto, DextoAgent, loadAgentConfig } from '@dexto/core';
 import { stringify as yamlStringify, parse as yamlParse } from 'yaml';
 import os from 'os';
 import { promises as fs } from 'fs';
@@ -55,6 +55,42 @@ export async function initializeApi(agent, agentCardOverride, listenPort, agentI
     let activeAgentId = agentId || 'default-agent';
     let isSwitchingAgent = false;
     registerGracefulShutdown(() => activeAgent);
+    // CORS middleware to allow frontend to connect from different ports
+    app.use((req, res, next) => {
+        const origin = req.headers.origin;
+        // Define allowed origins based on environment
+        const allowedOrigins = [];
+        // 1. Always allow localhost/127.0.0.1 on any port (for local development)
+        if (origin) {
+            const originUrl = new URL(origin);
+            const hostname = originUrl.hostname;
+            if (hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1') {
+                allowedOrigins.push(origin);
+            }
+        }
+        // 2. Allow custom origins from environment variable (for production/network deployments)
+        const customOrigins = process.env.DEXTO_ALLOWED_ORIGINS;
+        if (customOrigins) {
+            allowedOrigins.push(...customOrigins.split(',').map((o) => o.trim()));
+        }
+        // 3. Set CORS headers
+        if (origin && allowedOrigins.includes(origin)) {
+            res.setHeader('Access-Control-Allow-Origin', origin);
+            res.setHeader('Access-Control-Allow-Credentials', 'true');
+        }
+        else if (allowedOrigins.length === 0 && !origin) {
+            // If no origin header (e.g., server-to-server), allow it
+            res.setHeader('Access-Control-Allow-Origin', '*');
+        }
+        // If origin is not allowed, don't set CORS headers (browser will block)
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+        // Handle preflight requests
+        if (req.method === 'OPTIONS') {
+            return res.status(204).end();
+        }
+        return next();
+    });
     // this will apply middleware to all /api/llm/* routes
     app.use('/api/llm', expressRedactionMiddleware);
     app.use('/api/config.yaml', expressRedactionMiddleware);
@@ -80,7 +116,7 @@ export async function initializeApi(agent, agentCardOverride, listenPort, agentI
     function ensureAgentAvailable() {
         // Gate requests during agent switching
         if (isSwitchingAgent) {
-            throw AgentError.apiValidationError('Agent switch already in progress');
+            throw AgentError.switchInProgress();
         }
         // Fast path: most common case is agent is started and running
         if (activeAgent.isStarted() && !activeAgent.isStopped()) {
@@ -94,41 +130,103 @@ export async function initializeApi(agent, agentCardOverride, listenPort, agentI
             throw AgentError.notStarted();
         }
     }
+    /**
+     * Common agent switching logic shared by switchAgentById and switchAgentByPath.
+     * Handles: registering subscribers, starting agent, stopping previous agent, updating global state.
+     *
+     * @param newAgent The new DextoAgent instance to switch to
+     * @param agentId The identifier for the agent (used for logging and state tracking)
+     * @returns Agent info for the newly activated agent
+     */
+    async function performAgentSwitch(newAgent, agentId) {
+        // Register event subscribers with new agent before starting
+        logger.info('Registering event subscribers with new agent...');
+        newAgent.registerSubscriber(webSubscriber);
+        newAgent.registerSubscriber(webhookSubscriber);
+        logger.info(`Starting new agent: ${agentId}`);
+        await newAgent.start();
+        // Stop previous agent last (only after new one is fully operational)
+        const previousAgent = activeAgent;
+        activeAgent = newAgent;
+        activeAgentId = agentId;
+        // Update agent card for A2A and MCP routes
+        agentCardData = createAgentCard({
+            defaultName: agentId,
+            defaultVersion: overrides.version ?? '1.0.0',
+            defaultBaseUrl: baseApiUrl,
+            webSubscriber,
+        }, overrides);
+        logger.info(`Successfully switched to agent: ${agentId}`);
+        // Now safely stop the previous agent
+        try {
+            if (previousAgent && previousAgent !== newAgent) {
+                logger.info('Stopping previous agent...');
+                await previousAgent.stop();
+            }
+        }
+        catch (err) {
+            logger.warn(`Stopping previous agent failed: ${err}`);
+            // Don't throw here as the switch was successful
+        }
+        return await resolveAgentInfo(agentId);
+    }
     async function switchAgentById(agentId) {
         if (isSwitchingAgent) {
-            throw AgentError.apiValidationError('Agent switch already in progress');
+            throw AgentError.switchInProgress();
         }
         isSwitchingAgent = true;
         let newAgent;
         try {
-            // Use orchestrator to create new agent
-            newAgent = await getDexto().createAgent(agentId);
-            // Register event subscribers with new agent before starting
-            logger.info('Registering event subscribers with new agent...');
-            newAgent.registerSubscriber(webSubscriber);
-            newAgent.registerSubscriber(webhookSubscriber);
-            logger.info(`Starting new agent: ${agentId}`);
-            await newAgent.start();
-            // Stop previous agent last (only after new one is fully operational)
-            const previousAgent = activeAgent;
-            activeAgent = newAgent;
-            activeAgentId = agentId;
-            logger.info(`Successfully switched to agent: ${agentId}`);
-            // Now safely stop the previous agent
-            try {
-                if (previousAgent && previousAgent !== newAgent) {
-                    logger.info('Stopping previous agent...');
-                    await previousAgent.stop();
+            // 1. SHUTDOWN OLD TELEMETRY FIRST (before creating new agent)
+            // This allows new agent to have different telemetry config (endpoint, protocol, etc.)
+            logger.info('Shutting down telemetry for agent switch...');
+            const { Telemetry } = await import('@dexto/core');
+            await Telemetry.shutdownGlobal();
+            // 2. Create new agent from registry (will initialize fresh telemetry in createAgentServices)
+            newAgent = await Dexto.createAgent(agentId);
+            // 3. Use common switch logic (register subscribers, start agent, stop previous)
+            return await performAgentSwitch(newAgent, agentId);
+        }
+        catch (error) {
+            logger.error(`Failed to switch to agent '${agentId}': ${error instanceof Error ? error.message : String(error)}`, { error });
+            // Clean up the failed new agent if it was created
+            if (newAgent) {
+                try {
+                    await newAgent.stop();
+                }
+                catch (cleanupErr) {
+                    logger.warn(`Failed to cleanup new agent: ${cleanupErr}`);
                 }
             }
-            catch (err) {
-                logger.warn(`Stopping previous agent failed: ${err}`);
-                // Don't throw here as the switch was successful
-            }
-            return await resolveAgentInfo(agentId);
+            throw error;
+        }
+        finally {
+            isSwitchingAgent = false;
+        }
+    }
+    async function switchAgentByPath(filePath) {
+        if (isSwitchingAgent) {
+            throw AgentError.switchInProgress();
+        }
+        isSwitchingAgent = true;
+        let newAgent;
+        try {
+            // 1. SHUTDOWN OLD TELEMETRY FIRST (before creating new agent)
+            // This allows new agent to have different telemetry config (endpoint, protocol, etc.)
+            logger.info('Shutting down telemetry for agent switch...');
+            const { Telemetry } = await import('@dexto/core');
+            await Telemetry.shutdownGlobal();
+            // 2. Load agent configuration from file path
+            const config = await loadAgentConfig(filePath);
+            // 3. Create new agent instance directly (will initialize fresh telemetry in createAgentServices)
+            newAgent = new DextoAgent(config, filePath);
+            // 4. Derive agent ID from config or filename
+            const agentId = config.agentCard?.name || path.basename(filePath, path.extname(filePath));
+            // 5. Use common switch logic (register subscribers, start agent, stop previous)
+            return await performAgentSwitch(newAgent, agentId);
         }
         catch (error) {
-            logger.error(`Failed to switch to agent '${agentId}': ${error instanceof Error ? error.message : String(error)}`, { error });
+            logger.error(`Failed to switch to agent from path '${filePath}': ${error instanceof Error ? error.message : String(error)}`, { error });
             // Clean up the failed new agent if it was created
             if (newAgent) {
                 try {
@@ -587,6 +685,28 @@ export async function initializeApi(agent, agentCardOverride, listenPort, agentI
             return next(error);
         }
     });
+    // Endpoint to restart an MCP server
+    const RestartMcpServerParamsSchema = z.object({
+        serverId: z.string().min(1, 'Server ID is required'),
+    });
+    app.post('/api/mcp/servers/:serverId/restart', async (req, res, next) => {
+        try {
+            ensureAgentAvailable();
+            const { serverId } = parseQuery(RestartMcpServerParamsSchema, req.params);
+            logger.info(`Received request to POST /api/mcp/servers/${serverId}/restart`);
+            // Check if server exists before attempting to restart
+            const clientExists = activeAgent.getMcpClients().has(serverId);
+            if (!clientExists) {
+                logger.warn(`Attempted to restart non-existent server: ${serverId}`);
+                return res.status(404).json({ error: `Server '${serverId}' not found.` });
+            }
+            await activeAgent.restartMcpServer(serverId);
+            return res.status(200).json({ status: 'restarted', id: serverId });
+        }
+        catch (error) {
+            return next(error);
+        }
+    });
     // Execute an MCP tool via REST wrapper
     const ExecuteMcpToolParamsSchema = z.object({
         serverId: z.string().min(1, 'Server ID is required'),
@@ -878,7 +998,7 @@ export async function initializeApi(agent, agentCardOverride, listenPort, agentI
     const overrides = agentCardOverride ?? {};
     const resolvedPort = typeof listenPort === 'number' ? listenPort : Number(process.env.PORT || 3000);
     const baseApiUrl = process.env.DEXTO_BASE_URL || `http://localhost:${resolvedPort}`;
-    const agentCardData = createAgentCard({
+    let agentCardData = createAgentCard({
         defaultName: overrides.name ?? 'dexto',
         defaultVersion: overrides.version ?? '1.0.0',
         defaultBaseUrl: baseApiUrl,
@@ -887,19 +1007,15 @@ export async function initializeApi(agent, agentCardOverride, listenPort, agentI
     const _agentName = agentCardData.name;
     const _agentVersion = agentCardData.version;
     // Setup A2A routes
-    setupA2ARoutes(app, agentCardData);
+    setupA2ARoutes(app, () => agentCardData);
     // Setup Memory routes
-    app.use('/api/memory', setupMemoryRoutes(activeAgent));
+    app.use('/api/memory', setupMemoryRoutes(() => activeAgent));
     // --- Initialize and Setup MCP Server and Endpoints ---
     // Get transport type from environment variable or default to http
     try {
         const transportType = process.env.DEXTO_MCP_TRANSPORT_TYPE || 'http';
         const mcpTransport = await createMcpTransport(transportType);
-        // TODO: MCP server is bound to the initial agent; breaks after agent switch
-        // initializeMcpServer receives the original agent, so MCP endpoints keep talking to the stale instance post-switch.
-        // Make MCP consume the current agent via a getter to stay in sync.
-        await initializeMcpServer(agent, agentCardData, // Pass the agent card data for the MCP resource
-        mcpTransport);
+        await initializeMcpServer(() => activeAgent, () => agentCardData, mcpTransport);
         await initializeMcpServerApiEndpoints(app, mcpTransport);
     }
     catch (error) {
@@ -958,6 +1074,10 @@ export async function initializeApi(agent, agentCardOverride, listenPort, agentI
             .string()
             .min(1, 'Agent id is required')
             .describe('Unique agent identifier (e.g., "database-agent")'),
+        path: z
+            .string()
+            .optional()
+            .describe('Optional absolute file path for file-based agents (e.g., "/path/to/agent.yml")'),
     })
         .strict();
     const UninstallAgentSchema = z
@@ -1041,16 +1161,12 @@ export async function initializeApi(agent, agentCardOverride, listenPort, agentI
     });
     app.post('/api/agents/switch', express.json(), async (req, res, next) => {
         try {
-            const { id } = parseBody(AgentIdentifierSchema, req.body);
-            const result = await switchAgentById(id);
+            const { id, path } = parseBody(AgentIdentifierSchema, req.body);
+            // Route based on presence of path parameter
+            const result = path ? await switchAgentByPath(path) : await switchAgentById(id);
             return sendJsonResponse(res, { switched: true, ...result });
         }
         catch (error) {
-            if (error instanceof Error &&
-                error.message &&
-                error.message.includes('already in progress')) {
-                return res.status(409).json({ error: error.message });
-            }
             return next(error);
         }
     });

package/dist/api/websocket-subscriber.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"websocket-subscriber.d.ts","sourceRoot":"","sources":["../../src/api/websocket-subscriber.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAa,MAAM,IAAI,CAAC;AAEhD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7C;;GAEG;AACH,qBAAa,wBAAyB,YAAW,eAAe;IAIhD,OAAO,CAAC,GAAG;IAHvB,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,eAAe,CAAC,CAAkB;gBAEtB,GAAG,EAAE,eAAe;IAmBxC;;OAEG;IACH,SAAS,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI;IAqPxC;;OAEG;IACH,OAAO,IAAI,IAAI;IAiBf;;;OAGG;IACH,WAAW,IAAI,IAAI;IAYnB,OAAO,CAAC,SAAS;CAUpB"}
+{"version":3,"file":"websocket-subscriber.d.ts","sourceRoot":"","sources":["../../src/api/websocket-subscriber.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAa,MAAM,IAAI,CAAC;AAEhD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7C;;GAEG;AACH,qBAAa,wBAAyB,YAAW,eAAe;IAIhD,OAAO,CAAC,GAAG;IAHvB,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,eAAe,CAAC,CAAkB;gBAEtB,GAAG,EAAE,eAAe;IAmBxC;;OAEG;IACH,SAAS,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI;IA6PxC;;OAEG;IACH,OAAO,IAAI,IAAI;IAiBf;;;OAGG;IACH,WAAW,IAAI,IAAI;IAYnB,OAAO,CAAC,SAAS;CAUpB"}

package/dist/api/websocket-subscriber.js

@@ -70,6 +70,12 @@ export class WebSocketEventSubscriber {
             });
         }, { signal });
         eventBus.on('llmservice:toolResult', (payload) => {
+            logger.debug(`[websocket-subscriber]: llmservice:toolResult: ${JSON.stringify({
+                toolName: payload.toolName,
+                callId: payload.callId,
+                success: payload.success,
+                sessionId: payload.sessionId,
+            })}`);
             const data = {
                 toolName: payload.toolName,
                 callId: payload.callId,

package/dist/cli/commands/interactive-commands/model/model-commands.js

@@ -140,8 +140,8 @@ export const modelCommands = {
                 console.log(`  ${chalk.yellow('/model current')} - Display currently active model and configuration`);
                 console.log(`  ${chalk.yellow('/model switch')} ${chalk.blue('<model>')} - Switch to a different AI model (provider auto-detected)`);
                 console.log(`        Examples:`);
-                console.log(`          ${chalk.dim('/model switch gpt-4o')}`);
-                console.log(`          ${chalk.dim('/model switch claude-4-sonnet-20250514')}`);
+                console.log(`          ${chalk.dim('/model switch gpt-5')}`);
+                console.log(`          ${chalk.dim('/model switch claude-sonnet-4-5-20250929')}`);
                 console.log(`          ${chalk.dim('/model switch gemini-2.5-pro')}`);
                 console.log(`  ${chalk.yellow('/model help')} - Show this help message`);
                 console.log(chalk.dim('\n💡 Switching models allows you to use different AI capabilities'));

package/dist/cli/utils/options.js

@@ -13,9 +13,9 @@ export function validateCliOptions(opts) {
         agent: z.string().min(1, 'Agent name or path must not be empty').optional(),
         strict: z.boolean().optional().default(false),
         verbose: z.boolean().optional().default(true),
-        mode: z.enum(['cli', 'web', 'server', 'discord', 'telegram', 'mcp'], {
+        mode: z.enum(['web', 'cli', 'server', 'discord', 'telegram', 'mcp'], {
             errorMap: () => ({
-                message: 'Mode must be one of "cli", "web", "server", "discord", "telegram", or "mcp"',
+                message: 'Mode must be one of "web", "cli", "server", "discord", "telegram", or "mcp"',
             }),
         }),
         webPort: z.string().refine((val) => {

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';
@@ -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
@@ -409,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() !== '') {
@@ -456,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;
@@ -469,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;
@@ -536,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
@@ -551,6 +586,11 @@ program
         agent = new DextoAgent(validatedConfig, resolvedPath);
         // Start the agent (initialize async services)
         await agent.start();
+        // 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)
@@ -628,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
@@ -653,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');
@@ -706,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
@@ -716,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 }));

package/dist/webui/.next/standalone/.next/static/b_pyEEg2sitTwMzZWW7vE/_buildManifest.js

@@ -0,0 +1 @@
+self.__BUILD_MANIFEST=function(e,r,t,_){return{__rewrites:{afterFiles:[],beforeFiles:[],fallback:[]},__routerFilterStatic:{numItems:3,errorRate:1e-4,numBits:58,numHashes:14,bitArray:[1,1,e,e,0,e,e,0,r,e,r,e,r,e,e,e,r,e,e,e,r,r,e,r,r,r,r,r,e,e,e,e,e,e,r,e,e,r,e,e,r,r,e,r,e,r,r,e,e,e,r,r,r,r,e,r,r,e]},__routerFilterDynamic:{numItems:e,errorRate:1e-4,numBits:20,numHashes:14,bitArray:[r,r,r,r,e,e,e,r,e,e,r,r,r,r,e,r,r,e,e,e]},"/_error":["static/chunks/pages/_error-162d61367b59fad2.js"],sortedPages:["/_app","/_error"]}}(1,0,1e-4,14),self.__BUILD_MANIFEST_CB&&self.__BUILD_MANIFEST_CB();