dexto 1.5.6 → 1.5.8

package/dist/config/cli-overrides.js

@@ -2,13 +2,21 @@
  * CLI-specific configuration types and utilities
  * This file handles CLI argument processing and config merging logic
  *
- * TODO: Future preference system enhancement
- * Currently, global preferences are only applied to the coding-agent at runtime.
- * Future improvements could include:
- * - Per-agent preference overrides (~/.dexto/agents/{id}/preferences.yml)
+ * Current behavior (Three-Layer LLM Resolution):
+ * Global preferences from preferences.yml are applied to ALL agents at runtime.
+ * See feature-plans/auto-update.md section 8.11 for the resolution order:
+ *   1. agent.local.yml llm section     → Agent-specific override (NOT YET IMPLEMENTED)
+ *   2. preferences.yml llm section     → User's global default (CURRENT)
+ *   3. agent.yml llm section           → Bundled fallback
+ *
+ * Note: Sub-agents spawned via RuntimeService have separate LLM resolution logic
+ * that tries to preserve the sub-agent's intended model when possible.
+ * See packages/agent-management/src/tool-provider/llm-resolution.ts
+ *
+ * TODO: Future enhancements
+ * - Per-agent local overrides (~/.dexto/agents/{id}/{id}.local.yml)
  * - Agent capability requirements (requires: { vision: true, toolUse: true })
