cognitive-modules-cli 1.4.1 → 2.2.1

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 /**
  * Cognitive Runtime - Core Types
- * Version 2.5 - With streaming response and multimodal support
+ * Version 2.2 - With Control/Data plane separation, tier, overflow, extensible enums
  */
 export interface Provider {
     name: string;
@@ -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;
 }
@@ -282,310 +366,3 @@ export declare function extractMeta<T>(response: EnvelopeResponse<T>, riskRule?:
 export declare function aggregateRisk(data: Record<string, unknown>, riskRule?: RiskRule): RiskLevel;
 /** Check if result should be escalated to human review */
 export declare function shouldEscalate<T>(response: EnvelopeResponse<T>, confidenceThreshold?: number): boolean;
-/** Response mode configuration */
-export type ResponseMode = 'sync' | 'streaming' | 'both';
-/** Chunk type for streaming */
-export type ChunkType = 'delta' | 'snapshot';
-/** Response configuration in module.yaml */
-export interface ResponseConfig {
-    mode: ResponseMode;
-    chunk_type?: ChunkType;
-    buffer_size?: number;
-    heartbeat_interval_ms?: number;
-    max_duration_ms?: number;
-}
-/** Meta chunk - initial streaming response */
-export interface MetaChunk {
-    ok: true;
-    streaming: true;
-    session_id: string;
-    resumed?: boolean;
-    resume_from_seq?: number;
-    meta: Partial<EnvelopeMeta>;
-}
-/** Delta chunk - incremental content */
-export interface DeltaChunk {
-    chunk: {
-        seq: number;
-        type: 'delta';
-        field?: string;
-        delta: string;
-        checkpoint?: Checkpoint;
-    };
-}
-/** Snapshot chunk - full state replacement */
-export interface SnapshotChunk {
-    chunk: {
-        seq: number;
-        type: 'snapshot';
-        field?: string;
-        data: unknown;
-    };
-}
-/** Progress chunk - progress update */
-export interface ProgressChunk {
-    progress: {
-        percent: number;
-        stage?: string;
-        message?: string;
-    };
-}
-/** Final chunk - completion signal */
-export interface FinalChunk {
-    final: true;
-    meta: EnvelopeMeta;
-    data: ModuleResultData;
-    usage?: {
-        input_tokens: number;
-        output_tokens: number;
-        total_tokens: number;
-    };
-}
-/** Recovery checkpoint for stream resume */
-export interface Checkpoint {
-    offset: number;
-    hash: string;
-}
-/** Recovery information in error */
-export interface RecoveryInfo {
-    last_seq: number;
-    last_checkpoint?: Checkpoint;
-    retry_after_ms?: number;
-    max_retries?: number;
-}
-/** Error with optional recovery information */
-export interface ErrorWithRecovery {
-    code: string;
-    message: string;
-    recoverable?: boolean;
-    recovery?: RecoveryInfo;
-    details?: Record<string, unknown>;
-}
-/** Error chunk during streaming */
-export interface ErrorChunk {
-    ok: false;
-    streaming: true;
-    session_id?: string;
-    error: ErrorWithRecovery;
-    partial_data?: unknown;
-}
-/** Union of all streaming chunk types */
-export type StreamingChunk = MetaChunk | DeltaChunk | SnapshotChunk | ProgressChunk | FinalChunk | ErrorChunk;
-/** Streaming session state */
-export interface StreamingSession {
-    session_id: string;
-    module_name: string;
-    started_at: number;
-    chunks_sent: number;
-    accumulated_data: Record<string, unknown>;
-    accumulated_text: Record<string, string>;
-    last_checkpoint?: Checkpoint;
-}
-/** Request options for response mode negotiation */
-export interface RequestOptions {
-    response_mode?: ResponseMode;
-    chunk_type?: ChunkType;
-}
-/** Recovery context for stream retry */
-export interface RecoveryContext {
-    session_id: string;
-    last_seq: number;
-    last_checkpoint?: Checkpoint;
-}
-/** Warning in response (for fallback scenarios) */
-export interface ResponseWarning {
-    code: string;
-    message: string;
-    fallback_used?: string;
-}
-/** Execute options with negotiation support */
-export interface ExecuteOptionsV25 {
-    input: Record<string, unknown>;
-    _options?: RequestOptions;
-    _recovery?: RecoveryContext;
-}
-/** Negotiation result */
-export interface NegotiationResult {
-    mode: ResponseMode;
-    reason: 'header' | 'body_option' | 'query_param' | 'accept_header' | 'module_default';
-    warnings?: ResponseWarning[];
-}
-/** Supported modality types */
-export type ModalityType = 'text' | 'image' | 'audio' | 'video' | 'document';
-/** Modalities configuration in module.yaml */
-export interface ModalitiesConfig {
-    input: ModalityType[];
-    output: ModalityType[];
-    constraints?: MediaConstraints;
-}
-/** Media size/duration constraints */
-export interface MediaConstraints {
-    max_image_size_mb?: number;
-    max_audio_size_mb?: number;
-    max_video_size_mb?: number;
-    max_audio_duration_s?: number;
-    max_video_duration_s?: number;
-    allowed_image_types?: string[];
-    allowed_audio_types?: string[];
-    allowed_video_types?: string[];
-}
-/** Media input - URL reference */
-export interface UrlMediaInput {
-    type: 'url';
-    url: string;
-    media_type?: string;
-}
-/** Media input - Base64 inline */
-export interface Base64MediaInput {
-    type: 'base64';
-    media_type: string;
-    data: string;
-}
-/** Media input - File path */
-export interface FileMediaInput {
-    type: 'file';
-    path: string;
-}
-/** Media input - Upload reference (for pre-uploaded files) */
-export interface UploadRefMediaInput {
-    type: 'upload_ref';
-    upload_id: string;
-    media_type?: string;
-}
-/** Union of media input types */
-export type MediaInput = UrlMediaInput | Base64MediaInput | FileMediaInput | UploadRefMediaInput;
-/** Checksum for media integrity */
-export interface MediaChecksum {
-    algorithm: 'sha256' | 'md5' | 'crc32';
-    value: string;
-}
-/** Media validation result */
-export interface MediaValidationResult {
-    index: number;
-    media_type: string;
-    size_bytes: number;
-    dimensions?: {
-        width: number;
-        height: number;
-    };
-    duration_ms?: number;
-    valid: boolean;
-    errors?: string[];
-}
-/** Media validation summary in meta */
-export interface MediaValidationSummary {
-    input_count: number;
-    validated: MediaValidationResult[];
-}
-/** Magic bytes for media type detection */
-export declare const MEDIA_MAGIC_BYTES: Record<string, string[]>;
-/** Media size limits in bytes */
-export declare const MEDIA_SIZE_LIMITS: Record<string, number>;
-/** Media dimension limits */
-export declare const MEDIA_DIMENSION_LIMITS: {
-    max_width: number;
-    max_height: number;
-    min_width: number;
-    min_height: number;
-    max_pixels: number;
-};
-/** Media output with metadata */
-export interface MediaOutput {
-    type: 'url' | 'base64' | 'file';
-    media_type: string;
-    url?: string;
-    data?: string;
-    path?: string;
-    width?: number;
-    height?: number;
-    duration_ms?: number;
-    expires_at?: string;
-    generation_params?: Record<string, unknown>;
-}
-/** Supported image MIME types */
-export declare const SUPPORTED_IMAGE_TYPES: readonly ["image/jpeg", "image/png", "image/webp", "image/gif"];
-/** Supported audio MIME types */
-export declare const SUPPORTED_AUDIO_TYPES: readonly ["audio/mpeg", "audio/wav", "audio/ogg", "audio/webm"];
-/** Supported video MIME types */
-export declare const SUPPORTED_VIDEO_TYPES: readonly ["video/mp4", "video/webm", "video/quicktime"];
-/** v2.5 Error codes for streaming and multimodal */
-export declare const ErrorCodesV25: {
-    readonly UNSUPPORTED_MEDIA_TYPE: "E1010";
-    readonly MEDIA_TOO_LARGE: "E1011";
-    readonly MEDIA_FETCH_FAILED: "E1012";
-    readonly MEDIA_DECODE_FAILED: "E1013";
-    readonly MEDIA_TYPE_MISMATCH: "E1014";
-    readonly MEDIA_DIMENSION_EXCEEDED: "E1015";
-    readonly MEDIA_DIMENSION_TOO_SMALL: "E1016";
-    readonly MEDIA_PIXEL_LIMIT: "E1017";
-    readonly UPLOAD_EXPIRED: "E1018";
-    readonly UPLOAD_NOT_FOUND: "E1019";
-    readonly CHECKSUM_MISMATCH: "E1020";
-    readonly STREAM_INTERRUPTED: "E2010";
-    readonly STREAM_TIMEOUT: "E2011";
-    readonly STREAMING_NOT_SUPPORTED: "E4010";
-    readonly MULTIMODAL_NOT_SUPPORTED: "E4011";
-    readonly RECOVERY_NOT_SUPPORTED: "E4012";
-    readonly SESSION_EXPIRED: "E4013";
-    readonly CHECKPOINT_INVALID: "E4014";
-};
-export type ErrorCodeV25 = typeof ErrorCodesV25[keyof typeof ErrorCodesV25];
-/** Runtime capability declaration */
-export interface RuntimeCapabilities {
-    streaming: boolean;
-    multimodal: {
-        input: ModalityType[];
-        output: ModalityType[];
-    };
-    max_media_size_mb: number;
-    supported_transports: ('sse' | 'websocket' | 'ndjson')[];
-}
-/** Default runtime capabilities */
-export declare const DEFAULT_RUNTIME_CAPABILITIES: RuntimeCapabilities;
-/** Extended invoke params with streaming support */
-export interface InvokeParamsV25 extends InvokeParams {
-    stream?: boolean;
-    images?: MediaInput[];
-    audio?: MediaInput[];
-    video?: MediaInput[];
-}
-/** Streaming invoke result */
-export interface StreamingInvokeResult {
-    stream: AsyncIterable<string>;
-    usage?: {
-        promptTokens: number;
-        completionTokens: number;
-        totalTokens: number;
-    };
-}
-/** Extended provider interface for v2.5 */
-export interface ProviderV25 extends Provider {
-    /** Check if provider supports streaming */
-    supportsStreaming?(): boolean;
-    /** Check if provider supports multimodal input */
-    supportsMultimodal?(): {
-        input: ModalityType[];
-        output: ModalityType[];
-    };
-    /** Invoke with streaming */
-    invokeStream?(params: InvokeParamsV25): Promise<StreamingInvokeResult>;
-}
-/** Type guard for v2.5 provider */
-export declare function isProviderV25(provider: Provider): provider is ProviderV25;
-/** Extended module interface for v2.5 */
-export interface CognitiveModuleV25 extends CognitiveModule {
-    /** v2.5: Response configuration */
-    response?: ResponseConfig;
-    /** v2.5: Modalities configuration */
-    modalities?: ModalitiesConfig;
-}
-/** Type guard for v2.5 module */
-export declare function isModuleV25(module: CognitiveModule): module is CognitiveModuleV25;
-/** Check if module supports streaming */
-export declare function moduleSupportsStreaming(module: CognitiveModule): boolean;
-/** Check if module supports multimodal input */
-export declare function moduleSupportsMultimodal(module: CognitiveModule): boolean;
-/** Get supported input modalities for module */
-export declare function getModuleInputModalities(module: CognitiveModule): ModalityType[];
-/** Get supported output modalities for module */
-export declare function getModuleOutputModalities(module: CognitiveModule): ModalityType[];

package/dist/types.js

@@ -1,6 +1,6 @@
 /**
  * Cognitive Runtime - Core Types
- * Version 2.5 - With streaming response and multimodal support
+ * Version 2.2 - With Control/Data plane separation, tier, overflow, extensible enums
  */
 // =============================================================================
 // Utility Types
@@ -90,122 +90,3 @@ export function shouldEscalate(response, confidenceThreshold = 0.7) {
     }
     return false;
 }
