@within-7/minto 0.4.0 → 0.4.2

package/dist/utils/CircuitBreaker.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/utils/CircuitBreaker.ts"],
-  "sourcesContent": ["/**\n * Circuit Breaker pattern implementation for handling failing services gracefully\n *\n * States:\n * - CLOSED: Service is healthy, requests pass through normally\n * - OPEN: Service is unhealthy, requests fail immediately\n * - HALF_OPEN: Testing if service has recovered, limited requests allowed\n *\n * Transitions:\n * - CLOSED \u2192 OPEN: When failure count exceeds threshold\n * - OPEN \u2192 HALF_OPEN: After cooldown timeout\n * - HALF_OPEN \u2192 CLOSED: When success count exceeds threshold\n * - HALF_OPEN \u2192 OPEN: When a request fails\n */\n\nexport interface CircuitBreakerConfig {\n  /** Number of failures that trigger opening the circuit (default: 5) */\n  failureThreshold: number\n  /** Number of successful requests needed to close circuit from HALF_OPEN (default: 2) */\n  successThreshold: number\n  /** Time in ms before transitioning from OPEN to HALF_OPEN (default: 30000) */\n  openTimeout: number\n  /** Optional timeout in ms for operations (default: none) */\n  halfOpenTimeout?: number\n}\n\nexport class CircuitOpenError extends Error {\n  constructor(\n    public readonly remainingCooldown: number,\n    serverName?: string,\n  ) {\n    const message = serverName\n      ? `Circuit breaker for \"${serverName}\" is open. Retry in ${Math.ceil(remainingCooldown / 1000)}s`\n      : `Circuit breaker is open. Retry in ${Math.ceil(remainingCooldown / 1000)}s`\n    super(message)\n    this.name = 'CircuitOpenError'\n  }\n}\n\nexport type CircuitBreakerState = 'closed' | 'open' | 'half-open'\n\nexport interface CircuitBreakerStats {\n  state: CircuitBreakerState\n  failureCount: number\n  successCount: number\n  lastFailureTime: number | null\n  totalRequests: number\n  totalFailures: number\n}\n\nexport type CircuitBreakerListener = (\n  event: 'state-change' | 'failure' | 'success',\n  details: {\n    state?: CircuitBreakerState\n    previousState?: CircuitBreakerState\n    error?: Error\n  },\n) => void\n\n/**\n * Circuit Breaker implementation for fault tolerance\n *\n * Prevents cascading failures by failing fast when a service is unhealthy,\n * while automatically attempting recovery when the service potentially recovers.\n */\nexport class CircuitBreaker<T = unknown> {\n  private state: CircuitBreakerState = 'closed'\n  private failureCount: number = 0\n  private successCount: number = 0\n  private lastFailureTime: number | null = null\n  private readonly config: Required<CircuitBreakerConfig>\n  private readonly listeners: Set<CircuitBreakerListener> = new Set()\n  private readonly name: string\n  private totalRequests: number = 0\n  private totalFailures: number = 0\n\n  constructor(\n    name: string = 'default',\n    config?: Partial<CircuitBreakerConfig>,\n  ) {\n    this.name = name\n    this.config = {\n      failureThreshold: config?.failureThreshold ?? 5,\n      successThreshold: config?.successThreshold ?? 2,\n      openTimeout: config?.openTimeout ?? 30000,\n      halfOpenTimeout: config?.halfOpenTimeout ?? 30000,\n    }\n  }\n\n  /**\n   * Execute an operation through the circuit breaker\n   * @throws {CircuitOpenError} If circuit is open\n   * @throws {Error} If operation fails\n   */\n  async execute<R>(operation: () => Promise<R>): Promise<R> {\n    this.totalRequests++\n\n    // Check if we need to transition from OPEN to HALF_OPEN\n    if (this.state === 'open') {\n      const cooldownRemaining = this.getRemainingCooldown()\n      if (cooldownRemaining <= 0) {\n        this.transition('half-open')\n      } else {\n        const error = new CircuitOpenError(cooldownRemaining, this.name)\n        this.notifyListeners('failure', { error })\n        throw error\n      }\n    }\n\n    // Execute the operation\n    try {\n      const result = await operation()\n      this.onSuccess()\n      return result\n    } catch (error) {\n      this.onFailure(error instanceof Error ? error : new Error(String(error)))\n      throw error\n    }\n  }\n\n  /**\n   * Execute with timeout protection\n   * @throws {CircuitOpenError} If circuit is open\n   * @throws {Error} If operation times out or fails\n   */\n  async executeWithTimeout<R>(\n    operation: () => Promise<R>,\n    timeoutMs?: number,\n  ): Promise<R> {\n    const timeout = timeoutMs ?? this.config.halfOpenTimeout\n    if (!timeout) {\n      return this.execute(operation)\n    }\n\n    return Promise.race([\n      this.execute(operation),\n      new Promise<R>((_, reject) =>\n        setTimeout(\n          () => reject(new Error(`Operation timeout after ${timeout}ms`)),\n          timeout,\n        ),\n      ),\n    ])\n  }\n\n  /**\n   * Get current circuit state\n   */\n  getState(): CircuitBreakerState {\n    return this.state\n  }\n\n  /**\n   * Get detailed statistics\n   */\n  getStats(): CircuitBreakerStats {\n    return {\n      state: this.state,\n      failureCount: this.failureCount,\n      successCount: this.successCount,\n      lastFailureTime: this.lastFailureTime,\n      totalRequests: this.totalRequests,\n      totalFailures: this.totalFailures,\n    }\n  }\n\n  /**\n   * Get remaining cooldown time in milliseconds\n   */\n  getRemainingCooldown(): number {\n    if (!this.lastFailureTime) {\n      return 0\n    }\n    return Math.max(\n      0,\n      this.config.openTimeout - (Date.now() - this.lastFailureTime),\n    )\n  }\n\n  /**\n   * Register a listener for state changes and events\n   */\n  on(listener: CircuitBreakerListener): () => void {\n    this.listeners.add(listener)\n    return () => {\n      this.listeners.delete(listener)\n    }\n  }\n\n  /**\n   * Reset the circuit breaker to CLOSED state\n   */\n  reset(): void {\n    const previousState = this.state\n    this.state = 'closed'\n    this.failureCount = 0\n    this.successCount = 0\n    this.lastFailureTime = null\n    this.totalRequests = 0\n    this.totalFailures = 0\n\n    this.notifyListeners('state-change', {\n      state: this.state,\n      previousState,\n    })\n  }\n\n  /**\n   * Manually open the circuit (for testing or explicit fault injection)\n   */\n  forceOpen(): void {\n    this.transition('open')\n  }\n\n  /**\n   * Manually close the circuit (for recovery testing)\n   */\n  forceClosed(): void {\n    this.transition('closed')\n  }\n\n  /**\n   * Manually transition to half-open state (for testing)\n   */\n  forceHalfOpen(): void {\n    this.transition('half-open')\n  }\n\n  // Private methods\n\n  private transition(newState: CircuitBreakerState): void {\n    if (newState === this.state) {\n      return\n    }\n\n    const previousState = this.state\n    this.state = newState\n\n    // Reset counters on state transition\n    if (newState === 'closed') {\n      this.failureCount = 0\n      this.successCount = 0\n    } else if (newState === 'half-open') {\n      this.successCount = 0\n      this.failureCount = 0\n    }\n\n    this.notifyListeners('state-change', {\n      state: newState,\n      previousState,\n    })\n  }\n\n  private onSuccess(): void {\n    if (this.state === 'half-open') {\n      this.successCount++\n      if (this.successCount >= this.config.successThreshold) {\n        this.transition('closed')\n      }\n    } else if (this.state === 'closed') {\n      this.failureCount = 0\n    }\n\n    this.notifyListeners('success', {})\n  }\n\n  private onFailure(error: Error): void {\n    this.failureCount++\n    this.totalFailures++\n    this.lastFailureTime = Date.now()\n\n    if (this.state === 'closed') {\n      if (this.failureCount >= this.config.failureThreshold) {\n        this.transition('open')\n      }\n    } else if (this.state === 'half-open') {\n      // Any failure in half-open state goes back to open\n      this.transition('open')\n    }\n\n    this.notifyListeners('failure', { error })\n  }\n\n  private notifyListeners(\n    event: 'state-change' | 'failure' | 'success',\n    details: {\n      state?: CircuitBreakerState\n      previousState?: CircuitBreakerState\n      error?: Error\n    },\n  ): void {\n    for (const listener of this.listeners) {\n      try {\n        listener(event, details)\n      } catch {\n        // Ignore listener errors to prevent them from affecting the circuit\n      }\n    }\n  }\n}\n\n/**\n * Create a simple factory for managing multiple circuit breakers\n */\nexport class CircuitBreakerRegistry {\n  private readonly breakers = new Map<string, CircuitBreaker>()\n  private readonly defaultConfig?: Partial<CircuitBreakerConfig>\n\n  constructor(defaultConfig?: Partial<CircuitBreakerConfig>) {\n    this.defaultConfig = defaultConfig\n  }\n\n  /**\n   * Get or create a circuit breaker by name\n   */\n  getOrCreate(\n    name: string,\n    config?: Partial<CircuitBreakerConfig>,\n  ): CircuitBreaker {\n    if (!this.breakers.has(name)) {\n      const mergedConfig = { ...this.defaultConfig, ...config }\n      this.breakers.set(name, new CircuitBreaker(name, mergedConfig))\n    }\n    return this.breakers.get(name)!\n  }\n\n  /**\n   * Get all registered circuit breakers\n   */\n  getAll(): Map<string, CircuitBreaker> {\n    return new Map(this.breakers)\n  }\n\n  /**\n   * Reset all circuit breakers\n   */\n  resetAll(): void {\n    for (const breaker of this.breakers.values()) {\n      breaker.reset()\n    }\n  }\n\n  /**\n   * Clear all circuit breakers\n   */\n  clear(): void {\n    this.breakers.clear()\n  }\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["/**\n * Circuit Breaker pattern implementation for handling failing services gracefully\n *\n * States:\n * - CLOSED: Service is healthy, requests pass through normally\n * - OPEN: Service is unhealthy, requests fail immediately\n * - HALF_OPEN: Testing if service has recovered, limited requests allowed\n *\n * Transitions:\n * - CLOSED \u2192 OPEN: When failure count exceeds threshold\n * - OPEN \u2192 HALF_OPEN: After cooldown timeout\n * - HALF_OPEN \u2192 CLOSED: When success count exceeds threshold\n * - HALF_OPEN \u2192 OPEN: When a request fails\n */\n\nexport interface CircuitBreakerConfig {\n  /** Number of failures that trigger opening the circuit (default: 5) */\n  failureThreshold: number\n  /** Number of successful requests needed to close circuit from HALF_OPEN (default: 2) */\n  successThreshold: number\n  /** Time in ms before transitioning from OPEN to HALF_OPEN (default: 30000) */\n  openTimeout: number\n  /** Optional timeout in ms for operations (default: none) */\n  halfOpenTimeout?: number\n}\n\nexport class CircuitOpenError extends Error {\n  constructor(\n    public readonly remainingCooldown: number,\n    serverName?: string,\n  ) {\n    const message = serverName\n      ? `Circuit breaker for \"${serverName}\" is open. Retry in ${Math.ceil(remainingCooldown / 1000)}s`\n      : `Circuit breaker is open. Retry in ${Math.ceil(remainingCooldown / 1000)}s`\n    super(message)\n    this.name = 'CircuitOpenError'\n  }\n}\n\nexport type CircuitBreakerState = 'closed' | 'open' | 'half-open'\n\nexport interface CircuitBreakerStats {\n  state: CircuitBreakerState\n  failureCount: number\n  successCount: number\n  lastFailureTime: number | null\n  totalRequests: number\n  totalFailures: number\n}\n\nexport type CircuitBreakerListener = (\n  event: 'state-change' | 'failure' | 'success',\n  details: {\n    state?: CircuitBreakerState\n    previousState?: CircuitBreakerState\n    error?: Error\n  },\n) => void\n\n/**\n * Circuit Breaker implementation for fault tolerance\n *\n * Prevents cascading failures by failing fast when a service is unhealthy,\n * while automatically attempting recovery when the service potentially recovers.\n */\nexport class CircuitBreaker<T = unknown> {\n  private state: CircuitBreakerState = 'closed'\n  private failureCount: number = 0\n  private successCount: number = 0\n  private lastFailureTime: number | null = null\n  private readonly config: Required<CircuitBreakerConfig>\n  private readonly listeners: Set<CircuitBreakerListener> = new Set()\n  private readonly name: string\n  private totalRequests: number = 0\n  private totalFailures: number = 0\n\n  constructor(\n    name: string = 'default',\n    config?: Partial<CircuitBreakerConfig>,\n  ) {\n    this.name = name\n    this.config = {\n      failureThreshold: config?.failureThreshold ?? 5,\n      successThreshold: config?.successThreshold ?? 2,\n      openTimeout: config?.openTimeout ?? 30000,\n      halfOpenTimeout: config?.halfOpenTimeout ?? 30000,\n    }\n  }\n\n  /**\n   * Execute an operation through the circuit breaker\n   * @throws {CircuitOpenError} If circuit is open\n   * @throws {Error} If operation fails\n   */\n  async execute<R>(operation: () => Promise<R>): Promise<R> {\n    this.totalRequests++\n\n    // Check if we need to transition from OPEN to HALF_OPEN\n    if (this.state === 'open') {\n      const cooldownRemaining = this.getRemainingCooldown()\n      if (cooldownRemaining <= 0) {\n        this.transition('half-open')\n      } else {\n        const error = new CircuitOpenError(cooldownRemaining, this.name)\n        this.notifyListeners('failure', { error })\n        throw error\n      }\n    }\n\n    // Execute the operation\n    try {\n      const result = await operation()\n      this.onSuccess()\n      return result\n    } catch (error) {\n      this.onFailure(error instanceof Error ? error : new Error(String(error)))\n      throw error\n    }\n  }\n\n  /**\n   * Execute with timeout protection\n   * @throws {CircuitOpenError} If circuit is open\n   * @throws {Error} If operation times out or fails\n   */\n  async executeWithTimeout<R>(\n    operation: () => Promise<R>,\n    timeoutMs?: number,\n  ): Promise<R> {\n    const timeout = timeoutMs ?? this.config.halfOpenTimeout\n    if (!timeout) {\n      return this.execute(operation)\n    }\n\n    let timeoutId: ReturnType<typeof setTimeout> | undefined\n    try {\n      const result = await Promise.race([\n        this.execute(operation),\n        new Promise<R>((_, reject) => {\n          timeoutId = setTimeout(\n            () => reject(new Error(`Operation timeout after ${timeout}ms`)),\n            timeout,\n          )\n        }),\n      ])\n      return result\n    } finally {\n      if (timeoutId !== undefined) clearTimeout(timeoutId)\n    }\n  }\n\n  /**\n   * Get current circuit state\n   */\n  getState(): CircuitBreakerState {\n    return this.state\n  }\n\n  /**\n   * Get detailed statistics\n   */\n  getStats(): CircuitBreakerStats {\n    return {\n      state: this.state,\n      failureCount: this.failureCount,\n      successCount: this.successCount,\n      lastFailureTime: this.lastFailureTime,\n      totalRequests: this.totalRequests,\n      totalFailures: this.totalFailures,\n    }\n  }\n\n  /**\n   * Get remaining cooldown time in milliseconds\n   */\n  getRemainingCooldown(): number {\n    if (!this.lastFailureTime) {\n      return 0\n    }\n    return Math.max(\n      0,\n      this.config.openTimeout - (Date.now() - this.lastFailureTime),\n    )\n  }\n\n  /**\n   * Register a listener for state changes and events\n   */\n  on(listener: CircuitBreakerListener): () => void {\n    this.listeners.add(listener)\n    return () => {\n      this.listeners.delete(listener)\n    }\n  }\n\n  /**\n   * Reset the circuit breaker to CLOSED state\n   */\n  reset(): void {\n    const previousState = this.state\n    this.state = 'closed'\n    this.failureCount = 0\n    this.successCount = 0\n    this.lastFailureTime = null\n    this.totalRequests = 0\n    this.totalFailures = 0\n\n    this.notifyListeners('state-change', {\n      state: this.state,\n      previousState,\n    })\n  }\n\n  /**\n   * Manually open the circuit (for testing or explicit fault injection)\n   */\n  forceOpen(): void {\n    this.transition('open')\n  }\n\n  /**\n   * Manually close the circuit (for recovery testing)\n   */\n  forceClosed(): void {\n    this.transition('closed')\n  }\n\n  /**\n   * Manually transition to half-open state (for testing)\n   */\n  forceHalfOpen(): void {\n    this.transition('half-open')\n  }\n\n  // Private methods\n\n  private transition(newState: CircuitBreakerState): void {\n    if (newState === this.state) {\n      return\n    }\n\n    const previousState = this.state\n    this.state = newState\n\n    // Reset counters on state transition\n    if (newState === 'closed') {\n      this.failureCount = 0\n      this.successCount = 0\n    } else if (newState === 'half-open') {\n      this.successCount = 0\n      this.failureCount = 0\n    }\n\n    this.notifyListeners('state-change', {\n      state: newState,\n      previousState,\n    })\n  }\n\n  private onSuccess(): void {\n    if (this.state === 'half-open') {\n      this.successCount++\n      if (this.successCount >= this.config.successThreshold) {\n        this.transition('closed')\n      }\n    } else if (this.state === 'closed') {\n      this.failureCount = 0\n    }\n\n    this.notifyListeners('success', {})\n  }\n\n  private onFailure(error: Error): void {\n    this.failureCount++\n    this.totalFailures++\n    this.lastFailureTime = Date.now()\n\n    if (this.state === 'closed') {\n      if (this.failureCount >= this.config.failureThreshold) {\n        this.transition('open')\n      }\n    } else if (this.state === 'half-open') {\n      // Any failure in half-open state goes back to open\n      this.transition('open')\n    }\n\n    this.notifyListeners('failure', { error })\n  }\n\n  private notifyListeners(\n    event: 'state-change' | 'failure' | 'success',\n    details: {\n      state?: CircuitBreakerState\n      previousState?: CircuitBreakerState\n      error?: Error\n    },\n  ): void {\n    for (const listener of this.listeners) {\n      try {\n        listener(event, details)\n      } catch {\n        // Ignore listener errors to prevent them from affecting the circuit\n      }\n    }\n  }\n}\n\n/**\n * Create a simple factory for managing multiple circuit breakers\n */\nexport class CircuitBreakerRegistry {\n  private readonly breakers = new Map<string, CircuitBreaker>()\n  private readonly defaultConfig?: Partial<CircuitBreakerConfig>\n\n  constructor(defaultConfig?: Partial<CircuitBreakerConfig>) {\n    this.defaultConfig = defaultConfig\n  }\n\n  /**\n   * Get or create a circuit breaker by name\n   */\n  getOrCreate(\n    name: string,\n    config?: Partial<CircuitBreakerConfig>,\n  ): CircuitBreaker {\n    if (!this.breakers.has(name)) {\n      const mergedConfig = { ...this.defaultConfig, ...config }\n      this.breakers.set(name, new CircuitBreaker(name, mergedConfig))\n    }\n    return this.breakers.get(name)!\n  }\n\n  /**\n   * Get all registered circuit breakers\n   */\n  getAll(): Map<string, CircuitBreaker> {\n    return new Map(this.breakers)\n  }\n\n  /**\n   * Reset all circuit breakers\n   */\n  resetAll(): void {\n    for (const breaker of this.breakers.values()) {\n      breaker.reset()\n    }\n  }\n\n  /**\n   * Clear all circuit breakers\n   */\n  clear(): void {\n    this.breakers.clear()\n  }\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/utils/agentLoader.js

@@ -1,16 +1,13 @@
-import {
-  existsSync,
-  readFileSync,
-  readdirSync,
-  statSync,
-  watch
-} from "fs";
+import { existsSync, readFileSync, watch } from "fs";
+import { readdir, stat, readFile } from "fs/promises";
 import { join } from "path";
 import { homedir } from "os";
 import matter from "gray-matter";
 import { getCwd } from "./state.js";
 import { memoize } from "lodash-es";
+import { LRUCache } from "lru-cache";
 import { loadAllPlugins } from "./pluginLoader.js";
+import { debug as debugLog } from "./debugLogger.js";
 const warnedAgents = /* @__PURE__ */ new Set();
 const BUILTIN_AGENTS = [
   // general-purpose: Default agent for multi-step tasks
@@ -72,30 +69,89 @@ You are READ-ONLY. You cannot modify any files.`,
     // Inherit caller's model
     permissionMode: "plan",
     // Read-only mode
-    systemPrompt: `You are a planning agent specialized in analyzing codebases and creating implementation plans.
+    systemPrompt: `You are a planning agent. Analyze the codebase and create an implementation plan.
+
+Your output must include:
+1. Context \u2014 Problem being solved, motivation, intended outcome
+2. Critical file paths \u2014 All files to modify/create
+3. Recommended approach \u2014 Step-by-step plan referencing existing utilities and patterns
+4. Verification \u2014 Testing procedures for end-to-end validation
+
+Guidelines:
+- Read relevant files to understand current patterns before designing
+- Identify reusable utilities and existing conventions
+- Consider edge cases and dependencies
+- Be specific and actionable \u2014 reference exact file paths and function names
+
+You are READ-ONLY. You cannot modify any files. Focus on planning, not execution.`,
+    location: "built-in"
+  },
+  // output-style-setup: Agent for creating custom output styles
+  {
+    agentType: "output-style-setup",
+    whenToUse: "Agent for creating and customizing output display styles. Use this when you need to help the user configure how Minto formats and displays tool results, assistant responses, or status messages.",
+    tools: ["Read", "Write", "Edit", "Glob", "Grep"],
+    model_name: "main",
+    systemPrompt: `You are an output style configuration agent for Minto CLI.
 
 Your role:
-- Understand requirements and constraints
-- Analyze existing code patterns and architecture
-- Create detailed, step-by-step implementation plans
-- Identify potential issues and trade-offs
-- Recommend best approaches based on codebase conventions
+- Help users create custom output styles for Minto's terminal display
+- Modify style configuration files to adjust formatting, colors, and layout
+- Read existing style files to understand current configuration
 
 Guidelines:
-- Read relevant files to understand current patterns
-- Identify all files that will need modification
-- Consider edge cases and error handling
-- Note any dependencies or prerequisites
-- Provide specific, actionable steps
+- Check existing style files in .minto/ and src/utils/style.ts first
+- Follow the existing code style pattern exactly
+- Make minimal, focused changes
+- Validate that style changes won't break existing functionality`,
+    location: "built-in"
+  },
+  // statusline-setup: Agent for configuring the status line
+  {
+    agentType: "statusline-setup",
+    whenToUse: "Agent for configuring the Minto CLI status line. Use this when the user wants to customize what information appears in the bottom status bar (model name, token count, costs, git branch, etc.).",
+    tools: ["Read", "Edit"],
+    model_name: "main",
+    systemPrompt: `You are a status line configuration agent for Minto CLI.
 
-Output format:
-1. Summary of the task
-2. Files to modify/create (with paths)
-3. Step-by-step implementation plan
-4. Potential challenges or considerations
-5. Testing approach
+Your role:
+- Help users configure the status line (bottom bar) display
+- Modify status line settings to show/hide specific information segments
+- Adjust the layout and formatting of the status line
 
-You are READ-ONLY. You cannot modify any files. Focus on planning, not execution.`,
+Guidelines:
+- Read existing status line configuration first
+- The status line is rendered by Ink components in src/screens/
+- Make minimal changes to configuration values
+- Preserve existing formatting patterns`,
+    location: "built-in"
+  },
+  // minto-guide: Agent for answering questions about Minto CLI features
+  {
+    agentType: "minto-guide",
+    whenToUse: "Knowledge agent for answering questions about Minto CLI features, configuration, and usage. Use this when the user asks how to use a feature, what commands are available, or needs help understanding Minto capabilities.",
+    tools: ["Glob", "Grep", "Read", "WebFetch", "WebSearch"],
+    disallowedTools: ["Edit", "Write", "Bash", "NotebookEdit"],
+    model_name: "quick",
+    permissionMode: "plan",
+    systemPrompt: `You are a Minto CLI guide and knowledge agent.
+
+Your role:
+- Answer questions about Minto CLI features and capabilities
+- Explain how to configure models, agents, plugins, and hooks
+- Help users understand available commands and slash commands
+- Provide usage examples and best practices
+
+Guidelines:
+- Search the codebase to find accurate, up-to-date information
+- Check CLAUDE.md and MINTO.md files for project documentation
+- Look at src/commands/ for available commands
+- Look at src/tools/ for available tools
+- Look at src/utils/agentLoader.ts for agent configuration
+- Provide specific file paths and code references when helpful
+- Be concise but thorough in explanations
+
+You are READ-ONLY. You cannot modify any files.`,
     location: "built-in"
   },
   // Bash: Shell command execution agent (Claude Code spec)
@@ -196,6 +252,7 @@ function parsePermissionMode(mode) {
     "acceptEdits",
     "dontAsk",
     "plan",
+    "delegate",
     "bypassPermissions"
   ];
   if (typeof mode === "string" && validModes.includes(mode)) {
@@ -209,76 +266,116 @@ async function scanAgentDirectory(dirPath, location) {
   }
   const agents = [];
   try {
-    const files = readdirSync(dirPath);
-    for (const file of files) {
-      if (!file.endsWith(".md")) continue;
-      const filePath = join(dirPath, file);
-      const stat = statSync(filePath);
-      if (!stat.isFile()) continue;
-      try {
-        const content = readFileSync(filePath, "utf-8");
-        if (!content.trim()) continue;
-        const { data: frontmatter, content: body } = matter(content);
-        if (!frontmatter.name || !frontmatter.description) {
-          const headingMatch = body.match(/^#\s+(.+)/m);
-          const firstParagraph = body.split(/\n\n/).find((p) => p.trim() && !p.trim().startsWith("#"));
-          if (headingMatch) {
-            if (!frontmatter.name) {
-              frontmatter.name = headingMatch[1].trim();
-            }
-            if (!frontmatter.description) {
-              frontmatter.description = firstParagraph?.trim() || frontmatter.name;
+    const files = await readdir(dirPath);
+    const mdFiles = files.filter((f) => f.endsWith(".md"));
+    const fileResults = await Promise.all(
+      mdFiles.map(async (file) => {
+        const filePath = join(dirPath, file);
+        try {
+          const fileStat = await stat(filePath);
+          if (!fileStat.isFile()) return null;
+          const content = await readFile(filePath, "utf-8");
+          if (!content.trim()) return null;
+          const { data: frontmatter, content: body } = matter(content);
+          if (!frontmatter.name || !frontmatter.description) {
+            const headingMatch = body.match(/^#\s+(.+)/m);
+            const firstParagraph = body.split(/\n\n/).find((p) => p.trim() && !p.trim().startsWith("#"));
+            if (headingMatch) {
+              if (!frontmatter.name) {
+                frontmatter.name = headingMatch[1].trim();
+              }
+              if (!frontmatter.description) {
+                frontmatter.description = firstParagraph?.trim() || frontmatter.name;
+              }
+            } else {
+              debugLog.warn("AGENT_MISSING_FIELDS", {
+                filePath,
+                message: "missing required fields (name, description)"
+              });
+              return null;
             }
-          } else {
-            console.warn(
-              `Skipping ${filePath}: missing required fields (name, description)`
-            );
-            continue;
           }
-        }
-        if (frontmatter.model && !frontmatter.model_name && !warnedAgents.has(frontmatter.name) && process.env.MINTO_DEBUG_AGENTS) {
-          console.warn(
-            `\u26A0\uFE0F Agent ${frontmatter.name}: 'model' field is deprecated and ignored. Use 'model_name' instead, or omit to use default 'task' model.`
+          if (frontmatter.model && !frontmatter.model_name && !warnedAgents.has(frontmatter.name) && process.env.MINTO_DEBUG_AGENTS) {
+            debugLog.warn("AGENT_DEPRECATED_MODEL_FIELD", {
+              agent: frontmatter.name,
+              message: "'model' field is deprecated and ignored. Use 'model_name' instead."
+            });
+            warnedAgents.add(frontmatter.name);
+          }
+          const disallowedTools = parseDisallowedTools(
+            frontmatter.disallowedTools
           );
-          warnedAgents.add(frontmatter.name);
+          const skills = parseSkills(frontmatter.skills);
+          const memory = parseMemory(frontmatter.memory);
+          const permissionMode = parsePermissionMode(frontmatter.permissionMode);
+          const agent = {
+            agentType: frontmatter.name,
+            whenToUse: frontmatter.description.replace(/\\n/g, "\n"),
+            tools: parseTools(frontmatter.tools),
+            systemPrompt: body.trim(),
+            location,
+            sourcePath: filePath,
+            // Optional fields - only include if defined
+            ...frontmatter.color && { color: frontmatter.color },
+            ...frontmatter.model_name && {
+              model_name: frontmatter.model_name
+            },
+            ...disallowedTools && { disallowedTools },
+            ...permissionMode && { permissionMode },
+            ...skills && { skills },
+            ...memory && { memory },
+            ...frontmatter.maxThinkingTokens && {
+              maxThinkingTokens: Number(frontmatter.maxThinkingTokens)
+            },
+            ...frontmatter.hooks && {
+              hooks: frontmatter.hooks
+            },
+            ...frontmatter.isolation && { isolation: frontmatter.isolation },
+            ...frontmatter.background && {
+              background: frontmatter.background === true
+            },
+            ...frontmatter.mcpServers && {
+              mcpServers: frontmatter.mcpServers
+            },
+            ...frontmatter.maxTurns && {
+              maxTurns: Number(frontmatter.maxTurns)
+            }
+          };
+          const MAX_PROJECT_PERM_LEVEL = 2;
+          if (location === "project" && agent.permissionMode) {
+            const { PERMISSION_LEVELS } = await import("../types/PermissionMode.js");
+            const currentLevel = PERMISSION_LEVELS[agent.permissionMode] ?? 1;
+            if (currentLevel > MAX_PROJECT_PERM_LEVEL) {
+              if (!warnedAgents.has(agent.agentType + ":perm")) {
+                debugLog.warn("AGENT_PERMISSION_CAPPED", {
+                  agent: agent.agentType,
+                  requested: agent.permissionMode,
+                  capped: "acceptEdits"
+                });
+                warnedAgents.add(agent.agentType + ":perm");
+              }
+              agent.permissionMode = "acceptEdits";
+            }
+          }
+          if (location === "project" && agent.mcpServers) {
+            debugLog.warn("AGENT_MCPSERVERS_STRIPPED", {
+              agent: agent.agentType,
+              message: "mcpServers from project agents are ignored for security. Move to ~/.minto/agents/ to enable."
+            });
+            delete agent.mcpServers;
+          }
+          return agent;
+        } catch (error) {
+          debugLog.warn("AGENT_PARSE_FAILED", { filePath, error });
+          return null;
         }
-        const disallowedTools = parseDisallowedTools(
-          frontmatter.disallowedTools
-        );
-        const skills = parseSkills(frontmatter.skills);
-        const memory = parseMemory(frontmatter.memory);
-        const permissionMode = parsePermissionMode(frontmatter.permissionMode);
-        const agent = {
-          agentType: frontmatter.name,
-          whenToUse: frontmatter.description.replace(/\\n/g, "\n"),
-          tools: parseTools(frontmatter.tools),
-          systemPrompt: body.trim(),
-          location,
-          sourcePath: filePath,
-          // Optional fields - only include if defined
-          ...frontmatter.color && { color: frontmatter.color },
-          ...frontmatter.model_name && { model_name: frontmatter.model_name },
-          ...disallowedTools && { disallowedTools },
-          ...permissionMode && { permissionMode },
-          ...skills && { skills },
-          ...memory && { memory },
-          ...frontmatter.maxThinkingTokens && {
-            maxThinkingTokens: Number(frontmatter.maxThinkingTokens)
-          },
-          ...frontmatter.hooks && { hooks: frontmatter.hooks },
-          ...frontmatter.isolation && { isolation: frontmatter.isolation },
-          ...frontmatter.background && {
-            background: frontmatter.background === true
-          },
-          ...frontmatter.mcpServers && { mcpServers: frontmatter.mcpServers }
-        };
-        agents.push(agent);
-      } catch (error) {
-        console.warn(`Failed to parse agent file ${filePath}:`, error);
-      }
+      })
+    );
+    for (const agent of fileResults) {
+      if (agent) agents.push(agent);
     }
   } catch (error) {
-    console.warn(`Failed to scan directory ${dirPath}:`, error);
+    debugLog.warn("AGENT_SCAN_FAILED", { dirPath, error });
   }
   return agents;
 }
@@ -304,16 +401,19 @@ async function loadPluginAgents() {
                 frontmatter.description = firstParagraph?.trim() || frontmatter.name;
               }
             } else {
-              console.warn(
-                `Skipping plugin agent ${pluginAgent.filePath}: missing required fields (name, description)`
-              );
+              debugLog.warn("PLUGIN_AGENT_MISSING_FIELDS", {
+                filePath: pluginAgent.filePath,
+                message: "missing required fields (name, description)"
+              });
               continue;
             }
           }
           if (frontmatter.model && !frontmatter.model_name && !warnedAgents.has(frontmatter.name) && process.env.MINTO_DEBUG_AGENTS) {
-            console.warn(
-              `\u26A0\uFE0F Plugin agent ${frontmatter.name} (from ${plugin.manifest.name}): 'model' field is deprecated and ignored. Use 'model_name' instead, or omit to use default 'task' model.`
-            );
+            debugLog.warn("PLUGIN_AGENT_DEPRECATED_MODEL_FIELD", {
+              agent: frontmatter.name,
+              plugin: plugin.manifest.name,
+              message: "'model' field is deprecated and ignored. Use 'model_name' instead."
+            });
             warnedAgents.add(frontmatter.name);
           }
           const disallowedTools = parseDisallowedTools(
@@ -353,17 +453,42 @@ async function loadPluginAgents() {
               mcpServers: frontmatter.mcpServers
             }
           };
+          const MAX_PLUGIN_PERM_LEVEL = 2;
+          if (agent.permissionMode) {
+            const { PERMISSION_LEVELS } = await import("../types/PermissionMode.js");
+            const currentLevel = PERMISSION_LEVELS[agent.permissionMode] ?? 1;
+            if (currentLevel > MAX_PLUGIN_PERM_LEVEL) {
+              if (!warnedAgents.has(agent.agentType + ":perm")) {
+                debugLog.warn("PLUGIN_AGENT_PERMISSION_CAPPED", {
+                  agent: agent.agentType,
+                  plugin: plugin.manifest.name,
+                  requested: agent.permissionMode,
+                  capped: "acceptEdits"
+                });
+                warnedAgents.add(agent.agentType + ":perm");
+              }
+              agent.permissionMode = "acceptEdits";
+            }
+          }
+          if (agent.mcpServers) {
+            debugLog.warn("AGENT_MCPSERVERS_STRIPPED", {
+              agent: agent.agentType,
+              message: "mcpServers from plugin agents are ignored for security. Move to ~/.minto/agents/ to enable."
+            });
+            delete agent.mcpServers;
+          }
           agents.push(agent);
         } catch (error) {
-          console.warn(
-            `Failed to load plugin agent ${pluginAgent.name} from ${plugin.manifest.name}:`,
+          debugLog.warn("PLUGIN_AGENT_LOAD_FAILED", {
+            agent: pluginAgent.name,
+            plugin: plugin.manifest.name,
             error
-          );
+          });
         }
       }
     }
   } catch (error) {
-    console.warn("Failed to load plugin agents:", error);
+    debugLog.warn("PLUGIN_AGENTS_LOAD_FAILED", { error });
   }
   return agents;
 }
@@ -434,27 +559,39 @@ const getAllAgents = memoize(async () => {
   const { allAgents } = await loadAllAgents();
   return allAgents;
 });
+const _agentByTypeCache = new LRUCache({
+  max: 64,
+  ttl: 5 * 60 * 1e3,
+  // 5 min TTL
+  ttlAutopurge: false
+});
 function clearAgentCache() {
   getActiveAgents.cache?.clear?.();
   getAllAgents.cache?.clear?.();
-  getAgentByType.cache?.clear?.();
+  _agentByTypeCache.clear();
   getAvailableAgentTypes.cache?.clear?.();
 }
-const getAgentByType = memoize(
-  async (agentType) => {
-    const agents = await getActiveAgents();
-    const direct = agents.find((agent) => agent.agentType === agentType);
-    if (direct) return direct;
-    if (!agentType.includes(":")) {
-      for (const agent of agents) {
-        if (agent.agentType.includes(":") && agent.agentType.split(":").pop() === agentType) {
-          return agent;
-        }
+async function getAgentByType(agentType) {
+  const cached = _agentByTypeCache.get(agentType);
+  if (cached !== void 0) return cached;
+  if (_agentByTypeCache.has(agentType)) return void 0;
+  const agents = await getActiveAgents();
+  const direct = agents.find((agent) => agent.agentType === agentType);
+  if (direct) {
+    _agentByTypeCache.set(agentType, direct);
+    return direct;
+  }
+  if (!agentType.includes(":")) {
+    for (const agent of agents) {
+      if (agent.agentType.includes(":") && agent.agentType.split(":").pop() === agentType) {
+        _agentByTypeCache.set(agentType, agent);
+        return agent;
       }
     }
-    return void 0;
   }
-);
+  _agentByTypeCache.set(agentType, void 0);
+  return void 0;
+}
 const getAvailableAgentTypes = memoize(async () => {
   const agents = await getActiveAgents();
   return agents.map((agent) => agent.agentType);