@cleocode/cleo 2026.2.5

package/dist/mcp/lib/defaults.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Default configuration values for CLEO MCP Server
+ *
+ * @task T2928
+ * @task T3145
+ * @task T2916 - Rate limiting configuration (Section 13.3)
+ */
+import type { RateLimitingConfig } from './rate-limiter.js';
+export type { RateLimitingConfig } from './rate-limiter.js';
+export { DEFAULT_RATE_LIMITING } from './rate-limiter.js';
+/**
+ * Lifecycle enforcement configuration (Section 12.2)
+ */
+export interface LifecycleEnforcementConfig {
+    /** Enforcement mode: strict blocks, advisory warns, off skips */
+    mode: 'strict' | 'advisory' | 'off';
+    /** Stages that may be skipped without failing gates */
+    allowSkip: string[];
+    /** Emergency bypass flag - disables all gate checks */
+    emergencyBypass: boolean;
+}
+/**
+ * Protocol validation configuration (Section 12.3)
+ */
+export interface ProtocolValidationConfig {
+    /** Enable strict protocol validation */
+    strictMode: boolean;
+    /** Block operations on protocol violations */
+    blockOnViolation: boolean;
+    /** Log protocol violations to audit trail */
+    logViolations: boolean;
+}
+export interface MCPConfig {
+    /** Path to CLEO CLI binary (default: 'cleo') */
+    cliPath: string;
+    /** Operation timeout in milliseconds (default: 30000) */
+    timeout: number;
+    /** Logging verbosity level (default: 'info') */
+    logLevel: 'debug' | 'info' | 'warn' | 'error';
+    /** Enable token tracking metrics (default: false) */
+    enableMetrics: boolean;
+    /** Retry count for failed operations (default: 3) */
+    maxRetries: number;
+    /** Enable query cache (default: true) */
+    queryCache: boolean;
+    /** Query cache TTL in milliseconds (default: 30000) */
+    queryCacheTtl: number;
+    /** Enable audit logging (default: true) */
+    auditLog: boolean;
+    /** Strict validation mode (default: true) */
+    strictValidation: boolean;
+    /** Lifecycle enforcement configuration (Section 12.2) */
+    lifecycleEnforcement: LifecycleEnforcementConfig;
+    /** Protocol validation configuration (Section 12.3) */
+    protocolValidation: ProtocolValidationConfig;
+    /** Rate limiting configuration (Section 13.3) */
+    rateLimiting: RateLimitingConfig;
+}
+/**
+ * Default lifecycle enforcement configuration
+ */
+export declare const DEFAULT_LIFECYCLE_ENFORCEMENT: LifecycleEnforcementConfig;
+/**
+ * Default protocol validation configuration
+ */
+export declare const DEFAULT_PROTOCOL_VALIDATION: ProtocolValidationConfig;
+/**
+ * Default configuration values
+ */
+export declare const DEFAULT_CONFIG: MCPConfig;
+/**
+ * Environment variable prefix for CLEO configuration
+ */
+export declare const ENV_PREFIX = "CLEO_MCP_";
+/**
+ * Configuration schema for validation
+ */
+export declare const CONFIG_SCHEMA: {
+    readonly cliPath: {
+        readonly type: "string";
+        readonly required: true;
+    };
+    readonly timeout: {
+        readonly type: "number";
+        readonly min: 1000;
+        readonly max: 300000;
+    };
+    readonly logLevel: {
+        readonly type: "string";
+        readonly enum: readonly ["debug", "info", "warn", "error"];
+    };
+    readonly enableMetrics: {
+        readonly type: "boolean";
+    };
+    readonly maxRetries: {
+        readonly type: "number";
+        readonly min: 0;
+        readonly max: 10;
+    };
+    readonly queryCache: {
+        readonly type: "boolean";
+    };
+    readonly queryCacheTtl: {
+        readonly type: "number";
+        readonly min: 0;
+        readonly max: 600000;
+    };
+    readonly auditLog: {
+        readonly type: "boolean";
+    };
+    readonly strictValidation: {
+        readonly type: "boolean";
+    };
+};
+//# sourceMappingURL=defaults.d.ts.map

