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

package/dist/modules/runner.d.ts

@@ -1,370 +1,56 @@
 /**
  * Module Runner - Execute Cognitive Modules
- * v2.2: Envelope format with meta/data separation, risk_rule, repair pass
- * v2.2.1: Version field, enhanced error taxonomy, observability hooks, streaming
+ * v2.5: Streaming response and multimodal support
  */
-import type { Provider, CognitiveModule, ModuleResult, ModuleInput, EnvelopeResponseV22, EnvelopeMeta, RiskLevel } from '../types.js';
-/**
- * Validate data against JSON schema. Returns list of errors.
- */
-export declare function validateData(data: unknown, schema: object, label?: string): string[];
-/** Action types that can be checked against policies */
-export type PolicyAction = 'network' | 'filesystem_write' | 'side_effects' | 'code_execution';
-/** Result of a policy check */
-export interface PolicyCheckResult {
-    allowed: boolean;
-    reason?: string;
-    policy?: string;
-}
-/**
- * Check if a tool is allowed by the module's tools policy.
- *
- * @param toolName The name of the tool to check
- * @param module The cognitive module config
- * @returns PolicyCheckResult indicating if the tool is allowed
- *
- * @example
- * const result = checkToolPolicy('write_file', module);
- * if (!result.allowed) {
- *   throw new Error(result.reason);
- * }
- */
-export declare function checkToolPolicy(toolName: string, module: CognitiveModule): PolicyCheckResult;
-/**
- * Check if an action is allowed by the module's policies.
- *
- * @param action The action to check (network, filesystem_write, etc.)
- * @param module The cognitive module config
- * @returns PolicyCheckResult indicating if the action is allowed
- *
- * @example
- * const result = checkPolicy('network', module);
- * if (!result.allowed) {
- *   throw new Error(result.reason);
- * }
- */
-export declare function checkPolicy(action: PolicyAction, module: CognitiveModule): PolicyCheckResult;
-/**
- * Check if a tool is allowed considering both tools policy and general policies.
- * This performs a comprehensive check that:
- * 1. Checks the tools policy (allowed/denied lists)
- * 2. Maps the tool to policy actions and checks those
- *
- * @param toolName The name of the tool to check
- * @param module The cognitive module config
- * @returns PolicyCheckResult with detailed information
- *
- * @example
- * const result = checkToolAllowed('write_file', module);
- * if (!result.allowed) {
- *   return makeErrorResponse({
- *     code: 'POLICY_VIOLATION',
- *     message: result.reason,
- *   });
- * }
- */
-export declare function checkToolAllowed(toolName: string, module: CognitiveModule): PolicyCheckResult;
-/**
- * Validate that a list of tools are all allowed by the module's policies.
- * Returns all violations found.
- *
- * @param toolNames List of tool names to check
- * @param module The cognitive module config
- * @returns Array of PolicyCheckResult for denied tools
- */
-export declare function validateToolsAllowed(toolNames: string[], module: CognitiveModule): PolicyCheckResult[];
-/**
- * Get all denied actions for a module based on its policies.
- * Useful for informing LLM about restrictions.
- */
-export declare function getDeniedActions(module: CognitiveModule): PolicyAction[];
-/**
- * Get all denied tools for a module based on its tools policy.
- */
-export declare function getDeniedTools(module: CognitiveModule): string[];
-/**
- * Get all allowed tools for a module (only meaningful in deny_by_default mode).
- */
-export declare function getAllowedTools(module: CognitiveModule): string[] | null;
-/** Tool call request from LLM */
-export interface ToolCallRequest {
-    name: string;
-    arguments: Record<string, unknown>;
-}
-/** Tool call result */
-export interface ToolCallResult {
-    success: boolean;
-    result?: unknown;
-    error?: {
-        code: string;
-        message: string;
-    };
-}
-/** Tool executor function type */
-export type ToolExecutor = (args: Record<string, unknown>) => Promise<unknown>;
-/**
- * ToolCallInterceptor - Intercepts and validates tool calls against module policies.
- *
- * Use this class to wrap tool execution with policy enforcement:
- *
- * @example
- * const interceptor = new ToolCallInterceptor(module);
- *
- * // Register tool executors
- * interceptor.registerTool('read_file', async (args) => {
- *   return fs.readFile(args.path as string, 'utf-8');
- * });
- *
- * // Execute tool with policy check
- * const result = await interceptor.execute({
- *   name: 'write_file',
- *   arguments: { path: '/tmp/test.txt', content: 'hello' }
- * });
- *
- * if (!result.success) {
- *   console.error('Tool blocked:', result.error);
- * }
- */
-export declare class ToolCallInterceptor {
-    private module;
-    private tools;
-    private callLog;
-    constructor(module: CognitiveModule);
-    /**
-     * Register a tool executor.
-     */
-    registerTool(name: string, executor: ToolExecutor): void;
-    /**
-     * Register multiple tools at once.
-     */
-    registerTools(tools: Record<string, ToolExecutor>): void;
-    /**
-     * Check if a tool call is allowed without executing it.
-     */
-    checkAllowed(toolName: string): PolicyCheckResult;
-    /**
-     * Execute a tool call with policy enforcement.
-     *
-     * @param request The tool call request
-     * @returns ToolCallResult with success/error
-     */
-    execute(request: ToolCallRequest): Promise<ToolCallResult>;
-    /**
-     * Execute multiple tool calls in sequence.
-     * Stops on first policy violation.
-     */
-    executeMany(requests: ToolCallRequest[]): Promise<ToolCallResult[]>;
-    /**
-     * Get the call log for auditing.
-     */
-    getCallLog(): Array<{
-        tool: string;
-        allowed: boolean;
-        timestamp: number;
-    }>;
-    /**
-     * Get summary of denied calls.
-     */
-    getDeniedCalls(): Array<{
-        tool: string;
-        timestamp: number;
-    }>;
-    /**
-     * Clear the call log.
-     */
-    clearLog(): void;
-    /**
-     * Get policy summary for this module.
-     */
-    getPolicySummary(): {
-        deniedActions: PolicyAction[];
-        deniedTools: string[];
-        allowedTools: string[] | null;
-        toolsPolicy: 'allow_by_default' | 'deny_by_default' | undefined;
-    };
-}
-/**
- * Create a policy-aware tool executor wrapper.
- *
- * @example
- * const safeExecutor = createPolicyAwareExecutor(module, 'write_file', async (args) => {
- *   return fs.writeFile(args.path, args.content);
- * });
- *
- * // This will throw if write_file is denied
- * await safeExecutor({ path: '/tmp/test.txt', content: 'hello' });
- */
-export declare function createPolicyAwareExecutor(module: CognitiveModule, toolName: string, executor: ToolExecutor): ToolExecutor;
-/**
- * Validate overflow.insights against module's max_items config.
- *
- * @param data The response data object
- * @param module The cognitive module config
- * @returns Array of errors if insights exceed limit
- */
-export declare function validateOverflowLimits(data: Record<string, unknown>, module: CognitiveModule): string[];
-/**
- * Validate enum values against module's enum strategy.
- * For strict mode, custom enum objects are not allowed.
- *
- * @param data The response data object
- * @param module The cognitive module config
- * @returns Array of errors if enum violations found
- */
-export declare function validateEnumStrategy(data: Record<string, unknown>, module: CognitiveModule): string[];
-/** Hook called before module execution */
-export type BeforeCallHook = (moduleName: string, inputData: ModuleInput, moduleConfig: CognitiveModule) => void;
-/** Hook called after successful module execution */
-export type AfterCallHook = (moduleName: string, result: EnvelopeResponseV22<unknown>, latencyMs: number) => void;
-/** Hook called when an error occurs */
-export type ErrorHook = (moduleName: string, error: Error, partialResult: unknown | null) => void;
-/**
- * Decorator to register a before-call hook.
- *
- * @example
- * onBeforeCall((moduleName, inputData, config) => {
- *   console.log(`Calling ${moduleName} with`, inputData);
- * });
- */
-export declare function onBeforeCall(hook: BeforeCallHook): BeforeCallHook;
-/**
- * Decorator to register an after-call hook.
- *
- * @example
- * onAfterCall((moduleName, result, latencyMs) => {
- *   console.log(`${moduleName} completed in ${latencyMs}ms`);
- * });
- */
-export declare function onAfterCall(hook: AfterCallHook): AfterCallHook;
-/**
- * Decorator to register an error hook.
- *
- * @example
- * onError((moduleName, error, partialResult) => {
- *   console.error(`Error in ${moduleName}:`, error);
- * });
- */
-export declare function onError(hook: ErrorHook): ErrorHook;
-/**
- * Register a hook programmatically.
- */
-export declare function registerHook(hookType: 'before_call' | 'after_call' | 'error', hook: BeforeCallHook | AfterCallHook | ErrorHook): void;
-/**
- * Unregister a hook. Returns true if found and removed.
- */
-export declare function unregisterHook(hookType: 'before_call' | 'after_call' | 'error', hook: BeforeCallHook | AfterCallHook | ErrorHook): boolean;
-/**
- * Clear all registered hooks.
- */
-export declare function clearHooks(): void;
-/** Error codes and their default properties */
-export declare const ERROR_PROPERTIES: Record<string, {
-    recoverable: boolean;
-    retry_after_ms: number | null;
-}>;
-export interface MakeErrorResponseOptions {
-    code: string;
-    message: string;
-    explain?: string;
-    partialData?: unknown;
-    details?: Record<string, unknown>;
-    recoverable?: boolean;
-    retryAfterMs?: number;
-    confidence?: number;
-    risk?: RiskLevel;
-}
-/**
- * Build a standardized error response with enhanced taxonomy.
- */
-export declare function makeErrorResponse(options: MakeErrorResponseOptions): EnvelopeResponseV22<unknown>;
-export interface MakeSuccessResponseOptions {
-    data: unknown;
-    confidence: number;
-    risk: RiskLevel;
-    explain: string;
-    latencyMs?: number;
-    model?: string;
-    traceId?: string;
-}
-/**
- * Build a standardized success response.
- */
-export declare function makeSuccessResponse(options: MakeSuccessResponseOptions): EnvelopeResponseV22<unknown>;
+import type { Provider, CognitiveModule, ModuleResult, ModuleInput, StreamingChunk, MediaInput, ModalityType, RuntimeCapabilities } from '../types.js';
 export interface RunOptions {
     input?: ModuleInput;
     args?: string;
     verbose?: boolean;
-    validateInput?: boolean;
-    validateOutput?: boolean;
     useEnvelope?: boolean;
     useV22?: boolean;
     enableRepair?: boolean;
-    traceId?: string;
-    model?: string;
 }
 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';
