cognitive-modules-cli 2.2.0 → 2.2.5

package/dist/mcp/server.js

@@ -12,12 +12,14 @@ import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSche
 import { findModule, listModules, getDefaultSearchPaths } from '../modules/loader.js';
 import { runModule } from '../modules/runner.js';
 import { getProvider } from '../providers/index.js';
+import { VERSION } from '../version.js';
+import { ErrorCodes, attachContext, makeErrorEnvelope, makeMcpError, makeMcpSuccess } from '../errors/index.js';
 // =============================================================================
 // Server Setup
 // =============================================================================
 const server = new Server({
     name: 'cognitive-modules',
-    version: '1.3.0',
+    version: VERSION,
 }, {
     capabilities: {
         tools: {},
@@ -35,7 +37,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
         tools: [
             {
                 name: 'cognitive_run',
-                description: 'Run a Cognitive Module to get structured AI analysis results',
+                description: 'Run a Cognitive Module to get structured AI analysis results (Cognitive Protocol v2.2)',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -61,7 +63,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: 'cognitive_list',
-                description: 'List all installed Cognitive Modules',
+                description: 'List all installed Cognitive Modules (Cognitive Protocol v2.2)',
                 inputSchema: {
                     type: 'object',
                     properties: {},
@@ -69,7 +71,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: 'cognitive_info',
-                description: 'Get detailed information about a Cognitive Module',
+                description: 'Get detailed information about a Cognitive Module (Cognitive Protocol v2.2)',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -84,113 +86,105 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
         ],
     };
 });
+// Error handling now uses unified errors module (../errors/index.js)
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
+    const runContext = name === 'cognitive_run'
+        ? { module: args.module, provider: args.provider ?? 'unknown' }
+        : undefined;
     try {
         switch (name) {
             case 'cognitive_run': {
                 const { module: moduleName, args: inputArgs, provider: providerName, model } = args;
+                const providerLabel = providerName ?? 'unknown';
                 // Find module
                 const moduleData = await findModule(moduleName, searchPaths);
                 if (!moduleData) {
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: JSON.stringify({ ok: false, error: `Module '${moduleName}' not found` }),
-                            },
-                        ],
-                    };
+                    return makeMcpError({
+                        code: ErrorCodes.MODULE_NOT_FOUND,
+                        message: `Module '${moduleName}' not found`,
+                        suggestion: 'Use cognitive_list to see available modules',
+                        module: moduleName,
+                        provider: providerLabel,
+                    });
                 }
                 // Create provider
                 const provider = getProvider(providerName, model);
-                // Run module
+                const resolvedProvider = provider?.name ?? providerLabel;
+                // Run module - result is already v2.2 envelope
                 const result = await runModule(moduleData, provider, {
-                    input: { query: inputArgs, code: inputArgs },
+                    args: inputArgs,
                     useV22: true,
                 });
+                const contextual = attachContext(result, {
+                    module: moduleName,
+                    provider: resolvedProvider,
+                });
                 return {
                     content: [
                         {
                             type: 'text',
-                            text: JSON.stringify(result, null, 2),
+                            text: JSON.stringify(contextual, null, 2),
                         },
                     ],
                 };
             }
             case 'cognitive_list': {
                 const modules = await listModules(searchPaths);
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: JSON.stringify({
-                                modules: modules.map((m) => ({
-                                    name: m.name,
-                                    location: m.location,
-                                    format: m.format,
-                                    tier: m.tier,
-                                })),
-                                count: modules.length,
-                            }, null, 2),
-                        },
-                    ],
-                };
+                return makeMcpSuccess({
+                    data: {
+                        modules: modules.map((m) => ({
+                            name: m.name,
+                            location: m.location,
+                            format: m.format,
+                            tier: m.tier,
+                            responsibility: m.responsibility,
+                        })),
+                        count: modules.length,
+                    },
+                    explain: `Found ${modules.length} installed modules`,
+                });
             }
             case 'cognitive_info': {
                 const { module: moduleName } = args;
                 const moduleData = await findModule(moduleName, searchPaths);
                 if (!moduleData) {
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: JSON.stringify({ ok: false, error: `Module '${moduleName}' not found` }),
-                            },
-                        ],
-                    };
+                    return makeMcpError({
+                        code: ErrorCodes.MODULE_NOT_FOUND,
+                        message: `Module '${moduleName}' not found`,
+                        suggestion: 'Use cognitive_list to see available modules',
+                        module: moduleName,
+                    });
                 }
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: JSON.stringify({
-                                ok: true,
-                                name: moduleData.name,
-                                version: moduleData.version,
-                                responsibility: moduleData.responsibility,
-                                tier: moduleData.tier,
-                                format: moduleData.format,
-                                inputSchema: moduleData.inputSchema,
-                                outputSchema: moduleData.outputSchema,
-                            }, null, 2),
-                        },
-                    ],
-                };
+                return makeMcpSuccess({
+                    data: {
+                        name: moduleData.name,
+                        version: moduleData.version,
+                        responsibility: moduleData.responsibility,
+                        tier: moduleData.tier,
+                        format: moduleData.format,
+                        inputSchema: moduleData.inputSchema,
+                        outputSchema: moduleData.outputSchema,
+                    },
+                    explain: `Module '${moduleName}' info retrieved`,
+                });
             }
             default:
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: JSON.stringify({ ok: false, error: `Unknown tool: ${name}` }),
-                        },
-                    ],
-                };
+                return makeMcpError({
+                    code: ErrorCodes.INVALID_REFERENCE,
+                    message: `Unknown tool: ${name}`,
+                    suggestion: 'Use cognitive_run, cognitive_list, or cognitive_info',
+                });
         }
     }
     catch (error) {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: JSON.stringify({
-                        ok: false,
-                        error: error instanceof Error ? error.message : String(error),
-                    }),
-                },
-            ],
-        };
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return makeMcpError({
+            code: ErrorCodes.INTERNAL_ERROR,
+            message: errorMessage,
+            recoverable: false,
+            ...(runContext ?? {}),
+        });
     }
 });
 // =============================================================================
