cognitive-modules-cli 2.2.0 → 2.2.5

package/dist/modules/runner.d.ts

@@ -1,14 +1,435 @@
 /**
  * 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
  */
-import type { Provider, CognitiveModule, ModuleResult, ModuleInput } from '../types.js';
+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 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;
+    partialData?: unknown;
+    details?: Record<string, unknown>;
+    recoverable?: boolean;
+    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 {
+    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>;
 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;
+}
+/**
+ * Run a cognitive module with streaming output.
+ *
+ * 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);
+ *   }
+ * }
+ */
+export declare function runModuleStream(module: CognitiveModule, provider: Provider, options?: StreamOptions): AsyncGenerator<StreamEvent>;
+export interface RunModuleLegacyOptions {
+    validateInput?: boolean;
+    validateOutput?: boolean;
+    model?: string;
+}
+/**
+ * Run a cognitive module (legacy API, returns raw output).
+ * For backward compatibility. Throws on error instead of returning error envelope.
+ */
+export declare function runModuleLegacy(module: CognitiveModule, provider: Provider, input: ModuleInput, options?: RunModuleLegacyOptions): Promise<unknown>;
+/**
+ * Extract meta from v2.2 envelope for routing/logging.
+ */
+export declare function extractMeta(result: EnvelopeResponseV22<unknown>): EnvelopeMeta;
+export declare const extractMetaV22: typeof extractMeta;
+/**
+ * Determine if result should be escalated to human review based on meta.
+ */
+export declare function shouldEscalate(result: EnvelopeResponseV22<unknown>, confidenceThreshold?: number): boolean;
+export declare const shouldEscalateV22: typeof shouldEscalate;