dexto 1.0.1 → 1.1.0

package/dist/src/app/index.js

@@ -1,57 +1,181 @@
 #!/usr/bin/env node
+import {
+  getAgentRegistry
+} from "./chunk-UXCBS3TR.js";
+import {
+  createInitialPreferences,
+  globalPreferencesExist,
+  loadGlobalPreferences,
+  saveGlobalPreferences
+} from "./chunk-R4Q522DR.js";
 import {
   AgentConfigSchema,
+  ConfigError,
   DextoAgent,
-  DextoLLMError,
-  DextoValidationError,
-  FileNotFoundError,
   LLMUpdatesSchema,
   LLM_PROVIDERS,
   LLM_REGISTRY,
   MCPManager,
+  McpServerConfigSchema,
   NoOpConfirmationProvider,
-  UnknownModelError,
-  UnknownProviderError,
-  addScriptsToPackageJson,
-  checkForFileInCurrentDirectory,
   createAgentCard,
-  executeWithTimeout,
+  ensureDextoGlobalDirectory,
+  findDextoProjectRoot,
+  findDextoSourceRoot,
+  findPackageRoot,
   getAllSupportedModels,
-  getPackageManager,
-  getPackageManagerInstallCommand,
+  getDefaultModelForProvider,
+  getDextoEnvPath,
+  getDextoGlobalPath,
+  getDextoPath,
+  getExecutionContext,
+  getPrimaryApiKeyEnvVar,
   getProviderFromModel,
+  getSupportedModels,
   getSupportedProviders,
   getSupportedRoutersForProvider,
-  getUserInputToInitDextoApp,
-  initDexto,
+  isPath,
+  isValidProviderModel,
   jsonSchemaToZodShape,
   loadAgentConfig,
-  postInitDexto,
+  logger,
+  redactSensitiveData,
   resolveAndValidateMcpServerConfig,
   resolveApiKeyForProvider,
+  resolveBundledScript,
   supportsBaseURL,
-  validateInputForLLM
-} from "./chunk-M4OZIDPC.js";
+  toError,
+  validateInputForLLM,
+  zodToIssues
+} from "./chunk-CLDYRNV6.js";
+import "./chunk-PW2PHCHR.js";
+import "./chunk-DYNVXGAH.js";
 import {
-  ConfigurationError,
-  DEFAULT_CONFIG_PATH,
-  getDextoPath,
-  logger,
-  resolveBundledScript,
-  resolveConfigPath
-} from "./chunk-O5YHNFMH.js";
+  DextoValidationError
+} from "./chunk-X6LEX724.js";
+import {
+  DextoRuntimeError
+} from "./chunk-Y33BS5SA.js";
+
+// src/core/utils/env.ts
+import * as path from "path";
+import { homedir } from "os";
+import { promises as fs } from "fs";
+import dotenv from "dotenv";
+async function loadEnvironmentVariables(startPath = process.cwd()) {
+  const context = getExecutionContext(startPath);
+  const env = {};
+  const globalEnvPath = path.join(homedir(), ".dexto", ".env");
+  try {
+    const globalResult = dotenv.config({ path: globalEnvPath, processEnv: {} });
+    if (globalResult.parsed) {
+      Object.assign(env, globalResult.parsed);
+    }
+  } catch {
+  }
+  if (context === "dexto-source" || context === "dexto-project") {
+    const projectEnvPath = getDextoEnvPath(startPath);
+    try {
+      const projectResult = dotenv.config({ path: projectEnvPath, processEnv: {} });
+      if (projectResult.parsed) {
+        Object.assign(env, projectResult.parsed);
+      }
+    } catch {
+    }
+  }
+  for (const [key, value] of Object.entries(process.env)) {
+    if (value !== void 0 && value !== "") {
+      env[key] = value;
+    }
+  }
+  return env;
+}
+async function applyLayeredEnvironmentLoading(startPath = process.cwd()) {
+  await ensureDextoGlobalDirectory();
+  const layeredEnv = await loadEnvironmentVariables(startPath);
+  Object.assign(process.env, layeredEnv);
+}
+async function updateEnvFile(envFilePath, updates) {
+  const dextoEnvKeys = [
+    "OPENAI_API_KEY",
+    "ANTHROPIC_API_KEY",
+    "GOOGLE_GENERATIVE_AI_API_KEY",
+    "GROQ_API_KEY",
+    "DEXTO_LOG_LEVEL"
+  ];
+  await fs.mkdir(path.dirname(envFilePath), { recursive: true });
+  let envLines = [];
+  try {
+    const existingEnv = await fs.readFile(envFilePath, "utf8");
+    envLines = existingEnv.split("\n");
+  } catch {
+  }
+  const currentValues = {};
+  envLines.forEach((line) => {
+    const match = line.match(/^([A-Z0-9_]+)=(.*)$/);
+    if (match && match[1] && match[2] !== void 0 && dextoEnvKeys.includes(match[1])) {
+      currentValues[match[1]] = match[2];
+    }
+  });
+  const updatedValues = {
+    OPENAI_API_KEY: updates.OPENAI_API_KEY ?? currentValues.OPENAI_API_KEY ?? "",
+    ANTHROPIC_API_KEY: updates.ANTHROPIC_API_KEY ?? currentValues.ANTHROPIC_API_KEY ?? "",
+    GOOGLE_GENERATIVE_AI_API_KEY: updates.GOOGLE_GENERATIVE_AI_API_KEY ?? currentValues.GOOGLE_GENERATIVE_AI_API_KEY ?? "",
+    GROQ_API_KEY: updates.GROQ_API_KEY ?? currentValues.GROQ_API_KEY ?? "",
+    DEXTO_LOG_LEVEL: updates.DEXTO_LOG_LEVEL ?? currentValues.DEXTO_LOG_LEVEL ?? "info"
+  };
+  const sectionHeader = "## Dexto env variables";
+  const headerIndex = envLines.findIndex((line) => line.trim() === sectionHeader);
+  let contentLines;
+  if (headerIndex !== -1) {
+    const beforeSection = envLines.slice(0, headerIndex);
+    let sectionEnd = headerIndex + 1;
+    while (sectionEnd < envLines.length && envLines[sectionEnd]?.trim() !== "") {
+      sectionEnd++;
+    }
+    if (sectionEnd < envLines.length && envLines[sectionEnd]?.trim() === "") {
+      sectionEnd++;
+    }
+    const afterSection = envLines.slice(sectionEnd);
+    contentLines = [...beforeSection, ...afterSection];
+  } else {
+    contentLines = envLines;
+  }
+  const existingEnvVars = {};
+  contentLines.forEach((line) => {
+    const match = line.match(/^([A-Z0-9_]+)=(.*)$/);
+    if (match && match[1] && match[2] !== void 0 && dextoEnvKeys.includes(match[1])) {
+      existingEnvVars[match[1]] = match[2];
+    }
+  });
+  if (contentLines.length > 0) {
+    if (contentLines[contentLines.length - 1]?.trim() !== "") {
+      contentLines.push("");
+    }
+  } else {
+    contentLines.push("");
+  }
+  contentLines.push(sectionHeader);
+  for (const key of dextoEnvKeys) {
+    if (key in existingEnvVars && !(key in updates)) {
+      continue;
+    }
+    contentLines.push(`${key}=${updatedValues[key]}`);
+  }
+  contentLines.push("");
+  await fs.writeFile(envFilePath, contentLines.join("\n"), "utf8");
+}
 
 // src/app/index.ts
-import dotenv3 from "dotenv";
-import { existsSync as existsSync2 } from "fs";
+import { existsSync as existsSync4 } from "fs";
 import { Command } from "commander";