package/dist/mcp/lib/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../../src/mcp/lib/defaults.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,iEAAiE;IACjE,IAAI,EAAE,QAAQ,GAAG,UAAU,GAAG,KAAK,CAAC;IACpC,uDAAuD;IACvD,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,uDAAuD;IACvD,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,wCAAwC;IACxC,UAAU,EAAE,OAAO,CAAC;IACpB,8CAA8C;IAC9C,gBAAgB,EAAE,OAAO,CAAC;IAC1B,6CAA6C;IAC7C,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,SAAS;IACxB,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAEhB,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAEhB,gDAAgD;IAChD,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAE9C,qDAAqD;IACrD,aAAa,EAAE,OAAO,CAAC;IAEvB,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAC;IAEnB,yCAAyC;IACzC,UAAU,EAAE,OAAO,CAAC;IAEpB,uDAAuD;IACvD,aAAa,EAAE,MAAM,CAAC;IAEtB,2CAA2C;IAC3C,QAAQ,EAAE,OAAO,CAAC;IAElB,6CAA6C;IAC7C,gBAAgB,EAAE,OAAO,CAAC;IAE1B,yDAAyD;IACzD,oBAAoB,EAAE,0BAA0B,CAAC;IAEjD,uDAAuD;IACvD,kBAAkB,EAAE,wBAAwB,CAAC;IAE7C,iDAAiD;IACjD,YAAY,EAAE,kBAAkB,CAAC;CAClC;AAED;;GAEG;AACH,eAAO,MAAM,6BAA6B,EAAE,0BAI3C,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,2BAA2B,EAAE,wBAIzC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,SAa5B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,UAAU,cAAc,CAAC;AAEtC;;GAEG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAUhB,CAAC"}

package/dist/mcp/lib/defaults.js

@@ -0,0 +1,61 @@
+/**
+ * Default configuration values for CLEO MCP Server
+ *
+ * @task T2928
+ * @task T3145
+ * @task T2916 - Rate limiting configuration (Section 13.3)
+ */
+import { DEFAULT_RATE_LIMITING } from './rate-limiter.js';
+export { DEFAULT_RATE_LIMITING } from './rate-limiter.js';
+/**
+ * Default lifecycle enforcement configuration
+ */
+export const DEFAULT_LIFECYCLE_ENFORCEMENT = {
+    mode: 'strict',
+    allowSkip: ['consensus'],
+    emergencyBypass: false,
+};
+/**
+ * Default protocol validation configuration
+ */
+export const DEFAULT_PROTOCOL_VALIDATION = {
+    strictMode: true,
+    blockOnViolation: true,
+    logViolations: true,
+};
+/**
+ * Default configuration values
+ */
+export const DEFAULT_CONFIG = {
+    cliPath: 'cleo',
+    timeout: 30000, // 30 seconds
+    logLevel: 'info',
+    enableMetrics: false,
+    maxRetries: 3,
+    queryCache: true,
+    queryCacheTtl: 30000, // 30 seconds
+    auditLog: true,
+    strictValidation: true,
+    lifecycleEnforcement: { ...DEFAULT_LIFECYCLE_ENFORCEMENT },
+    protocolValidation: { ...DEFAULT_PROTOCOL_VALIDATION },
+    rateLimiting: { ...DEFAULT_RATE_LIMITING },
+};
+/**
+ * Environment variable prefix for CLEO configuration
+ */
+export const ENV_PREFIX = 'CLEO_MCP_';
+/**
+ * Configuration schema for validation
+ */
+export const CONFIG_SCHEMA = {
+    cliPath: { type: 'string', required: true },
+    timeout: { type: 'number', min: 1000, max: 300000 },
+    logLevel: { type: 'string', enum: ['debug', 'info', 'warn', 'error'] },
+    enableMetrics: { type: 'boolean' },
+    maxRetries: { type: 'number', min: 0, max: 10 },
+    queryCache: { type: 'boolean' },
+    queryCacheTtl: { type: 'number', min: 0, max: 600000 },
+    auditLog: { type: 'boolean' },
+    strictValidation: { type: 'boolean' },
+};
+//# sourceMappingURL=defaults.js.map