-/** Event emitted during streaming execution */
-export interface StreamEvent {
-    type: StreamEventType;
-    timestamp_ms: number;
-    module_name: string;
-    chunk?: string;
-    meta?: EnvelopeMeta;
-    result?: EnvelopeResponseV22<unknown>;
-    error?: {
-        code: string;
-        message: string;
-    };
-}
-export interface StreamOptions {
-    input?: ModuleInput;
-    args?: string;
-    validateInput?: boolean;
-    validateOutput?: boolean;
-    useV22?: boolean;
-    enableRepair?: boolean;
-    traceId?: string;
-    model?: string;
+export interface StreamRunOptions extends RunOptions {
+    /** Callback for each chunk */
+    onChunk?: (chunk: StreamingChunk) => void;
+    /** Callback for progress updates */
+    onProgress?: (percent: number, message?: string) => void;
+    /** Heartbeat interval in milliseconds (default: 15000) */
+    heartbeatInterval?: number;
+    /** Maximum stream duration in milliseconds (default: 300000) */
+    maxDuration?: number;
 }
 /**
- * Run a cognitive module with streaming output.
+ * Run module with streaming response
  *
- * Yields StreamEvent objects as the module executes:
- * - type="start": Module execution started
- * - type="chunk": Incremental data chunk (if LLM supports streaming)
- * - type="meta": Meta information available early
- * - type="complete": Final complete result
- * - type="error": Error occurred
- *
- * @example
- * for await (const event of runModuleStream(module, provider, options)) {
- *   if (event.type === 'chunk') {
- *     process.stdout.write(event.chunk);
- *   } else if (event.type === 'complete') {
- *     console.log('Result:', event.result);
- *   }
- * }
+ * @param module - The cognitive module to execute
+ * @param provider - The LLM provider
+ * @param options - Run options including streaming callbacks
+ * @yields Streaming chunks
  */
-export declare function runModuleStream(module: CognitiveModule, provider: Provider, options?: StreamOptions): AsyncGenerator<StreamEvent>;
-export interface RunModuleLegacyOptions {
-    validateInput?: boolean;
-    validateOutput?: boolean;
-    model?: string;
-}
+export declare function runModuleStream(module: CognitiveModule, provider: Provider, options?: StreamRunOptions): AsyncGenerator<StreamingChunk, ModuleResult | undefined, unknown>;
+/**
+ * Load media file as base64
+ */
+export declare function loadMediaAsBase64(path: string): Promise<{
+    data: string;
+    media_type: string;
+} | null>;
 /**
- * Run a cognitive module (legacy API, returns raw output).
- * For backward compatibility. Throws on error instead of returning error envelope.
+ * Validate media input against module constraints
  */
-export declare function runModuleLegacy(module: CognitiveModule, provider: Provider, input: ModuleInput, options?: RunModuleLegacyOptions): Promise<unknown>;
+export declare function validateMediaInput(media: MediaInput, module: CognitiveModule, maxSizeMb?: number): {
+    valid: boolean;
+    error?: string;
+    code?: string;
+};
 /**
- * Extract meta from v2.2 envelope for routing/logging.
+ * Get runtime capabilities
  */
-export declare function extractMeta(result: EnvelopeResponseV22<unknown>): EnvelopeMeta;
-export declare const extractMetaV22: typeof extractMeta;
+export declare function getRuntimeCapabilities(): RuntimeCapabilities;
 /**
- * Determine if result should be escalated to human review based on meta.
+ * Check if runtime supports a specific modality
  */
-export declare function shouldEscalate(result: EnvelopeResponseV22<unknown>, confidenceThreshold?: number): boolean;
-export declare const shouldEscalateV22: typeof shouldEscalate;
+export declare function runtimeSupportsModality(modality: ModalityType, direction?: 'input' | 'output'): boolean;