-import * as p2 from "@clack/prompts";
-import chalk15 from "chalk";
+import * as p6 from "@clack/prompts";
+import chalk23 from "chalk";
 
 // package.json
 var package_default = {
   name: "dexto",
-  version: "1.0.1",
+  version: "1.1.0",
   engines: {
     node: ">=20.0.0",
     npm: ">=8.3.0"
@@ -107,27 +231,35 @@ var package_default = {
     "cli",
     "natural-language",
     "openai",
-    "truffle-ai"
+    "truffle-ai",
+    "dexto"
   ],
   author: "",
   license: "Elastic-2.0",
   files: [
     "dist/",
-    "agents/agent.yml",
+    "agents/agent-registry.json",
     "agents/agent-template.yml",
+    "agents/default-agent.yml",
+    "agents/database-agent/",
+    "agents/talk2pdf-agent/",
+    "agents/image-editor-agent/",
+    "agents/music-agent/",
+    "agents/product-name-researcher/",
+    "agents/triage-demo/",
     "public/"
   ],
   dependencies: {
-    "@ai-sdk/anthropic": "^1.2.2",
-    "@ai-sdk/cohere": "^1.2.10",
-    "@ai-sdk/google": "^1.2.8",
-    "@ai-sdk/groq": "^1.2.9",
-    "@ai-sdk/openai": "^1.3.3",
-    "@ai-sdk/xai": "^1.2.17",
+    "@ai-sdk/anthropic": "^2.0.0",
+    "@ai-sdk/cohere": "^2.0.0",
+    "@ai-sdk/google": "^2.0.0",
+    "@ai-sdk/groq": "^2.0.0",
+    "@ai-sdk/openai": "^2.0.0",
+    "@ai-sdk/xai": "^2.0.0",
     "@anthropic-ai/sdk": "^0.39.0",
     "@clack/prompts": "^0.10.1",
-    "@modelcontextprotocol/sdk": "^1.11.0",
-    ai: "^4.2.6",
+    "@modelcontextprotocol/sdk": "^1.17.2",
+    ai: "^5.0.0",
     "better-sqlite3": "^11.10.0",
     boxen: "^7.1.1",
     chalk: "^5.4.1",
@@ -150,7 +282,7 @@ var package_default = {
     winston: "^3.17.0",
     ws: "^8.18.1",
     yaml: "^2.7.1",
-    zod: "^3.24.3",
+    zod: "^3.25.0",
     "zod-to-json-schema": "^3.24.6"
   },
   devDependencies: {
@@ -186,25 +318,100 @@ var package_default = {
   }
 };
 
-// src/app/config/cli-overrides.ts
-function applyCLIOverrides(baseConfig, cliOverrides) {
-  if (!cliOverrides) {
-    return AgentConfigSchema.parse(baseConfig);
+// src/core/config/agent-resolver.ts
+import { promises as fs2 } from "fs";
+import path2 from "path";
+async function resolveAgentPath(nameOrPath, autoInstall = true, injectPreferences = true) {
+  if (nameOrPath && isPath(nameOrPath)) {
+    const resolved = path2.resolve(nameOrPath);
+    try {
+      const stat = await fs2.stat(resolved);
+      if (!stat.isFile()) {
+        throw ConfigError.fileNotFound(resolved);
+      }
+      return resolved;
+    } catch {
+      throw ConfigError.fileNotFound(resolved);
+    }
   }
-  const mergedConfig = JSON.parse(JSON.stringify(baseConfig));
-  if (cliOverrides.provider) {
-    mergedConfig.llm.provider = cliOverrides.provider;
+  if (nameOrPath) {
+    const { getAgentRegistry: getAgentRegistry2 } = await import("./registry-RALMVM3P.js");
+    const registry = getAgentRegistry2();
+    return await registry.resolveAgent(nameOrPath, autoInstall, injectPreferences);
   }
-  if (cliOverrides.model) {
-    mergedConfig.llm.model = cliOverrides.model;
+  return await resolveDefaultAgentByContext(autoInstall, injectPreferences);
+}
+async function resolveDefaultAgentByContext(autoInstall = true, injectPreferences = true) {
+  const executionContext = getExecutionContext();
+  switch (executionContext) {
+    case "dexto-source":
+      return await resolveDefaultAgentForDextoSource();
+    case "dexto-project":
+      return await resolveDefaultAgentForDextoProject(autoInstall, injectPreferences);
+    case "global-cli":
+      return await resolveDefaultAgentForGlobalCLI(autoInstall, injectPreferences);
+    default:
+      throw ConfigError.unknownContext(executionContext);
   }
-  if (cliOverrides.router) {
-    mergedConfig.llm.router = cliOverrides.router;
+}
+async function resolveDefaultAgentForDextoSource() {
+  logger.debug("Resolving default agent for dexto source context");
+  const sourceRoot = findDextoSourceRoot();
+  if (!sourceRoot) {
+    throw ConfigError.bundledNotFound("dexto source directory not found");
   }
-  if (cliOverrides.apiKey) {
-    mergedConfig.llm.apiKey = cliOverrides.apiKey;
+  const bundledPath = path2.join(sourceRoot, "agents", "default-agent.yml");
+  try {
+    await fs2.access(bundledPath);
+    return bundledPath;
+  } catch {
+    throw ConfigError.bundledNotFound(bundledPath);
+  }
+}
+async function resolveDefaultAgentForDextoProject(autoInstall = true, injectPreferences = true) {
+  logger.debug("Resolving default agent for dexto project context");
+  const projectRoot = findDextoProjectRoot();
+  if (!projectRoot) {
+    throw ConfigError.unknownContext("dexto-project: project root not found");
+  }
+  const candidatePaths = [
+    path2.join(projectRoot, "default-agent.yml"),
+    path2.join(projectRoot, "agents", "default-agent.yml"),
+    path2.join(projectRoot, "src", "dexto", "agents", "default-agent.yml")
+  ];
+  for (const p7 of candidatePaths) {
+    try {
+      await fs2.access(p7);
+      return p7;
+    } catch {
+    }
+  }
+  logger.debug(`No project-local default-agent.yml found in ${projectRoot}`);
+  if (!globalPreferencesExist()) {
+    throw ConfigError.noProjectDefault(projectRoot);
+  }
+  const preferences = await loadGlobalPreferences();
+  if (!preferences.setup.completed) {
+    throw ConfigError.setupIncomplete();
   }
-  return AgentConfigSchema.parse(mergedConfig);
+  const preferredAgentName = preferences.defaults.defaultAgent;
+  const { getAgentRegistry: getAgentRegistry2 } = await import("./registry-RALMVM3P.js");
+  const registry = getAgentRegistry2();
+  return await registry.resolveAgent(preferredAgentName, autoInstall, injectPreferences);
+}
+async function resolveDefaultAgentForGlobalCLI(autoInstall = true, injectPreferences = true) {
+  logger.debug("Resolving default agent for global CLI context");
+  if (!globalPreferencesExist()) {
+    throw ConfigError.noGlobalPreferences();
+  }
+  const preferences = await loadGlobalPreferences();
+  if (!preferences.setup.completed) {
+    throw ConfigError.setupIncomplete();
+  }
+  const preferredAgentName = preferences.defaults.defaultAgent;
+  const { getAgentRegistry: getAgentRegistry2 } = await import("./registry-RALMVM3P.js");
+  const registry = getAgentRegistry2();
+  return await registry.resolveAgent(preferredAgentName, autoInstall, injectPreferences);
 }
 
 // src/app/cli/cli.ts
@@ -219,7 +426,11 @@ var CLISubscriber = class {
   currentLines = 0;
   subscribe(eventBus) {
     eventBus.on("llmservice:thinking", this.onThinking.bind(this));
-    eventBus.on("llmservice:chunk", (payload) => this.onChunk(payload.content));
+    eventBus.on("llmservice:chunk", (payload) => {
+      if (payload.type === "text") {
+        this.onChunk(payload.content);
+      }
+    });
     eventBus.on(
       "llmservice:toolCall",
       (payload) => this.onToolCall(payload.toolName, payload.args)
@@ -248,8 +459,8 @@ var CLISubscriber = class {
   onThinking() {
     logger.info("AI thinking...", null, "yellow");
   }
-  onChunk(text2) {
-    this.accumulatedResponse += text2;
+  onChunk(text3) {
+    this.accumulatedResponse += text3;
     const box = boxen(chalk.white(this.accumulatedResponse), {
       padding: 1,
       borderColor: "yellow",
@@ -270,15 +481,28 @@ var CLISubscriber = class {
   onToolResult(toolName, result) {
     logger.toolResult(result);
   }
-  onResponse(text2) {
+  onResponse(text3) {
     this.accumulatedResponse = "";
     this.currentLines = 0;
-    logger.displayAIResponse({ content: text2 });
+    logger.displayAIResponse({ content: text3 });
   }
   onError(error) {
     this.accumulatedResponse = "";
     this.currentLines = 0;
-    logger.error(`\u274C Error: ${error.message}`, null, "red");
+    logger.displayError(error.message, error);
+    if (logger.getLevel() === "debug") {
+      logger.error(
+        `\u274C Error: ${error.message}`,
+        {
+          stack: error.stack,
+          name: error.name,
+          cause: error.cause
+        },
+        "red"
+      );
+    } else {
+      logger.error(`\u274C Error: ${error.message}`, null, "red");
+    }
   }
   onConversationReset() {
     this.accumulatedResponse = "";
@@ -287,7 +511,7 @@ var CLISubscriber = class {
   }
 };
 
-// src/app/cli/interactive-commands/command-parser.ts
+// src/app/cli/commands/interactive-commands/command-parser.ts
 import chalk2 from "chalk";
 function parseQuotedArguments(input) {
   const args = [];
@@ -401,7 +625,7 @@ function displayAllCommands(commands) {
   console.log(chalk2.dim("\u{1F4A1} Tip: Type your message normally (without /) to chat with the AI\n"));
 }
 
-// src/app/cli/interactive-commands/general-commands.ts
+// src/app/cli/commands/interactive-commands/general-commands.ts
 import chalk3 from "chalk";
 function createHelpCommand(getAllCommands) {
   return {
@@ -490,10 +714,10 @@ var generalCommands = [
   }
 ];
 
-// src/app/cli/interactive-commands/session/session-commands.ts
+// src/app/cli/commands/interactive-commands/session/session-commands.ts
 import chalk5 from "chalk";
 
-// src/app/cli/interactive-commands/session/helpers/formatters.ts
+// src/app/cli/commands/interactive-commands/session/helpers/formatters.ts
 import chalk4 from "chalk";
 function formatSessionInfo(sessionId, metadata, isCurrent = false) {
   const prefix = isCurrent ? chalk4.green("\u2192") : " ";
@@ -557,7 +781,7 @@ function formatHistoryMessage(message, index) {
   return `  ${chalk4.dim(timestamp)} ${roleColor.bold(displayLabel)}: ${content}${toolInfo}`;
 }
 
-// src/app/cli/interactive-commands/session/session-commands.ts
+// src/app/cli/commands/interactive-commands/session/session-commands.ts
 async function getCurrentSessionInfo(agent) {
   const currentId = agent.getCurrentSessionId();
   const metadata = await agent.getSessionMetadata(currentId);
@@ -603,13 +827,30 @@ var sessionCommand = {
             );
             return true;
           }
-          for (const sessionId of sessionIds) {
-            const metadata = await agent.getSessionMetadata(sessionId);
-            const isCurrent = sessionId === current.id;
-            console.log("  " + formatSessionInfo(sessionId, metadata, isCurrent));
+          const entries = await Promise.all(
+            sessionIds.map(async (id) => {
+              try {
+                const metadata = await agent.getSessionMetadata(id);
+                return { id, metadata };
+              } catch (e) {
+                logger.error(
+                  `Failed to fetch metadata for session ${id}: ${e instanceof Error ? e.message : String(e)}`
+                );
+                return { id, metadata: void 0 };
+              }
+            })
+          );
+          let displayed = 0;
+          for (const { id, metadata } of entries) {
+            if (!metadata) continue;
+            const isCurrent = id === current.id;
+            console.log(`  ${formatSessionInfo(id, metadata, isCurrent)}`);
+            displayed++;
           }
-          console.log(chalk5.dim(`
-  Total: ${sessionIds.length} sessions`));
+          console.log(
+            chalk5.dim(`
+  Total: ${displayed} of ${sessionIds.length} sessions`)
+          );
           console.log(chalk5.dim("  \u{1F4A1} Use /session switch <id> to change sessions\n"));
         } catch (error) {
           logger.error(
@@ -919,10 +1160,10 @@ var searchCommand = {
   }
 };
 
-// src/app/cli/interactive-commands/session/index.ts
+// src/app/cli/commands/interactive-commands/session/index.ts
 var sessionCommands = [sessionCommand, historyCommand, searchCommand];
 
-// src/app/cli/interactive-commands/model/model-commands.ts
+// src/app/cli/commands/interactive-commands/model/model-commands.ts
 import chalk6 from "chalk";
 var modelCommands = {
   name: "model",
@@ -1016,20 +1257,21 @@ var modelCommands = {
           await agent.switchLLM(llmConfig);
           console.log(chalk6.green(`\u2705 Successfully switched to ${model} (${provider})`));
         } catch (error) {
-          if (error instanceof DextoLLMError) {
+          if (error instanceof DextoRuntimeError) {
             console.log(chalk6.red("\u274C Failed to switch model:"));
-            const errors = error.issues.filter((issue) => issue.severity === "error");
-            for (const err of errors) {
-              console.log(chalk6.red(`   ${err.message}`));
-            }
-            const warnings = error.issues.filter(
-              (issue) => issue.severity === "warning"
-            );
-            if (warnings.length > 0) {
-              for (const warning of warnings) {
-                console.log(chalk6.yellow(`\u26A0\uFE0F  ${warning.message}`));
+            console.log(chalk6.red(`   ${error.message}`));
+            console.log(chalk6.dim(`   Code: ${error.code}`));
+            if (error.recovery) {
+              const recoverySteps = Array.isArray(error.recovery) ? error.recovery : [error.recovery];
+              for (const step of recoverySteps) {
+                console.log(chalk6.blue(`\u{1F4A1} ${step}`));
               }
             }
+          } else if (error instanceof DextoValidationError) {
+            console.log(chalk6.red("\u274C Validation failed:"));
+            error.errors.forEach((err) => {
+              console.log(chalk6.red(`   - ${err.message}`));
+            });
           } else {
             logger.error(
               `Failed to switch model: ${error instanceof Error ? error.message : String(error)}`
@@ -1091,10 +1333,10 @@ var modelCommands = {
   }
 };
 
-// src/app/cli/interactive-commands/mcp/mcp-commands.ts
+// src/app/cli/commands/interactive-commands/mcp/mcp-commands.ts
 import chalk8 from "chalk";
 
-// src/app/cli/interactive-commands/utils/arg-parser.ts
+// src/app/cli/commands/interactive-commands/utils/arg-parser.ts
 function parseOptions(args) {
   const parsedArgs = [];
   const options = {};
@@ -1116,7 +1358,7 @@ function parseOptions(args) {
   return { parsedArgs, options, flags };
 }
 
-// src/app/cli/interactive-commands/mcp/mcp-add-utils.ts
+// src/app/cli/commands/interactive-commands/mcp/mcp-add-utils.ts
 import chalk7 from "chalk";
 function parseStdioArgs(args) {
   const errors = [];
@@ -1276,7 +1518,7 @@ function validateAndShowErrors(serverName, config, existingServers = []) {
   return true;
 }
 
-// src/app/cli/interactive-commands/mcp/mcp-commands.ts
+// src/app/cli/commands/interactive-commands/mcp/mcp-commands.ts
 async function handleMcpAddStdio(args, agent) {
   const { serverName, config, errors } = parseStdioArgs(args);
   if (errors.length > 0) {
@@ -1555,7 +1797,7 @@ var mcpCommands = {
   }
 };
 
-// src/app/cli/interactive-commands/system/system-commands.ts
+// src/app/cli/commands/interactive-commands/system/system-commands.ts
 import chalk9 from "chalk";
 var systemCommands = [
   {
@@ -1670,7 +1912,7 @@ Current log level: ${chalk9.cyan(logger.getLevel())}`));
   }
 ];
 
-// src/app/cli/interactive-commands/tool-commands.ts
+// src/app/cli/commands/interactive-commands/tool-commands.ts
 import chalk10 from "chalk";
 var toolCommands = [
   {
@@ -1718,7 +1960,7 @@ var toolCommands = [
   }
 ];
 
-// src/app/cli/interactive-commands/prompt-commands.ts
+// src/app/cli/commands/interactive-commands/prompt-commands.ts
 import chalk11 from "chalk";
 var promptCommands = [
   {
@@ -1744,7 +1986,7 @@ var promptCommands = [
   }
 ];
 
-// src/app/cli/interactive-commands/documentation-commands.ts
+// src/app/cli/commands/interactive-commands/documentation-commands.ts
 import chalk12 from "chalk";
 var documentationCommands = [
   {
@@ -1754,29 +1996,25 @@ var documentationCommands = [
     category: "Documentation",
     aliases: ["doc"],
     handler: async (_args, _agent) => {
+      const docsUrl = "https://docs.dexto.ai/category/getting-started/";
       try {
-        const { spawn: spawn2 } = await import("child_process");
-        const url = "https://truffle-ai.github.io/dexto/docs/category/getting-started/";
-        console.log(chalk12.blue(`\u{1F310} Opening Dexto documentation: ${url}`));
+        const { spawn: spawn3 } = await import("child_process");
+        console.log(chalk12.blue(`\u{1F310} Opening Dexto documentation: ${docsUrl}`));
         const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-        spawn2(command, [url], { detached: true, stdio: "ignore" });
+        spawn3(command, [docsUrl], { detached: true, stdio: "ignore" });
         console.log(chalk12.green("\u2705 Documentation opened in browser"));
       } catch (error) {
         logger.error(
           `Failed to open documentation: ${error instanceof Error ? error.message : String(error)}`
         );
-        console.log(
-          chalk12.yellow(
-            "\u{1F4A1} You can manually visit: https://truffle-ai.github.io/dexto/docs/category/getting-started/"
-          )
-        );
+        console.log(chalk12.yellow(`\u{1F4A1} You can manually visit: ${docsUrl}`));
       }
       return true;
     }
   }
 ];
 
-// src/app/cli/interactive-commands/commands.ts
+// src/app/cli/commands/interactive-commands/commands.ts
 var CLI_COMMANDS = [];
 var baseCommands = [
   // General commands (without help)
@@ -1893,25 +2131,48 @@ async function loadMostRecentSession(agent) {
 async function _initCli(agent) {
   await loadMostRecentSession(agent);
   registerGracefulShutdown(agent);
-  logger.debug(`Log level: ${logger.getLevel()}`);
-  logger.info(`Connected servers: ${agent.mcpManager.getClients().size}`, null, "green");
+  const llmConfig = agent.getCurrentLLMConfig();
+  const connectedServers = agent.mcpManager.getClients();
   const failedConnections = agent.mcpManager.getFailedConnections();
+  const currentSessionId = agent.getCurrentSessionId();
+  let toolStats;
+  try {
+    toolStats = await agent.toolManager.getToolStats();
+  } catch (error) {
+    logger.error(
+      `Failed to load tools: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  const startupInfo = {
+    model: llmConfig.model,
+    provider: llmConfig.provider,
+    connectedServers: {
+      count: connectedServers.size,
+      names: Array.from(connectedServers.keys())
+    },
+    sessionId: currentSessionId,
+    logLevel: logger.getLevel()
+  };
   if (Object.keys(failedConnections).length > 0) {
-    logger.error(`Failed connections: ${Object.keys(failedConnections).length}.`, null, "red");
+    startupInfo.failedConnections = failedConnections;
+  }
+  if (toolStats) {
+    startupInfo.toolStats = toolStats;
   }
+  const logFile = logger.getLogFilePath();
+  if (logFile) {
+    startupInfo.logFile = logFile;
+  }
+  logger.displayStartupInfo(startupInfo);
+  logger.debug(`Startup configuration: ${JSON.stringify(startupInfo, null, 2)}`);
   logger.info("Setting up CLI event subscriptions...");
   const cliSubscriber = new CLISubscriber();
   cliSubscriber.subscribe(agent.agentEventBus);
   logger.info("Loading available tools...");
-  try {
-    const toolStats = await agent.toolManager.getToolStats();
+  if (toolStats) {
     logger.info(
       `Loaded ${toolStats.total} total tools: ${toolStats.mcp} MCP, ${toolStats.internal} internal`
     );
-  } catch (error) {
-    logger.error(
-      `Failed to load tools: ${error instanceof Error ? error.message : String(error)}`
-    );
   }
   logger.info(`CLI initialized successfully. Ready for input.`, null, "green");
   console.log(chalk13.bold.cyan("\n\u{1F680} Welcome to Dexto CLI!"));
@@ -1999,11 +2260,14 @@ async function startHeadlessCli(agent, prompt) {
       await agent.run(prompt);
     }
   } catch (error) {
-    if (error instanceof UnknownProviderError) {
-      logger.error(`Provider error: ${error.message}`, null, "red");
-    } else if (error instanceof UnknownModelError) {
-      logger.error(`Model error: ${error.message}`, null, "red");
-    } else if (error instanceof ConfigurationError) {
+    if (error instanceof DextoRuntimeError && error.code === "llm_model_unknown" /* MODEL_UNKNOWN */) {
+      logger.error(`LLM error: ${error.message}`, null, "red");
+    } else if (error instanceof DextoValidationError) {
+      logger.error(`Validation failed:`, null, "red");
+      error.errors.forEach((err) => {
+        logger.error(`  - ${err.message}`, null, "red");
+      });
+    } else if (error instanceof DextoRuntimeError && error.scope === "config" /* CONFIG */) {
       logger.error(`Configuration error: ${error.message}`, null, "red");
     } else {
       logger.error(
@@ -2063,7 +2327,8 @@ var WebSocketEventSubscriber = class {
         this.broadcast({
           event: "chunk",
           data: {
-            text: payload.content,
+            type: payload.type,
+            content: payload.content,
             isComplete: payload.isComplete,
             sessionId: payload.sessionId
           }
@@ -2105,12 +2370,17 @@ var WebSocketEventSubscriber = class {
     eventBus.on(
       "llmservice:response",
       (payload) => {
+        logger.debug(
+          `[websocket-subscriber]: llmservice:response: ${JSON.stringify(payload)}`
+        );
         this.broadcast({
           event: "response",
           data: {
             text: payload.content,
-            tokenCount: payload.tokenCount,
+            reasoning: payload.reasoning,
+            tokenUsage: payload.tokenUsage,
             model: payload.model,
+            router: payload.router,
             sessionId: payload.sessionId
           }
         });
@@ -2356,10 +2626,10 @@ var WebhookEventSubscriber = class {
       });
     };
     if (process.env.NODE_ENV === "test") {
-      const results = await Promise.allSettled(deliveryPromises.map((p3) => p3.promise));
+      const results = await Promise.allSettled(deliveryPromises.map((p7) => p7.promise));
       handleSettled(results);
     } else {
-      Promise.allSettled(deliveryPromises.map((p3) => p3.promise)).then(handleSettled);
+      Promise.allSettled(deliveryPromises.map((p7) => p7.promise)).then(handleSettled);
     }
   }
   /**
@@ -2517,11 +2787,11 @@ async function initializeMcpServer(agent, agentCardData, mcpTransport) {
       logger.info(
         `MCP tool '${toolName}' received message: ${message.substring(0, 100)}${message.length > 100 ? "..." : ""}`
       );
-      const text2 = await agent.run(message);
+      const text3 = await agent.run(message);
       logger.info(
-        `MCP tool '${toolName}' sending response: ${text2?.substring(0, 100)}${(text2?.length ?? 0) > 100 ? "..." : ""}`
+        `MCP tool '${toolName}' sending response: ${text3?.substring(0, 100)}${(text3?.length ?? 0) > 100 ? "..." : ""}`
       );
-      return { content: [{ type: "text", text: text2 ?? "" }] };
+      return { content: [{ type: "text", text: text3 ?? "" }] };
     }
   );
   logger.info(
@@ -2579,57 +2849,6 @@ async function initializeMcpServerApiEndpoints(app, mcpTransport) {
 import { stringify as yamlStringify } from "yaml";
 import os from "os";
 
-// src/app/api/middleware/redactor.ts
-var SENSITIVE_FIELDS = [
-  "apikey",
-  "api_key",
-  "token",
-  "access_token",
-  "refresh_token",
-  "password",
-  "secret"
-];
-var SENSITIVE_PATTERNS = [
-  /\bsk-[A-Za-z0-9]{20,}\b/g,
-  // OpenAI API keys (at least 20 chars after sk-)
-  /\bBearer\s+[A-Za-z0-9\-_.=]+\b/gi,
-  // Bearer tokens
-  /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,
-  // Emails
-  /\beyJ[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*/g
-  // JWT tokens
-];
-var REDACTED = "[REDACTED]";
-var REDACTED_CIRCULAR = "[REDACTED_CIRCULAR]";
-function redactSensitiveData(input, seen = /* @__PURE__ */ new WeakSet()) {
-  if (typeof input === "string") {
-    let result = input;
-    for (const pattern of SENSITIVE_PATTERNS) {
-      result = result.replace(pattern, REDACTED);
-    }
-    return result;
-  }
-  if (Array.isArray(input)) {
-    if (seen.has(input)) return REDACTED_CIRCULAR;
-    seen.add(input);
-    return input.map((item) => redactSensitiveData(item, seen));
-  }
-  if (input && typeof input === "object") {
-    if (seen.has(input)) return REDACTED_CIRCULAR;
-    seen.add(input);
-    const result = {};
-    for (const [key, value] of Object.entries(input)) {
-      if (SENSITIVE_FIELDS.includes(key.toLowerCase())) {
-        result[key] = REDACTED;
-      } else {
-        result[key] = redactSensitiveData(value, seen);
-      }
-    }
-    return result;
-  }
-  return input;
-}
-
 // src/app/api/middleware/expressRedactionMiddleware.ts
 function expressRedactionMiddleware(req, res, next) {
   const originalJson = res.json.bind(res);
@@ -2649,6 +2868,136 @@ function expressRedactionMiddleware(req, res, next) {
 
 // src/app/api/server.ts
 import { z as z2 } from "zod";
+
+// src/app/api/middleware/errorHandler.ts
+import { ZodError } from "zod";
+var mapErrorTypeToStatus = (type) => {
+  switch (type) {
+    case "user" /* USER */:
+      return 400;
+    case "not_found" /* NOT_FOUND */:
+      return 404;
+    case "forbidden" /* FORBIDDEN */:
+      return 403;
+    case "timeout" /* TIMEOUT */:
+      return 408;
+    case "rate_limit" /* RATE_LIMIT */:
+      return 429;
+    case "system" /* SYSTEM */:
+      return 500;
+    case "third_party" /* THIRD_PARTY */:
+      return 502;
+    case "unknown" /* UNKNOWN */:
+    default:
+      return 500;
+  }
+};
+var statusForValidation = (issues) => {
+  const firstError = issues.find((i) => i.severity === "error");
+  const type = firstError?.type ?? "user" /* USER */;
+  return mapErrorTypeToStatus(type);
+};
+function errorHandler(err, _req, res, _next) {
+  if (err instanceof DextoRuntimeError) {
+    const status = mapErrorTypeToStatus(err.type);
+    res.status(status).json(err.toJSON());
+    return;
+  }
+  if (err instanceof DextoValidationError) {
+    const status = statusForValidation(err.issues);
+    res.status(status).json(err.toJSON());
+    return;
+  }
+  if (err instanceof ZodError) {
+    const issues = zodToIssues(err);
+    const dexErr = new DextoValidationError(issues);
+    const status = statusForValidation(issues);
+    res.status(status).json(dexErr.toJSON());
+    return;
+  }
+  const errorMessage = err instanceof Error ? err.message : String(err);
+  const errorStack = err instanceof Error ? err.stack : void 0;
+  logger.error(`Unhandled error in API middleware: ${errorMessage}`, {
+    error: err,
+    stack: errorStack,
+    type: typeof err
+  });
+  res.status(500).json({
+    code: "internal_error",
+    message: "An unexpected error occurred",
+    scope: "system",
+    type: "system",
+    severity: "error"
+  });
+}
+
+// src/app/api/websocket-error-handler.ts
+import { ZodError as ZodError2 } from "zod";
+function sendWebSocketError(ws, error) {
+  let errorData;
+  if (error instanceof DextoRuntimeError) {
+    errorData = error.toJSON();
+  } else if (error instanceof DextoValidationError) {
+    errorData = error.toJSON();
+  } else if (error instanceof ZodError2) {
+    const issues = zodToIssues(error);
+    const dexErr = new DextoValidationError(issues);
+    errorData = dexErr.toJSON();
+  } else {
+    const errorObj = toError(error);
+    const errorStack = error instanceof Error ? error.stack : void 0;
+    logger.error(`Unhandled WebSocket error: ${errorObj.message}`, {
+      error,
+      stack: errorStack,
+      type: typeof error
+    });
+    errorData = {
+      code: "internal_error",
+      message: errorObj.message,
+      scope: "agent" /* AGENT */,
+      type: "system" /* SYSTEM */,
+      severity: "error"
+    };
+  }
+  try {
+    ws.send(
+      JSON.stringify({
+        event: "error",
+        data: errorData
+      })
+    );
+  } catch (sendErr) {
+    const msg = sendErr instanceof Error ? sendErr.message : String(sendErr);
+    logger.error(`Failed to send WebSocket error frame: ${msg}`, { errorData });
+  }
+}
+function sendWebSocketValidationError(ws, message, context) {
+  const dexErr = new DextoValidationError([
+    {
+      code: "agent_api_validation_error" /* API_VALIDATION_ERROR */,
+      message,
+      scope: "agent" /* AGENT */,
+      type: "user" /* USER */,
+      severity: "error",
+      context
+    }
+  ]);
+  const data = dexErr.toJSON();
+  logger.error(`Sending WebSocket validation error: ${message}`, { data });
+  try {
+    ws.send(
+      JSON.stringify({
+        event: "error",
+        data
+      })
+    );
+  } catch (sendErr) {
+    const msg = sendErr instanceof Error ? sendErr.message : String(sendErr);
+    logger.error(`Failed to send WebSocket validation error: ${msg}`, { data });
+  }
+}
+
+// src/app/api/server.ts
 function sendJsonResponse(res, data, statusCode = 200) {
   const pretty = res.req.query.pretty === "true" || res.req.query.pretty === "1";
   res.status(statusCode);
@@ -2659,27 +3008,47 @@ function sendJsonResponse(res, data, statusCode = 200) {
     res.json(data);
   }
 }
-var LLMSwitchRequestSchema = z2.object({
-  sessionId: z2.string().optional()
-}).merge(LLMUpdatesSchema);
-function validateBody(schema, body) {
-  const result = schema.safeParse(body);
-  if (!result.success) {
-    return {
-      success: false,
-      response: {
-        ok: false,
-        issues: result.error.errors.map((err) => ({
-          code: "schema_validation",
-          message: err.message,
-          path: err.path,
-          severity: "error",
-          context: { field: err.path.join(".") }
-        }))
-      }
-    };
-  }
-  return { success: true, data: result.data };
+var MessageRequestSchema = z2.object({
+  message: z2.string().optional(),
+  sessionId: z2.string().optional(),
+  stream: z2.boolean().optional(),
+  imageData: z2.object({
+    base64: z2.string(),
+    mimeType: z2.string()
+  }).optional(),
+  fileData: z2.object({
+    base64: z2.string(),
+    mimeType: z2.string(),
+    filename: z2.string().optional()
+  }).optional()
+}).refine(
+  (data) => {
+    const msg = (data.message ?? "").trim();
+    return msg.length > 0 || !!data.imageData || !!data.fileData;
+  },
+  { message: "Must provide either message text, image data, or file data" }
+);
+var McpServerRequestSchema = z2.object({
+  name: z2.string().min(1, "Server name is required"),
+  config: McpServerConfigSchema
+});
+var WebhookRequestSchema = z2.object({
+  url: z2.string().url("Invalid URL format"),
+  secret: z2.string().optional(),
+  description: z2.string().optional()
+});
+var SearchQuerySchema = z2.object({
+  q: z2.string().min(1, "Search query is required"),
+  limit: z2.coerce.number().min(1).max(100).optional(),
+  offset: z2.coerce.number().min(0).optional(),
+  sessionId: z2.string().optional(),
+  role: z2.enum(["user", "assistant", "system", "tool"]).optional()
+});
+function parseBody(schema, body) {
+  return schema.parse(body);
+}
+function parseQuery(schema, query) {
+  return schema.parse(query);
 }
 async function initializeApi(agent, agentCardOverride) {
   const app = express2();
@@ -2694,145 +3063,96 @@ async function initializeApi(agent, agentCardOverride) {
   app.get("/health", (req, res) => {
     res.status(200).send("OK");
   });
-  app.post("/api/message", express2.json(), async (req, res) => {
+  app.post("/api/message", express2.json(), async (req, res, next) => {
     logger.info("Received message via POST /api/message");
-    if (!req.body || !req.body.message) {
-      return res.status(400).send({ error: "Missing message content" });
-    }
     try {
-      const sessionId = req.body.sessionId;
-      const stream = req.body.stream === true;
-      const imageDataInput = req.body.imageData ? { image: req.body.imageData.base64, mimeType: req.body.imageData.mimeType } : void 0;
-      const fileDataInput = req.body.fileData ? {
-        data: req.body.fileData.base64,
-        mimeType: req.body.fileData.mimeType,
-        filename: req.body.fileData.filename
+      const { message, sessionId, stream, imageData, fileData } = parseBody(
+        MessageRequestSchema,
+        req.body
+      );
+      const imageDataInput = imageData ? { image: imageData.base64, mimeType: imageData.mimeType } : void 0;
+      const fileDataInput = fileData ? {
+        data: fileData.base64,
+        mimeType: fileData.mimeType,
+        ...fileData.filename && { filename: fileData.filename }
       } : void 0;
       if (imageDataInput) logger.info("Image data included in message.");
       if (fileDataInput) logger.info("File data included in message.");
       if (sessionId) logger.info(`Message for session: ${sessionId}`);
-      const currentConfig = agent.getEffectiveConfig(sessionId);
-      const validation = validateInputForLLM(
-        {
-          text: req.body.message,
-          ...imageDataInput && { imageData: imageDataInput },
-          ...fileDataInput && { fileData: fileDataInput }
-        },
-        {
-          provider: currentConfig.llm.provider,
-          model: currentConfig.llm.model
-        }
+      const response = await agent.run(
+        message || "",
+        imageDataInput,
+        fileDataInput,
+        sessionId,
+        stream || false
       );
-      if (!validation.ok) {
-        const errorMessages = validation.issues.filter((issue) => issue.severity === "error").map((issue) => issue.message);
-        return res.status(400).send({
-          error: errorMessages.join("; "),
-          provider: currentConfig.llm.provider,
-          model: currentConfig.llm.model,
-          issues: validation.issues
-        });
-      }
-      await agent.run(req.body.message, imageDataInput, fileDataInput, sessionId, stream);
-      return res.status(202).send({ status: "processing", sessionId });
+      return res.status(202).send({ response, sessionId });
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : "Unknown error";
-      logger.error(`Error handling POST /api/message: ${errorMessage}`);
-      return res.status(500).send({ error: "Internal server error" });
+      return next(error);
     }
   });
-  app.post("/api/message-sync", express2.json(), async (req, res) => {
+  app.post("/api/message-sync", express2.json(), async (req, res, next) => {
     logger.info("Received message via POST /api/message-sync");
-    if (!req.body || !req.body.message) {
-      return res.status(400).send({ error: "Missing message content" });
-    }
     try {
-      const imageDataInput = req.body.imageData ? { image: req.body.imageData.base64, mimeType: req.body.imageData.mimeType } : void 0;
-      const fileDataInput = req.body.fileData ? {
-        data: req.body.fileData.base64,
-        mimeType: req.body.fileData.mimeType,
-        filename: req.body.fileData.filename
+      const { message, sessionId, imageData, fileData } = parseBody(
+        MessageRequestSchema,
+        req.body
+      );
+      const imageDataInput = imageData ? { image: imageData.base64, mimeType: imageData.mimeType } : void 0;
+      const fileDataInput = fileData ? {
+        data: fileData.base64,
+        mimeType: fileData.mimeType,
+        ...fileData.filename && { filename: fileData.filename }
       } : void 0;
-      const sessionId = req.body.sessionId;
-      const stream = req.body.stream === true;
       if (imageDataInput) logger.info("Image data included in message.");
       if (fileDataInput) logger.info("File data included in message.");
       if (sessionId) logger.info(`Message for session: ${sessionId}`);
-      const currentConfig = agent.getEffectiveConfig(sessionId);
-      const validation = validateInputForLLM(
-        {
-          text: req.body.message,
-          ...imageDataInput && { imageData: imageDataInput },
-          ...fileDataInput && { fileData: fileDataInput }
-        },
-        {
-          provider: currentConfig.llm.provider,
-          model: currentConfig.llm.model
-        }
+      const response = await agent.run(
+        message || "",
+        imageDataInput,
+        fileDataInput,
+        sessionId,
+        false
+        // Force non-streaming for sync endpoint
       );
-      if (!validation.ok) {
-        const errorMessages = validation.issues.filter((issue) => issue.severity === "error").map((issue) => issue.message);
-        return res.status(400).send({
-          error: errorMessages.join("; "),
-          provider: currentConfig.llm.provider,
-          model: currentConfig.llm.model,
-          issues: validation.issues
-        });
-      }
-      await agent.run(req.body.message, imageDataInput, fileDataInput, sessionId, stream);
-      return res.status(202).send({ status: "processing", sessionId });
+      return res.status(200).json({ response, sessionId });
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : "Unknown error";
-      logger.error(`Error handling POST /api/message-sync: ${errorMessage}`);
-      return res.status(500).send({ error: "Internal server error" });
+      return next(error);
     }
   });
-  app.post("/api/reset", express2.json(), async (req, res) => {
+  app.post("/api/reset", express2.json(), async (req, res, next) => {
     logger.info("Received request via POST /api/reset");
     try {
-      const sessionId = req.body.sessionId;
+      const { sessionId } = parseBody(
+        z2.object({ sessionId: z2.string().optional() }),
+        req.body
+      );
       await agent.resetConversation(sessionId);
       return res.status(200).send({ status: "reset initiated", sessionId });
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : "Unknown error";
-      logger.error(`Error handling POST /api/reset: ${errorMessage}`);
-      return res.status(500).send({ error: "Internal server error" });
+      return next(error);
     }
   });
-  app.post("/api/connect-server", express2.json(), async (req, res) => {
-    const { name, config } = req.body;
-    if (!name || typeof name !== "string" || name.trim() === "") {
-      return res.status(400).send({ error: "Missing or invalid server name" });
-    }
-    if (!config || typeof config !== "object") {
-      return res.status(400).send({ error: "Missing or invalid server config object" });
-    }
+  app.post("/api/connect-server", express2.json(), async (req, res, next) => {
     try {
+      const { name, config } = parseBody(McpServerRequestSchema, req.body);
       await agent.connectMcpServer(name, config);
       logger.info(`Successfully connected to new server '${name}' via API request.`);
       return res.status(200).send({ status: "connected", name });
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : "Unknown error during connection";
-      logger.error(`Error handling POST /api/connect-server for '${name}': ${errorMessage}`);
-      return res.status(500).send({
-        error: `Failed to connect to server '${name}': ${errorMessage}`
-      });
+      return next(error);
     }
   });
-  app.post("/api/mcp/servers", express2.json(), async (req, res) => {
-    const { name, config } = req.body;
-    if (!name || !config) {
-      return res.status(400).json({ error: "Missing name or config" });
-    }
+  app.post("/api/mcp/servers", express2.json(), async (req, res, next) => {
     try {
+      const { name, config } = parseBody(McpServerRequestSchema, req.body);
       await agent.connectMcpServer(name, config);
       return res.status(201).json({ status: "connected", name });
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : "Unknown error";
-      logger.error(`Error connecting MCP server '${name}': ${errorMessage}`);
-      return res.status(500).json({ error: `Failed to connect server: ${errorMessage}` });
+      return next(error);
     }
   });
-  app.get("/api/mcp/servers", async (req, res) => {
+  app.get("/api/mcp/servers", async (req, res, next) => {
     try {
       const clientsMap = agent.getMcpClients();
       const failedConnections = agent.getMcpFailedConnections();
@@ -2845,12 +3165,10 @@ async function initializeApi(agent, agentCardOverride) {
       }
       return res.status(200).json({ servers });
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : "Unknown error";
-      logger.error(`Error listing MCP servers: ${errorMessage}`);
-      return res.status(500).json({ error: "Failed to list servers" });
+      return next(error);
     }
   });
-  app.get("/api/mcp/servers/:serverId/tools", async (req, res) => {
+  app.get("/api/mcp/servers/:serverId/tools", async (req, res, next) => {
     const serverId = req.params.serverId;
     const client = agent.getMcpClients().get(serverId);
     if (!client) {
@@ -2866,12 +3184,10 @@ async function initializeApi(agent, agentCardOverride) {
       }));
       return res.status(200).json({ tools });
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : "Unknown error";
-      logger.error(`Error fetching tools for server '${serverId}': ${errorMessage}`);
-      return res.status(500).json({ error: "Failed to fetch tools for server" });
+      return next(error);
     }
   });
-  app.delete("/api/mcp/servers/:serverId", async (req, res) => {
+  app.delete("/api/mcp/servers/:serverId", async (req, res, next) => {
     const { serverId } = req.params;
     logger.info(`Received request to DELETE /api/mcp/servers/${serverId}`);
     try {
@@ -2883,17 +3199,13 @@ async function initializeApi(agent, agentCardOverride) {
       await agent.removeMcpServer(serverId);
       return res.status(200).json({ status: "disconnected", id: serverId });
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : "Unknown error";
-      logger.error(`Error deleting server '${serverId}': ${errorMessage}`);
-      return res.status(500).json({
-        error: `Failed to delete server '${serverId}': ${errorMessage}`
-      });
+      return next(error);
     }
   });
   app.post(
     "/api/mcp/servers/:serverId/tools/:toolName/execute",
     express2.json(),
-    async (req, res) => {
+    async (req, res, next) => {
       const { serverId, toolName } = req.params;
       const client = agent.getMcpClients().get(serverId);
       if (!client) {
@@ -2903,11 +3215,7 @@ async function initializeApi(agent, agentCardOverride) {
         const rawResult = await agent.executeTool(toolName, req.body);
         return res.json({ success: true, data: rawResult });
       } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : "Unknown error";
-        logger.error(
-          `Error executing tool '${toolName}' on server '${serverId}': ${errorMessage}`
-        );
-        return res.status(500).json({ success: false, error: errorMessage });
+        return next(error);
       }
     }
   );
@@ -2915,7 +3223,15 @@ async function initializeApi(agent, agentCardOverride) {
     logger.info("WebSocket client connected.");
     ws.on("message", async (messageBuffer) => {
       const messageString = messageBuffer.toString();
-      logger.debug(`WebSocket received message: ${messageString}`);
+      try {
+        const parsedMessage = JSON.parse(messageString);
+        const redactedMessage = redactSensitiveData(parsedMessage);
+        logger.debug(`WebSocket received message: ${JSON.stringify(redactedMessage)}`);
+      } catch {
+        const redacted = String(redactSensitiveData(messageString));
+        const truncated = redacted.length > 200 ? `${redacted.substring(0, 200)}... (${redacted.length} total chars)` : redacted;
+        logger.debug(`WebSocket received message: ${truncated}`);
+      }
       try {
         const data = JSON.parse(messageString);
         if (data.type === "toolConfirmationResponse" && data.data) {
@@ -2923,13 +3239,13 @@ async function initializeApi(agent, agentCardOverride) {
           return;
         } else if (data.type === "message" && (data.content || data.imageData || data.fileData)) {
           logger.info(
-            `Processing message from WebSocket: ${data.content.substring(0, 50)}...`
+            `Processing message from WebSocket: ${data.content ? data.content.substring(0, 50) + "..." : "[image/file only]"}`
           );
           const imageDataInput = data.imageData ? { image: data.imageData.base64, mimeType: data.imageData.mimeType } : void 0;
           const fileDataInput = data.fileData ? {
             data: data.fileData.base64,
             mimeType: data.fileData.mimeType,
-            filename: data.fileData.filename
+            ...data.fileData.filename && { filename: data.fileData.filename }
           } : void 0;
           const sessionId = data.sessionId;
           const stream = data.stream === true;
@@ -2949,19 +3265,28 @@ async function initializeApi(agent, agentCardOverride) {
             }
           );
           if (!validation.ok) {
-            const errorMessages = validation.issues.filter((issue) => issue.severity === "error").map((issue) => issue.message);
-            const errorDetails = {
-              error: errorMessages.join("; "),
+            const redactedIssues = redactSensitiveData(validation.issues);
+            logger.error(`Invalid input for current LLM configuration`, {
               provider: currentConfig.llm.provider,
               model: currentConfig.llm.model,
-              issues: validation.issues
-            };
-            ws.send(
-              JSON.stringify({
-                event: "error",
-                data: errorDetails
-              })
-            );
+              issues: redactedIssues
+            });
+            const hierarchicalError = new DextoValidationError([
+              {
+                code: "agent_api_validation_error" /* API_VALIDATION_ERROR */,
+                message: "Invalid input for current LLM configuration",
+                scope: "agent" /* AGENT */,
+                type: "user" /* USER */,
+                severity: "error",
+                context: {
+                  provider: currentConfig.llm.provider,
+                  model: currentConfig.llm.model,
+                  detailedIssues: validation.issues
+                  // Nest the specific validation details
+                }
+              }
+            ]);
+            sendWebSocketError(ws, hierarchicalError);
             return;
           }
           await agent.run(data.content, imageDataInput, fileDataInput, sessionId, stream);
@@ -2973,22 +3298,15 @@ async function initializeApi(agent, agentCardOverride) {
           await agent.resetConversation(sessionId);
         } else {
           logger.warn(`Received unknown WebSocket message type: ${data.type}`);
-          ws.send(
-            JSON.stringify({
-              event: "error",
-              data: { message: "Unknown message type" }
-            })
-          );
+          sendWebSocketValidationError(ws, "Unknown message type", {
+            messageType: data.type
+          });
         }
       } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : "Unknown error";
-        logger.error(`Error processing WebSocket message: ${errorMessage}`);
-        ws.send(
-          JSON.stringify({
-            event: "error",
-            data: { message: "Failed to process message" }
-          })
+        logger.error(
+          `Error processing WebSocket message: ${error instanceof Error ? error.message : "Unknown error"}`
         );
+        sendWebSocketError(ws, error);
       }
     });
     ws.on("close", () => {
@@ -3058,7 +3376,7 @@ async function initializeApi(agent, agentCardOverride) {
     }
     return redactedServers;
   }
-  app.get("/api/config.yaml", async (req, res) => {
+  app.get("/api/config.yaml", async (req, res, next) => {
     try {
       const sessionId = req.query.sessionId;
       const config = agent.getEffectiveConfig(sessionId);
@@ -3074,21 +3392,19 @@ async function initializeApi(agent, agentCardOverride) {
       res.set("Content-Type", "application/x-yaml");
       res.send(yamlStr);
     } catch (error) {
-      logger.error(`Error exporting config: ${error.message}`);
-      res.status(500).json({ error: "Failed to export configuration" });
+      return next(error);
     }
   });
-  app.get("/api/llm/current", async (req, res) => {
+  app.get("/api/llm/current", async (req, res, next) => {
     try {
       const { sessionId } = req.query;
       const currentConfig = sessionId ? agent.getEffectiveConfig(sessionId).llm : agent.getCurrentLLMConfig();
       res.json({ config: currentConfig });
     } catch (error) {
-      logger.error(`Error getting current LLM config: ${error.message}`);
-      res.status(500).json({ error: "Failed to get current LLM configuration" });
+      return next(error);
     }
   });
-  app.get("/api/llm/providers", async (req, res) => {
+  app.get("/api/llm/providers", async (req, res, next) => {
     try {
       const providers = {};
       for (const provider of LLM_PROVIDERS) {
@@ -3103,67 +3419,50 @@ async function initializeApi(agent, agentCardOverride) {
       }
       res.json({ providers });
     } catch (error) {
-      logger.error(`Error getting LLM providers: ${error.message}`);
-      res.status(500).json({ error: "Failed to get LLM providers" });
+      return next(error);
     }
   });
-  app.post("/api/llm/switch", express2.json(), async (req, res) => {
-    const validation = validateBody(LLMSwitchRequestSchema, req.body);
-    if (!validation.success) {
-      return res.status(400).json(validation.response);
-    }
-    const { sessionId, ...llmConfig } = validation.data;
+  app.post("/api/llm/switch", express2.json(), async (req, res, next) => {
     try {
+      const body = req.body ?? {};
+      const sessionId = typeof body.sessionId === "string" ? body.sessionId : void 0;
+      const { sessionId: _omit, ...llmCandidate } = body;
+      const llmConfig = LLMUpdatesSchema.parse(llmCandidate);
       const config = await agent.switchLLM(llmConfig, sessionId);
-      return res.status(200).json({
-        ok: true,
-        data: config,
-        issues: []
-      });
+      return res.status(200).json({ config, sessionId });
     } catch (error) {
-      if (error instanceof DextoValidationError) {
-        return res.status(400).json({
-          ok: false,
-          issues: error.issues
-        });
-      } else {
-        logger.error("LLM switch failed:", error);
-        return res.status(500).json({
-          ok: false,
-          issues: [
-            {
-              code: "internal_server_error",
-              message: "Internal server error during LLM switch",
-              severity: "error",
-              context: {}
-            }
-          ]
-        });
-      }
+      return next(error);
     }
   });
-  app.get("/api/sessions", async (req, res) => {
+  app.get("/api/sessions", async (req, res, next) => {
     try {
       const sessionIds = await agent.listSessions();
       const sessions = await Promise.all(
         sessionIds.map(async (id) => {
-          const metadata = await agent.getSessionMetadata(id);
-          return {
-            id,
-            createdAt: metadata?.createdAt || null,
-            lastActivity: metadata?.lastActivity || null,
-            messageCount: metadata?.messageCount || 0
-          };
+          try {
+            const metadata = await agent.getSessionMetadata(id);
+            return {
+              id,
+              createdAt: metadata?.createdAt || null,
+              lastActivity: metadata?.lastActivity || null,
+              messageCount: metadata?.messageCount || 0
+            };
+          } catch (_error) {
+            return {
+              id,
+              createdAt: null,
+              lastActivity: null,
+              messageCount: 0
+            };
+          }
         })
       );
       return res.json({ sessions });
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : "Unknown error";
-      logger.error(`Error listing sessions: ${errorMessage}`);
-      return res.status(500).json({ error: "Failed to list sessions" });
+      return next(error);
     }
   });
-  app.post("/api/sessions", express2.json(), async (req, res) => {
+  app.post("/api/sessions", express2.json(), async (req, res, next) => {
     try {
       const { sessionId } = req.body;
       const session = await agent.createSession(sessionId);
@@ -3171,24 +3470,26 @@ async function initializeApi(agent, agentCardOverride) {
       return res.status(201).json({
         session: {
           id: session.id,
-          createdAt: metadata?.createdAt || null,
-          lastActivity: metadata?.lastActivity || null,
+          createdAt: metadata?.createdAt || Date.now(),
+          lastActivity: metadata?.lastActivity || Date.now(),
           messageCount: metadata?.messageCount || 0
         }
       });
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : "Unknown error";
-      logger.error(`Error creating session: ${errorMessage}`);
-      return res.status(500).json({ error: "Failed to create session" });
+      return next(error);
+    }
+  });
+  app.get("/api/sessions/current", async (req, res, next) => {
+    try {
+      const currentSessionId = agent.getCurrentSessionId();
+      return res.json({ currentSessionId });
+    } catch (error) {
+      return next(error);
     }
   });
-  app.get("/api/sessions/:sessionId", async (req, res) => {
+  app.get("/api/sessions/:sessionId", async (req, res, next) => {
     try {
       const { sessionId } = req.params;
-      const session = await agent.getSession(sessionId);
-      if (!session) {
-        return res.status(404).json({ error: "Session not found" });
-      }
       const metadata = await agent.getSessionMetadata(sessionId);
       const history = await agent.getSessionHistory(sessionId);
       return res.json({
@@ -3201,84 +3502,61 @@ async function initializeApi(agent, agentCardOverride) {
         }
       });
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : "Unknown error";
-      logger.error(`Error getting session ${req.params.sessionId}: ${errorMessage}`);
-      return res.status(500).json({ error: "Failed to get session details" });
+      return next(error);
     }
   });
-  app.get("/api/sessions/:sessionId/history", async (req, res) => {
+  app.get("/api/sessions/:sessionId/history", async (req, res, next) => {
     try {
       const { sessionId } = req.params;
-      const session = await agent.getSession(sessionId);
-      if (!session) {
-        return res.status(404).json({ error: "Session not found" });
-      }
       const history = await agent.getSessionHistory(sessionId);
       return res.json({ history });
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : "Unknown error";
-      logger.error(
-        `Error getting session history for ${req.params.sessionId}: ${errorMessage}`
-      );
-      return res.status(500).json({ error: "Failed to get session history" });
+      return next(error);
     }
   });
-  app.get("/api/search/messages", async (req, res) => {
+  app.get("/api/search/messages", async (req, res, next) => {
     try {
-      const query = req.query.q;
-      if (!query) {
-        return res.status(400).json({ error: "Search query is required" });
-      }
+      const {
+        q: query,
+        limit,
+        offset,
+        sessionId,
+        role
+      } = parseQuery(SearchQuerySchema, req.query);
       const options = {
-        limit: req.query.limit ? parseInt(req.query.limit) : 20,
-        offset: req.query.offset ? parseInt(req.query.offset) : 0
+        limit: limit || 20,
+        offset: offset || 0,
+        ...sessionId && { sessionId },
+        ...role && { role }
       };
-      const sessionId = req.query.sessionId;
-      const role = req.query.role;
-      if (sessionId) {
-        options.sessionId = sessionId;
-      }
-      if (role) {
-        options.role = role;
-      }
       const searchResults = await agent.searchMessages(query, options);
       return sendJsonResponse(res, searchResults);
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : "Unknown error";
-      logger.error(`Error searching messages: ${errorMessage}`);
-      return res.status(500).json({ error: "Failed to search messages" });
+      return next(error);
     }
   });
-  app.get("/api/search/sessions", async (req, res) => {
+  app.get("/api/search/sessions", async (req, res, next) => {
     try {
-      const query = req.query.q;
-      if (!query) {
-        return res.status(400).json({ error: "Search query is required" });
-      }
+      const { q: query } = parseQuery(
+        z2.object({ q: z2.string().min(1, "Search query is required") }),
+        req.query
+      );
       const searchResults = await agent.searchSessions(query);
       return sendJsonResponse(res, searchResults);
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : "Unknown error";
-      logger.error(`Error searching sessions: ${errorMessage}`);
-      return res.status(500).json({ error: "Failed to search sessions" });
+      return next(error);
     }
   });
-  app.delete("/api/sessions/:sessionId", async (req, res) => {
+  app.delete("/api/sessions/:sessionId", async (req, res, next) => {
     try {
       const { sessionId } = req.params;
-      const session = await agent.getSession(sessionId);
-      if (!session) {
-        return res.status(404).json({ error: "Session not found" });
-      }
       await agent.deleteSession(sessionId);
       return res.json({ status: "deleted", sessionId });
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : "Unknown error";
-      logger.error(`Error deleting session ${req.params.sessionId}: ${errorMessage}`);
-      return res.status(500).json({ error: "Failed to delete session" });
+      return next(error);
     }
   });
-  app.post("/api/sessions/:sessionId/load", async (req, res) => {
+  app.post("/api/sessions/:sessionId/load", async (req, res, next) => {
     try {
       const { sessionId } = req.params;
       if (sessionId === "null" || sessionId === "undefined") {
@@ -3290,10 +3568,6 @@ async function initializeApi(agent, agentCardOverride) {
         });
         return;
       }
-      const session = await agent.getSession(sessionId);
-      if (!session) {
-        return res.status(404).json({ error: "Session not found" });
-      }
       await agent.loadSession(sessionId);
       return res.json({
         status: "loaded",
@@ -3301,35 +3575,15 @@ async function initializeApi(agent, agentCardOverride) {
         currentSession: agent.getCurrentSessionId()
       });
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : "Unknown error";
-      logger.error(`Error loading session ${req.params.sessionId}: ${errorMessage}`);
-      return res.status(500).json({ error: "Failed to load session" });
+      return next(error);
     }
   });
-  app.get("/api/sessions/current", async (req, res) => {
+  const webhookSubscriber = new WebhookEventSubscriber();
+  logger.info("Setting up webhook event subscriptions...");
+  webhookSubscriber.subscribe(agent.agentEventBus);
+  app.post("/api/webhooks", express2.json(), async (req, res, next) => {
     try {
-      const currentSessionId = agent.getCurrentSessionId();
-      return res.json({ currentSessionId });
-    } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : "Unknown error";
-      logger.error(`Error getting current session: ${errorMessage}`);
-      return res.status(500).json({ error: "Failed to get current session" });
-    }
-  });
-  const webhookSubscriber = new WebhookEventSubscriber();
-  logger.info("Setting up webhook event subscriptions...");
-  webhookSubscriber.subscribe(agent.agentEventBus);
-  app.post("/api/webhooks", express2.json(), async (req, res) => {
-    try {
-      const { url, secret, description } = req.body;
-      if (!url || typeof url !== "string") {
-        return res.status(400).json({ error: "Invalid or missing webhook URL" });
-      }
-      try {
-        new URL(url);
-      } catch {
-        return res.status(400).json({ error: "Invalid URL format" });
-      }
+      const { url, secret, description } = parseBody(WebhookRequestSchema, req.body);
       const webhookId = `wh_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
       const webhook = {
         id: webhookId,
@@ -3353,12 +3607,10 @@ async function initializeApi(agent, agentCardOverride) {
         201
       );
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : "Unknown error";
-      logger.error(`Error registering webhook: ${errorMessage}`);
-      return res.status(500).json({ error: "Failed to register webhook" });
+      return next(error);
     }
   });
-  app.get("/api/webhooks", async (req, res) => {
+  app.get("/api/webhooks", async (req, res, next) => {
     try {
       const webhooks = webhookSubscriber.getWebhooks().map((webhook) => ({
         id: webhook.id,
@@ -3368,12 +3620,10 @@ async function initializeApi(agent, agentCardOverride) {
       }));
       return sendJsonResponse(res, { webhooks });
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : "Unknown error";
-      logger.error(`Error listing webhooks: ${errorMessage}`);
-      return res.status(500).json({ error: "Failed to list webhooks" });
+      return next(error);
     }
   });
-  app.get("/api/webhooks/:webhookId", async (req, res) => {
+  app.get("/api/webhooks/:webhookId", async (req, res, next) => {
     try {
       const { webhookId } = req.params;
       const webhook = webhookSubscriber.getWebhook(webhookId);
@@ -3389,12 +3639,10 @@ async function initializeApi(agent, agentCardOverride) {
         }
       });
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : "Unknown error";
-      logger.error(`Error getting webhook ${req.params.webhookId}: ${errorMessage}`);
-      return res.status(500).json({ error: "Failed to get webhook" });
+      return next(error);
     }
   });
-  app.delete("/api/webhooks/:webhookId", async (req, res) => {
+  app.delete("/api/webhooks/:webhookId", async (req, res, next) => {
     try {
       const { webhookId } = req.params;
       const removed = webhookSubscriber.removeWebhook(webhookId);
@@ -3404,12 +3652,10 @@ async function initializeApi(agent, agentCardOverride) {
       logger.info(`Webhook removed: ${webhookId}`);
       return res.json({ status: "removed", webhookId });
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : "Unknown error";
-      logger.error(`Error removing webhook ${req.params.webhookId}: ${errorMessage}`);
-      return res.status(500).json({ error: "Failed to remove webhook" });
+      return next(error);
     }
   });
-  app.post("/api/webhooks/:webhookId/test", async (req, res) => {
+  app.post("/api/webhooks/:webhookId/test", async (req, res, next) => {
     try {
       const { webhookId } = req.params;
       const webhook = webhookSubscriber.getWebhook(webhookId);
@@ -3428,11 +3674,10 @@ async function initializeApi(agent, agentCardOverride) {
         }
       });
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : "Unknown error";
-      logger.error(`Error testing webhook ${req.params.webhookId}: ${errorMessage}`);
-      return res.status(500).json({ error: "Failed to test webhook" });
+      return next(error);
     }
   });
+  app.use(errorHandler);
   return { app, server, wss, webSubscriber, webhookSubscriber };
 }
 function startLegacyWebUI(app) {
@@ -3481,11 +3726,11 @@ async function startApiAndLegacyWebUIServer(agent, port = 3e3, serveLegacyWebUI,
 }
 
 // src/app/discord/bot.ts
-import dotenv from "dotenv";
+import dotenv2 from "dotenv";
 import { Client, GatewayIntentBits, Partials } from "discord.js";
 import https from "https";
 import http2 from "http";
-dotenv.config();
+dotenv2.config();
 var token = process.env.DISCORD_BOT_TOKEN;
 var userCooldowns = /* @__PURE__ */ new Map();
 var RATE_LIMIT_ENABLED = process.env.DISCORD_RATE_LIMIT_ENABLED?.toLowerCase() !== "false";
@@ -3646,10 +3891,10 @@ function startDiscordBot(agent) {
 }
 
 // src/app/telegram/bot.ts
-import dotenv2 from "dotenv";
+import dotenv3 from "dotenv";
 import { Bot, InlineKeyboard } from "grammy";
 import https2 from "https";
-dotenv2.config();
+dotenv3.config();
 var token2 = process.env.TELEGRAM_BOT_TOKEN;
 var MAX_CONCURRENT_INLINE_QUERIES = process.env.TELEGRAM_INLINE_QUERY_CONCURRENCY ? Number(process.env.TELEGRAM_INLINE_QUERY_CONCURRENCY) : 5;
 var currentInlineQueries = 0;
@@ -3835,11 +4080,11 @@ function startTelegramBot(agent) {
 
 // src/app/cli/utils/options.ts
 import { z as z3 } from "zod";
+import chalk14 from "chalk";
 function validateCliOptions(opts) {
-  logger.debug("Validating command-line options", "cyanBright");
-  const supportedProviders = getSupportedProviders().map((p3) => p3.toLowerCase());
+  const supportedProviders = getSupportedProviders().map((p7) => p7.toLowerCase());
   const cliOptionShape = z3.object({
-    agent: z3.string().nonempty("Agent config file path must not be empty"),
+    agent: z3.string().min(1, "Agent name or path must not be empty").optional(),
     strict: z3.boolean().optional().default(false),
     verbose: z3.boolean().optional().default(true),
     mode: z3.enum(["cli", "web", "server", "discord", "telegram", "mcp"], {
@@ -3856,7 +4101,8 @@ function validateCliOptions(opts) {
     ),
     provider: z3.string().optional(),
     model: z3.string().optional(),
-    router: z3.enum(["vercel", "in-built"]).optional()
+    router: z3.enum(["vercel", "in-built"]).optional(),
+    interactive: z3.boolean().optional().default(true).describe("Enable interactive prompts (set to false with --no-interactive)")
   });
   const cliOptionSchema = cliOptionShape.refine(
     (data) => !data.provider || supportedProviders.includes(data.provider.toLowerCase()),
@@ -3895,28 +4141,387 @@ function validateCliOptions(opts) {
     webPort: opts.webPort,
     provider: opts.provider,
     model: opts.model,
-    router: opts.router
+    router: opts.router,
+    interactive: opts.interactive
   });
-  logger.debug("Command-line options validated successfully", "green");
 }
 function handleCliOptionsError(error) {
   if (error instanceof z3.ZodError) {
-    logger.error("Invalid command-line options detected:");
+    console.error(chalk14.red("\u274C Invalid command-line options detected:"));
     error.errors.forEach((err) => {
       const fieldName = err.path.join(".") || "Unknown Option";
-      logger.error(`- Option '${fieldName}': ${err.message}`);
+      console.error(chalk14.red(`   \u2022 Option '${fieldName}': ${err.message}`));
     });
-    logger.error(
-      "Please check your command-line arguments or run with --help for usage details."
+    console.error(
+      chalk14.dim(
+        "\nPlease check your command-line arguments or run with --help for usage details."
+      )
     );
   } else {
-    logger.error(
-      `Validation error: ${error instanceof Error ? error.message : JSON.stringify(error)}`
+    console.error(
+      chalk14.red(
+        `\u274C Validation error: ${error instanceof Error ? error.message : JSON.stringify(error)}`
+      )
     );
   }
   process.exit(1);
 }
 
+// src/app/cli/utils/config-validation.ts
+import chalk17 from "chalk";
+
+// src/app/cli/utils/api-key-setup.ts
+import * as p2 from "@clack/prompts";
+import chalk16 from "chalk";
+
+// src/app/cli/utils/env-utils.ts
+async function updateEnvFileWithLLMKeys(envFilePath, llmProvider, llmApiKey) {
+  logger.debug(
+    `updateEnvFileWithLLMKeys: ${JSON.stringify({
+      envFilePath,
+      llmProvider,
+      hasApiKey: Boolean(llmApiKey)
+    })}`
+  );
+  const updates = {};
+  if (llmProvider && llmApiKey) {
+    const envVar = getPrimaryApiKeyEnvVar(llmProvider);
+    updates[envVar] = llmApiKey;
+  }
+  await updateEnvFile(envFilePath, updates);
+}
+
+// src/app/cli/utils/provider-setup.ts
+import * as p from "@clack/prompts";
+import chalk15 from "chalk";
+var PROVIDER_OPTIONS = [
+  {
+    value: "google",
+    label: "\u{1F7E2} Google Gemini",
+    hint: "Free tier available - Recommended for beginners"
+  },
+  {
+    value: "groq",
+    label: "\u{1F7E2} Groq",
+    hint: "Free tier available - Very fast responses"
+  },
+  {
+    value: "openai",
+    label: "\u{1F7E1} OpenAI",
+    hint: "Most popular, requires payment"
+  },
+  {
+    value: "anthropic",
+    label: "\u{1F7E1} Anthropic",
+    hint: "High quality models, requires payment"
+  }
+];
+async function selectProvider() {
+  const choice = await p.select({
+    message: "Choose your AI provider",
+    options: PROVIDER_OPTIONS
+  });
+  if (p.isCancel(choice)) {
+    p.cancel("Setup cancelled");
+    process.exit(1);
+  }
+  return choice;
+}
+function getProviderDisplayName(provider) {
+  switch (provider) {
+    case "google":
+      return "Google Gemini";
+    case "openai":
+      return "OpenAI";
+    case "anthropic":
+      return "Anthropic";
+    case "groq":
+      return "Groq";
+    default:
+      return provider;
+  }
+}
+function isValidApiKeyFormat(apiKey, provider) {
+  switch (provider) {
+    case "google":
+      return apiKey.startsWith("AIza") && apiKey.length > 20;
+    case "openai":
+      return apiKey.startsWith("sk-") && apiKey.length > 40;
+    case "anthropic":
+      return apiKey.startsWith("sk-ant-") && apiKey.length > 40;
+    case "groq":
+      return apiKey.startsWith("gsk_") && apiKey.length > 40;
+    default:
+      return apiKey.length > 10;
+  }
+}
+function getProviderInstructions(provider) {
+  switch (provider) {
+    case "google":
+      return {
+        title: chalk15.green("Google Gemini - Free API Key"),
+        content: `1. Visit: ${chalk15.cyan("https://aistudio.google.com/apikey")}
+2. Sign in with your Google account
+3. Click "Create API Key"
+4. Copy the key
+
+${chalk15.dim("\u2728 Free tier included")}`
+      };
+    case "openai":
+      return {
+        title: chalk15.blue("OpenAI API Key"),
+        content: `1. Visit: ${chalk15.cyan("https://platform.openai.com/api-keys")}
+2. Sign in to your OpenAI account
+3. Click "Create new secret key"
+4. Copy the key
+
+${chalk15.dim("\u{1F4B0} Requires payment")}`
+      };
+    case "anthropic":
+      return {
+        title: chalk15.magenta("Anthropic API Key"),
+        content: `1. Visit: ${chalk15.cyan("https://console.anthropic.com/settings/keys")}
+2. Sign in to your Anthropic account
+3. Click "Create Key"
+4. Copy the key
+
+${chalk15.dim("\u{1F4B0} Requires payment")}`
+      };
+    case "groq":
+      return {
+        title: chalk15.yellow("Groq API Key"),
+        content: `1. Visit: ${chalk15.cyan("https://console.groq.com/keys")}
+2. Sign in with your account
+3. Click "Create API Key"
+4. Copy the key
+
+${chalk15.dim("\u{1F193} Free tier included")}`
+      };
+    default:
+      return null;
+  }
+}
+
+// src/app/cli/utils/api-key-setup.ts
+async function interactiveApiKeySetup(provider) {
+  try {
+    p2.intro(chalk16.cyan("\u{1F511} API Key Setup "));
+    const instructions = getProviderInstructions(provider);
+    p2.note(
+      `Your configuration requires a ${getProviderDisplayName(provider)} API key.
+
+` + (instructions ? instructions.content : "Please get an API key for this provider."),
+      chalk16.bold(`${getProviderDisplayName(provider)} API Key Required`)
+    );
+    const action = await p2.select({
+      message: "What would you like to do?",
+      options: [
+        {
+          value: "setup",
+          label: "Set up an API key now",
+          hint: "Interactive setup (recommended)"
+        },
+        {
+          value: "manual",
+          label: "Set up manually later",
+          hint: "Get instructions for manual setup"
+        },
+        {
+          value: "exit",
+          label: "Exit",
+          hint: "Quit Dexto for now"
+        }
+      ]
+    });
+    if (action === "exit") {
+      p2.cancel("Setup cancelled. Run dexto again when you have an API key!");
+      process.exit(0);
+    }
+    if (action === "manual") {
+      showManualSetupInstructions(provider);
+      console.log(chalk16.dim("\n\u{1F44B} Run dexto again once you have set up your API key!"));
+      process.exit(0);
+    }
+    if (p2.isCancel(action)) {
+      p2.cancel("Setup cancelled");
+      process.exit(1);
+    }
+    const apiKey = await p2.password({
+      message: `Enter your ${getProviderDisplayName(provider)} API key`,
+      mask: "*",
+      validate: (value) => {
+        if (!value || value.trim().length === 0) {
+          return "API key is required";
+        }
+        if (!isValidApiKeyFormat(value.trim(), provider)) {
+          return `Invalid ${getProviderDisplayName(provider)} API key format`;
+        }
+        return void 0;
+      }
+    });
+    if (p2.isCancel(apiKey)) {
+      p2.cancel("Setup cancelled");
+      process.exit(0);
+    }
+    const spinner4 = p2.spinner();
+    spinner4.start("Saving API key...");
+    try {
+      const envFilePath = getDextoEnvPath(process.cwd());
+      await updateEnvFileWithLLMKeys(envFilePath, provider, apiKey.trim());
+      spinner4.stop(
+        `\u2728 API key saved successfully for ${getProviderDisplayName(provider)} in ${envFilePath}!`
+      );
+      p2.outro(chalk16.green(`\u2728 API key setup complete!`));
+      await applyLayeredEnvironmentLoading();
+    } catch (error) {
+      spinner4.stop("Failed to save API key");
+      logger.error(`Failed to update .env file: ${error}`);
+      let instructions2;
+      if (getExecutionContext() === "global-cli") {
+        instructions2 = `1. Create ~/.dexto/.env file
+2. Add this line: ${getPrimaryApiKeyEnvVar(provider)}=your_api_key_here
+3. Run dexto again
+
+Alternatively:
+\u2022 Set environment variable: export ${getPrimaryApiKeyEnvVar(provider)}=your_api_key_here
+\u2022 Or run: dexto setup`;
+      } else {
+        instructions2 = `1. Create a .env file in your project root
+2. Add this line: ${getPrimaryApiKeyEnvVar(provider)}=your_api_key_here
+3. Run dexto again`;
+      }
+      p2.note(
+        `Manual setup required:
+
+${instructions2}`,
+        chalk16.yellow("Save this API key manually")
+      );
+      console.error(chalk16.red("\n\u274C API key setup required to continue."));
+      process.exit(1);
+    }
+  } catch (error) {
+    if (p2.isCancel(error)) {
+      p2.cancel("Setup cancelled");
+      process.exit(0);
+    }
+    console.error(chalk16.red("\n\u274C API key setup required to continue."));
+    process.exit(1);
+  }
+}
+function showManualSetupInstructions(provider) {
+  const envVar = getPrimaryApiKeyEnvVar(provider);
+  const envInstructions = getExecutionContext() === "global-cli" ? [
+    `${chalk16.bold("2. Recommended: Use dexto setup (easiest):")}`,
+    `   dexto setup`,
+    ``,
+    `${chalk16.bold("Or manually create ~/.dexto/.env:")}`,
+    `   mkdir -p ~/.dexto && echo "${envVar}=your_api_key_here" > ~/.dexto/.env`
+  ] : [
+    `${chalk16.bold("2. Create a .env file in your project:")}`,
+    `   echo "${envVar}=your_api_key_here" > .env`
+  ];
+  const instructions = [
+    `${chalk16.bold("1. Get an API key:")}`,
+    `   \u2022 ${chalk16.green("Google Gemini (Free)")}:  https://aistudio.google.com/apikey`,
+    `   \u2022 ${chalk16.blue("OpenAI")}:           https://platform.openai.com/api-keys`,
+    `   \u2022 ${chalk16.magenta("Anthropic")}:        https://console.anthropic.com/keys`,
+    `   \u2022 ${chalk16.yellow("Groq (Free)")}:      https://console.groq.com/keys`,
+    ``,
+    ...envInstructions,
+    `   # OR for other providers:`,
+    `   # OPENAI_API_KEY=your_key_here`,
+    `   # ANTHROPIC_API_KEY=your_key_here`,
+    `   # GROQ_API_KEY=your_key_here`,
+    ``,
+    `${chalk16.bold("3. Run dexto again:")}`,
+    `   dexto | npx dexto`,
+    ``,
+    `${chalk16.dim("\u{1F4A1} Tip: Start with Google Gemini for a free experience!")}`
+  ].join("\n");
+  p2.note(instructions, chalk16.bold("Manual Setup Instructions"));
+}
+
+// src/app/cli/utils/config-validation.ts
+async function validateAgentConfig(config, interactive = false) {
+  const parseResult = AgentConfigSchema.safeParse(config);
+  if (!parseResult.success) {
+    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(
+        chalk17.yellow(`
+\u{1F511} API key required for ${apiKeyError.provider} provider
+`)
+      );
+      await interactiveApiKeySetup(apiKeyError.provider);
+      return validateAgentConfig(config, interactive);
+    }
+    console.error(chalk17.red("\u274C Configuration Error:"));
+    formatZodError(parseResult.error);
+    process.exit(1);
+  }
+  return parseResult.data;
+}
+function findApiKeyError(error, configData) {
+  for (const issue of error.issues) {
+    if (issue.code === "custom" && hasErrorCode(issue.params, "llm_api_key_missing" /* API_KEY_MISSING */)) {
+      const provider = getProviderFromParams(issue.params);
+      if (provider) {
+        return { provider };
+      }
+    }
+    if (issue.path.includes("apiKey") && issue.message.includes("Missing API key")) {
+      const provider = configData.llm?.provider;
+      if (provider) {
+        return { provider };
+      }
+    }
+  }
+  return null;
+}
+function hasErrorCode(params, expectedCode) {
+  return typeof params === "object" && params !== null && "code" in params && params.code === expectedCode;
+}
+function getProviderFromParams(params) {
+  if (typeof params === "object" && params !== null && "provider" in params && typeof params.provider === "string") {
+    return params.provider;
+  }
+  return null;
+}
+function formatZodError(error) {
+  for (const issue of error.issues) {
+    const path9 = issue.path.length > 0 ? issue.path.join(".") : "config";
+    console.error(chalk17.red(`  \u2022 ${path9}: ${issue.message}`));
+  }
+}
+
+// src/app/config/cli-overrides.ts
+function applyCLIOverrides(baseConfig, cliOverrides) {
+  if (!cliOverrides || Object.keys(cliOverrides).length === 0) {
+    return baseConfig;
+  }
+  const mergedConfig = JSON.parse(JSON.stringify(baseConfig));
+  if (!mergedConfig.llm) {
+    mergedConfig.llm = {};
+  }
+  if (cliOverrides.provider) {
+    mergedConfig.llm.provider = cliOverrides.provider;
+  }
+  if (cliOverrides.model) {
+    mergedConfig.llm.model = cliOverrides.model;
+  }
+  if (cliOverrides.router) {
+    mergedConfig.llm.router = cliOverrides.router;
+  }
+  if (cliOverrides.apiKey) {
+    mergedConfig.llm.apiKey = cliOverrides.apiKey;
+  }
+  return mergedConfig;
+}
+
 // src/core/utils/port-utils.ts
 function getPort(envVar, defaultPort, varName) {
   if (envVar === void 0) {
@@ -3929,18 +4534,145 @@ function getPort(envVar, defaultPort, varName) {
   return port;
 }
 
-// src/app/cli/project-commands/create.ts
-import fs from "fs-extra";
-import path from "path";
-import chalk14 from "chalk";
-import * as p from "@clack/prompts";
+// src/app/cli/commands/create-app.ts
+import fs3 from "fs-extra";
+import path4 from "path";
+import chalk18 from "chalk";
+
+// src/app/cli/utils/execute.ts
+import { spawn } from "child_process";
+var DEFAULT_TIMEOUT_MS = 5 * 60 * 1e3;
+function executeWithTimeout(command, args, options) {
+  return new Promise((resolve, reject) => {
+    const { cwd, timeoutMs: timeout = DEFAULT_TIMEOUT_MS } = options;
+    const child = spawn(command, args, { cwd });
+    let stdout = "";
+    let stderr = "";
+    const timer = setTimeout(() => {
+      logger.error(`Process timed out after ${timeout}ms, killing process`);
+      child.kill();
+      reject(new Error(`Process timed out after ${timeout}ms`));
+    }, timeout);
+    child.stdout.on("data", (data) => {
+      const text3 = data.toString();
+      stdout += text3;
+      logger.debug(text3);
+    });
+    child.stderr.on("data", (data) => {
+      const text3 = data.toString();
+      stderr += text3;
+    });
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      logger.error(`Error spawning process: ${error.message}`);
+      reject(error);
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      if (code !== 0) {
+        logger.error(`Process exited with code ${code}
+${stderr}`);
+        reject(new Error(`Process exited with code ${code}`));
+      } else {
+        logger.debug(`${command} ${args.join(" ")} stdout: ${stdout}`);
+        resolve();
+      }
+    });
+  });
+}
+
+// src/app/cli/commands/create-app.ts
+import * as p3 from "@clack/prompts";
+
+// src/app/cli/utils/package-mgmt.ts
+import fsExtra from "fs-extra";
+import path3 from "path";
+function getPackageManagerInstallCommand(pm) {
+  switch (pm) {
+    case "npm":
+      return "install";
+    case "yarn":
+      return "add";
+    case "pnpm":
+      return "add";
+    case "bun":
+      return "add";
+    default:
+      return "install";
+  }
+}
+function getPackageManager() {
+  const projectRoot = findPackageRoot(process.cwd());
+  if (!projectRoot) {
+    return "npm";
+  }
+  if (fsExtra.existsSync(path3.join(projectRoot, "pnpm-lock.yaml"))) {
+    return "pnpm";
+  }
+  if (fsExtra.existsSync(path3.join(projectRoot, "yarn.lock"))) {
+    return "yarn";
+  }
+  if (fsExtra.existsSync(path3.join(projectRoot, "bun.lockb")) || fsExtra.existsSync(path3.join(projectRoot, "bun.lock"))) {
+    return "bun";
+  }
+  return "npm";
+}
+async function addScriptsToPackageJson(scripts) {
+  let packageJson;
+  try {
+    packageJson = await fsExtra.readJSON("package.json");
+  } catch (err) {
+    throw new Error(
+      `Failed to read package.json: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  packageJson.scripts = {
+    ...packageJson.scripts,
+    ...scripts
+  };
+  logger.debug(`Adding scripts to package.json: ${JSON.stringify(scripts, null, 2)}`);
+  try {
+    logger.debug(
+      `Writing to package.json. 
+ Contents: ${JSON.stringify(packageJson, null, 2)}`
+    );
+    await fsExtra.writeJSON("package.json", packageJson, { spaces: 4 });
+  } catch (err) {
+    throw new Error(
+      `Failed to write to package.json: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+async function checkForFileInCurrentDirectory(fileName) {
+  const file = path3.join(process.cwd(), fileName);
+  let isFilePresent = false;
+  try {
+    await fsExtra.readJSON(file);
+    isFilePresent = true;
+  } catch {
+    isFilePresent = false;
+  }
+  if (isFilePresent) {
+    return;
+  }
+  logger.debug(`${fileName} not found in the current directory.`);
+  throw new FileNotFoundError(`${fileName} not found in the current directory.`);
+}
+var FileNotFoundError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "FileNotFoundError";
+  }
+};
+
+// src/app/cli/commands/create-app.ts
 async function createDextoProject(name) {
   const nameRegex = /^[a-zA-Z][a-zA-Z0-9-_]*$/;
   let projectName;
   if (name) {
     if (!nameRegex.test(name)) {
       console.log(
-        chalk14.red(
+        chalk18.red(
           "Invalid project name. Must start with a letter and contain only letters, numbers, hyphens or underscores."
         )
       );
@@ -3950,18 +4682,18 @@ async function createDextoProject(name) {
   } else {
     let input;
     do {
-      input = await p.text({
+      input = await p3.text({
         message: "What do you want to name your Dexto project?",
         placeholder: "my-dexto-project",
         defaultValue: "my-dexto-project"
       });
-      if (p.isCancel(input)) {
-        p.cancel("Project creation cancelled");
+      if (p3.isCancel(input)) {
+        p3.cancel("Project creation cancelled");
         process.exit(0);
       }
       if (!nameRegex.test(input)) {
         console.log(
-          chalk14.red(
+          chalk18.red(
             "Invalid project name. Must start with a letter and contain only letters, numbers, hyphens or underscores."
           )
         );
@@ -3969,31 +4701,31 @@ async function createDextoProject(name) {
     } while (!nameRegex.test(input));
     projectName = input;
   }
-  const spinner2 = p.spinner();
-  const projectPath = path.resolve(process.cwd(), projectName);
-  spinner2.start(`Creating dexto project in ${projectPath}...`);
+  const spinner4 = p3.spinner();
+  const projectPath = path4.resolve(process.cwd(), projectName);
+  spinner4.start(`Creating dexto project in ${projectPath}...`);
   try {
-    await fs.mkdir(projectPath);
+    await fs3.mkdir(projectPath);
   } catch (error) {
     if (error instanceof Error && "code" in error && error.code === "EEXIST") {
-      spinner2.stop(
+      spinner4.stop(
         `Directory "${projectName}" already exists. Please choose a different name or delete the existing directory.`
       );
       process.exit(1);
     } else {
-      spinner2.stop(`Failed to create project: ${error}`);
+      spinner4.stop(`Failed to create project: ${error}`);
       throw error;
     }
   }
   process.chdir(projectPath);
   await executeWithTimeout("npm", ["init", "-y"], { cwd: projectPath });
   await executeWithTimeout("git", ["init"], { cwd: projectPath });
-  await fs.writeFile(".gitignore", "node_modules\n.env\ndist\n.dexto\n*.log");
-  const packageJson = JSON.parse(await fs.readFile("package.json", "utf8"));
+  await fs3.writeFile(".gitignore", "node_modules\n.env\ndist\n.dexto\n*.log");
+  const packageJson = JSON.parse(await fs3.readFile("package.json", "utf8"));
   packageJson.type = "module";
-  await fs.writeFile("package.json", JSON.stringify(packageJson, null, 2));
-  spinner2.stop("Project files created successfully!");
-  spinner2.start("Installing dependencies...");
+  await fs3.writeFile("package.json", JSON.stringify(packageJson, null, 2));
+  spinner4.stop("Project files created successfully!");
+  spinner4.start("Installing dependencies...");
   const packageManager = getPackageManager();
   const installCommand = getPackageManagerInstallCommand(packageManager);
   await executeWithTimeout(packageManager, [installCommand, "yaml", "dotenv"], {
@@ -4004,15 +4736,15 @@ async function createDextoProject(name) {
     [installCommand, "typescript", "tsx", "ts-node", "@types/node", "--save-dev"],
     { cwd: projectPath }
   );
-  spinner2.stop("Dependencies installed!");
+  spinner4.stop("Dependencies installed!");
   return projectPath;
 }
 async function addDextoScriptsToPackageJson(directory, projectPath) {
   logger.debug(`Adding dexto scripts to package.json in ${projectPath}`);
   await addScriptsToPackageJson({
     build: "tsc",
-    start: `node dist/${path.join("dexto", "dexto-example.js")}`,
-    dev: `node --loader ts-node/esm ${path.join(directory, "dexto", "dexto-example.ts")}`
+    start: `node dist/${path4.join("dexto", "dexto-example.js")}`,
+    dev: `node --loader ts-node/esm ${path4.join(directory, "dexto", "dexto-example.ts")}`
   });
   logger.debug(`Successfully added dexto scripts to package.json in ${projectPath}`);
 }
@@ -4033,42 +4765,806 @@ async function createTsconfigJson(projectPath, directory) {
     include: [`${directory}/**/*.ts`],
     exclude: ["node_modules", "dist", ".dexto"]
   };
-  await fs.writeJSON(path.join(projectPath, "tsconfig.json"), tsconfig, { spaces: 4 });
+  await fs3.writeJSON(path4.join(projectPath, "tsconfig.json"), tsconfig, { spaces: 4 });
   logger.debug(`Successfully created tsconfig.json in ${projectPath}`);
 }
 async function postCreateDexto(projectPath, directory) {
   const nextSteps = [
-    `1. Go to the project directory: ${chalk14.cyan(`cd ${projectPath}`)}`,
-    `2. Run the example: ${chalk14.cyan(`npm run dev`)}`,
-    `3. Add/update your API key(s) in ${chalk14.cyan(".env")}`,
-    `4. Check out the agent configuration file ${chalk14.cyan(path.join(directory, "dexto", "agents", "agent.yml"))}`,
-    `5. Try out different LLMs and MCP servers in the agent.yml file`,
-    `6. Read more about Dexto: ${chalk14.cyan("https://github.com/truffle-ai/dexto")}`
+    `1. Go to the project directory: ${chalk18.cyan(`cd ${projectPath}`)}`,
+    `2. Run the example: ${chalk18.cyan(`npm run dev`)}`,
+    `3. Add/update your API key(s) in ${chalk18.cyan(".env")}`,
+    `4. Check out the agent configuration file ${chalk18.cyan(path4.join(directory, "dexto", "agents", "default-agent.yml"))}`,
+    `5. Try out different LLMs and MCP servers in the default-agent.yml file`,
+    `6. Run dexto in your project directory to start the interactive CLI with default-agent.yml file`,
+    `7. Read more about Dexto: ${chalk18.cyan("https://docs.dexto.ai")}`
   ].join("\n");
-  p.note(nextSteps, chalk14.yellow("Next steps:"));
+  p3.note(nextSteps, chalk18.yellow("Next steps:"));
 }
 
-// src/app/web.ts
-import { spawn } from "child_process";
+// src/app/cli/commands/init-app.ts
+import * as p4 from "@clack/prompts";
+import chalk19 from "chalk";
+import fs5 from "node:fs/promises";
+import fsExtra2 from "fs-extra";
+import path5 from "node:path";
+import { createRequire } from "module";
+
+// src/app/cli/utils/project-utils.ts
+import fs4 from "node:fs/promises";
+import { parseDocument } from "yaml";
+async function updateDextoConfigFile(filepath, llmProvider) {
+  const fileContent = await fs4.readFile(filepath, "utf8");
+  const doc = parseDocument(fileContent);
+  doc.setIn(["llm", "provider"], llmProvider);
+  doc.setIn(["llm", "apiKey"], `$${getPrimaryApiKeyEnvVar(llmProvider)}`);
+  const defaultModel = getDefaultModelForProvider(llmProvider);
+  if (defaultModel) {
+    doc.setIn(["llm", "model"], defaultModel);
+  }
+  await fs4.writeFile(filepath, doc.toString(), "utf8");
+}
+
+// src/app/cli/commands/init-app.ts
+var require2 = createRequire(import.meta.url);
+async function getUserInputToInitDextoApp() {
+  const answers = await p4.group(
+    {
+      llmProvider: () => p4.select({
+        message: "Choose your AI provider",
+        options: PROVIDER_OPTIONS
+      }),
+      llmApiKey: async ({ results }) => {
+        const llmProvider = results.llmProvider;
+        const selection = await p4.select({
+          message: `Enter your API key for ${getProviderDisplayName(llmProvider)}?`,
+          options: [
+            { value: "enter", label: "Enter", hint: "recommended" },
+            { value: "skip", label: "Skip", hint: "" }
+          ],
+          initialValue: "enter"
+        });
+        if (p4.isCancel(selection)) {
+          p4.cancel("Dexto initialization cancelled");
+          process.exit(0);
+        }
+        if (selection === "enter") {
+          const apiKey = await p4.password({
+            message: `Enter your ${getProviderDisplayName(llmProvider)} API key`,
+            mask: "*",
+            validate: (value) => {
+              if (!value || value.trim().length === 0) {
+                return "API key is required";
+              }
+              if (!isValidApiKeyFormat(value.trim(), llmProvider)) {
+                return `Invalid ${getProviderDisplayName(llmProvider)} API key format`;
+              }
+              return void 0;
+            }
+          });
+          if (p4.isCancel(apiKey)) {
+            p4.cancel("Dexto initialization cancelled");
+            process.exit(0);
+          }
+          return apiKey;
+        }
+        return "";
+      },
+      directory: () => p4.text({
+        message: "Enter the directory to add the dexto files in",
+        placeholder: "src/",
+        defaultValue: "src/"
+      }),
+      createExampleFile: () => p4.confirm({
+        message: "Create a dexto example file? [Recommended]",
+        initialValue: true
+      })
+    },
+    {
+      onCancel: () => {
+        p4.cancel("Dexto initialization cancelled");
+        process.exit(0);
+      }
+    }
+  );
+  return answers;
+}
+async function initDexto(directory, createExampleFile = true, llmProvider, llmApiKey) {
+  const spinner4 = p4.spinner();
+  try {
+    const packageManager = getPackageManager();
+    const installCommand = getPackageManagerInstallCommand(packageManager);
+    spinner4.start("Installing Dexto...");
+    const label = "latest";
+    logger.debug(
+      `Installing Dexto using ${packageManager} with install command: ${installCommand} and label: ${label}`
+    );
+    try {
+      await executeWithTimeout(packageManager, [installCommand, `dexto@${label}`], {
+        cwd: process.cwd()
+      });
+    } catch (installError) {
+      logger.debug(`Install error: ${installError}`);
+      if (packageManager === "pnpm" && "ERR_PNPM_ADDING_TO_ROOT") {
+        spinner4.stop(chalk19.red("Error: Cannot install in pnpm workspace root"));
+        p4.note(
+          'You are initializing dexto in a pnpm workspace root. Go to a specific package in the workspace and run "pnpm add dexto" instead.',
+          chalk19.yellow("Workspace Error")
+        );
+        return { success: false };
+      }
+      throw installError;
+    }
+    spinner4.stop("Dexto installed successfully!");
+    spinner4.start("Creating Dexto files...");
+    const result = await createDextoDirectories(directory);
+    if (!result.ok) {
+      spinner4.stop(
+        chalk19.inverse(
+          `Dexto already initialized in ${path5.join(directory, "dexto")}. Would you like to overwrite it?`
+        )
+      );
+      const overwrite = await p4.confirm({
+        message: "Overwrite Dexto?",
+        initialValue: false
+      });
+      if (p4.isCancel(overwrite) || !overwrite) {
+        p4.cancel("Dexto initialization cancelled");
+        return { success: false };
+      }
+    }
+    logger.debug("Creating dexto config file...");
+    const dextoDir = path5.join(directory, "dexto");
+    const agentsDir = path5.join(dextoDir, "agents");
+    let configPath;
+    try {
+      configPath = await createDextoConfigFile(agentsDir);
+      logger.debug(`Dexto config file created at ${configPath}`);
+    } catch (configError) {
+      spinner4.stop(chalk19.red("Failed to create agent config file"));
+      logger.error(`Config creation error: ${configError}`);
+      throw new Error(
+        `Failed to create default-agent.yml: ${configError instanceof Error ? configError.message : String(configError)}`
+      );
+    }
+    if (llmProvider) {
+      logger.debug(`Updating dexto config file based on llmProvider: ${llmProvider}`);
+      await updateDextoConfigFile(configPath, llmProvider);
+      logger.debug(`Dexto config file updated with llmProvider: ${llmProvider}`);
+    }
+    if (createExampleFile) {
+      logger.debug("Creating dexto example file...");
+      await createDextoExampleFile(dextoDir);
+      logger.debug("Dexto example file created successfully!");
+    }
+    spinner4.start("Updating .env file with dexto env variables...");
+    logger.debug(
+      `Updating .env file with dexto env variables: directory ${directory}, llmProvider: ${llmProvider}, llmApiKey: [REDACTED]`
+    );
+    const envFilePath = path5.join(process.cwd(), ".env");
+    await updateEnvFileWithLLMKeys(envFilePath, llmProvider, llmApiKey);
+    spinner4.stop("Updated .env file with dexto env variables...");
+    return { success: true };
+  } catch (err) {
+    spinner4.stop(chalk19.inverse("An error occurred initializing Dexto project"));
+    logger.debug(`Error: ${err}`);
+    return { success: false };
+  }
+}
+async function postInitDexto(directory) {
+  const nextSteps = [
+    `1. Run the example: ${chalk19.cyan(`node --loader ts-node/esm ${path5.join(directory, "dexto", "dexto-example.ts")}`)}`,
+    `2. Add/update your API key(s) in ${chalk19.cyan(".env")}`,
+    `3. Check out the agent configuration file ${chalk19.cyan(path5.join(directory, "dexto", "agents", "default-agent.yml"))}`,
+    `4. Try out different LLMs and MCP servers in the default-agent.yml file`,
+    `5. Read more about Dexto: ${chalk19.cyan("https://github.com/truffle-ai/dexto")}`
+  ].join("\n");
+  p4.note(nextSteps, chalk19.yellow("Next steps:"));
+}
+async function createDextoDirectories(directory) {
+  const dirPath = path5.join(directory, "dexto");
+  const agentsPath = path5.join(directory, "dexto", "agents");
+  try {
+    await fs5.access(dirPath);
+    return { ok: false };
+  } catch {
+    await fsExtra2.ensureDir(dirPath);
+    await fsExtra2.ensureDir(agentsPath);
+    return { ok: true, dirPath };
+  }
+}
+async function createDextoConfigFile(directory) {
+  await fsExtra2.ensureDir(directory);
+  try {
+    const pkgJsonPath = require2.resolve("dexto/package.json");
+    const pkgDir = path5.dirname(pkgJsonPath);
+    logger.debug(`Package directory: ${pkgDir}`);
+    const templateConfigSrc = path5.join(pkgDir, "agents", "agent-template.yml");
+    logger.debug(`Looking for template at: ${templateConfigSrc}`);
+    const templateExists = await fsExtra2.pathExists(templateConfigSrc);
+    if (!templateExists) {
+      throw new Error(
+        `Template file not found at: ${templateConfigSrc}. This indicates a build issue - the template should be included in the package.`
+      );
+    }
+    const destConfigPath = path5.join(directory, "default-agent.yml");
+    logger.debug(`Copying template to: ${destConfigPath}`);
+    await fsExtra2.copy(templateConfigSrc, destConfigPath);
+    logger.debug(`Successfully created config file at: ${destConfigPath}`);
+    return destConfigPath;
+  } catch (error) {
+    logger.error(`Failed to create Dexto config file: ${error}`);
+    throw error;
+  }
+}
+async function createDextoExampleFile(directory) {
+  const baseDir = path5.dirname(directory);
+  const configPath = `./${path5.posix.join(baseDir, "dexto/agents/default-agent.yml")}`;
+  const indexTsLines = [
+    "import 'dotenv/config';",
+    "import { DextoAgent, loadAgentConfig } from 'dexto';",
+    "",
+    "console.log('\u{1F680} Starting Dexto Basic Example\\n');",
+    "",
+    "try {",
+    "  // Load the agent configuration",
+    `  const config = await loadAgentConfig('${configPath}');`,
+    "",
+    "  // Create a new DextoAgent instance",
+    "  const agent = new DextoAgent(config);",
+    "",
+    "  // Start the agent (connects to MCP servers)",
+    "  console.log('\u{1F517} Connecting to MCP servers...');",
+    "  await agent.start();",
+    "  console.log('\u2705 Agent started successfully!\\n');",
+    "",
+    "  // Example 1: Simple task",
+    "  console.log('\u{1F4CB} Example 1: Simple information request');",
+    "  const request1 = 'What tools do you have available?';",
+    "  console.log('Request:', request1);",
+    "  const response1 = await agent.run(request1);",
+    "  console.log('Response:', response1);",
+    "  console.log('\\n\u2014\u2014\u2014\u2014\u2014\u2014\\n');",
+    "",
+    "  // Example 2: File operation",
+    "  console.log('\u{1F4C4} Example 2: File creation');",
+    `  const request2 = 'Create a file called test-output.txt with the content "Hello from Dexto!"';`,
+    "  console.log('Request:', request2);",
+    "  const response2 = await agent.run(request2);",
+    "  console.log('Response:', response2);",
+    "  console.log('\\n\u2014\u2014\u2014\u2014\u2014\u2014\\n');",
+    "",
+    "  // Example 3: Multi-step conversation",
+    "  console.log('\u{1F5E3}\uFE0F Example 3: Multi-step conversation');",
+    `  const request3a = 'Create a simple HTML file called demo.html with a heading that says "Dexto Demo"';`,
+    "  console.log('Request 3a:', request3a);",
+    "  const response3a = await agent.run(request3a);",
+    "  console.log('Response:', response3a);",
+    "  console.log('\\n\\n');",
+    "  const request3b = 'Now add a paragraph to that HTML file explaining what Dexto is';",
+    "  console.log('Request 3b:', request3b);",
+    "  const response3b = await agent.run(request3b);",
+    "  console.log('Response:', response3b);",
+    "  console.log('\\n\u2014\u2014\u2014\u2014\u2014\u2014\\n');",
+    "",
+    "  // Reset conversation (clear context)",
+    "  console.log('\u{1F504} Resetting conversation context...');",
+    "  agent.resetConversation();",
+    "",
+    "  // Example 4: Complex task",
+    "  console.log('\u{1F3D7}\uFE0F Example 4: Complex multi-tool task');",
+    "  const request4 = ",
+    "    'Create a simple webpage about AI agents with HTML, CSS, and JavaScript. ' +",
+    "    'The page should have a title, some content about what AI agents are, ' +",
+    "    'and a button that shows an alert when clicked.';",
+    "  console.log('Request:', request4);",
+    "  const response4 = await agent.run(request4);",
+    "  console.log('Response:', response4);",
+    "  console.log('\\n\u2014\u2014\u2014\u2014\u2014\u2014\\n');",
+    "",
+    "  // Stop the agent (disconnect from MCP servers)",
+    "  console.log('\\n\u{1F6D1} Stopping agent...');",
+    "  await agent.stop();",
+    "  console.log('\u2705 Agent stopped successfully!');",
+    "",
+    "} catch (error) {",
+    "  console.error('\u274C Error:', error);",
+    "}",
+    "",
+    "console.log('\\n\u{1F4D6} Read Dexto documentation to understand more about using Dexto: https://docs.dexto.ai');"
+  ];
+  const indexTsContent = indexTsLines.join("\n");
+  const outputPath = path5.join(directory, "dexto-example.ts");
+  logger.debug(`Creating example file with config path: ${configPath}`);
+  logger.debug(`Base directory: ${baseDir}, Output path: ${outputPath}`);
+  logger.debug(`Generated file content:
+${indexTsContent}`);
+  await fs5.writeFile(outputPath, indexTsContent);
+  return outputPath;
+}
+
+// src/app/cli/commands/setup.ts
+import chalk20 from "chalk";
+import { z as z4 } from "zod";
+
+// src/app/cli/utils/setup-utils.ts
+function isFirstTimeUser() {
+  return !globalPreferencesExist();
+}
+async function requiresSetup() {
+  if (getExecutionContext() !== "global-cli") {
+    return false;
+  }
+  if (isFirstTimeUser()) {
+    return true;
+  }
+  try {
+    const preferences = await loadGlobalPreferences();
+    if (!preferences.setup.completed) {
+      return true;
+    }
+    if (!preferences.defaults.defaultAgent) {
+      return true;
+    }
+    return false;
+  } catch (_error) {
+    return true;
+  }
+}
+
+// src/app/cli/commands/setup.ts
+import * as p5 from "@clack/prompts";
+var SetupCommandSchema = z4.object({
+  provider: z4.enum(LLM_PROVIDERS).optional().describe("AI provider identifier to use for LLM calls"),
+  model: z4.string().min(1, "Model name cannot be empty").optional().describe("Preferred model name for the selected provider"),
+  defaultAgent: z4.string().min(1, "Default agent name cannot be empty").default("default-agent").describe("Registry agent id to use when none is specified"),
+  interactive: z4.boolean().default(true).describe("Enable interactive prompts"),
+  force: z4.boolean().default(false).describe("Overwrite existing setup when already configured")
+}).strict().superRefine((data, ctx) => {
+  if (data.provider && data.model) {
+    if (!isValidProviderModel(data.provider, data.model)) {
+      const supportedModels = getSupportedModels(data.provider);
+      ctx.addIssue({
+        code: z4.ZodIssueCode.custom,
+        path: ["model"],
+        message: `Model '${data.model}' is not supported by provider '${data.provider}'. Supported models: ${supportedModels.join(", ")}`
+      });
+    }
+  }
+});
+function validateSetupCommand(options) {
+  const validated = SetupCommandSchema.parse(options);
+  if (!validated.interactive && !validated.provider) {
+    throw new Error("Provider required in non-interactive mode. Use --provider option.");
+  }
+  return validated;
+}
+async function handleSetupCommand(options) {
+  const validated = validateSetupCommand(options);
+  logger.debug(`Validated setup command options: ${JSON.stringify(validated, null, 2)}`);
+  const needsSetup = await requiresSetup();
+  if (!needsSetup) {
+    if (!validated.interactive) {
+      if (!validated.force) {
+        console.error(chalk20.red("\u274C Setup is already complete."));
+        console.error(
+          chalk20.dim(
+            "   Use --force to overwrite existing setup, or run in interactive mode for confirmation."
+          )
+        );
+        process.exit(1);
+      }
+      logger.warn("Overwriting existing setup due to --force flag");
+    } else {
+      p5.intro(chalk20.yellow("\u26A0\uFE0F  Setup Already Complete"));
+      p5.note(
+        "Dexto is already set up and configured.\nRe-running setup will overwrite your current preferences.",
+        "Current Setup Detected"
+      );
+      const shouldContinue = await p5.confirm({
+        message: "Do you want to continue and overwrite your current setup?",
+        initialValue: false
+      });
+      if (p5.isCancel(shouldContinue) || !shouldContinue) {
+        p5.cancel("Setup cancelled. Your existing configuration remains unchanged.");
+        process.exit(0);
+      }
+      p5.log.warn("Proceeding with setup override...");
+    }
+  }
+  console.log(chalk20.cyan("\n\u{1F5FF} Setting up Dexto...\n"));
+  let provider = validated.provider;
+  if (!provider) {
+    provider = await selectProvider();
+  }
+  const model = validated.model || getDefaultModelForProvider(provider);
+  if (!model) {
+    throw new Error(`Provider '${provider}' requires a specific model. Use --model option.`);
+  }
+  const apiKeyVar = getPrimaryApiKeyEnvVar(provider);
+  const defaultAgent = validated.defaultAgent;
+  const preferences = createInitialPreferences(provider, model, apiKeyVar, defaultAgent);
+  await saveGlobalPreferences(preferences);
+  if (validated.interactive) {
+    const existingApiKey = resolveApiKeyForProvider(provider);
+    if (existingApiKey) {
+      p5.outro(chalk20.green(`\u2705 API key for ${provider} already configured`));
+    } else {
+      p5.outro(chalk20.cyan(`API key not found for ${provider}, starting api key setup...`));
+      await interactiveApiKeySetup(provider);
+    }
+  }
+  console.log(chalk20.green("\n\u2728 Setup complete! Dexto is ready to use.\n"));
+}
+
+// src/app/cli/commands/install.ts
 import { existsSync } from "fs";
-import path2 from "path";
+import path6 from "path";
+import { z as z5 } from "zod";
+var InstallCommandSchema = z5.object({
+  agents: z5.array(z5.string().min(1, "Agent name cannot be empty")),
+  all: z5.boolean().default(false),
+  injectPreferences: z5.boolean().default(true),
+  force: z5.boolean().default(false)
+}).strict();
+function validateInstallCommand(agents, options) {
+  const registry = getAgentRegistry();
+  const validated = InstallCommandSchema.parse({
+    ...options,
+    agents
+  });
+  const availableAgents = registry.getAvailableAgents();
+  if (!validated.all && validated.agents.length === 0) {
+    throw new Error(
+      `No agents specified. Use agent names or --all flag.  Available agents: ${Object.keys(availableAgents).join(", ")}`
+    );
+  }
+  if (!validated.all) {
+    const invalidAgents = validated.agents.filter((agent) => !registry.hasAgent(agent));
+    if (invalidAgents.length > 0) {
+      throw new Error(
+        `Unknown agents: ${invalidAgents.join(", ")}. Available agents: ${Object.keys(availableAgents).join(", ")}`
+      );
+    }
+  }
+  return validated;
+}
+async function handleInstallCommand(agents, options) {
+  const validated = validateInstallCommand(agents, options);
+  const registry = getAgentRegistry();
+  let agentsToInstall;
+  if (validated.all) {
+    agentsToInstall = Object.keys(registry.getAvailableAgents());
+    console.log(`\u{1F4CB} Installing all ${agentsToInstall.length} available agents...`);
+  } else {
+    agentsToInstall = validated.agents;
+  }
+  console.log(`\u{1F680} Installing ${agentsToInstall.length} agents...`);
+  let successCount = 0;
+  let errorCount = 0;
+  const errors = [];
+  for (const agentName of agentsToInstall) {
+    try {
+      console.log(`
+\u{1F4E6} Installing ${agentName}...`);
+      const globalAgentsDir = getDextoGlobalPath("agents");
+      const installedPath = path6.join(globalAgentsDir, agentName);
+      if (existsSync(installedPath) && !validated.force) {
+        console.log(`\u23ED\uFE0F  ${agentName} already installed (use --force to reinstall)`);
+        successCount++;
+        continue;
+      }
+      await registry.installAgent(agentName, validated.injectPreferences);
+      successCount++;
+      console.log(`\u2705 ${agentName} installed successfully`);
+    } catch (error) {
+      errorCount++;
+      const errorMsg = `Failed to install ${agentName}: ${error instanceof Error ? error.message : String(error)}`;
+      errors.push(errorMsg);
+      console.error(`\u274C ${errorMsg}`);
+    }
+  }
+  if (agentsToInstall.length === 1) {
+    if (errorCount > 0) {
+      throw new Error(errors[0]);
+    }
+    return;
+  }
+  console.log(`
+\u{1F4CA} Installation Summary:`);
+  console.log(`\u2705 Successfully installed: ${successCount}`);
+  if (errorCount > 0) {
+    console.log(`\u274C Failed to install: ${errorCount}`);
+    errors.forEach((error) => console.log(`   \u2022 ${error}`));
+  }
+  if (errorCount > 0 && successCount === 0) {
+    throw new Error("All installations failed");
+  } else if (errorCount > 0) {
+    console.log(`\u26A0\uFE0F  Some installations failed, but ${successCount} succeeded.`);
+  } else {
+    console.log(`\u{1F389} All agents installed successfully!`);
+  }
+}
+
+// src/app/cli/commands/uninstall.ts
+import { z as z6 } from "zod";
+var UninstallCommandSchema = z6.object({
+  agents: z6.array(z6.string().min(1, "Agent name cannot be empty")),
+  all: z6.boolean().default(false),
+  force: z6.boolean().default(false)
+}).strict();
+async function validateUninstallCommand(agents, options) {
+  const validated = UninstallCommandSchema.parse({
+    ...options,
+    agents
+  });
+  const registry = getAgentRegistry();
+  const installedAgents = await registry.getInstalledAgents();
+  if (installedAgents.length === 0) {
+    throw new Error("No agents are currently installed.");
+  }
+  if (!validated.all && validated.agents.length === 0) {
+    throw new Error(
+      `No agents specified. Use agent names or --all flag. Installed agents: ${installedAgents.join(", ")}`
+    );
+  }
+  return validated;
+}
+async function handleUninstallCommand(agents, options) {
+  const validated = await validateUninstallCommand(agents, options);
+  const registry = getAgentRegistry();
+  const installedAgents = await registry.getInstalledAgents();
+  if (installedAgents.length === 0) {
+    console.log("\u{1F4CB} No agents are currently installed.");
+    return;
+  }
+  let agentsToUninstall;
+  if (validated.all) {
+    agentsToUninstall = installedAgents;
+    console.log(`\u{1F4CB} Uninstalling all ${agentsToUninstall.length} installed agents...`);
+  } else {
+    agentsToUninstall = validated.agents;
+    const notInstalled = agentsToUninstall.filter((agent) => !installedAgents.includes(agent));
+    if (notInstalled.length > 0) {
+      throw new Error(
+        `Agents not installed: ${notInstalled.join(", ")}. Installed agents: ${installedAgents.join(", ")}`
+      );
+    }
+  }
+  console.log(`\u{1F5D1}\uFE0F  Uninstalling ${agentsToUninstall.length} agents...`);
+  let successCount = 0;
+  let errorCount = 0;
+  const errors = [];
+  for (const agentName of agentsToUninstall) {
+    try {
+      console.log(`
+\u{1F5D1}\uFE0F  Uninstalling ${agentName}...`);
+      await registry.uninstallAgent(agentName, validated.force);
+      successCount++;
+      console.log(`\u2705 ${agentName} uninstalled successfully`);
+    } catch (error) {
+      errorCount++;
+      const errorMsg = `Failed to uninstall ${agentName}: ${error instanceof Error ? error.message : String(error)}`;
+      errors.push(errorMsg);
+      console.error(`\u274C ${errorMsg}`);
+    }
+  }
+  if (agentsToUninstall.length === 1) {
+    if (errorCount > 0) {
+      throw new Error(errors[0]);
+    }
+    return;
+  }
+  console.log(`
+\u{1F4CA} Uninstallation Summary:`);
+  console.log(`\u2705 Successfully uninstalled: ${successCount}`);
+  if (errorCount > 0) {
+    console.log(`\u274C Failed to uninstall: ${errorCount}`);
+    errors.forEach((error) => console.log(`   \u2022 ${error}`));
+  }
+  if (errorCount > 0 && successCount === 0) {
+    throw new Error("All uninstallations failed");
+  } else if (errorCount > 0) {
+    console.log(`\u26A0\uFE0F  Some uninstallations failed, but ${successCount} succeeded.`);
+  } else {
+    console.log(`\u{1F389} All agents uninstalled successfully!`);
+  }
+}
+
+// src/app/cli/commands/list-agents.ts
+import { existsSync as existsSync2 } from "fs";
+import { promises as fs6 } from "fs";
+import path7 from "path";
+import chalk21 from "chalk";
+import { z as z7 } from "zod";
+var ListAgentsCommandSchema = z7.object({
+  verbose: z7.boolean().default(false),
+  installed: z7.boolean().default(false),
+  available: z7.boolean().default(false)
+}).strict();
+async function getInstalledAgents() {
+  const globalAgentsDir = getDextoGlobalPath("agents");
+  if (!existsSync2(globalAgentsDir)) {
+    return [];
+  }
+  const registry = getAgentRegistry();
+  const installedAgents = [];
+  try {
+    const entries = await fs6.readdir(globalAgentsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory() || entry.name.endsWith(".yml")) {
+        const agentName = entry.isDirectory() ? entry.name : path7.basename(entry.name, ".yml");
+        const agentPath = path7.join(globalAgentsDir, entry.name);
+        try {
+          const mainConfigPath = entry.isDirectory() ? registry.resolveMainConfig(agentPath, agentName) : agentPath;
+          const stats = await fs6.stat(agentPath);
+          let llmProvider;
+          let llmModel;
+          if (existsSync2(mainConfigPath)) {
+            try {
+              const configContent = await fs6.readFile(mainConfigPath, "utf-8");
+              const configMatch = configContent.match(/provider:\s*([^\n\r]+)/);
+              const modelMatch = configContent.match(/model:\s*([^\n\r]+)/);
+              llmProvider = configMatch?.[1]?.trim();
+              llmModel = modelMatch?.[1]?.trim();
+            } catch (_error) {
+            }
+          }
+          const registryData = registry.getAvailableAgents()[agentName];
+          const description = registryData?.description || "Custom agent";
+          const agentInfo = {
+            name: agentName,
+            description,
+            path: mainConfigPath,
+            installedAt: stats.birthtime || stats.mtime
+          };
+          if (llmProvider) agentInfo.llmProvider = llmProvider;
+          if (llmModel) agentInfo.llmModel = llmModel;
+          installedAgents.push(agentInfo);
+        } catch (error) {
+          console.warn(`Warning: Could not process agent '${agentName}': ${error}`);
+        }
+      }
+    }
+  } catch (_error) {
+    return [];
+  }
+  return installedAgents.sort((a, b) => a.name.localeCompare(b.name));
+}
+function getAvailableAgents() {
+  const registry = getAgentRegistry();
+  const availableAgents = registry.getAvailableAgents();
+  return Object.entries(availableAgents).map(([name, data]) => ({
+    name,
+    description: data.description,
+    author: data.author,
+    tags: data.tags
+  })).sort((a, b) => a.name.localeCompare(b.name));
+}
+async function handleListAgentsCommand(options) {
+  const validated = ListAgentsCommandSchema.parse(options);
+  console.log(chalk21.cyan("\n\u{1F4CB} Dexto Agents\n"));
+  let globalLLM;
+  if (globalPreferencesExist()) {
+    try {
+      const preferences = await loadGlobalPreferences();
+      globalLLM = `${preferences.llm.provider}/${preferences.llm.model}`;
+    } catch {
+    }
+  }
+  const installedAgents = await getInstalledAgents();
+  const availableAgents = getAvailableAgents();
+  const showInstalled = !validated.available || validated.installed;
+  const showAvailable = !validated.installed || validated.available;
+  if (showInstalled && installedAgents.length > 0) {
+    console.log(chalk21.green("\u2705 Installed Agents:"));
+    for (const agent of installedAgents) {
+      const llmInfo = agent.llmProvider && agent.llmModel ? `${agent.llmProvider}/${agent.llmModel}` : globalLLM || "Unknown LLM";
+      const llmDisplay = chalk21.gray(`(${llmInfo})`);
+      if (validated.verbose) {
+        console.log(`  ${chalk21.bold(agent.name)} ${llmDisplay}`);
+        console.log(`    ${chalk21.gray(agent.description)}`);
+        console.log(`    ${chalk21.gray("Path:")} ${agent.path}`);
+        if (agent.installedAt) {
+          console.log(
+            `    ${chalk21.gray("Installed:")} ${agent.installedAt.toLocaleDateString()}`
+          );
+        }
+        console.log();
+      } else {
+        console.log(`  \u2022 ${chalk21.bold(agent.name)} ${llmDisplay} - ${agent.description}`);
+      }
+    }
+    console.log();
+  } else if (showInstalled) {
+    console.log(chalk21.yellow("\u{1F4E6} No agents installed yet."));
+    console.log(
+      chalk21.gray("   Use `dexto install <agent-name>` to install agents from the registry.\n")
+    );
+  }
+  if (showAvailable) {
+    const availableNotInstalled = availableAgents.filter(
+      (available) => !installedAgents.some((installed) => installed.name === available.name)
+    );
+    if (availableNotInstalled.length > 0) {
+      console.log(chalk21.blue("\u{1F4CB} Available to Install:"));
+      for (const agent of availableNotInstalled) {
+        if (validated.verbose) {
+          console.log(`  ${chalk21.bold(agent.name)}`);
+          console.log(`    ${chalk21.gray(agent.description)}`);
+          console.log(`    ${chalk21.gray("Author:")} ${agent.author}`);
+          console.log(`    ${chalk21.gray("Tags:")} ${agent.tags.join(", ")}`);
+          console.log();
+        } else {
+          console.log(`  \u2022 ${chalk21.bold(agent.name)} - ${agent.description}`);
+        }
+      }
+      console.log();
+    }
+  }
+  const totalInstalled = installedAgents.length;
+  const availableToInstall = availableAgents.filter(
+    (a) => !installedAgents.some((i) => i.name === a.name)
+  ).length;
+  if (!validated.verbose) {
+    console.log(
+      chalk21.gray(
+        `\u{1F4CA} Summary: ${totalInstalled} installed, ${availableToInstall} available to install`
+      )
+    );
+    if (availableToInstall > 0) {
+      console.log(
+        chalk21.gray(`   Use \`dexto install <agent-name>\` to install more agents.`)
+      );
+    }
+    console.log(chalk21.gray(`   Use \`dexto list-agents --verbose\` for detailed information.`));
+  }
+  console.log();
+}
+
+// src/app/cli/commands/which.ts
+import chalk22 from "chalk";
+import { z as z8 } from "zod";
+var WhichCommandSchema = z8.object({
+  agentName: z8.string().min(1, "Agent name cannot be empty")
+}).strict();
+async function handleWhichCommand(agentName) {
+  const validated = WhichCommandSchema.parse({ agentName });
+  const registry = getAgentRegistry();
+  const availableAgents = Object.keys(registry.getAvailableAgents());
+  try {
+    const resolvedPath = await resolveAgentPath(validated.agentName, false, false);
+    console.log(resolvedPath);
+  } catch (error) {
+    console.error(
+      chalk22.red(
+        `\u274C dexto which command failed: ${error instanceof Error ? error.message : String(error)}. Available agents: ${availableAgents.join(", ")}`
+      )
+    );
+    process.exit(1);
+  }
+}
+
+// src/app/web.ts
+import { spawn as spawn2 } from "child_process";
+import { existsSync as existsSync3 } from "fs";
+import path8 from "path";
 import { fileURLToPath } from "url";
 async function startNextJsWebServer(apiUrl, frontPort = 3e3, frontUrl = `http://localhost:${frontPort}`) {
-  const scriptDir = path2.dirname(fileURLToPath(import.meta.url));
+  const scriptDir = path8.dirname(fileURLToPath(import.meta.url));
   logger.debug(`Script directory for web mode: ${scriptDir}`);
-  let webuiPath = path2.resolve(scriptDir, "webui");
-  if (!existsSync(webuiPath)) {
-    const srcPath = path2.resolve(scriptDir, "..", "..", "src", "app", "webui");
-    if (existsSync(srcPath)) {
+  let webuiPath = path8.resolve(scriptDir, "webui");
+  if (!existsSync3(webuiPath)) {
+    const srcPath = path8.resolve(scriptDir, "..", "..", "src", "app", "webui");
+    if (existsSync3(srcPath)) {
       return startDevServer(apiUrl, frontPort, frontUrl, srcPath);
     } else {
       logger.warn("Could not locate webui directory. Web UI may not be available.");
       return false;
     }
   }
-  const standaloneServerPath = path2.join(webuiPath, ".next", "standalone", "server.js");
-  const serverScriptPath = path2.join(webuiPath, "server.js");
-  if (!existsSync(standaloneServerPath) && !existsSync(serverScriptPath)) {
+  const standaloneServerPath = path8.join(webuiPath, ".next", "standalone", "server.js");
+  const serverScriptPath = path8.join(webuiPath, "server.js");
+  if (!existsSync3(standaloneServerPath) && !existsSync3(serverScriptPath)) {
     logger.warn(
       "Built WebUI not found. This may indicate the package was not built correctly.",
       null,
@@ -4088,8 +5584,8 @@ async function startNextJsWebServer(apiUrl, frontPort = 3e3, frontUrl = `http://
       }
     })();
     logger.info(`Starting Next.js production server on ${frontUrl}`, null, "cyanBright");
-    const serverToUse = existsSync(serverScriptPath) ? serverScriptPath : standaloneServerPath;
-    const nextProc = spawn("node", [serverToUse], {
+    const serverToUse = existsSync3(serverScriptPath) ? serverScriptPath : standaloneServerPath;
+    const nextProc = spawn2("node", [serverToUse], {
       cwd: webuiPath,
       stdio: ["inherit", "pipe", "inherit"],
       env: {
@@ -4162,11 +5658,11 @@ async function startDevServer(apiUrl, frontPort, frontUrl, webuiPath) {
         return "3001";
       }
     })();
-    const nodeModulesPath = path2.join(webuiPath, "node_modules");
-    const needsInstall = !existsSync(nodeModulesPath);
+    const nodeModulesPath = path8.join(webuiPath, "node_modules");
+    const needsInstall = !existsSync3(nodeModulesPath);
     if (needsInstall) {
       logger.info("Installing Next.js dependencies...", null, "cyanBright");
-      const installProc = spawn("npm", ["install"], {
+      const installProc = spawn2("npm", ["install"], {
         cwd: webuiPath,
         stdio: "inherit"
       });
@@ -4180,7 +5676,7 @@ async function startDevServer(apiUrl, frontPort, frontUrl, webuiPath) {
       }
     }
     logger.info(`Starting Next.js dev server on ${frontUrl}`, null, "cyanBright");
-    const nextProc = spawn("npm", ["run", "dev", "--", "--port", String(frontPort)], {
+    const nextProc = spawn2("npm", ["run", "dev", "--", "--port", String(frontPort)], {
       cwd: webuiPath,
       stdio: ["inherit", "pipe", "inherit"],
       env: {
@@ -4322,16 +5818,19 @@ async function initializeMcpToolAggregationServer(serverConfigs, mcpTransport, s
 }
 
 // src/app/index.ts
-dotenv3.config();
+await applyLayeredEnvironmentLoading();
 var program = new Command();
-program.name("dexto").description("AI-powered CLI and WebUI for interacting with MCP servers").version(package_default.version, "-v, --version", "output the current version").option("-a, --agent <path>", "Path to agent config file", DEFAULT_CONFIG_PATH).option("-s, --strict", "Require all server connections to succeed").option("--no-verbose", "Disable verbose output").option("-m, --model <model>", "Specify the LLM model to use. ").option("-r, --router <router>", "Specify the LLM router to use (vercel or in-built)").option("--new-session [sessionId]", "Start with a new session (optionally specify session ID)").option(
+program.name("dexto").description("AI-powered CLI and WebUI for interacting with MCP servers").version(package_default.version, "-v, --version", "output the current version").option("-a, --agent <name|path>", "Agent name or path to agent config file").option(
+  "-p, --prompt <text>",
+  "One-shot prompt text. Alternatively provide a single quoted string as positional argument."
+).option("-s, --strict", "Require all server connections to succeed").option("--no-verbose", "Disable verbose output").option("--no-interactive", "Disable interactive prompts and API key setup").option("-m, --model <model>", "Specify the LLM model to use").option("-r, --router <router>", "Specify the LLM router to use (vercel or in-built)").option("--new-session [sessionId]", "Start with a new session (optionally specify session 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("--web-port <port>", "optional port for the web UI", "3000").option("--no-auto-install", "Disable automatic installation of missing agents from registry").enablePositionalOptions();
 program.command("create-app").description("Scaffold a new Dexto Typescript app").action(async () => {
   try {
-    p2.intro(chalk15.inverse("Dexto Create App"));
+    p6.intro(chalk23.inverse("Dexto Create App"));
     const appPath = await createDextoProject();
     const userInput = await getUserInputToInitDextoApp();
     process.chdir(appPath);
@@ -4343,7 +5842,7 @@ program.command("create-app").description("Scaffold a new Dexto Typescript app")
       userInput.llmProvider,
       userInput.llmApiKey
     );
-    p2.outro(chalk15.greenBright("Dexto app created and initialized successfully!"));
+    p6.outro(chalk23.greenBright("Dexto app created and initialized successfully!"));
     await postCreateDexto(appPath, userInput.directory);
     process.exit(0);
   } catch (err) {
@@ -4355,7 +5854,7 @@ program.command("init-app").description("Initialize an existing Typescript app w
   try {
     await checkForFileInCurrentDirectory("package.json");
     await checkForFileInCurrentDirectory("tsconfig.json");
-    p2.intro(chalk15.inverse("Dexto Init App"));
+    p6.intro(chalk23.inverse("Dexto Init App"));
     const userInput = await getUserInputToInitDextoApp();
     await initDexto(
       userInput.directory,
@@ -4363,7 +5862,7 @@ program.command("init-app").description("Initialize an existing Typescript app w
       userInput.llmProvider,
       userInput.llmApiKey
     );
-    p2.outro(chalk15.greenBright("Dexto app initialized successfully!"));
+    p6.outro(chalk23.greenBright("Dexto app initialized successfully!"));
     await postInitDexto(userInput.directory);
     process.exit(0);
   } catch (err) {
@@ -4375,6 +5874,53 @@ program.command("init-app").description("Initialize an existing Typescript app w
     process.exit(1);
   }
 });
+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("--no-interactive", "Skip interactive prompts and API key setup").option("--force", "Overwrite existing setup without confirmation").action(async (options) => {
+  try {
+    await handleSetupCommand(options);
+    process.exit(0);
+  } catch (err) {
+    console.error(
+      `\u274C dexto setup command failed: ${err}. Check logs in ~/.dexto/logs/dexto.log for more information`
+    );
+    process.exit(1);
+  }
+});
+program.command("install [agents...]").description("Install agents from the registry").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").action(async (agents = [], options) => {
+  try {
+    await handleInstallCommand(agents, options);
+    process.exit(0);
+  } catch (err) {
+    console.error(`\u274C dexto install command failed: ${err}`);
+    process.exit(1);
+  }
+});
+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)").action(async (agents, options) => {
+  try {
+    await handleUninstallCommand(agents, options);
+    process.exit(0);
+  } catch (err) {
+    console.error(`\u274C dexto uninstall command failed: ${err}`);
+    process.exit(1);
+  }
+});
+program.command("list-agents").description("List available and installed agents").option("--verbose", "Show detailed agent information").option("--installed", "Show only installed agents").option("--available", "Show only available agents").action(async (options) => {
+  try {
+    await handleListAgentsCommand(options);
+    process.exit(0);
+  } catch (err) {
+    console.error(`\u274C dexto list-agents command failed: ${err}`);
+    process.exit(1);
+  }
+});
+program.command("which <agent>").description("Show the path to an agent").action(async (agent) => {
+  try {
+    await handleWhichCommand(agent);
+    process.exit(0);
+  } catch (err) {
+    console.error(`\u274C dexto which command failed: ${err}`);
+    process.exit(1);
+  }
+});
 program.command("mcp").description(
   "Start Dexto as an MCP server. Use --group-servers to aggregate and re-expose tools from configured MCP servers.         In the future, this command will expose the agent as an MCP server by default."
 ).option("-s, --strict", "Require all MCP server connections to succeed").option(
@@ -4390,9 +5936,14 @@ program.command("mcp").description(
       process.exit(1);
     }
     const globalOpts = program.opts();
-    const configPath = globalOpts.agent === DEFAULT_CONFIG_PATH ? void 0 : globalOpts.agent;
+    const nameOrPath = globalOpts.agent;
+    const configPath = await resolveAgentPath(
+      nameOrPath,
+      globalOpts.autoInstall !== false,
+      true
+    );
     const config = await loadAgentConfig(configPath);
-    console.log(`\u{1F4C4} Loading Dexto config from: ${resolveConfigPath(configPath)}`);
+    console.log(`\u{1F4C4} Loading Dexto config from: ${configPath}`);
     if (!config.mcpServers || Object.keys(config.mcpServers).length === 0) {
       console.error(
         "\u274C No MCP servers configured. Please configure mcpServers in your config file."
@@ -4424,38 +5975,30 @@ program.argument(
   "[prompt...]",
   "Natural-language prompt to run once. If not passed, dexto will start as an interactive CLI"
 ).description(
-  "Dexto CLI allows you to talk to Dexto, build custom AI Agents, build complex AI applications like Cursor, and more.\n\nRun dexto interactive CLI with `dexto` or run a one-shot prompt with `dexto <prompt>`\nStart with a new session using `dexto --new-session [sessionId]`\nRun dexto web UI with `dexto --mode web`\nRun dexto as a server (REST APIs + WebSockets) with `dexto --mode server`\nRun dexto as a discord bot with `dexto --mode discord`\nRun dexto as a telegram bot with `dexto --mode telegram`\nRun dexto agent as an MCP server with `dexto --mode mcp`\nRun dexto as an MCP server aggregator with `dexto mcp --group-servers`\n\nCheck subcommands for more features. Check https://github.com/truffle-ai/dexto for documentation on how to customize dexto and other examples"
+  'Dexto CLI allows you to talk to Dexto, build custom AI Agents, build complex AI applications like Cursor, and more.\n\nRun dexto interactive CLI with `dexto` or run a one-shot prompt with `dexto -p "<prompt>"` or `dexto "<prompt>"`\nStart with a new session using `dexto --new-session [sessionId]`\nRun dexto web UI with `dexto --mode web`\nRun dexto as a server (REST APIs + WebSockets) with `dexto --mode server`\nRun dexto as a discord bot with `dexto --mode discord`\nRun dexto as a telegram bot with `dexto --mode telegram`\nRun dexto agent as an MCP server with `dexto --mode mcp`\nRun dexto as an MCP server aggregator with `dexto mcp --group-servers`\n\nCheck subcommands for more features. Check https://github.com/truffle-ai/dexto for documentation on how to customize dexto and other examples'
 ).action(async (prompt = []) => {
-  if (!existsSync2(".env")) {
+  if (!existsSync4(".env")) {
     logger.debug("WARNING: .env file not found; copy .env.example and set your API keys.");
   }
-  const commonProviders = [
-    "openai",
-    "google",
-    "anthropic",
-    "groq",
-    "xai",
-    "cohere"
-  ];
-  const hasApiKey = commonProviders.some((provider) => resolveApiKeyForProvider(provider));
-  if (!hasApiKey) {
-    const { interactiveApiKeySetup } = await import("./interactive-api-key-setup-V3GAACLN.js");
-    const setupResult = await interactiveApiKeySetup();
-    if (!setupResult.success) {
-      if (setupResult.skipSetup) {
-        console.log(
-          chalk15.dim("\n\u{1F44B} Run dexto again once you have set up your API key!")
-        );
-      } else {
-        console.error(chalk15.red("\n\u274C API key setup required to continue."));
-      }
-      process.exit(0);
+  const opts = program.opts();
+  let headlessInput = void 0;
+  if (opts.prompt !== void 0 && String(opts.prompt).trim() !== "") {
+    headlessInput = String(opts.prompt);
+  } else if (opts.prompt !== void 0) {
+    console.error(
+      "\u274C For headless one-shot mode, prompt cannot be empty. Provide a non-empty prompt with -p/--prompt or use positional argument."
+    );
+    process.exit(1);
+  } else if (prompt.length > 0) {
+    if (prompt.length === 1) {
+      headlessInput = prompt[0];
+    } else {
+      console.error(
+        '\u274C For headless one-shot mode, pass the prompt in double quotes as a single argument (e.g., "say hello") or use -p/--prompt.'
+      );
+      process.exit(1);
     }
-    dotenv3.config();
-    console.log(chalk15.green("\n\u2728 API key configured! Starting Dexto...\n"));
   }
-  const opts = program.opts();
-  const headlessInput = prompt.join(" ") || void 0;
   if (opts.model) {
     let provider;
     try {
@@ -4480,25 +6023,54 @@ program.argument(
   } catch (err) {
     handleCliOptionsError(err);
   }
+  let validatedConfig;
+  let resolvedPath;
+  try {
+    if (opts.agent && isPath(opts.agent)) {
+      resolvedPath = await resolveAgentPath(opts.agent, opts.autoInstall !== false, true);
+    } else {
+      if (opts.agent) {
+        const registry = getAgentRegistry();
+        if (!registry.hasAgent(opts.agent)) {
+          console.error(`\u274C Agent '${opts.agent}' not found in registry`);
+          const available = Object.keys(registry.getAvailableAgents());
+          if (available.length > 0) {
+            console.log(`\u{1F4CB} Available agents: ${available.join(", ")}`);
+          } else {
+            console.log("\u{1F4CB} No agents available in registry");
+          }
+          process.exit(1);
+        }
+      }
+      if (await requiresSetup()) {
+        if (opts.interactive === false) {
+          console.error("\u274C Setup required but --no-interactive flag is set.");
+          console.error("\u{1F4A1} Run `dexto setup` to configure preferences first.");
+          process.exit(1);
+        }
+        await handleSetupCommand({ interactive: true });
+      }
+      resolvedPath = await resolveAgentPath(opts.agent, opts.autoInstall !== false, true);
+    }
+    const rawConfig = await loadAgentConfig(resolvedPath);
+    const mergedConfig = applyCLIOverrides(rawConfig, opts);
+    validatedConfig = await validateAgentConfig(mergedConfig, opts.interactive !== false);
+  } catch (err) {
+    console.error(`\u274C Failed to load configuration: ${err}`);
+    process.exit(1);
+  }
   let agent;
   try {
-    const configPath = opts.agent === DEFAULT_CONFIG_PATH ? void 0 : opts.agent;
-    console.log(`\u{1F680} Initializing Dexto with config: ${resolveConfigPath(configPath)}`);
-    const cfg = await loadAgentConfig(configPath);
-    const cliOverrides = {
-      model: opts.model,
-      provider: opts.provider,
-      router: opts.router,
-      apiKey: opts.apiKey
-    };
+    console.log(`\u{1F680} Initializing Dexto with config: ${resolvedPath}`);
     process.env.DEXTO_RUN_MODE = opts.mode;
-    const finalConfig = applyCLIOverrides(cfg, cliOverrides);
-    if (opts.strict && finalConfig.mcpServers) {
-      for (const [_serverName, serverConfig] of Object.entries(finalConfig.mcpServers)) {
+    if (opts.strict && validatedConfig.mcpServers) {
+      for (const [_serverName, serverConfig] of Object.entries(
+        validatedConfig.mcpServers
+      )) {
         serverConfig.connectionMode = "strict";
       }
     }
-    agent = new DextoAgent(finalConfig, configPath);
+    agent = new DextoAgent(validatedConfig, opts.agent);
     await agent.start();
     if (opts.newSession !== void 0) {
       try {
@@ -4519,7 +6091,7 @@ program.argument(
   }
   switch (opts.mode) {
     case "cli": {
-      const { CLIToolConfirmationSubscriber } = await import("./cli-confirmation-handler-2APQRKHG.js");
+      const { CLIToolConfirmationSubscriber } = await import("./cli-confirmation-handler-GJHPLGOL.js");
       const cliSubscriber = new CLIToolConfirmationSubscriber();
       cliSubscriber.subscribe(agent.agentEventBus);
       logger.info("Setting up CLI event subscriptions...");
@@ -4598,7 +6170,7 @@ program.argument(
             defaultBaseUrl: "stdio://local-dexto"
           },
           agentCardConfig
-          // preserve overrides from agent.yml
+          // preserve overrides from agent file
         );
         const mcpTransport = await createMcpTransport("stdio");
         await initializeMcpServer(agent, agentCardData, mcpTransport);