cognitive-modules-cli 1.4.1 → 2.2.1

package/src/types.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
  */
 
 // =============================================================================
@@ -53,6 +53,90 @@ export type EnumStrategy = 'strict' | 'extensible';
 /** Risk aggregation rule */
 export type RiskRule = 'max_changes_risk' | 'max_issues_risk' | 'explicit';
 
+// =============================================================================
+// Composition Types (v2.2)
+// =============================================================================
+
+/** 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; // e.g., ">=1.0.0", "^1.0.0", "~1.0.0", "*"
+
+/** 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; // target_field: "$.source.path"
+}
+
+/** 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;
+}
+
 // =============================================================================
 // Module Configuration (v2.2)
 // =============================================================================
@@ -100,6 +184,9 @@ export interface CognitiveModule {
   // v2.2: Meta configuration (including risk_rule)
   metaConfig?: MetaConfig;
   
+  // v2.2: Composition configuration
+  composition?: CompositionConfig;
+  
   // Execution context
   context?: 'fork' | 'main';
   
@@ -223,9 +310,30 @@ export interface EnvelopeMeta {
   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;  // Envelope version (e.g., "2.2")
   meta: EnvelopeMeta;
   data: T;
 }
@@ -233,11 +341,9 @@ export interface EnvelopeSuccessV22<T = unknown> {
 /** Error response in v2.2 envelope format */
 export interface EnvelopeErrorV22 {
   ok: false;
+  version?: string;  // Envelope version (e.g., "2.2")
   meta: EnvelopeMeta;
-  error: {
-    code: string;
-    message: string;
-  };
+  error: EnvelopeError;
   partial_data?: unknown;
 }
 
@@ -318,12 +424,10 @@ export interface ModuleResultData {
 /** v2.2 module result with meta and data separation */
 export interface ModuleResultV22 {
   ok: boolean;
+  version?: string;  // Envelope version (e.g., "2.2")
   meta: EnvelopeMeta;
   data?: ModuleResultData;
-  error?: {
-    code: string;
-    message: string;
-  };
+  error?: EnvelopeError;
   partial_data?: unknown;
   raw?: string;
 }
@@ -493,456 +597,3 @@ export function shouldEscalate<T>(
   
   return false;
 }
-
-// =============================================================================
-// v2.5 Streaming Types
-// =============================================================================
-
-/** 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;  // First 6 chars of SHA256
-}
-
-/** 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;
-}
-
-// =============================================================================
-// v2.5 Response Mode Negotiation
-// =============================================================================
-
-/** 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[];
-}
-
-// =============================================================================
-// v2.5 Multimodal Types
-// =============================================================================
-
-/** 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 const MEDIA_MAGIC_BYTES: Record<string, string[]> = {
-  '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: Record<string, number> = {
-  '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
-};
-
-/** 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 const SUPPORTED_IMAGE_TYPES = [
-  'image/jpeg',
-  'image/png',
-  'image/webp',
-  'image/gif'
-] as const;
-
-/** Supported audio MIME types */
-export const SUPPORTED_AUDIO_TYPES = [
-  'audio/mpeg',
-  'audio/wav',
-  'audio/ogg',
-  'audio/webm'
-] as const;
-
-/** Supported video MIME types */
-export const SUPPORTED_VIDEO_TYPES = [
-  'video/mp4',
-  'video/webm',
-  'video/quicktime'
-] as const;
-
-// =============================================================================
-// 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',
-} as const;
-
-export type ErrorCodeV25 = typeof ErrorCodesV25[keyof typeof ErrorCodesV25];
-
-// =============================================================================
-// v2.5 Runtime Capabilities
-// =============================================================================
-
-/** 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 const DEFAULT_RUNTIME_CAPABILITIES: RuntimeCapabilities = {
-  streaming: true,
-  multimodal: {
-    input: ['text', 'image'],
-    output: ['text']
-  },
-  max_media_size_mb: 20,
-  supported_transports: ['sse', 'ndjson']
-};
-
-// =============================================================================
-// v2.5 Extended Provider Interface
-// =============================================================================
-
-/** 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 function isProviderV25(provider: Provider): provider is ProviderV25 {
-  return 'invokeStream' in provider || 'supportsStreaming' in provider;
-}
-
-// =============================================================================
-// v2.5 Module Configuration Extensions
-// =============================================================================
-
-/** 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 function isModuleV25(module: CognitiveModule): module is CognitiveModuleV25 {
-  return 'response' in module || 'modalities' in module;
-}
-
-/** Check if module supports streaming */
-export function moduleSupportsStreaming(module: CognitiveModule): boolean {
-  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: CognitiveModule): boolean {
-  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: CognitiveModule): ModalityType[] {
-  if (!isModuleV25(module)) return ['text'];
-  return module.modalities?.input ?? ['text'];
-}
-
-/** Get supported output modalities for module */
-export function getModuleOutputModalities(module: CognitiveModule): ModalityType[] {
-  if (!isModuleV25(module)) return ['text'];
-  return module.modalities?.output ?? ['text'];
-}

package/tsconfig.json

@@ -13,5 +13,5 @@
     "resolveJsonModule": true
   },
   "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
 }