Skip to content

LeoYeAI/agent-master-skills / skills/agent-mode-upgrades

agentic-loop-upgrade

Flagged

Enhanced agentic loop with planning, parallel execution, confidence gates, semantic error recovery, and observable state machine. Includes Mode dashboard UI for easy configuration.

src/enhanced-loop.ts

View on GitHub
/**
 * Enhanced Agentic Loop
 * 
 * Main orchestrator that wraps the core runner with advanced capabilities:
 * - Planning and reflection
 * - Parallel tool execution
 * - Confidence-gated autonomy
 * - Semantic error recovery
 * - Proactive context management
 * - Observable state machine
 */

import type {
  EnhancedLoopConfig,
  EnhancedLoopState,
  EnhancedLoopCallbacks,
  TaskPlan,
  ToolCall,
  ToolResult,
  LLMCaller,
  ToolExecutor,
  AgentMessage,
} from "./types.js";

import { AgentStateMachine, LoggingObserver, MetricsObserver } from "./state-machine/fsm.js";
import {
  createTaskStack,
  createTask,
  updateTaskStatus,
  getActiveTask,
  setActiveTask,
  buildTaskContextPrompt,
} from "./tasks/task-stack.js";
import {
  shouldGeneratePlan,
  generatePlan,
  reflect,
  replan,
  completeStep,
  failStep,
  getNextStep,
  formatPlanForContext,
} from "./planning/planner.js";
import {
  executeToolCalls,
  executeWithMetrics,
  classifyToolDependencies,
} from "./execution/parallel.js";
import {
  gateAction,
  createCheckpoint,
  classifyRisk,
} from "./execution/confidence-gate.js";
import {
  diagnoseAndRecover,
  executeWithRecovery,
  ErrorLearningStore,
} from "./execution/error-recovery.js";
import {
  createTokenBudget,
  createWorkingMemory,
  estimateMessageTokens,
  shouldManageContext,
  manageContext,
  buildWorkingMemoryContext,
  getBudgetUsage,
} from "./context/manager.js";

// ============================================================================
// Default Configuration
// ============================================================================

export const DEFAULT_CONFIG: EnhancedLoopConfig = {
  enabled: false,
  planning: {
    enabled: true,
    reflectionAfterTools: true,
    maxPlanSteps: 7,
  },
  execution: {
    parallelTools: true,
    maxConcurrentTools: 5,
    confidenceGates: true,
    confidenceThreshold: 0.7,
  },
  context: {
    proactiveManagement: true,
    summarizeAfterIterations: 5,
    contextThreshold: 0.7,
  },
  errorRecovery: {
    enabled: true,
    maxAttempts: 3,
    learnFromErrors: true,
  },
  stateMachine: {
    enabled: true,
    logging: true,
    metrics: false,
  },
};

// ============================================================================
// Enhanced Loop Class
// ============================================================================

export class EnhancedAgentLoop {
  private config: EnhancedLoopConfig;
  private state: EnhancedLoopState;
  private stateMachine: AgentStateMachine;
  private errorStore: ErrorLearningStore;
  private callbacks: EnhancedLoopCallbacks;

  constructor(
    config: Partial<EnhancedLoopConfig> = {},
    callbacks: EnhancedLoopCallbacks = {}
  ) {
    this.config = { ...DEFAULT_CONFIG, ...config };
    this.callbacks = callbacks;
    this.stateMachine = new AgentStateMachine(this.config.stateMachine);
    this.errorStore = new ErrorLearningStore();

    // Initialize state
    this.state = {
      config: this.config,
      taskStack: createTaskStack(),
      currentPlan: null,
      workingMemory: createWorkingMemory(),
      stateContext: this.stateMachine.getContext(),
      tokenBudget: createTokenBudget(128000), // Default, will be updated
      iterationCount: 0,
    };

    // Set up observers
    if (this.config.stateMachine.enabled) {
      if (this.config.stateMachine.logging) {
        this.stateMachine.subscribe(new LoggingObserver());
      }
      if (this.config.stateMachine.metrics) {
        this.stateMachine.subscribe(new MetricsObserver());
      }
      if (callbacks.onStateChange) {
        this.stateMachine.subscribe({ onTransition: callbacks.onStateChange });
      }
    }
  }

