cognitive-modules-cli 2.2.0 → 2.2.1

package/dist/types.d.ts

@@ -35,6 +35,77 @@ export type RiskLevel = 'none' | 'low' | 'medium' | 'high';
 export type EnumStrategy = 'strict' | 'extensible';
 /** Risk aggregation rule */
 export type RiskRule = 'max_changes_risk' | 'max_issues_risk' | 'explicit';
+/** 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;
+}
+/** 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;
+}
+/** Iteration configuration */
+export interface IterationConfig {
+    /** Maximum iterations */
+    max_iterations?: number;
+    /** Condition to continue iterating */
+    continue_condition?: string;
+    /** Condition to stop iterating */
+    stop_condition?: string;
+}
+/** 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?: IterationConfig;
+}
 export interface CognitiveModule {
     name: string;
     version: string;
@@ -52,6 +123,7 @@ export interface CognitiveModule {
     enums?: EnumConfig;
     compat?: CompatConfig;
     metaConfig?: MetaConfig;
+    composition?: CompositionConfig;
     context?: 'fork' | 'main';
     prompt: string;
     inputSchema?: object;
@@ -148,20 +220,34 @@ export interface EnvelopeMeta {
     /** Execution latency in milliseconds */
     latency_ms?: number;
 }
+/**
+ * Enhanced error structure with retry and recovery info (v2.2.1).
+ */
+export interface EnvelopeError {
+    /** Error code (e.g., "INVALID_INPUT", "PARSE_ERROR") */
+    code: string;
+    /** Human-readable error message */
+    message: string;
+    /** Whether the error can be retried */
+    recoverable?: boolean;
+    /** Suggested wait time before retry (in milliseconds) */
+    retry_after_ms?: number;
+    /** Additional error context */
+    details?: Record<string, unknown>;
+}
 /** Success response in v2.2 envelope format */
 export interface EnvelopeSuccessV22<T = unknown> {
     ok: true;
+    version?: string;
     meta: EnvelopeMeta;
     data: T;
 }
 /** Error response in v2.2 envelope format */
 export interface EnvelopeErrorV22 {
     ok: false;
+    version?: string;
     meta: EnvelopeMeta;
-    error: {
-        code: string;
-        message: string;
-    };
+    error: EnvelopeError;
     partial_data?: unknown;
 }
 /** v2.2 envelope response (union type) */
@@ -217,12 +303,10 @@ export interface ModuleResultData {
 /** v2.2 module result with meta and data separation */
 export interface ModuleResultV22 {
     ok: boolean;
+    version?: string;
     meta: EnvelopeMeta;
     data?: ModuleResultData;
-    error?: {
-        code: string;
-        message: string;
-    };
+    error?: EnvelopeError;
     partial_data?: unknown;
     raw?: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cognitive-modules-cli",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "description": "Cognitive Modules - Structured AI Task Execution with version management",
   "type": "module",
   "main": "dist/index.js",
@@ -37,6 +37,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
+    "ajv": "^8.12.0",
     "js-yaml": "^4.1.1"
   },
   "optionalDependencies": {

package/src/cli.ts

@@ -16,7 +16,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';
 import type { CommandContext } from './types.js';
 
 const VERSION = '1.3.0';
@@ -55,6 +55,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,
   });
@@ -291,6 +295,53 @@ 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'] as string, 10) : undefined,
+          timeout: values.timeout ? parseInt(values.timeout as string, 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 as string, 10) : 8000;
@@ -338,17 +389,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
@@ -364,6 +417,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
 
@@ -382,6 +438,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/src/commands/compose.ts

@@ -0,0 +1,185 @@
+/**
+ * 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';
+import { findModule, getDefaultSearchPaths, executeComposition } from '../modules/index.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 async function compose(
+  moduleName: string,
+  ctx: CommandContext,
+  options: ComposeOptions = {}
+): Promise<CommandResult> {
+  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: Record<string, unknown> = {};
+    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 as { data?: unknown }).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: string,
+  ctx: CommandContext
+): Promise<CommandResult> {
+  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/src/commands/index.ts

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

package/src/index.ts

@@ -19,6 +19,15 @@ export type {
   FailureContract,
   CommandContext,
   CommandResult,
+  // v2.2 Composition Types
+  CompositionConfig,
+  CompositionPattern,
+  DependencyDeclaration,
+  DataflowStep,
+  DataflowMapping,
+  RoutingRule,
+  AggregationStrategy,
+  IterationConfig,
 } from './types.js';
 
 // Providers
@@ -43,6 +52,32 @@ export {
   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,
+  type PolicyAction,
+  type PolicyCheckResult,
+  type ToolCallRequest,
+  type ToolCallResult,
+  type ToolExecutor,
 } from './modules/index.js';
 
 // Server