- * - Merge strategy configuration (global > agent, agent > global, field-specific)
- * - User-controlled preference scopes via CLI flags (--prefer-global-llm)
+ * - Merge strategy configuration for non-LLM fields
  */
 /**
  * Applies CLI overrides to an agent configuration
@@ -59,9 +67,10 @@ export function applyCLIOverrides(baseConfig, cliOverrides) {
 }
 /**
  * Applies global user preferences to an agent configuration at runtime.
- * This is used for the coding-agent to ensure user's LLM preferences are applied.
+ * This is used to ensure user's LLM preferences are applied to all agents.
  *
  * Unlike writeLLMPreferences() which modifies files, this performs an in-memory merge.
+ * User preferences fully override agent defaults for provider, model, and apiKey.
  *
  * @param baseConfig The configuration loaded from agent file
  * @param preferences Global user preferences
@@ -70,21 +79,22 @@ export function applyCLIOverrides(baseConfig, cliOverrides) {
 export function applyUserPreferences(baseConfig, preferences) {
     // Create a deep copy to avoid mutating the original
     const mergedConfig = JSON.parse(JSON.stringify(baseConfig));
-    // Apply LLM preferences (user preferences override agent defaults)
-    if (preferences.llm) {
-        mergedConfig.llm = {
-            ...mergedConfig.llm,
-            provider: preferences.llm.provider,
-            model: preferences.llm.model,
-        };
-        // Only override apiKey if user has one configured
-        if (preferences.llm.apiKey) {
-            mergedConfig.llm.apiKey = preferences.llm.apiKey;
-        }
-        // Only override baseURL if user has one configured
-        if (preferences.llm.baseURL) {
-            mergedConfig.llm.baseURL = preferences.llm.baseURL;
-        }
+    // No LLM preferences to apply
+    if (!preferences.llm) {
+        return mergedConfig;
+    }
+    // Apply user preferences - only override if defined (preferences is Partial)
+    if (preferences.llm.provider) {
+        mergedConfig.llm.provider = preferences.llm.provider;
+    }
+    if (preferences.llm.model) {
+        mergedConfig.llm.model = preferences.llm.model;
+    }
+    if (preferences.llm.apiKey) {
+        mergedConfig.llm.apiKey = preferences.llm.apiKey;
+    }
+    if (preferences.llm.baseURL) {
+        mergedConfig.llm.baseURL = preferences.llm.baseURL;
     }
     return mergedConfig;
 }
@@ -140,6 +150,8 @@ function getEnvVarForProvider(provider) {
         groq: 'GROQ_API_KEY',
         xai: 'XAI_API_KEY',
         cohere: 'COHERE_API_KEY',
+        minimax: 'MINIMAX_API_KEY',
+        glm: 'ZHIPU_API_KEY',
         openrouter: 'OPENROUTER_API_KEY',
         litellm: 'LITELLM_API_KEY',
         glama: 'GLAMA_API_KEY',
@@ -148,6 +160,8 @@ function getEnvVarForProvider(provider) {
         // Local providers don't require API keys (empty string signals no key needed)
         local: '',
         ollama: '',
+        // Dexto gateway uses DEXTO_API_KEY from `dexto login`
+        'dexto-nova': 'DEXTO_API_KEY',
     };
     return envVarMap[provider];
 }

package/dist/config/effective-llm.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Effective LLM Configuration Resolution
+ *
+ * This module provides utilities to determine the effective LLM configuration
+ * at runtime, considering the layered config approach.
+ *
+ * ## Configuration Layers (Priority Order)
+ *
+ * 1. **agent.local.yml** (highest priority) - Agent-specific user overrides
+ *    - Path: `~/.dexto/agents/{agent-id}/{agent-id}.local.yml`
+ *    - Use case: User wants a specific agent to use a different LLM
+ *    - NOT YET IMPLEMENTED - see feature-plans/auto-update.md section 8.9-8.11
+ *
+ * 2. **preferences.yml** - User's global default LLM
+ *    - Path: `~/.dexto/preferences.yml`
+ *    - Use case: User's default choice from setup wizard or `/model` command
+ *    - This is where most users' LLM config comes from
+ *
+ * 3. **agent.yml** (lowest priority) - Bundled agent defaults
+ *    - Path: `~/.dexto/agents/{agent-id}/{agent-id}.yml`
+ *    - Use case: Fallback for users who skip setup or power users with BYOK
+ *    - This file is managed by Dexto and replaced on CLI updates
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { getEffectiveLLMConfig } from './config/effective-llm.js';
+ *
+ * const llm = await getEffectiveLLMConfig();
+ * if (llm?.provider === 'dexto-nova') {
+ *   // User is configured to use Dexto Nova credits
+ * }
+ *
+ * console.log(`Using ${llm.model} via ${llm.provider} (from ${llm.source})`);
+ * ```
+ *
+ * ## Related Documentation
+ *
+ * - feature-plans/auto-update.md - Layered config and .local.yml design
+ * - feature-plans/holistic-dexto-auth-analysis/ - Explicit provider routing
+ *
+ * @module effective-llm
+ */
+import type { LLMProvider } from '@dexto/core';
+/**
+ * Source of the effective LLM configuration
+ */
+export type LLMConfigSource = 'local' | 'preferences' | 'bundled';
+/**
+ * The resolved effective LLM configuration with source tracking
+ */
+export interface EffectiveLLMConfig {
+    /** LLM provider (e.g., 'dexto-nova', 'anthropic', 'openai') */
+    provider: LLMProvider;
+    /** Model identifier (format depends on provider) */
+    model: string;
+    /** API key or environment variable reference (e.g., '$DEXTO_API_KEY') */
+    apiKey?: string;
+    /** Base URL for custom endpoints */
+    baseURL?: string;
+    /** Where this config came from */
+    source: LLMConfigSource;
+}
+/**
+ * Options for getEffectiveLLMConfig
+ */
+export interface GetEffectiveLLMConfigOptions {
+    /**
+     * Agent ID to resolve config for.
+     * @default 'coding-agent'
+     */
+    agentId?: string;
+    /**
+     * Whether to include the bundled agent config as fallback.
+     * Set to false if you only want user-configured LLM.
+     * @default true
+     */
+    includeBundledFallback?: boolean;
+}
+/**
+ * Get the effective LLM configuration considering all config layers.
+ *
+ * This function resolves which LLM config will actually be used at runtime
+ * by checking each layer in priority order:
+ *
+ * 1. agent.local.yml (NOT YET IMPLEMENTED)
+ * 2. preferences.yml
+ * 3. bundled agent.yml (if includeBundledFallback is true)
+ *
+ * @param options - Configuration options
+ * @returns The effective LLM config with source, or null if none found
+ *
+ * @example
+ * ```typescript
+ * // Get effective LLM for default agent
+ * const llm = await getEffectiveLLMConfig();
+ *
+ * // Get effective LLM for a specific agent
+ * const llm = await getEffectiveLLMConfig({ agentId: 'explore-agent' });
+ *
+ * // Only get user-configured LLM (no bundled fallback)
+ * const llm = await getEffectiveLLMConfig({ includeBundledFallback: false });
+ * ```
+ */
+export declare function getEffectiveLLMConfig(options?: GetEffectiveLLMConfigOptions): Promise<EffectiveLLMConfig | null>;
+/**
+ * Check if the effective LLM config uses Dexto credits.
+ *
+ * Convenience function that checks if the user is configured to use
+ * the Dexto provider (which requires authentication).
+ *
+ * @param options - Same options as getEffectiveLLMConfig
+ * @returns true if using provider: dexto-nova, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (await isUsingDextoCredits()) {
+ *   // Check authentication, show billing info, etc.
+ * }
+ * ```
+ */
+export declare function isUsingDextoCredits(options?: GetEffectiveLLMConfigOptions): Promise<boolean>;
+//# sourceMappingURL=effective-llm.d.ts.map

