cognitive-modules-cli 2.2.0 → 2.2.5

package/dist/errors/index.js

@@ -0,0 +1,412 @@
+/**
+ * Cognitive Modules - Unified Error Handling
+ *
+ * Provides consistent error structures across HTTP, MCP, and CLI layers.
+ * Based on ERROR-CODES.md specification.
+ */
+// =============================================================================
+// Error Codes
+// =============================================================================
+/**
+ * Standard error codes per ERROR-CODES.md specification.
+ *
+ * Format: E{category}{sequence}
+ * - Category 1: Input errors
+ * - Category 2: Processing errors
+ * - Category 3: Output errors
+ * - Category 4: Runtime errors
+ * - Category 5-9: Module-specific (reserved)
+ */
+export const ErrorCodes = {
+    // E1xxx: Input Errors
+    PARSE_ERROR: 'E1000',
+    INVALID_INPUT: 'E1001',
+    MISSING_REQUIRED_FIELD: 'E1002',
+    TYPE_MISMATCH: 'E1003',
+    UNSUPPORTED_VALUE: 'E1004',
+    INPUT_TOO_LARGE: 'E1005',
+    INVALID_REFERENCE: 'E1006',
+    // E2xxx: Processing Errors
+    LOW_CONFIDENCE: 'E2001',
+    TIMEOUT: 'E2002',
+    TOKEN_LIMIT: 'E2003',
+    NO_ACTION_POSSIBLE: 'E2004',
+    SEMANTIC_CONFLICT: 'E2005',
+    AMBIGUOUS_INPUT: 'E2006',
+    INSUFFICIENT_CONTEXT: 'E2007',
+    // E3xxx: Output Errors
+    OUTPUT_SCHEMA_VIOLATION: 'E3001',
+    PARTIAL_RESULT: 'E3002',
+    MISSING_RATIONALE: 'E3003',
+    OVERFLOW_LIMIT: 'E3004',
+    INVALID_ENUM: 'E3005',
+    CONSTRAINT_VIOLATION: 'E3006',
+    // E4xxx: Runtime Errors
+    INTERNAL_ERROR: 'E4000',
+    PROVIDER_UNAVAILABLE: 'E4001',
+    RATE_LIMITED: 'E4002',
+    CONTEXT_OVERFLOW: 'E4003',
+    CIRCULAR_DEPENDENCY: 'E4004',
+    MAX_DEPTH_EXCEEDED: 'E4005',
+    MODULE_NOT_FOUND: 'E4006',
+    PERMISSION_DENIED: 'E4007',
+    ENDPOINT_NOT_FOUND: 'E4008',
+    RESOURCE_NOT_FOUND: 'E4009',
+};
+// =============================================================================
+// Legacy Code Mapping
+// =============================================================================
+const LEGACY_CODE_MAP = {
+    // Input errors
+    'PARSE_ERROR': ErrorCodes.PARSE_ERROR,
+    'INVALID_INPUT': ErrorCodes.INVALID_INPUT,
+    'MISSING_REQUIRED_FIELD': ErrorCodes.MISSING_REQUIRED_FIELD,
+    'TYPE_MISMATCH': ErrorCodes.TYPE_MISMATCH,
+    'UNSUPPORTED_VALUE': ErrorCodes.UNSUPPORTED_VALUE,
+    'UNSUPPORTED_LANGUAGE': ErrorCodes.UNSUPPORTED_VALUE,
+    'INPUT_TOO_LARGE': ErrorCodes.INPUT_TOO_LARGE,
+    'INVALID_REFERENCE': ErrorCodes.INVALID_REFERENCE,
+    // Processing errors
+    'LOW_CONFIDENCE': ErrorCodes.LOW_CONFIDENCE,
+    'TIMEOUT': ErrorCodes.TIMEOUT,
+    'TOKEN_LIMIT': ErrorCodes.TOKEN_LIMIT,
+    'NO_ACTION_POSSIBLE': ErrorCodes.NO_ACTION_POSSIBLE,
+    'NO_SIMPLIFICATION_POSSIBLE': ErrorCodes.NO_ACTION_POSSIBLE,
+    'SEMANTIC_CONFLICT': ErrorCodes.SEMANTIC_CONFLICT,
+    'BEHAVIOR_CHANGE_REQUIRED': ErrorCodes.SEMANTIC_CONFLICT,
+    'AMBIGUOUS_INPUT': ErrorCodes.AMBIGUOUS_INPUT,
+    'INSUFFICIENT_CONTEXT': ErrorCodes.INSUFFICIENT_CONTEXT,
+    // Output errors
+    'SCHEMA_VALIDATION_FAILED': ErrorCodes.OUTPUT_SCHEMA_VIOLATION,
+    'OUTPUT_SCHEMA_VIOLATION': ErrorCodes.OUTPUT_SCHEMA_VIOLATION,
+    'PARTIAL_RESULT': ErrorCodes.PARTIAL_RESULT,
+    // Runtime errors
+    'INTERNAL_ERROR': ErrorCodes.INTERNAL_ERROR,
+    'PROVIDER_UNAVAILABLE': ErrorCodes.PROVIDER_UNAVAILABLE,
+    'RATE_LIMITED': ErrorCodes.RATE_LIMITED,
+    'MODULE_NOT_FOUND': ErrorCodes.MODULE_NOT_FOUND,
+    'PERMISSION_DENIED': ErrorCodes.PERMISSION_DENIED,
+    'ENDPOINT_NOT_FOUND': ErrorCodes.ENDPOINT_NOT_FOUND,
+    'RESOURCE_NOT_FOUND': ErrorCodes.RESOURCE_NOT_FOUND,
+    'NOT_FOUND': ErrorCodes.RESOURCE_NOT_FOUND,
+};
+/**
+ * Normalize error code to E-format.
+ * Accepts both legacy string codes and E-format codes.
+ */
+export function normalizeErrorCode(code) {
+    // Already E-format
+    if (/^E\d{4}$/.test(code)) {
+        return code;
+    }
+    // Legacy format
+    return LEGACY_CODE_MAP[code] || ErrorCodes.INTERNAL_ERROR;
+}
+// =============================================================================
+// Error Envelope Factory
+// =============================================================================
+/**
+ * Default recoverability by error category.
+ */
+function getDefaultRecoverable(code) {
+    const category = code.charAt(1);
+    switch (category) {
+        case '1': return true; // Input errors are usually recoverable
+        case '2': return true; // Processing errors may be recoverable
+        case '3': return false; // Output errors are not recoverable
+        case '4': {
+            // Runtime errors: some are recoverable
+            const recoverable4xxx = [
+                ErrorCodes.PROVIDER_UNAVAILABLE,
+                ErrorCodes.RATE_LIMITED,
+                ErrorCodes.MODULE_NOT_FOUND,
+            ];
+            return recoverable4xxx.includes(code);
+        }
+        default: return false;
+    }
+}
+/**
+ * Create a standardized error envelope.
+ *
+ * @example
+ * // Simple error
+ * makeErrorEnvelope({
+ *   code: ErrorCodes.MODULE_NOT_FOUND,
+ *   message: "Module 'code-reviewer' not found",
+ *   suggestion: "Use 'cog list' to see available modules"
+ * });
+ *
+ * @example
+ * // Error with retry info
+ * makeErrorEnvelope({
+ *   code: ErrorCodes.RATE_LIMITED,
+ *   message: "Rate limit exceeded",
+ *   retry_after_ms: 60000
+ * });
+ */
+export function makeErrorEnvelope(options) {
+    const code = normalizeErrorCode(options.code);
+    const recoverable = options.recoverable ?? getDefaultRecoverable(code);
+    const error = {
+        code,
+        message: options.message,
+        recoverable,
+    };
+    if (options.suggestion) {
+        error.suggestion = options.suggestion;
+    }
+    if (options.retry_after_ms !== undefined) {
+        error.retry_after_ms = options.retry_after_ms;
+    }
+    if (options.details) {
+        error.details = options.details;
+    }
+    return {
+        ok: false,
+        version: options.version || '2.2',
+        meta: {
+            confidence: options.confidence ?? 0.0,
+            risk: options.risk ?? 'high',
+            explain: (options.explain || options.message).slice(0, 280),
+            trace_id: options.trace_id,
+        },
+        error,
+        partial_data: options.partial_data,
+    };
+}
+// =============================================================================
+// Layer-Specific Helpers
+// =============================================================================
+export function attachContext(envelope, context) {
+    if (!context)
+        return envelope;
+    const { module, provider } = context;
+    if (!module && !provider)
+        return envelope;
+    return {
+        ...envelope,
+        ...(module ? { module } : {}),
+        ...(provider ? { provider } : {}),
+    };
+}
+/**
+ * Create error envelope for HTTP API responses.
+ *
+ * @returns Tuple of [statusCode, body]
+ */
+export function makeHttpError(options) {
+    const envelope = attachContext(makeErrorEnvelope(options), options);
+    const code = normalizeErrorCode(options.code);
+    // Determine HTTP status code
+    let statusCode;
+    const category = code.charAt(1);
+    switch (category) {
+        case '1': {
+            // Input errors -> Bad Request (with specific overrides)
+            if (code === ErrorCodes.INPUT_TOO_LARGE) {
+                statusCode = 413; // Payload Too Large
+            }
+            else {
+                statusCode = 400;
+            }
+            break;
+        }
+        case '2':
+            statusCode = 422;
+            break; // Processing errors -> Unprocessable Entity
+        case '3':
+            statusCode = 500;
+            break; // Output errors -> Internal Server Error
+        case '4': {
+            // Runtime errors - map to appropriate HTTP status
+            if (code === ErrorCodes.MODULE_NOT_FOUND ||
+                code === ErrorCodes.ENDPOINT_NOT_FOUND ||
+                code === ErrorCodes.RESOURCE_NOT_FOUND) {
+                statusCode = 404; // Not Found
+            }
+            else if (code === ErrorCodes.PERMISSION_DENIED) {
+                statusCode = 403; // Forbidden
+            }
+            else if (code === ErrorCodes.RATE_LIMITED) {
+                statusCode = 429; // Too Many Requests
+            }
+            else {
+                statusCode = 500; // Internal Server Error
+            }
+            break;
+        }
+        default: statusCode = 500;
+    }
+    // Add HTTP-specific fields
+    return [statusCode, envelope];
+}
+/**
+ * Create error envelope for MCP tool responses.
+ */
+export function makeMcpError(options) {
+    const envelope = attachContext(makeErrorEnvelope(options), {
+        module: options.module ?? 'unknown',
+        provider: options.provider ?? 'unknown',
+    });
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify(envelope, null, 2),
+            },
+        ],
+    };
+}
+/**
+ * Convert error envelope to CLI-friendly error message.
+ */
+export function toCliError(envelope) {
+    const { error } = envelope;
+    let message = `Error [${error.code}]: ${error.message}`;
+    if (error.suggestion) {
+        message += `\n  Suggestion: ${error.suggestion}`;
+    }
+    if (error.retry_after_ms) {
+        const seconds = Math.ceil(error.retry_after_ms / 1000);
+        message += `\n  Retry after: ${seconds}s`;
+    }
+    return message;
+}
+/**
+ * Convert CLI CommandResult-style error to standard envelope.
+ * Used for backward compatibility during migration.
+ */
+export function fromCliError(errorMessage, code = ErrorCodes.INTERNAL_ERROR) {
+    return makeErrorEnvelope({
+        code,
+        message: errorMessage,
+    });
+}
+// =============================================================================
+// Error Type Guards
+// =============================================================================
+/**
+ * Check if an error envelope indicates a recoverable error.
+ */
+export function isRecoverable(envelope) {
+    return envelope.error.recoverable === true;
+}
+/**
+ * Check if an error envelope has partial data.
+ */
+export function hasPartialData(envelope) {
+    return envelope.partial_data !== undefined;
+}
+/**
+ * Check if an error envelope suggests retrying.
+ */
+export function shouldRetry(envelope) {
+    const retryableCodes = [
+        ErrorCodes.RATE_LIMITED,
+        ErrorCodes.PROVIDER_UNAVAILABLE,
+        ErrorCodes.TIMEOUT,
+    ];
+    return (envelope.error.recoverable === true &&
+        (envelope.error.retry_after_ms !== undefined ||
+            retryableCodes.includes(envelope.error.code)));
+}
+/**
+ * Create a standardized success envelope.
+ * Use this for consistent success responses across HTTP and MCP layers.
+ */
+export function makeSuccessEnvelope(options) {
+    return {
+        ok: true,
+        version: options.version || '2.2',
+        meta: {
+            confidence: options.confidence ?? 1.0,
+            risk: options.risk ?? 'none',
+            explain: (options.explain || 'Operation completed successfully').slice(0, 280),
+            trace_id: options.trace_id,
+        },
+        data: options.data,
+    };
+}
+/**
+ * Create success envelope for MCP tool responses.
+ */
+export function makeMcpSuccess(options) {
+    const envelope = makeSuccessEnvelope(options);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify(envelope, null, 2),
+            },
+        ],
+    };
+}
+// =============================================================================
+// Common Error Factories
+// =============================================================================
+/**
+ * Create MODULE_NOT_FOUND error.
+ */
+export function moduleNotFoundError(moduleName, options) {
+    return makeErrorEnvelope({
+        code: ErrorCodes.MODULE_NOT_FOUND,
+        message: `Module '${moduleName}' not found`,
+        suggestion: options?.suggestion || "Use 'cog list' to see available modules, or 'cog search' to find modules in registry",
+        trace_id: options?.trace_id,
+    });
+}
+/**
+ * Create PARSE_ERROR error.
+ */
+export function parseError(details, options) {
+    return makeErrorEnvelope({
+        code: ErrorCodes.PARSE_ERROR,
+        message: details ? `JSON parsing failed: ${details}` : 'Invalid JSON body',
+        recoverable: false,
+        trace_id: options?.trace_id,
+    });
+}
+/**
+ * Create RATE_LIMITED error.
+ */
+export function rateLimitedError(retryAfterMs, provider) {
+    return makeErrorEnvelope({
+        code: ErrorCodes.RATE_LIMITED,
+        message: `Rate limit exceeded${provider ? ` for provider '${provider}'` : ''}`,
+        retry_after_ms: retryAfterMs,
+        suggestion: `Wait ${Math.ceil(retryAfterMs / 1000)} seconds before retrying`,
+    });
+}
+/**
+ * Create INTERNAL_ERROR error.
+ */
+export function internalError(message, options) {
+    return makeErrorEnvelope({
+        code: ErrorCodes.INTERNAL_ERROR,
+        message,
+        recoverable: false,
+        details: options?.details,
+        trace_id: options?.trace_id,
+    });
+}
+/**
+ * Create MISSING_REQUIRED_FIELD error.
+ */
+export function missingFieldError(fieldName, options) {
+    return makeErrorEnvelope({
+        code: ErrorCodes.MISSING_REQUIRED_FIELD,
+        message: `Missing required field: ${fieldName}`,
+        suggestion: options?.suggestion || `Provide the '${fieldName}' field in your request`,
+    });
+}
+/**
+ * Create PERMISSION_DENIED error.
+ */
+export function permissionDeniedError(reason) {
+    return makeErrorEnvelope({
+        code: ErrorCodes.PERMISSION_DENIED,
+        message: reason,
+        recoverable: false,
+    });
+}

