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/execution/error-recovery.ts
View on GitHub/**
* Semantic Error Recovery
*
* Diagnose errors and adapt approach instead of simple retry.
*/
import type {
ToolCall,
ToolResult,
ErrorDiagnosis,
RecoveryStrategy,
ErrorRecoveryConfig,
LLMCaller,
} from "../types.js";
// ============================================================================
// Error Pattern Matching
// ============================================================================
interface ErrorPattern {
match: RegExp;
strategy: (tool: ToolCall, error: string) => RecoveryStrategy;
}
/**
* File operation error patterns
*/
const FILE_ERROR_PATTERNS: ErrorPattern[] = [
{
match: /ENOENT|no such file|file not found/i,
strategy: (tool, _error) => {
if (tool.name === "Read") {
return {
type: "alternative_approach",
newPlan: `File ${tool.arguments.path} doesn't exist. Check if we need to create it first or use a different path.`,
};
}
if (tool.name === "Edit") {
return {
type: "retry_modified",
modifiedArgs: { ...tool.arguments, createIfMissing: true },
};
}
return { type: "escalate", explanation: "File not found" };
},
},
{
match: /EACCES|permission denied/i,
strategy: () => ({
type: "alternative_approach",
newPlan: "Permission denied. Try with elevated privileges or use a different location.",
}),
},
{
match: /ENOSPC|no space left/i,
strategy: () => ({
type: "escalate",
explanation: "Disk full. Cannot continue without human intervention.",
}),
},
{
match: /EEXIST|already exists/i,
strategy: (tool) => ({
type: "alternative_approach",
newPlan: `File/directory ${tool.arguments.path} already exists. Decide whether to overwrite, rename, or skip.`,
}),
},
{
match: /EISDIR|is a directory/i,
strategy: () => ({
type: "alternative_approach",
newPlan: "Target is a directory, not a file. Adjust the path.",
}),
},
];
/**
* Network error patterns
*/
const NETWORK_ERROR_PATTERNS: ErrorPattern[] = [
{
match: /ETIMEDOUT|timeout|timed out/i,
strategy: () => ({
type: "retry_same",
delay: 5000,
}),
},
{
match: /ECONNREFUSED|connection refused/i,
strategy: (tool) => ({
type: "alternative_approach",
newPlan: `Service is not running or refusing connections. Check if it needs to be started.`,
}),
},
{
match: /ENOTFOUND|getaddrinfo|DNS/i,
strategy: () => ({
type: "alternative_approach",
newPlan: "DNS resolution failed. Check the hostname or network connectivity.",
}),
},
{
match: /404|not found/i,
strategy: (tool) => ({
type: "alternative_approach",
newPlan: `Resource not found. Verify the URL or search for the correct endpoint.`,
}),
},
{
match: /401|unauthorized/i,
strategy: () => ({
type: "escalate",
explanation: "Authentication required. Need credentials.",
}),
},
{
match: /403|forbidden/i,
strategy: () => ({
type: "escalate",
explanation: "Access forbidden. Need different permissions.",
}),
},
{
match: /429|rate limit|too many requests/i,
strategy: () => ({
type: "retry_same",
delay: 60000, // Wait 1 minute
}),
},
{
match: /5\d{2}|server error|internal error/i,
strategy: () => ({
type: "retry_same",
delay: 10000,
}),
},
];
/**
* Exec/command error patterns
*/
const EXEC_ERROR_PATTERNS: ErrorPattern[] = [
{
match: /command not found|not recognized/i,
strategy: (tool) => {
const cmd = (tool.arguments.command as string)?.split(" ")[0] ?? "command";
return {
type: "alternative_approach",
newPlan: `Command '${cmd}' not installed. Try installing it or use an alternative.`,
};
},
},
{
match: /npm ERR!.*ERESOLVE/i,
strategy: () => ({
type: "retry_modified",
modifiedArgs: { command: "npm install --legacy-peer-deps" },
}),
},
{
match: /git.*conflict/i,
strategy: () => ({
type: "escalate",
explanation: "Git merge conflict requires manual resolution.",
}),
},
{
match: /git.*diverged/i,
strategy: () => ({
type: "alternative_approach",
newPlan: "Git branches have diverged. Need to decide whether to merge, rebase, or force push.",
}),
},
{
match: /docker.*no such image/i,
strategy: () => ({
type: "alternative_approach",
newPlan: "Docker image not found. Need to build or pull it first.",
}),
},
{
match: /syntax error|parse error/i,
strategy: () => ({
type: "alternative_approach",
newPlan: "Syntax error in command or script. Review and fix the syntax.",
}),
},
];
/**
* All error patterns
*/
const ALL_ERROR_PATTERNS: ErrorPattern[] = [
...FILE_ERROR_PATTERNS,
...NETWORK_ERROR_PATTERNS,
...EXEC_ERROR_PATTERNS,
];
/**
* Try to match error against known patterns
*/
function matchErrorPattern(
tool: ToolCall,
error: string
): RecoveryStrategy | null {
for (const pattern of ALL_ERROR_PATTERNS) {
if (pattern.match.test(error)) {
return pattern.strategy(tool, error);
}
}
return null;
}
// ============================================================================
// LLM-Based Diagnosis
// ============================================================================
const DIAGNOSIS_PROMPT = `A tool call failed. Diagnose the cause and suggest recovery.
Tool: {toolName}
Arguments: {arguments}
Error: {error}
Analyze:
1. What likely caused this error?
2. Is this recoverable?
3. What alternative approaches could work?
4. Should we skip this and continue, or is it blocking?
Output valid JSON:
{
"cause": "Brief diagnosis",
"recoverable": true|false|"maybe",
"strategy": "alternative_approach"|"retry_modified"|"skip_and_continue"|"escalate"|"retry_same",
"alternative": "If alternative_approach, describe the new approach",
"modifiedArgs": {}, // If retry_modified, the new arguments
"skipReason": "If skip_and_continue, explain why it's safe",
"escalateExplanation": "If escalate, explain why human needed",
"retryDelay": 0 // If retry_same, delay in ms
}`;
/**
* Diagnose error using LLM
*/
async function llmDiagnose(
tool: ToolCall,
error: string,
llmCall: LLMCaller
): Promise<ErrorDiagnosis> {
const prompt = DIAGNOSIS_PROMPT
.replace("{toolName}", tool.name)
.replace("{arguments}", JSON.stringify(tool.arguments, null, 2))
.replace("{error}", error);
try {
const response = await llmCall({
messages: [
{ role: "system", content: "You are diagnosing tool errors. Output valid JSON only." },
{ role: "user", content: prompt },
],
maxTokens: 500,
});
const parsed = parseJsonFromResponse(response.content);
if (!parsed) {
return defaultDiagnosis(error);
}
const strategy = parseStrategy(parsed);
return {
cause: String(parsed.cause ?? "Unknown cause"),
recoverable: (parsed.recoverable as boolean | "maybe") ?? "maybe",
strategy,
};
} catch {
return defaultDiagnosis(error);
}
}
function parseStrategy(parsed: Record<string, unknown>): RecoveryStrategy {
switch (parsed.strategy) {
case "alternative_approach":
return {
type: "alternative_approach",
newPlan: (parsed.alternative as string) ?? "Try a different approach",
};
case "retry_modified":
return {
type: "retry_modified",
modifiedArgs: (parsed.modifiedArgs as Record<string, unknown>) ?? {},
};
case "skip_and_continue":
return {
type: "skip_and_continue",
reason: (parsed.skipReason as string) ?? "Error is non-blocking",
};
case "escalate":
return {
type: "escalate",
explanation: (parsed.escalateExplanation as string) ?? "Human intervention needed",
};
case "retry_same":
default:
return {
type: "retry_same",
delay: (parsed.retryDelay as number) ?? 1000,
};
}
}
function defaultDiagnosis(error: string): ErrorDiagnosis {
return {
cause: error,
recoverable: "maybe",
strategy: { type: "escalate", explanation: error },
};
}
// ============================================================================
// Main Recovery Function
// ============================================================================
/**
* Diagnose and get recovery strategy
*/
export async function diagnoseAndRecover(
tool: ToolCall,
result: ToolResult,
config: ErrorRecoveryConfig,
llmCall?: LLMCaller
): Promise<ErrorDiagnosis> {
if (!config.enabled) {
return {
cause: result.error ?? "Unknown error",
recoverable: false,
strategy: { type: "escalate", explanation: result.error ?? "Error recovery disabled" },
};
}
const error = result.error ?? "Unknown error";
// First, try pattern matching (fast)
const patternStrategy = matchErrorPattern(tool, error);
if (patternStrategy) {
return {
cause: error,
recoverable: patternStrategy.type !== "escalate",
strategy: patternStrategy,
};
}
// Then, try LLM diagnosis (if available)
if (llmCall) {
return llmDiagnose(tool, error, llmCall);
}
// Fallback
return defaultDiagnosis(error);
}
// ============================================================================
// Recovery Execution
// ============================================================================
/**
* Execute tool with recovery attempts
*/
export async function executeWithRecovery(
tool: ToolCall,
executor: (tool: ToolCall) => Promise<ToolResult>,
config: ErrorRecoveryConfig,
llmCall?: LLMCaller
): Promise<{ result: ToolResult; diagnosis?: ErrorDiagnosis; attempts: number }> {
let attempts = 0;
let currentTool = tool;
const tried = new Set<string>();
while (attempts < config.maxAttempts) {
attempts++;
const callSignature = JSON.stringify(currentTool);
// Prevent infinite loops
if (tried.has(callSignature)) {
return {
result: {
id: tool.id,
success: false,
error: "Recovery loop detected",
},
attempts,
};
}
tried.add(callSignature);
try {
const result = await executor(currentTool);
if (result.success) {
return { result, attempts };
}
// Tool returned an error result
const diagnosis = await diagnoseAndRecover(currentTool, result, config, llmCall);
switch (diagnosis.strategy.type) {
case "retry_same":
if (diagnosis.strategy.delay) {
await sleep(diagnosis.strategy.delay);
}
// currentTool stays the same
break;
case "retry_modified":
currentTool = {
...currentTool,
arguments: { ...currentTool.arguments, ...diagnosis.strategy.modifiedArgs },
};
break;
case "alternative_approach":
// Can't execute alternative here, return for replanning
return {
result: {
id: tool.id,
success: false,
error: result.error,
needsReplan: true,
reason: diagnosis.strategy.newPlan,
},
diagnosis,
attempts,
};
case "skip_and_continue":
return {
result: {
id: tool.id,
success: false,
skipped: true,
reason: diagnosis.strategy.reason,
},
diagnosis,
attempts,
};
case "escalate":
return {
result: {
id: tool.id,
success: false,
error: result.error,
needsHuman: true,
reason: diagnosis.strategy.explanation,
},
diagnosis,
attempts,
};
}
} catch (err) {
// Unexpected exception
const error = err instanceof Error ? err.message : String(err);
const result: ToolResult = {
id: tool.id,
success: false,
error,
};
if (attempts >= config.maxAttempts) {
return { result, attempts };
}
const diagnosis = await diagnoseAndRecover(currentTool, result, config, llmCall);
if (diagnosis.strategy.type === "escalate") {
return { result, diagnosis, attempts };
}
// Apply non-escalate strategy and continue
if (diagnosis.strategy.type === "retry_modified") {
currentTool = {
...currentTool,
arguments: { ...currentTool.arguments, ...diagnosis.strategy.modifiedArgs },
};
}
}
}
return {
result: {
id: tool.id,
success: false,
error: `Failed after ${config.maxAttempts} recovery attempts`,
},
attempts,
};
}
// ============================================================================
// Learning from Errors (optional)
// ============================================================================
export interface ErrorRecord {
toolName: string;
errorPattern: string;
successfulRecovery: RecoveryStrategy;
timestamp: number;
}
/**
* Store for learned error patterns
*/
export class ErrorLearningStore {
private records: ErrorRecord[] = [];
private maxRecords = 100;
add(record: ErrorRecord): void {
this.records.push(record);
if (this.records.length > this.maxRecords) {
this.records.shift();
}
}
find(toolName: string, error: string): RecoveryStrategy | null {
// Find most recent matching record
for (let i = this.records.length - 1; i >= 0; i--) {
const record = this.records[i];
if (
record.toolName === toolName &&
error.toLowerCase().includes(record.errorPattern.toLowerCase())
) {
return record.successfulRecovery;
}
}
return null;
}
getRecords(): readonly ErrorRecord[] {
return this.records;
}
clear(): void {
this.records = [];
}
}
// ============================================================================
// Utilities
// ============================================================================
function sleep(ms: number): Promise<void> {
return new Promise((resolve) => setTimeout(resolve, ms));
}
function parseJsonFromResponse(content: string): Record<string, unknown> | null {
try {
return JSON.parse(content);
} catch {
const match = content.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
if (match) {
try {
return JSON.parse(match[1]);
} catch {
return null;
}
}
return null;
}
}
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 |