cognitive-modules-cli 2.2.1 → 2.5.0-beta.1

package/src/types.ts

@@ -1,6 +1,6 @@
 /**
  * Cognitive Runtime - Core Types
- * Version 2.2 - With Control/Data plane separation, tier, overflow, extensible enums
+ * Version 2.5 - With streaming response and multimodal support
  */
 
 // =============================================================================
@@ -53,90 +53,6 @@ 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)
 // =============================================================================
@@ -184,9 +100,6 @@ export interface CognitiveModule {
   // v2.2: Meta configuration (including risk_rule)
   metaConfig?: MetaConfig;
   
-  // v2.2: Composition configuration
-  composition?: CompositionConfig;
-  
   // Execution context
   context?: 'fork' | 'main';
   
@@ -310,30 +223,9 @@ 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;
 }
@@ -341,9 +233,11 @@ 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: EnvelopeError;
+  error: {
+    code: string;
+    message: string;
+  };
   partial_data?: unknown;
 }
 
@@ -424,10 +318,12 @@ 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?: EnvelopeError;
+  error?: {
+    code: string;
+    message: string;
+  };
   partial_data?: unknown;
   raw?: string;
 }
@@ -597,3 +493,456 @@ 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", "**/*.test.ts"]
+  "exclude": ["node_modules", "dist"]
 }

package/dist/commands/compose.d.ts

@@ -1,31 +0,0 @@
-/**
- * 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>;