-/** Magic bytes for media type detection */
-export const MEDIA_MAGIC_BYTES = {
-    'image/jpeg': ['ffd8ff'],
-    'image/png': ['89504e470d0a1a0a'],
-    'image/gif': ['47494638'],
-    'image/webp': ['52494646'],
-    'audio/mpeg': ['fffb', 'fffa', '494433'],
-    'audio/wav': ['52494646'],
-    'audio/ogg': ['4f676753'],
-    'video/mp4': ['0000001866747970', '0000002066747970'],
-    'video/webm': ['1a45dfa3'],
-    'application/pdf': ['25504446'],
-};
-/** Media size limits in bytes */
-export const MEDIA_SIZE_LIMITS = {
-    'image': 20 * 1024 * 1024, // 20MB
-    'audio': 25 * 1024 * 1024, // 25MB
-    'video': 100 * 1024 * 1024, // 100MB
-    'document': 50 * 1024 * 1024, // 50MB
-};
-/** Media dimension limits */
-export const MEDIA_DIMENSION_LIMITS = {
-    max_width: 8192,
-    max_height: 8192,
-    min_width: 10,
-    min_height: 10,
-    max_pixels: 67108864, // 8192 x 8192
-};
-/** Supported image MIME types */
-export const SUPPORTED_IMAGE_TYPES = [
-    'image/jpeg',
-    'image/png',
-    'image/webp',
-    'image/gif'
-];
-/** Supported audio MIME types */
-export const SUPPORTED_AUDIO_TYPES = [
-    'audio/mpeg',
-    'audio/wav',
-    'audio/ogg',
-    'audio/webm'
-];
-/** Supported video MIME types */
-export const SUPPORTED_VIDEO_TYPES = [
-    'video/mp4',
-    'video/webm',
-    'video/quicktime'
-];
-// =============================================================================
-// v2.5 Error Codes
-// =============================================================================
-/** v2.5 Error codes for streaming and multimodal */
-export const ErrorCodesV25 = {
-    // Media errors (E1xxx)
-    UNSUPPORTED_MEDIA_TYPE: 'E1010',
-    MEDIA_TOO_LARGE: 'E1011',
-    MEDIA_FETCH_FAILED: 'E1012',
-    MEDIA_DECODE_FAILED: 'E1013',
-    MEDIA_TYPE_MISMATCH: 'E1014',
-    MEDIA_DIMENSION_EXCEEDED: 'E1015',
-    MEDIA_DIMENSION_TOO_SMALL: 'E1016',
-    MEDIA_PIXEL_LIMIT: 'E1017',
-    UPLOAD_EXPIRED: 'E1018',
-    UPLOAD_NOT_FOUND: 'E1019',
-    CHECKSUM_MISMATCH: 'E1020',
-    // Streaming errors (E2xxx)
-    STREAM_INTERRUPTED: 'E2010',
-    STREAM_TIMEOUT: 'E2011',
-    // Capability errors (E4xxx)
-    STREAMING_NOT_SUPPORTED: 'E4010',
-    MULTIMODAL_NOT_SUPPORTED: 'E4011',
-    RECOVERY_NOT_SUPPORTED: 'E4012',
-    SESSION_EXPIRED: 'E4013',
-    CHECKPOINT_INVALID: 'E4014',
-};
-/** Default runtime capabilities */
-export const DEFAULT_RUNTIME_CAPABILITIES = {
-    streaming: true,
-    multimodal: {
-        input: ['text', 'image'],
-        output: ['text']
-    },
-    max_media_size_mb: 20,
-    supported_transports: ['sse', 'ndjson']
-};
-/** Type guard for v2.5 provider */
-export function isProviderV25(provider) {
-    return 'invokeStream' in provider || 'supportsStreaming' in provider;
-}
-/** Type guard for v2.5 module */
-export function isModuleV25(module) {
-    return 'response' in module || 'modalities' in module;
-}
-/** Check if module supports streaming */
-export function moduleSupportsStreaming(module) {
-    if (!isModuleV25(module))
-        return false;
-    const mode = module.response?.mode;
-    return mode === 'streaming' || mode === 'both';
-}
-/** Check if module supports multimodal input */
-export function moduleSupportsMultimodal(module) {
-    if (!isModuleV25(module))
-        return false;
-    const modalities = module.modalities?.input ?? ['text'];
-    return modalities.some(m => m !== 'text');
-}
-/** Get supported input modalities for module */
-export function getModuleInputModalities(module) {
-    if (!isModuleV25(module))
-        return ['text'];
-    return module.modalities?.input ?? ['text'];
-}
-/** Get supported output modalities for module */
-export function getModuleOutputModalities(module) {
-    if (!isModuleV25(module))
-        return ['text'];
-    return module.modalities?.output ?? ['text'];
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cognitive-modules-cli",
-  "version": "1.4.1",
+  "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": {