  /**
   * Get current configuration
   */
  getConfig(): EnhancedLoopConfig {
    return { ...this.config };
  }

  /**
   * Update configuration
   */
  updateConfig(update: Partial<EnhancedLoopConfig>): void {
    this.config = { ...this.config, ...update };
    this.state.config = this.config;
  }

  /**
   * Get current state
   */
  getState(): Readonly<EnhancedLoopState> {
    return {
      ...this.state,
      stateContext: this.stateMachine.getContext(),
    };
  }

  /**
   * Run the enhanced loop
   */
  async run(
    userGoal: string,
    context: string,
    llmCall: LLMCaller,
    toolExecutor: ToolExecutor,
    options: {
      maxTokens?: number;
      maxIterations?: number;
      abortSignal?: AbortSignal;
    } = {}
  ): Promise<{
    success: boolean;
    result?: string;
    error?: string;
    metrics: {
      iterations: number;
      toolsExecuted: number;
      planGenerated: boolean;
      replans: number;
      humanEscalations: number;
    };
  }> {
    const maxIterations = options.maxIterations ?? 50;
    this.state.tokenBudget = createTokenBudget(options.maxTokens ?? 128000);
    this.state.iterationCount = 0;

    let toolsExecuted = 0;
    let replans = 0;
    let humanEscalations = 0;
    let planGenerated = false;

    try {
      // ─────────────────────────────────────────────────────────────────────
      // PLANNING PHASE
      // ─────────────────────────────────────────────────────────────────────
      this.stateMachine.transition("planning", "user_input", { goal: userGoal });

      if (shouldGeneratePlan(userGoal, this.state.currentPlan, this.config.planning)) {
        this.state.currentPlan = await generatePlan(
          userGoal,
          context,
          this.config.planning,
          llmCall
        );
        planGenerated = true;

        if (this.callbacks.onPlanGenerated) {
          this.callbacks.onPlanGenerated(this.state.currentPlan);
        }

        // Create task from plan
        const rootTask = createTask(this.state.taskStack, {
          title: this.state.currentPlan.goal,
          description: formatPlanForContext(this.state.currentPlan),
          priority: 10,
        });
        setActiveTask(this.state.taskStack, rootTask.id);
      }

      this.stateMachine.transition("executing", "plan_ready");

      // ─────────────────────────────────────────────────────────────────────
      // MAIN LOOP
      // ─────────────────────────────────────────────────────────────────────
      while (this.state.iterationCount < maxIterations) {
        if (options.abortSignal?.aborted) {
          throw new Error("Aborted");
        }

        this.state.iterationCount++;

        // Check context management
        if (shouldManageContext(
          this.state.tokenBudget,
          this.state.iterationCount,
          this.config.context
        )) {
          // Would need actual messages here - simplified for now
          console.log("[enhanced-loop] Context management triggered");
        }

        // Get next step from plan
        const nextStep = this.state.currentPlan ? getNextStep(this.state.currentPlan) : null;

        if (!nextStep && this.state.currentPlan) {
          // Plan complete
          this.stateMachine.transition("completing", "all_done");
          break;
        }

        // ─────────────────────────────────────────────────────────────────────
        // TOOL EXECUTION PHASE
        // ─────────────────────────────────────────────────────────────────────
        // This is where we'd integrate with the actual LLM to get tool calls
        // For now, we provide hooks for the caller to use

        // Note: In real integration, we'd call the LLM here and get tool calls
        // The caller would pass in a function that returns tool calls from the LLM

        // For demonstration, assume we have a tool call to execute
        // In real usage, this would come from the LLM response

        // ─────────────────────────────────────────────────────────────────────
        // REFLECTION PHASE
        // ─────────────────────────────────────────────────────────────────────
        if (this.config.planning.reflectionAfterTools && this.state.currentPlan) {
          this.stateMachine.transition("reflecting", "tool_complete");

          // Simplified - would have actual tool call and result here
          const mockToolCall: ToolCall = { id: "mock", name: "mock", arguments: {} };
          const mockResult: ToolResult = { id: "mock", success: true };

          const reflection = await reflect(
            this.state.currentPlan,
            mockToolCall,
            mockResult,
            this.config.planning,
            llmCall
          );

          if (this.callbacks.onReflection) {
            this.callbacks.onReflection(reflection);
          }

          if (reflection.decision === "replan") {
            this.stateMachine.transition("replanning", "need_replan", {
              reason: reflection.reason,
            });

            this.state.currentPlan = await replan(
              this.state.currentPlan,
              reflection.reason ?? "Reflection indicated replanning needed",
              this.config.planning,
              llmCall
            );
            replans++;

            this.stateMachine.transition("executing", "plan_revised");
          } else if (reflection.decision === "escalate") {
            humanEscalations++;

            if (this.callbacks.onHumanInputRequired) {
              this.stateMachine.transition("waiting_human", "low_confidence", {
                reason: reflection.reason,
              });

              await this.callbacks.onHumanInputRequired(
                reflection.reason ?? "Human input needed"
              );

              this.stateMachine.transition("executing", "human_responded");
            } else {
              // No human callback, treat as complete
              this.stateMachine.transition("completing", "escalate_no_handler");
              break;
            }
          } else {
            // Continue
            this.stateMachine.transition("executing", "on_track");
          }
        }

        // Mark step complete if we have a plan
        if (nextStep && this.state.currentPlan) {
          this.state.currentPlan = completeStep(
            this.state.currentPlan,
            nextStep.id,
            "Completed"
          );
        }

        // Simple iteration limit for this demo
        // In real usage, the loop would continue until the LLM signals completion
        if (this.state.iterationCount >= 3) {
          break;
        }
      }

      // ─────────────────────────────────────────────────────────────────────
      // COMPLETION
      // ─────────────────────────────────────────────────────────────────────
      this.stateMachine.transition("completing", "loop_done");
      
      // Update task status
      const activeTask = getActiveTask(this.state.taskStack);
      if (activeTask) {
        updateTaskStatus(this.state.taskStack, activeTask.id, "complete", {
          success: true,
          summary: "Task completed",
        });
      }

      this.stateMachine.transition("idle", "response_sent");

      return {
        success: true,
        result: "Enhanced loop completed",
        metrics: {
          iterations: this.state.iterationCount,
          toolsExecuted,
          planGenerated,
          replans,
          humanEscalations,
        },
      };
    } catch (err) {
      const error = err instanceof Error ? err.message : String(err);

      this.stateMachine.transition("error", "unrecoverable", { error });

      // Update task status
      const activeTask = getActiveTask(this.state.taskStack);
      if (activeTask) {
        updateTaskStatus(this.state.taskStack, activeTask.id, "failed", {
          success: false,
          summary: error,
          error,
        });
      }

      this.stateMachine.transition("idle", "error_reported");

      return {
        success: false,
        error,
        metrics: {
          iterations: this.state.iterationCount,
          toolsExecuted,
          planGenerated,
          replans,
          humanEscalations,
        },
      };
    }
  }