package/dist/mcp/lib/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../../src/mcp/lib/defaults.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAgE1D;;GAEG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAA+B;IACvE,IAAI,EAAE,QAAQ;IACd,SAAS,EAAE,CAAC,WAAW,CAAC;IACxB,eAAe,EAAE,KAAK;CACvB,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAA6B;IACnE,UAAU,EAAE,IAAI;IAChB,gBAAgB,EAAE,IAAI;IACtB,aAAa,EAAE,IAAI;CACpB,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAc;IACvC,OAAO,EAAE,MAAM;IACf,OAAO,EAAE,KAAK,EAAE,aAAa;IAC7B,QAAQ,EAAE,MAAM;IAChB,aAAa,EAAE,KAAK;IACpB,UAAU,EAAE,CAAC;IACb,UAAU,EAAE,IAAI;IAChB,aAAa,EAAE,KAAK,EAAE,aAAa;IACnC,QAAQ,EAAE,IAAI;IACd,gBAAgB,EAAE,IAAI;IACtB,oBAAoB,EAAE,EAAE,GAAG,6BAA6B,EAAE;IAC1D,kBAAkB,EAAE,EAAE,GAAG,2BAA2B,EAAE;IACtD,YAAY,EAAE,EAAE,GAAG,qBAAqB,EAAE;CAC3C,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,WAAW,CAAC;AAEtC;;GAEG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;IAC3C,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE;IACnD,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IACtE,aAAa,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;IAClC,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE;IAC/C,UAAU,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;IAC/B,aAAa,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE;IACtD,QAAQ,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;IAC7B,gBAAgB,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;CAC7B,CAAC"}

package/dist/mcp/lib/error-handler.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Error handler for CLEO CLI operations
+ *
+ * @task T2913
+ * @epic T2908
+ *
+ * Processes CLI errors, generates contextual fix commands,
+ * and formats error responses with recovery suggestions.
+ */
+import { ErrorSeverity, ErrorCategory, type ErrorAlternative } from './exit-codes.js';
+/**
+ * CLI error context
+ */
+export interface CLIErrorContext {
+    command: string;
+    args: string[];
+    stderr?: string;
+    stdout?: string;
+    details?: Record<string, string>;
+}
+/**
+ * Formatted error response
+ */
+export interface FormattedError {
+    code: string;
+    name: string;
+    exitCode: number;
+    message: string;
+    description: string;
+    category: ErrorCategory;
+    severity: ErrorSeverity;
+    retryable: boolean;
+    fix?: string;
+    alternatives?: ErrorAlternative[];
+    context?: Record<string, string>;
+    documentation?: string;
+}
+/**
+ * Handle CLI error and format response
+ */
+export declare function handleCLIError(exitCode: number, context: CLIErrorContext): FormattedError;
+/**
+ * Check if error is recoverable (can be fixed by user action)
+ */
+export declare function isRecoverable(exitCode: number): boolean;
+/**
+ * Format error for MCP response
+ */
+export declare function formatErrorForMCP(error: FormattedError): {
+    success: false;
+    error: {
+        code: string;
+        exitCode: number;
+        message: string;
+        details?: Record<string, unknown>;
+        fix?: string;
+        alternatives?: ErrorAlternative[];
+    };
+};
+/**
+ * Add error context from operation details
+ */
+export declare function addErrorContext(context: CLIErrorContext, additionalDetails: Record<string, string>): CLIErrorContext;
+/**
+ * Create error context from operation
+ */
+export declare function createErrorContext(command: string, args: string[], stderr?: string, stdout?: string, details?: Record<string, string>): CLIErrorContext;
+/**
+ * Error with exit code information for retry logic
+ *
+ * @task T3142
+ */
+export interface CLIError extends Error {
+    exitCode: number;
+}
+/**
+ * Result of a retried operation, including retry metadata
+ *
+ * @task T3142
+ */
+export interface RetryResult<T> {
+    result: T;
+    attempts: number;
+    retriedExitCodes: number[];
+}
+/**
+ * Retry an operation with exponential backoff for retryable errors.
+ *
+ * Per MCP-SERVER-SPECIFICATION Section 9.1:
+ * - Exit codes 7, 20-22, 60-63 support retry with exponential backoff
+ * - Max 3 attempts by default
+ * - Backoff: 2^attempt seconds
+ * - Tracks retry count in response metadata
+ *
+ * Non-recoverable errors (Section 9.2) are never retried and
+ * immediately rethrown.
+ *
+ * @task T3142
+ */
+export declare function retryOperation<T>(fn: () => Promise<T>, maxAttempts?: number): Promise<RetryResult<T>>;
+//# sourceMappingURL=error-handler.d.ts.map

