cognitive-modules-cli 2.2.1 → 2.2.7

package/dist/modules/composition.js

@@ -401,9 +401,12 @@ export function aggregateResults(results, strategy) {
             const avgConfidence = allMeta.length > 0
                 ? allMeta.reduce((sum, m) => sum + m.confidence, 0) / allMeta.length
                 : 0.5;
-            const maxRisk = allMeta.length > 0
-                ? ['none', 'low', 'medium', 'high'][Math.max(...allMeta.map(m => ['none', 'low', 'medium', 'high'].indexOf(m.risk)))]
-                : 'medium';
+            const riskLevels = { none: 0, low: 1, medium: 2, high: 3 };
+            const riskNames = ['none', 'low', 'medium', 'high'];
+            const maxRiskLevel = allMeta.length > 0
+                ? Math.max(...allMeta.map(m => riskLevels[m.risk] ?? 2))
+                : 2;
+            const maxRisk = riskNames[maxRiskLevel];
             return {
                 ok: true,
                 meta: {
@@ -502,6 +505,28 @@ export function versionMatches(version, pattern) {
         }
         return false;
     }
+    // <= match
+    if (pattern.startsWith('<=')) {
+        const pParts = parseVersion(pattern.slice(2));
+        for (let i = 0; i < 3; i++) {
+            if (vParts[i] < pParts[i])
+                return true;
+            if (vParts[i] > pParts[i])
+                return false;
+        }
+        return true;
+    }
+    // < match
+    if (pattern.startsWith('<') && !pattern.startsWith('<=')) {
+        const pParts = parseVersion(pattern.slice(1));
+        for (let i = 0; i < 3; i++) {
+            if (vParts[i] < pParts[i])
+                return true;
+            if (vParts[i] > pParts[i])
+                return false;
+        }
+        return false;
+    }
     // ^ (compatible) - same major
     if (pattern.startsWith('^')) {
         const pParts = parseVersion(pattern.slice(1));
@@ -816,18 +841,28 @@ export class CompositionOrchestrator {
             let sourceData = context.input;
             if (step.from) {
                 const sources = Array.isArray(step.from) ? step.from : [step.from];
+                const sourceDataArray = [];
                 for (const source of sources) {
                     if (source === 'input') {
-                        sourceData = context.input;
+                        sourceDataArray.push(context.input);
                     }
                     else {
                         const moduleName = source.replace('.output', '');
                         const moduleResult = context.results[moduleName];
                         if (moduleResult && 'data' in moduleResult) {
-                            sourceData = moduleResult.data;
+                            sourceDataArray.push(moduleResult.data);
                         }
                     }
                 }
+                if (sourceDataArray.length === 1) {
+                    sourceData = sourceDataArray[0];
+                }
+                else if (sourceDataArray.length > 1) {
+                    sourceData = { sources: sourceDataArray };
+                }
+                else {
+                    sourceData = context.input;
+                }
             }
             // Apply mapping
             if (step.mapping) {
@@ -866,6 +901,25 @@ export class CompositionOrchestrator {
             for (let i = 0; i < parallelModules.length; i++) {
                 context.results[parallelModules[i]] = parallelResults[i];
             }
+            // Attempt fallbacks for failed modules
+            for (let i = 0; i < parallelModules.length; i++) {
+                const result = parallelResults[i];
+                if (result.ok)
+                    continue;
+                const name = parallelModules[i];
+                const depConfig = composition.requires?.find(d => d.name === name);
+                const fallbackName = depConfig?.fallback;
+                if (!fallbackName)
+                    continue;
+                const fallbackModule = await findModule(fallbackName, this.searchPaths);
+                if (!fallbackModule)
+                    continue;
+                const depTimeout = depConfig?.timeout_ms;
+                const fallbackResult = await this.executeModuleWithTimeout(fallbackModule, sourceData, context, trace, depTimeout);
+                parallelResults[i] = fallbackResult;
+                context.results[fallbackName] = fallbackResult;
+                context.results[name] = fallbackResult;
+            }
             // Check for failures
             const failures = parallelResults.filter(r => !r.ok);
             if (failures.length > 0) {
@@ -1146,38 +1200,49 @@ export class CompositionOrchestrator {
      */
     async executeModuleWithTimeout(module, input, context, trace, timeoutMs) {
         const timeout = timeoutMs ?? context.timeoutMs;
+        const localTrace = [];
+        const localContext = {
+            ...context,
+            running: new Set(context.running),
+            results: { ...context.results },
+        };
+        const startTime = Date.now();
+        const execPromise = this.executeModule(module, input, localContext, localTrace);
         if (!timeout) {
-            return this.executeModule(module, input, context, trace);
+            const result = await execPromise;
+            trace.push(...localTrace);
+            return result;
         }
         let timeoutId = null;
-        const timeoutPromise = new Promise((_, reject) => {
-            timeoutId = setTimeout(() => {
-                reject(new Error(`Module ${module.name} timed out after ${timeout}ms`));
-            }, timeout);
+        const timeoutPromise = new Promise((resolve) => {
+            timeoutId = setTimeout(() => resolve({ type: 'timeout' }), timeout);
         });
-        try {
-            const result = await Promise.race([
-                this.executeModule(module, input, context, trace),
-                timeoutPromise
-            ]);
-            // Clear timeout on success to prevent memory leak
-            if (timeoutId)
-                clearTimeout(timeoutId);
-            return result;
-        }
-        catch (error) {
-            // Clear timeout on error too
-            if (timeoutId)
-                clearTimeout(timeoutId);
-            return {
-                ok: false,
-                meta: { confidence: 0, risk: 'high', explain: `Timeout: ${module.name}` },
-                error: {
-                    code: COMPOSITION_ERRORS.E4008,
-                    message: error.message
-                }
-            };
+        const raceResult = await Promise.race([
+            execPromise.then(result => ({ type: 'result', result })),
+            timeoutPromise
+        ]);
+        if (timeoutId)
+            clearTimeout(timeoutId);
+        if ('result' in raceResult) {
+            trace.push(...localTrace);
+            return raceResult.result;
         }
+        trace.push({
+            module: module.name,
+            startTime,
+            endTime: Date.now(),
+            durationMs: Date.now() - startTime,
+            success: false,
+            reason: `Timeout after ${timeout}ms`
+        });
+        return {
+            ok: false,
+            meta: { confidence: 0, risk: 'high', explain: `Timeout: ${module.name}` },
+            error: {
+                code: COMPOSITION_ERRORS.E4008,
+                message: `Module ${module.name} timed out after ${timeout}ms`
+            }
+        };
     }
     /**
      * Check if composition has timed out

package/dist/modules/loader.js

@@ -4,6 +4,7 @@
  */
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
+import { homedir } from 'node:os';
 import yaml from 'js-yaml';
 const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n([\s\S]*))?/;
 /**
@@ -54,7 +55,8 @@ async function loadModuleV2(modulePath) {
     const schemaFile = path.join(modulePath, 'schema.json');
     // Read module.yaml
     const manifestContent = await fs.readFile(manifestFile, 'utf-8');
-    const manifest = yaml.load(manifestContent);
+    const loaded = yaml.load(manifestContent);
+    const manifest = loaded && typeof loaded === 'object' ? loaded : {};
     // Detect v2.x version
     const formatVersion = detectV2Version(manifest);
     // Read prompt.md
@@ -394,7 +396,7 @@ export async function listModules(searchPaths) {
     return modules;
 }
 export function getDefaultSearchPaths(cwd) {
-    const home = process.env.HOME || '';
+    const home = homedir();
     return [
         path.join(cwd, 'cognitive', 'modules'),
         path.join(cwd, '.cognitive', 'modules'),

package/dist/modules/runner.d.ts

@@ -257,12 +257,69 @@ export declare function unregisterHook(hookType: 'before_call' | 'after_call' |
  * Clear all registered hooks.
  */
 export declare function clearHooks(): void;
+/**
+ * Error code taxonomy following CONFORMANCE.md E1xxx-E4xxx structure.
+ *
+ * E1xxx: Input errors (caller errors, fixable by modifying input)
+ * E2xxx: Processing errors (module understood input but couldn't complete)
+ * E3xxx: Output errors (generated output doesn't meet requirements)
+ * E4xxx: Runtime errors (infrastructure/system-level failures)
+ */
+/** Standard error codes with E-format (as per ERROR-CODES.md) */
+export declare const ERROR_CODES: {
+    readonly E1000: "PARSE_ERROR";
+    readonly E1001: "INVALID_INPUT";
+    readonly E1002: "MISSING_REQUIRED_FIELD";
+    readonly E1003: "TYPE_MISMATCH";
+    readonly E1004: "UNSUPPORTED_VALUE";
+    readonly E1005: "INPUT_TOO_LARGE";
+    readonly E1006: "INVALID_REFERENCE";
+    readonly E2001: "LOW_CONFIDENCE";
+    readonly E2002: "TIMEOUT";
+    readonly E2003: "TOKEN_LIMIT";
+    readonly E2004: "NO_ACTION_POSSIBLE";
+    readonly E2005: "SEMANTIC_CONFLICT";
+    readonly E2006: "AMBIGUOUS_INPUT";
+    readonly E2007: "INSUFFICIENT_CONTEXT";
+    readonly E3001: "OUTPUT_SCHEMA_VIOLATION";
+    readonly E3002: "PARTIAL_RESULT";
+    readonly E3003: "MISSING_RATIONALE";
+    readonly E3004: "OVERFLOW_LIMIT";
+    readonly E3005: "INVALID_ENUM";
+    readonly E3006: "CONSTRAINT_VIOLATION";
+    readonly E4000: "INTERNAL_ERROR";
+    readonly E4001: "PROVIDER_UNAVAILABLE";
+    readonly E4002: "RATE_LIMITED";
+    readonly E4003: "CONTEXT_OVERFLOW";
+    readonly E4004: "CIRCULAR_DEPENDENCY";
+    readonly E4005: "MAX_DEPTH_EXCEEDED";
+    readonly E4006: "MODULE_NOT_FOUND";
+    readonly E4007: "PERMISSION_DENIED";
+};
+/** Reverse mapping: legacy code -> E-format code */
+export declare const LEGACY_TO_E_CODE: Record<string, string>;
 /** Error codes and their default properties */
 export declare const ERROR_PROPERTIES: Record<string, {
     recoverable: boolean;
     retry_after_ms: number | null;
 }>;
+/**
+ * Normalize error code to E-format.
+ * Accepts both E-format (E1001) and legacy format (INVALID_INPUT).
+ *
+ * @param code Error code in any format
+ * @returns E-format code (e.g., "E1001")
+ */
+export declare function normalizeErrorCode(code: string): string;
+/**
+ * Get error category from E-format code.
+ *
+ * @param code E-format error code (e.g., "E1001")
+ * @returns Category: 'input' | 'processing' | 'output' | 'runtime'
+ */
+export declare function getErrorCategory(code: string): 'input' | 'processing' | 'output' | 'runtime';
 export interface MakeErrorResponseOptions {
+    /** Error code - accepts both E-format (E1001) and legacy format (INVALID_INPUT) */
     code: string;
     message: string;
     explain?: string;
@@ -272,9 +329,17 @@ export interface MakeErrorResponseOptions {
     retryAfterMs?: number;
     confidence?: number;
     risk?: RiskLevel;
+    /** Suggestion for how to fix the error */
+    suggestion?: string;
+    /** Whether to use E-format codes in output (default: true) */
+    useEFormat?: boolean;
 }
 /**
  * Build a standardized error response with enhanced taxonomy.
+ * Supports both E-format (E1001) and legacy format (INVALID_INPUT) error codes.
+ *
+ * @param options Error response options
+ * @returns Standardized error envelope
  */
 export declare function makeErrorResponse(options: MakeErrorResponseOptions): EnvelopeResponseV22<unknown>;
 export interface MakeSuccessResponseOptions {
@@ -304,13 +369,15 @@ export interface RunOptions {
 }
 export declare function runModule(module: CognitiveModule, provider: Provider, options?: RunOptions): Promise<ModuleResult>;
 /** Event types emitted during streaming execution */
-export type StreamEventType = 'start' | 'chunk' | 'meta' | 'complete' | 'error';
+export type StreamEventType = 'start' | 'delta' | 'meta' | 'end' | 'error';
 /** Event emitted during streaming execution */
 export interface StreamEvent {
     type: StreamEventType;
+    version: string;
     timestamp_ms: number;
-    module_name: string;
-    chunk?: string;
+    module: string;
+    provider?: string;
+    delta?: string;
     meta?: EnvelopeMeta;
     result?: EnvelopeResponseV22<unknown>;
     error?: {
@@ -333,9 +400,9 @@ export interface StreamOptions {
  *
  * Yields StreamEvent objects as the module executes:
  * - type="start": Module execution started
- * - type="chunk": Incremental data chunk (if LLM supports streaming)
+ * - type="delta": Incremental output delta (provider streaming chunk)
  * - type="meta": Meta information available early
- * - type="complete": Final complete result
+ * - type="end": Final result envelope (always emitted)
  * - type="error": Error occurred
  *
  * @example