  /**
   * Execute tool calls with enhanced features
   */
  async executeTools(
    toolCalls: ToolCall[],
    executor: ToolExecutor,
    context: string,
    llmCall?: LLMCaller
  ): Promise<Map<string, ToolResult>> {
    const results = new Map<string, ToolResult>();

    for (const tool of toolCalls) {
      // ─────────────────────────────────────────────────────────────────────
      // CONFIDENCE GATE
      // ─────────────────────────────────────────────────────────────────────
      if (this.config.execution.confidenceGates) {
        const { assessment, decision } = await gateAction(
          tool,
          context,
          this.config.execution,
          llmCall
        );

        if (this.callbacks.onConfidenceGate) {
          this.callbacks.onConfidenceGate(decision, tool);
        }

        if (decision.checkpoint) {
          await createCheckpoint(tool, context);
        }

        if (decision.waitForHuman) {
          if (this.callbacks.onHumanInputRequired) {
            const response = await this.callbacks.onHumanInputRequired(
              decision.question ?? "Should I proceed?",
              decision.options
            );

            if (response.toLowerCase().includes("no") || response.toLowerCase().includes("cancel")) {
              results.set(tool.id, {
                id: tool.id,
                success: false,
                skipped: true,
                reason: "Cancelled by user",
              });
              continue;
            }
          }
        }

        if (decision.refused) {
          results.set(tool.id, {
            id: tool.id,
            success: false,
            error: decision.reason ?? "Action refused due to low confidence",
          });
          continue;
        }
      }

      // ─────────────────────────────────────────────────────────────────────
      // EXECUTE WITH RECOVERY
      // ─────────────────────────────────────────────────────────────────────
      if (this.config.errorRecovery.enabled) {
        const { result, diagnosis, attempts } = await executeWithRecovery(
          tool,
          executor,
          this.config.errorRecovery,
          llmCall
        );

        if (diagnosis && this.callbacks.onErrorRecovery) {
          this.callbacks.onErrorRecovery(diagnosis, tool);
        }

        // Learn from successful recovery
        if (
          this.config.errorRecovery.learnFromErrors &&
          diagnosis &&
          result.success &&
          attempts > 1
        ) {
          this.errorStore.add({
            toolName: tool.name,
            errorPattern: diagnosis.cause,
            successfulRecovery: diagnosis.strategy,
            timestamp: Date.now(),
          });
        }

        results.set(tool.id, result);
      } else {
        // Simple execution
        const result = await executor(tool);
        results.set(tool.id, result);
      }
    }

    return results;
  }