package/dist/mcp/lib/error-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../../../src/mcp/lib/error-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAEL,aAAa,EACb,aAAa,EAOb,KAAK,gBAAgB,EACtB,MAAM,iBAAiB,CAAC;AAEzB;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,aAAa,CAAC;IACxB,QAAQ,EAAE,aAAa,CAAC;IACxB,SAAS,EAAE,OAAO,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,eAAe,GACvB,cAAc,CA0BhB;AAuHD;;GAEG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAgDvD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,cAAc,GAAG;IACxD,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAClC,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,YAAY,CAAC,EAAE,gBAAgB,EAAE,CAAC;KACnC,CAAC;CACH,CAmBA;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,eAAe,EACxB,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACxC,eAAe,CAQjB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,MAAM,CAAC,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC/B,eAAe,CAQjB;AAED;;;;GAIG;AACH,MAAM,WAAW,QAAS,SAAQ,KAAK;IACrC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,MAAM,EAAE,CAAC,CAAC;IACV,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AASD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,cAAc,CAAC,CAAC,EACpC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,WAAW,GAAE,MAA6B,GACzC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAuCzB"}

package/dist/mcp/lib/error-handler.js

@@ -0,0 +1,277 @@
+/**
+ * Error handler for CLEO CLI operations
+ *
+ * @task T2913
+ * @epic T2908
+ *
+ * Processes CLI errors, generates contextual fix commands,
+ * and formats error responses with recovery suggestions.
+ */
+import { ExitCode, ErrorCategory, getErrorMapping, isError, isRetryable, isNonRecoverable, generateFixCommand, generateSuggestions, } from './exit-codes.js';
+/**
+ * Handle CLI error and format response
+ */
+export function handleCLIError(exitCode, context) {
+    const mapping = getErrorMapping(exitCode);
+    // Extract context from stderr/stdout
+    const errorContext = extractErrorContext(exitCode, context);
+    // Generate fix command
+    const fix = generateFixCommand(exitCode, errorContext);
+    // Generate alternatives
+    const alternatives = generateSuggestions(exitCode, errorContext);
+    return {
+        code: mapping.code,
+        name: mapping.name,
+        exitCode,
+        message: formatErrorMessage(exitCode, context, errorContext),
+        description: mapping.description,
+        category: mapping.category,
+        severity: mapping.severity,
+        retryable: mapping.retryable,
+        fix,
+        alternatives,
+        context: errorContext,
+        documentation: mapping.documentation,
+    };
+}
+/**
+ * Extract error context from CLI output
+ */
+function extractErrorContext(_exitCode, context) {
+    const extracted = {
+        command: context.command,
+        ...context.details,
+    };
+    // Parse stderr for context clues
+    if (context.stderr) {
+        const stderr = context.stderr;
+        // Extract task IDs
+        const taskIdMatch = stderr.match(/T(\d+)/);
+        if (taskIdMatch) {
+            extracted.taskId = taskIdMatch[0];
+        }
+        // Extract parent IDs
+        const parentMatch = stderr.match(/parent[:\s]+T(\d+)/i);
+        if (parentMatch) {
+            extracted.parentId = parentMatch[0].match(/T\d+/)?.[0] || '';
+        }
+        // Extract epic IDs
+        const epicMatch = stderr.match(/epic[:\s]+T(\d+)/i);
+        if (epicMatch) {
+            extracted.epicId = epicMatch[0].match(/T\d+/)?.[0] || '';
+        }
+        // Extract session IDs
+        const sessionMatch = stderr.match(/session[:\s]+([a-z0-9_]+)/i);
+        if (sessionMatch) {
+            extracted.sessionId = sessionMatch[1];
+        }
+        // Extract gate names
+        const gateMatch = stderr.match(/gate[:\s]+(\w+)/i);
+        if (gateMatch) {
+            extracted.gateName = gateMatch[1];
+        }
+        // Extract agent names
+        const agentMatch = stderr.match(/agent[:\s]+(\w+)/i);
+        if (agentMatch) {
+            extracted.agentName = agentMatch[1];
+        }
+        // Extract resource names
+        const resourceMatch = stderr.match(/resource[:\s]+([^\s]+)/i);
+        if (resourceMatch) {
+            extracted.resource = resourceMatch[1];
+        }
+        // Extract query strings
+        const queryMatch = stderr.match(/query[:\s]+"([^"]+)"/i);
+        if (queryMatch) {
+            extracted.query = queryMatch[1];
+        }
+        // Extract percentages
+        const percentageMatch = stderr.match(/(\d+)%/);
+        if (percentageMatch) {
+            extracted.percentage = percentageMatch[1];
+        }
+        // Extract violations
+        const violationsMatch = stderr.match(/violations?[:\s]+(.+)/i);
+        if (violationsMatch) {
+            extracted.violations = violationsMatch[1];
+        }
+        // Extract stages
+        const stageMatch = stderr.match(/stage[:\s]+(\w+)/i);
+        if (stageMatch) {
+            extracted.stage = stageMatch[1];
+        }
+        // Extract missing stages
+        const missingStagesMatch = stderr.match(/missing[:\s]+(.+)/i);
+        if (missingStagesMatch) {
+            extracted.missingStages = missingStagesMatch[1];
+        }
+    }
+    return extracted;
+}
+/**
+ * Format error message with context
+ */
+function formatErrorMessage(exitCode, context, _extracted) {
+    const mapping = getErrorMapping(exitCode);
+    // Start with base description
+    let message = mapping.description;
+    // Add context-specific details
+    if (context.stderr) {
+        // Try to extract first line of error message
+        const firstLine = context.stderr.split('\n')[0].trim();
+        if (firstLine && firstLine.length < 200) {
+            message = firstLine;
+        }
+    }
+    return message;
+}
+/**
+ * Check if error is recoverable (can be fixed by user action)
+ */
+export function isRecoverable(exitCode) {
+    const mapping = getErrorMapping(exitCode);
+    // Context errors require agent action, not user action
+    if (mapping.category === ErrorCategory.CONTEXT) {
+        return false;
+    }
+    // Verification locked errors cannot be recovered automatically
+    if (exitCode === ExitCode.E_VERIFICATION_LOCKED) {
+        return false;
+    }
+    // Cascade failures need manual intervention
+    if (exitCode === ExitCode.E_CASCADE_FAILED) {
+        return false;
+    }
+    // Session close blocked needs tasks to be completed first
+    if (exitCode === ExitCode.E_SESSION_CLOSE_BLOCKED) {
+        return false;
+    }
+    // Circular validation needs different agent
+    if (exitCode === ExitCode.E_CIRCULAR_VALIDATION) {
+        return false;
+    }
+    // Invalid lifecycle transitions cannot be recovered
+    if (exitCode === ExitCode.E_LIFECYCLE_TRANSITION_INVALID) {
+        return false;
+    }
+    // File errors and dependency errors are not recoverable
+    if (exitCode === ExitCode.E_FILE_ERROR ||
+        exitCode === ExitCode.E_DEPENDENCY_ERROR) {
+        return false;
+    }
+    // Circular references are not recoverable
+    if (exitCode === ExitCode.E_CIRCULAR_REFERENCE) {
+        return false;
+    }
+    // Most other errors are recoverable by user action
+    return isError(exitCode);
+}
+/**
+ * Format error for MCP response
+ */
+export function formatErrorForMCP(error) {
+    return {
+        success: false,
+        error: {
+            code: error.code,
+            exitCode: error.exitCode,
+            message: error.message,
+            details: {
+                description: error.description,
+                category: error.category,
+                severity: error.severity,
+                retryable: error.retryable,
+                recoverable: isRecoverable(error.exitCode),
+                context: error.context,
+            },
+            fix: error.fix,
+            alternatives: error.alternatives,
+        },
+    };
+}
+/**
+ * Add error context from operation details
+ */
+export function addErrorContext(context, additionalDetails) {
+    return {
+        ...context,
+        details: {
+            ...context.details,
+            ...additionalDetails,
+        },
+    };
+}
+/**
+ * Create error context from operation
+ */
+export function createErrorContext(command, args, stderr, stdout, details) {
+    return {
+        command,
+        args,
+        stderr,
+        stdout,
+        details,
+    };
+}
+/**
+ * Default maximum retry attempts
+ *
+ * @task T3142
+ */
+const DEFAULT_MAX_ATTEMPTS = 3;
+/**
+ * Retry an operation with exponential backoff for retryable errors.
+ *
+ * Per MCP-SERVER-SPECIFICATION Section 9.1:
+ * - Exit codes 7, 20-22, 60-63 support retry with exponential backoff
+ * - Max 3 attempts by default
+ * - Backoff: 2^attempt seconds
+ * - Tracks retry count in response metadata
+ *
+ * Non-recoverable errors (Section 9.2) are never retried and
+ * immediately rethrown.
+ *
+ * @task T3142
+ */
+export async function retryOperation(fn, maxAttempts = DEFAULT_MAX_ATTEMPTS) {
+    const retriedExitCodes = [];
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            const result = await fn();
+            return {
+                result,
+                attempts: attempt,
+                retriedExitCodes,
+            };
+        }
+        catch (error) {
+            const exitCode = error?.exitCode;
+            // Non-recoverable errors must never be retried (Section 9.2)
+            if (exitCode !== undefined && isNonRecoverable(exitCode)) {
+                throw error;
+            }
+            // Non-retryable errors or last attempt: throw immediately
+            if (exitCode === undefined ||
+                !isRetryable(exitCode) ||
+                attempt === maxAttempts) {
+                throw error;
+            }
+            // Track the retried exit code
+            retriedExitCodes.push(exitCode);
+            // Exponential backoff: 2^attempt seconds
+            const delayMs = Math.pow(2, attempt) * 1000;
+            await sleep(delayMs);
+        }
+    }
+    // Should never reach here, but TypeScript requires it
+    throw new Error('retryOperation: exhausted all attempts');
+}
+/**
+ * Sleep for a given number of milliseconds
+ *
+ * @task T3142
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=error-handler.js.map

package/dist/mcp/lib/error-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.js","sourceRoot":"","sources":["../../../src/mcp/lib/error-handler.ts"],"names":[],"mappings":"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"}