package/dist/config/effective-llm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effective-llm.d.ts","sourceRoot":"","sources":["../../src/config/effective-llm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAS/C;;GAEG;AACH,MAAM,MAAM,eAAe,GACrB,OAAO,GACP,aAAa,GACb,SAAS,CAAC;AAEhB;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAC/B,+DAA+D;IAC/D,QAAQ,EAAE,WAAW,CAAC;IACtB,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,MAAM,EAAE,eAAe,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,4BAA4B;IACzC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,qBAAqB,CACvC,OAAO,GAAE,4BAAiC,GAC3C,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAsFpC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,mBAAmB,CACrC,OAAO,GAAE,4BAAiC,GAC3C,OAAO,CAAC,OAAO,CAAC,CAGlB"}

package/dist/config/effective-llm.js

@@ -0,0 +1,171 @@
+/**
+ * Effective LLM Configuration Resolution
+ *
+ * This module provides utilities to determine the effective LLM configuration
+ * at runtime, considering the layered config approach.
+ *
+ * ## Configuration Layers (Priority Order)
+ *
+ * 1. **agent.local.yml** (highest priority) - Agent-specific user overrides
+ *    - Path: `~/.dexto/agents/{agent-id}/{agent-id}.local.yml`
+ *    - Use case: User wants a specific agent to use a different LLM
+ *    - NOT YET IMPLEMENTED - see feature-plans/auto-update.md section 8.9-8.11
+ *
+ * 2. **preferences.yml** - User's global default LLM
+ *    - Path: `~/.dexto/preferences.yml`
+ *    - Use case: User's default choice from setup wizard or `/model` command
+ *    - This is where most users' LLM config comes from
+ *
+ * 3. **agent.yml** (lowest priority) - Bundled agent defaults
+ *    - Path: `~/.dexto/agents/{agent-id}/{agent-id}.yml`
+ *    - Use case: Fallback for users who skip setup or power users with BYOK
+ *    - This file is managed by Dexto and replaced on CLI updates
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { getEffectiveLLMConfig } from './config/effective-llm.js';
+ *
+ * const llm = await getEffectiveLLMConfig();
+ * if (llm?.provider === 'dexto-nova') {
+ *   // User is configured to use Dexto Nova credits
+ * }
+ *
+ * console.log(`Using ${llm.model} via ${llm.provider} (from ${llm.source})`);
+ * ```
+ *
+ * ## Related Documentation
+ *
+ * - feature-plans/auto-update.md - Layered config and .local.yml design
+ * - feature-plans/holistic-dexto-auth-analysis/ - Explicit provider routing
+ *
+ * @module effective-llm
+ */
+import { loadGlobalPreferences, globalPreferencesExist, loadAgentConfig, resolveAgentPath, } from '@dexto/agent-management';
+import { logger } from '@dexto/core';
+/**
+ * Get the effective LLM configuration considering all config layers.
+ *
+ * This function resolves which LLM config will actually be used at runtime
+ * by checking each layer in priority order:
+ *
+ * 1. agent.local.yml (NOT YET IMPLEMENTED)
+ * 2. preferences.yml
+ * 3. bundled agent.yml (if includeBundledFallback is true)
+ *
+ * @param options - Configuration options
+ * @returns The effective LLM config with source, or null if none found
+ *
+ * @example
+ * ```typescript
+ * // Get effective LLM for default agent
+ * const llm = await getEffectiveLLMConfig();
+ *
+ * // Get effective LLM for a specific agent
+ * const llm = await getEffectiveLLMConfig({ agentId: 'explore-agent' });
+ *
+ * // Only get user-configured LLM (no bundled fallback)
+ * const llm = await getEffectiveLLMConfig({ includeBundledFallback: false });
+ * ```
+ */
+export async function getEffectiveLLMConfig(options = {}) {
+    const { agentId = 'coding-agent', includeBundledFallback = true } = options;
+    // -------------------------------------------------------------------------
+    // Layer 1: agent.local.yml (NOT YET IMPLEMENTED)
+    // -------------------------------------------------------------------------
+    // TODO: Implement .local.yml loading when the feature is built
+    // See feature-plans/auto-update.md section 8.9-8.11 for the design
+    //
+    // The implementation would look something like:
+    //
+    // const localConfig = await loadLocalAgentConfig(agentId);
+    // if (localConfig?.llm?.provider && localConfig?.llm?.model) {
+    //     logger.debug(`Using LLM config from ${agentId}.local.yml`);
+    //     return {
+    //         provider: localConfig.llm.provider,
+    //         model: localConfig.llm.model,
+    //         apiKey: localConfig.llm.apiKey,
+    //         baseURL: localConfig.llm.baseURL,
+    //         source: 'local',
+    //     };
+    // }
+    // -------------------------------------------------------------------------
+    // -------------------------------------------------------------------------
+    // Layer 2: preferences.yml (user's global default)
+    // -------------------------------------------------------------------------
+    if (globalPreferencesExist()) {
+        try {
+            const preferences = await loadGlobalPreferences();
+            if (preferences?.llm?.provider && preferences?.llm?.model) {
+                logger.debug('Using LLM config from preferences.yml');
+                const result = {
+                    provider: preferences.llm.provider,
+                    model: preferences.llm.model,
+                    source: 'preferences',
+                };
+                // Only set optional fields if they have values
+                if (preferences.llm.apiKey) {
+                    result.apiKey = preferences.llm.apiKey;
+                }
+                if (preferences.llm.baseURL) {
+                    result.baseURL = preferences.llm.baseURL;
+                }
+                return result;
+            }
+        }
+        catch (error) {
+            logger.debug(`Could not load preferences: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Layer 3: Bundled agent.yml (fallback)
+    // -------------------------------------------------------------------------
+    if (includeBundledFallback) {
+        try {
+            const agentPath = await resolveAgentPath(agentId);
+            if (agentPath) {
+                const agentConfig = await loadAgentConfig(agentPath);
+                if (agentConfig?.llm?.provider && agentConfig?.llm?.model) {
+                    logger.debug(`Using LLM config from bundled ${agentId}.yml`);
+                    const result = {
+                        provider: agentConfig.llm.provider,
+                        model: agentConfig.llm.model,
+                        source: 'bundled',
+                    };
+                    // Only set optional fields if they have values
+                    if (agentConfig.llm.apiKey) {
+                        result.apiKey = agentConfig.llm.apiKey;
+                    }
+                    if (agentConfig.llm.baseURL) {
+                        result.baseURL = agentConfig.llm.baseURL;
+                    }
+                    return result;
+                }
+            }
+        }
+        catch (error) {
+            logger.debug(`Could not load agent config: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return null;
+}
+/**
+ * Check if the effective LLM config uses Dexto credits.
+ *
+ * Convenience function that checks if the user is configured to use
+ * the Dexto provider (which requires authentication).
+ *
+ * @param options - Same options as getEffectiveLLMConfig
+ * @returns true if using provider: dexto-nova, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (await isUsingDextoCredits()) {
+ *   // Check authentication, show billing info, etc.
+ * }
+ * ```
+ */
+export async function isUsingDextoCredits(options = {}) {
+    const config = await getEffectiveLLMConfig(options);
+    return config?.provider === 'dexto-nova';
+}