LeoYeAI/agent-master-skills / skills/agent-mode-upgrades
agentic-loop-upgrade
FlaggedEnhanced 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);
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |