cognitive-modules-cli 2.2.0 → 2.2.1

package/dist/cli.js

@@ -15,7 +15,7 @@
  */
 import { parseArgs } from 'node:util';
 import { getProvider, listProviders } from './providers/index.js';
-import { run, list, pipe, init, add, update, remove, versions } from './commands/index.js';
+import { run, list, pipe, init, add, update, remove, versions, compose, composeInfo } from './commands/index.js';
 const VERSION = '1.3.0';
 async function main() {
     const args = process.argv.slice(2);
@@ -48,6 +48,10 @@ async function main() {
             // Server options
             host: { type: 'string', short: 'H' },
             port: { type: 'string', short: 'P' },
+            // Compose options
+            'max-depth': { type: 'string', short: 'd' },
+            timeout: { type: 'string', short: 'T' },
+            trace: { type: 'boolean', default: false },
         },
         allowPositionals: true,
     });
@@ -252,6 +256,45 @@ async function main() {
                 }
                 break;
             }
+            case 'compose': {
+                const moduleName = args[1];
+                if (!moduleName || moduleName.startsWith('-')) {
+                    console.error('Usage: cog compose <module> [--args "..."] [--timeout <ms>] [--max-depth <n>]');
+                    process.exit(1);
+                }
+                const result = await compose(moduleName, ctx, {
+                    args: values.args,
+                    input: values.input,
+                    maxDepth: values['max-depth'] ? parseInt(values['max-depth'], 10) : undefined,
+                    timeout: values.timeout ? parseInt(values.timeout, 10) : undefined,
+                    trace: values.trace,
+                    pretty: values.pretty,
+                    verbose: values.verbose,
+                });
+                if (!result.success) {
+                    console.error(`Error: ${result.error}`);
+                    if (result.data) {
+                        console.error('Partial results:', JSON.stringify(result.data, null, 2));
+                    }
+                    process.exit(1);
+                }
+                console.log(JSON.stringify(result.data, null, values.pretty ? 2 : 0));
+                break;
+            }
+            case 'compose-info': {
+                const moduleName = args[1];
+                if (!moduleName || moduleName.startsWith('-')) {
+                    console.error('Usage: cog compose-info <module>');
+                    process.exit(1);
+                }
+                const result = await composeInfo(moduleName, ctx);
+                if (!result.success) {
+                    console.error(`Error: ${result.error}`);
+                    process.exit(1);
+                }
+                console.log(JSON.stringify(result.data, null, 2));
+                break;
+            }
             case 'serve': {
                 const { serve } = await import('./server/http.js');
                 const port = values.port ? parseInt(values.port, 10) : 8000;
@@ -298,17 +341,19 @@ USAGE:
   cog <command> [options]
 
 COMMANDS:
-  run <module>      Run a Cognitive Module
-  list              List available modules
-  add <url>         Add module from GitHub
-  update <module>   Update module to latest version
-  remove <module>   Remove installed module
-  versions <url>    List available versions
-  pipe              Pipe mode (stdin/stdout)
-  init [name]       Initialize project or create module
-  serve             Start HTTP API server
-  mcp               Start MCP server (for Claude Code, Cursor)
-  doctor            Check configuration
+  run <module>        Run a Cognitive Module
+  compose <module>    Execute a composed module workflow
+  compose-info <mod>  Show composition configuration
+  list                List available modules
+  add <url>           Add module from GitHub
+  update <module>     Update module to latest version
+  remove <module>     Remove installed module
+  versions <url>      List available versions
+  pipe                Pipe mode (stdin/stdout)
+  init [name]         Initialize project or create module
+  serve               Start HTTP API server
+  mcp                 Start MCP server (for Claude Code, Cursor)
+  doctor              Check configuration
 
 OPTIONS:
   -a, --args <str>      Arguments to pass to module
@@ -324,6 +369,9 @@ OPTIONS:
   --no-validate         Skip schema validation
   -H, --host <host>     Server host (default: 0.0.0.0)
   -P, --port <port>     Server port (default: 8000)
+  -d, --max-depth <n>   Max composition depth (default: 5)
+  -T, --timeout <ms>    Composition timeout in milliseconds
+  --trace               Include execution trace (for compose)
   -v, --version         Show version
   -h, --help            Show this help
 
@@ -342,6 +390,11 @@ EXAMPLES:
   cog run code-reviewer --provider openai --model gpt-4o --args "..."
   cog list
 
+  # Compose modules (multi-step workflows)
+  cog compose code-review-pipeline --args "code to review"
+  cog compose smart-processor --args "input" --timeout 60000 --verbose
+  cog compose-info code-review-pipeline
+
   # Servers
   cog serve --port 8080
   cog mcp

package/dist/commands/compose.d.ts

@@ -0,0 +1,31 @@
+/**
+ * cog compose - Execute a Composed Cognitive Module Workflow
+ *
+ * Supports all composition patterns:
+ * - Sequential: A → B → C
+ * - Parallel: A → [B, C, D] → Aggregate
+ * - Conditional: A → (condition) → B or C
+ * - Iterative: A → (check) → A → ... → Done
+ */
+import type { CommandContext, CommandResult } from '../types.js';
+export interface ComposeOptions {
+    /** Direct text input */
+    args?: string;
+    /** JSON input data */
+    input?: string;
+    /** Maximum composition depth */
+    maxDepth?: number;
+    /** Timeout in milliseconds */
+    timeout?: number;
+    /** Include execution trace */
+    trace?: boolean;
+    /** Pretty print output */
+    pretty?: boolean;
+    /** Verbose mode */
+    verbose?: boolean;
+}
+export declare function compose(moduleName: string, ctx: CommandContext, options?: ComposeOptions): Promise<CommandResult>;
+/**
+ * Show composition info for a module
+ */
+export declare function composeInfo(moduleName: string, ctx: CommandContext): Promise<CommandResult>;

package/dist/commands/compose.js

@@ -0,0 +1,148 @@
+/**
+ * cog compose - Execute a Composed Cognitive Module Workflow
+ *
+ * Supports all composition patterns:
+ * - Sequential: A → B → C
+ * - Parallel: A → [B, C, D] → Aggregate
+ * - Conditional: A → (condition) → B or C
+ * - Iterative: A → (check) → A → ... → Done
+ */
+import { findModule, getDefaultSearchPaths, executeComposition } from '../modules/index.js';
+export async function compose(moduleName, ctx, options = {}) {
+    const searchPaths = getDefaultSearchPaths(ctx.cwd);
+    // Find module
+    const module = await findModule(moduleName, searchPaths);
+    if (!module) {
+        return {
+            success: false,
+            error: `Module not found: ${moduleName}\nSearch paths: ${searchPaths.join(', ')}`,
+        };
+    }
+    try {
+        // Parse input if provided as JSON
+        let inputData = {};
+        if (options.input) {
+            try {
+                inputData = JSON.parse(options.input);
+            }
+            catch {
+                return {
+                    success: false,
+                    error: `Invalid JSON input: ${options.input}`,
+                };
+            }
+        }
+        // Handle --args as text input
+        if (options.args) {
+            inputData.query = options.args;
+            inputData.code = options.args;
+        }
+        // Execute composition
+        const result = await executeComposition(moduleName, inputData, ctx.provider, {
+            cwd: ctx.cwd,
+            maxDepth: options.maxDepth,
+            timeoutMs: options.timeout
+        });
+        if (options.verbose) {
+            console.error('--- Composition Trace ---');
+            for (const entry of result.trace) {
+                const status = entry.success
+                    ? (entry.skipped ? '⏭️ SKIPPED' : '✅ OK')
+                    : '❌ FAILED';
+                console.error(`${status} ${entry.module} (${entry.durationMs}ms)`);
+                if (entry.reason) {
+                    console.error(`   Reason: ${entry.reason}`);
+                }
+            }
+            console.error(`--- Total: ${result.totalTimeMs}ms ---`);
+        }
+        // Return result
+        if (options.trace) {
+            // Include full result with trace
+            return {
+                success: result.ok,
+                data: {
+                    ok: result.ok,
+                    result: result.result,
+                    moduleResults: result.moduleResults,
+                    trace: result.trace,
+                    totalTimeMs: result.totalTimeMs,
+                    error: result.error
+                }
+            };
+        }
+        else if (options.pretty) {
+            return {
+                success: result.ok,
+                data: result.result,
+            };
+        }
+        else {
+            // For non-pretty mode, return data (success) or error (failure)
+            if (result.ok && result.result) {
+                return {
+                    success: true,
+                    data: result.result.data,
+                };
+            }
+            else {
+                return {
+                    success: false,
+                    error: result.error
+                        ? `${result.error.code}: ${result.error.message}`
+                        : 'Composition failed',
+                    data: result.moduleResults,
+                };
+            }
+        }
+    }
+    catch (e) {
+        return {
+            success: false,
+            error: e instanceof Error ? e.message : String(e),
+        };
+    }
+}
+/**
+ * Show composition info for a module
+ */
+export async function composeInfo(moduleName, ctx) {
+    const searchPaths = getDefaultSearchPaths(ctx.cwd);
+    const module = await findModule(moduleName, searchPaths);
+    if (!module) {
+        return {
+            success: false,
+            error: `Module not found: ${moduleName}`,
+        };
+    }
+    const composition = module.composition;
+    if (!composition) {
+        return {
+            success: true,
+            data: {
+                name: module.name,
+                hasComposition: false,
+                message: 'Module does not have composition configuration'
+            }
+        };
+    }
+    return {
+        success: true,
+        data: {
+            name: module.name,
+            hasComposition: true,
+            pattern: composition.pattern,
+            requires: composition.requires?.map(d => ({
+                name: d.name,
+                version: d.version,
+                optional: d.optional,
+                fallback: d.fallback
+            })),
+            dataflowSteps: composition.dataflow?.length ?? 0,
+            routingRules: composition.routing?.length ?? 0,
+            maxDepth: composition.max_depth,
+            timeoutMs: composition.timeout_ms,
+            iteration: composition.iteration
+        }
+    };
+}

package/dist/commands/index.d.ts

@@ -9,3 +9,4 @@ export * from './add.js';
 export * from './update.js';
 export * from './remove.js';
 export * from './versions.js';
+export * from './compose.js';

package/dist/commands/index.js

@@ -9,3 +9,4 @@ export * from './add.js';
 export * from './update.js';
 export * from './remove.js';
 export * from './versions.js';
+export * from './compose.js';

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

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[];
+};