package/dist/index.d.ts

@@ -3,9 +3,9 @@
  *
  * Exports all public APIs for programmatic use.
  */
-export type { Provider, InvokeParams, InvokeResult, Message, CognitiveModule, ModuleResult, ModuleInput, ModuleConstraints, ToolsPolicy, OutputContract, FailureContract, CommandContext, CommandResult, } from './types.js';
+export type { Provider, InvokeParams, InvokeResult, Message, CognitiveModule, ModuleResult, ModuleInput, ModuleConstraints, ToolsPolicy, OutputContract, FailureContract, CommandContext, CommandResult, CompositionConfig, CompositionPattern, DependencyDeclaration, DataflowStep, DataflowMapping, RoutingRule, AggregationStrategy, IterationConfig, } from './types.js';
 export { getProvider, listProviders, GeminiProvider, OpenAIProvider, AnthropicProvider, BaseProvider, } from './providers/index.js';
-export { loadModule, findModule, listModules, getDefaultSearchPaths, runModule, SubagentOrchestrator, runWithSubagents, parseCalls, createContext, } from './modules/index.js';
+export { loadModule, findModule, listModules, getDefaultSearchPaths, runModule, SubagentOrchestrator, runWithSubagents, parseCalls, createContext, CompositionOrchestrator, executeComposition, validateCompositionConfig, evaluateJsonPath, evaluateCondition, applyMapping, aggregateResults, versionMatches, resolveDependency, COMPOSITION_ERRORS, checkToolPolicy, checkPolicy, checkToolAllowed, validateToolsAllowed, getDeniedActions, getDeniedTools, getAllowedTools, ToolCallInterceptor, createPolicyAwareExecutor, type PolicyAction, type PolicyCheckResult, type ToolCallRequest, type ToolCallResult, type ToolExecutor, } from './modules/index.js';
 export { serve as serveHttp, createServer } from './server/index.js';
 export { serve as serveMcp } from './mcp/index.js';
 export { run, list, pipe } from './commands/index.js';

package/dist/index.js

@@ -8,7 +8,11 @@ export { getProvider, listProviders, GeminiProvider, OpenAIProvider, AnthropicPr
 // Modules
 export { loadModule, findModule, listModules, getDefaultSearchPaths, runModule, 
 // Subagent
-SubagentOrchestrator, runWithSubagents, parseCalls, createContext, } from './modules/index.js';
+SubagentOrchestrator, runWithSubagents, parseCalls, createContext, 
+// Composition
+CompositionOrchestrator, executeComposition, validateCompositionConfig, evaluateJsonPath, evaluateCondition, applyMapping, aggregateResults, versionMatches, resolveDependency, COMPOSITION_ERRORS, 
+// Policy Enforcement
+checkToolPolicy, checkPolicy, checkToolAllowed, validateToolsAllowed, getDeniedActions, getDeniedTools, getAllowedTools, ToolCallInterceptor, createPolicyAwareExecutor, } from './modules/index.js';
 // Server
 export { serve as serveHttp, createServer } from './server/index.js';
 // MCP