@@ -234,12 +228,17 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
         const moduleName = match[1];
         const moduleData = await findModule(moduleName, searchPaths);
         if (!moduleData) {
+            const envelope = attachContext(makeErrorEnvelope({
+                code: ErrorCodes.MODULE_NOT_FOUND,
+                message: `Module '${moduleName}' not found`,
+                recoverable: true,
+            }), { module: moduleName });
             return {
                 contents: [
                     {
                         uri,
-                        mimeType: 'text/plain',
-                        text: `Module '${moduleName}' not found`,
+                        mimeType: 'application/json',
+                        text: JSON.stringify(envelope, null, 2),
                     },
                 ],
             };
@@ -254,12 +253,18 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
             ],
         };
     }
+    // Return structured error for unknown resource
+    const envelope = makeErrorEnvelope({
+        code: ErrorCodes.RESOURCE_NOT_FOUND,
+        message: `Unknown resource: ${uri}`,
+        recoverable: true,
+    });
     return {
         contents: [
             {
                 uri,
-                mimeType: 'text/plain',
-                text: `Unknown resource: ${uri}`,
+                mimeType: 'application/json',
+                text: JSON.stringify(envelope, null, 2),
             },
         ],
     };

package/dist/modules/composition.d.ts

@@ -0,0 +1,251 @@
+/**
+ * Composition Engine - Module Composition and Orchestration
+ *
+ * Implements COMPOSITION.md specification:
+ * - Sequential Composition: A → B → C
+ * - Parallel Composition: A → [B, C, D] → Aggregator
+ * - Conditional Composition: A → (condition) → B or C
+ * - Iterative Composition: A → (check) → A → ... → Done
+ * - Dataflow Mapping: JSONPath-like expressions
+ * - Aggregation Strategies: merge, array, first, custom
+ * - Dependency Resolution with fallbacks
+ * - Timeout handling
+ * - Circular dependency detection
+ */
+import type { CognitiveModule, ModuleResult, ModuleInput, Provider } from '../types.js';
+/** Composition pattern types */
+export type CompositionPattern = 'sequential' | 'parallel' | 'conditional' | 'iterative';
+/** Aggregation strategy for combining multiple outputs */
+export type AggregationStrategy = 'merge' | 'array' | 'first' | 'custom';
+/** Semver-like version matching pattern */
+export type VersionPattern = string;
+/** Dependency declaration for composition.requires */
+export interface DependencyDeclaration {
+    /** Module name */
+    name: string;
+    /** Semver version pattern */
+    version?: VersionPattern;
+    /** Whether dependency is optional */
+    optional?: boolean;
+    /** Fallback module if unavailable */
+    fallback?: string | null;
+    /** Per-module timeout (ms) */
+    timeout_ms?: number;
+}
+/** Dataflow mapping expression */
+export interface DataflowMapping {
+    [key: string]: string;
+}
+/** Condition expression for routing */
+export interface ConditionExpression {
+    expression: string;
+}
+/** Dataflow step configuration */
+export interface DataflowStep {
+    /** Source of data: 'input' or 'module-name.output' */
+    from: string | string[];
+    /** Destination: module name or 'output' */
+    to: string | string[];
+    /** Field mapping expressions */
+    mapping?: DataflowMapping;
+    /** Condition for execution */
+    condition?: string;
+    /** Aggregation strategy when from is an array */
+    aggregate?: AggregationStrategy;
+    /** Custom aggregation function name */
+    aggregator?: string;
+}
+/** Conditional routing rule */
+export interface RoutingRule {
+    /** Condition expression */
+    condition: string;
+    /** Next module to execute (null means use current result) */
+    next: string | null;
+}
+/** Full composition configuration (from module.yaml) */
+export interface CompositionConfig {
+    /** Composition pattern */
+    pattern: CompositionPattern;
+    /** Required dependencies */
+    requires?: DependencyDeclaration[];
+    /** Dataflow configuration */
+    dataflow?: DataflowStep[];
+    /** Conditional routing rules */
+    routing?: RoutingRule[];
+    /** Maximum composition depth */
+    max_depth?: number;
+    /** Total timeout for composition (ms) */
+    timeout_ms?: number;
+    /** Iteration configuration */
+    iteration?: {
+        /** Maximum iterations */
+        max_iterations?: number;
+        /** Condition to continue iterating */
+        continue_condition?: string;
+        /** Condition to stop iterating */
+        stop_condition?: string;
+    };
+}
+/** Execution context for composition */
+export interface CompositionContext {
+    /** Current execution depth */
+    depth: number;
+    /** Maximum allowed depth */
+    maxDepth: number;
+    /** Results from completed modules */
+    results: Record<string, ModuleResult>;
+    /** Original input data */
+    input: ModuleInput;
+    /** Currently running modules (for circular detection) */
+    running: Set<string>;
+    /** Start time for timeout tracking */
+    startTime: number;
+    /** Total timeout (ms) */
+    timeoutMs?: number;
+    /** Iteration count (for iterative composition) */
+    iterationCount: number;
+}
+/** Result of composition execution */
+export interface CompositionResult {
+    /** Whether composition succeeded */
+    ok: boolean;
+    /** Final aggregated result */
+    result?: ModuleResult;
+    /** Results from all executed modules */
+    moduleResults: Record<string, ModuleResult>;
+    /** Execution trace for debugging */
+    trace: ExecutionTrace[];
+    /** Total execution time (ms) */
+    totalTimeMs: number;
+    /** Error if composition failed */
+    error?: {
+        code: string;
+        message: string;
+        module?: string;
+    };
+}
+/** Execution trace entry */
+export interface ExecutionTrace {
+    module: string;
+    startTime: number;
+    endTime: number;
+    durationMs: number;
+    success: boolean;
+    skipped?: boolean;
+    reason?: string;
+}
+export declare const COMPOSITION_ERRORS: {
+    readonly E4004: "CIRCULAR_DEPENDENCY";
+    readonly E4005: "MAX_DEPTH_EXCEEDED";
+    readonly E4008: "COMPOSITION_TIMEOUT";
+    readonly E4009: "DEPENDENCY_NOT_FOUND";
+    readonly E4010: "DATAFLOW_ERROR";
+    readonly E4011: "CONDITION_EVAL_ERROR";
+    readonly E4012: "AGGREGATION_ERROR";
+    readonly E4013: "ITERATION_LIMIT_EXCEEDED";
+};
+/**
+ * Parse and evaluate JSONPath-like expressions.
+ *
+ * Supported syntax:
+ * - $.field - Root field access
+ * - $.nested.field - Nested access
+ * - $.array[0] - Array index
+ * - $.array[*].field - Array map
+ * - $ - Entire object
+ */
+export declare function evaluateJsonPath(expression: string, data: unknown): unknown;
+/**
+ * Apply dataflow mapping to transform data
+ */
+export declare function applyMapping(mapping: DataflowMapping, sourceData: unknown): Record<string, unknown>;
+/**
+ * Evaluate condition expressions.
+ *
+ * Supported operators:
+ * - Comparison: ==, !=, >, <, >=, <=
+ * - Logical: &&, ||, !
+ * - Existence: exists($.field)
+ * - String: contains($.field, "value")
+ */
+export declare function evaluateCondition(expression: string, data: unknown): boolean;
+/**
+ * Aggregate multiple results using specified strategy
+ */
+export declare function aggregateResults(results: ModuleResult[], strategy: AggregationStrategy): ModuleResult;
+/**
+ * Check if version matches pattern (simplified semver)
+ */
+export declare function versionMatches(version: string, pattern: string): boolean;
+/**
+ * Resolve a dependency, checking version and trying fallbacks
+ */
+export declare function resolveDependency(dep: DependencyDeclaration, searchPaths: string[]): Promise<CognitiveModule | null>;
+export declare class CompositionOrchestrator {
+    private provider;
+    private cwd;
+    private searchPaths;
+    constructor(provider: Provider, cwd?: string);
+    /**
+     * Execute a composed module workflow
+     */
+    execute(moduleName: string, input: ModuleInput, options?: {
+        maxDepth?: number;
+        timeoutMs?: number;
+    }): Promise<CompositionResult>;
+    /**
+     * Get composition config from module (if exists)
+     */
+    private getCompositionConfig;
+    /**
+     * Execute composition based on pattern
+     */
+    private executeComposition;
+    /**
+     * Execute sequential composition: A → B → C
+     */
+    private executeSequential;
+    /**
+     * Execute parallel composition: A → [B, C, D] → Aggregator
+     */
+    private executeParallel;
+    /**
+     * Execute conditional composition: A → (condition) → B or C
+     */
+    private executeConditional;
+    /**
+     * Execute iterative composition: A → (check) → A → ... → Done
+     */
+    private executeIterative;
+    /**
+     * Execute a single module
+     */
+    private executeModule;
+    /**
+     * Execute module with timeout
+     */
+    private executeModuleWithTimeout;
+    /**
+     * Check if composition has timed out
+     */
+    private isTimedOut;
+    /**
+     * Create timeout error response
+     */
+    private timeoutError;
+}
+/**
+ * Execute a composed module workflow
+ */
+export declare function executeComposition(moduleName: string, input: ModuleInput, provider: Provider, options?: {
+    cwd?: string;
+    maxDepth?: number;
+    timeoutMs?: number;
+}): Promise<CompositionResult>;
+/**
+ * Validate composition configuration
+ */
+export declare function validateCompositionConfig(config: CompositionConfig): {
+    valid: boolean;
+    errors: string[];
+};