  /**
   * Execute tools in parallel where possible
   */
  async executeToolsParallel(
    toolCalls: ToolCall[],
    executor: ToolExecutor
  ): Promise<{ results: Map<string, ToolResult>; metrics?: unknown }> {
    if (!this.config.execution.parallelTools) {
      // Sequential execution
      const results = new Map<string, ToolResult>();
      for (const tool of toolCalls) {
        const result = await executor(tool);
        results.set(tool.id, result);
      }
      return { results };
    }

    // Parallel execution with metrics
    return executeWithMetrics(toolCalls, executor, this.config.execution);
  }

  /**
   * Reset the loop state
   */
  reset(): void {
    this.stateMachine.reset();
    this.state = {
      config: this.config,
      taskStack: createTaskStack(),
      currentPlan: null,
      workingMemory: createWorkingMemory(),
      stateContext: this.stateMachine.getContext(),
      tokenBudget: createTokenBudget(128000),
      iterationCount: 0,
    };
  }

  /**
   * Get state machine metrics
   */
  getMetrics(): ReturnType<AgentStateMachine["getMetrics"]> {
    return this.stateMachine.getMetrics();
  }

  /**
   * Get state machine history
   */
  getHistory(): ReturnType<AgentStateMachine["getHistory"]> {
    return this.stateMachine.getHistory();
  }
}

// ============================================================================
// Factory Function
// ============================================================================

/**
 * Create an enhanced agent loop
 */
export function createEnhancedLoop(
  config?: Partial<EnhancedLoopConfig>,
  callbacks?: EnhancedLoopCallbacks
): EnhancedAgentLoop {
  return new EnhancedAgentLoop(config, callbacks);
}
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall