cognitive-modules-cli 1.4.0 → 2.2.0

package/dist/modules/runner.d.ts

@@ -1,8 +1,8 @@
 /**
  * Module Runner - Execute Cognitive Modules
- * v2.5: Streaming response and multimodal support
+ * v2.2: Envelope format with meta/data separation, risk_rule, repair pass
  */
-import type { Provider, CognitiveModule, ModuleResult, ModuleInput, StreamingChunk, MediaInput, ModalityType, RuntimeCapabilities } from '../types.js';
+import type { Provider, CognitiveModule, ModuleResult, ModuleInput } from '../types.js';
 export interface RunOptions {
     input?: ModuleInput;
     args?: string;
@@ -12,45 +12,3 @@ export interface RunOptions {
     enableRepair?: boolean;
 }
 export declare function runModule(module: CognitiveModule, provider: Provider, options?: RunOptions): Promise<ModuleResult>;
-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 module with streaming response
- *
- * @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?: StreamRunOptions): AsyncGenerator<StreamingChunk, ModuleResult | undefined, unknown>;
-/**
- * Load media file as base64
- */
-export declare function loadMediaAsBase64(path: string): Promise<{
-    data: string;
-    media_type: string;
-} | null>;
-/**
- * Validate media input against module constraints
- */
-export declare function validateMediaInput(media: MediaInput, module: CognitiveModule, maxSizeMb?: number): {
-    valid: boolean;
-    error?: string;
-    code?: string;
-};
-/**
- * Get runtime capabilities
- */
-export declare function getRuntimeCapabilities(): RuntimeCapabilities;
-/**
- * Check if runtime supports a specific modality
- */
-export declare function runtimeSupportsModality(modality: ModalityType, direction?: 'input' | 'output'): boolean;

package/dist/modules/runner.js

@@ -1,12 +1,8 @@
 /**
  * Module Runner - Execute Cognitive Modules
- * v2.5: Streaming response and multimodal support
+ * v2.2: Envelope format with meta/data separation, risk_rule, repair pass
  */
-import { aggregateRisk, isV22Envelope, isProviderV25, isModuleV25, moduleSupportsStreaming, moduleSupportsMultimodal, getModuleInputModalities, ErrorCodesV25, DEFAULT_RUNTIME_CAPABILITIES } from '../types.js';
-import { randomUUID } from 'crypto';
-import { readFile } from 'fs/promises';
-import { existsSync } from 'fs';
-import { extname } from 'path';
+import { aggregateRisk, isV22Envelope } from '../types.js';
 // =============================================================================
 // Repair Pass (v2.2)
 // =============================================================================
@@ -409,601 +405,3 @@ function looksLikeCode(str) {
     ];
     return codeIndicators.some(re => re.test(str));
 }
-/**
- * Create a new streaming session
- */
-function createStreamingSession(moduleName) {
-    return {
-        session_id: `sess_${randomUUID().slice(0, 12)}`,
-        module_name: moduleName,
-        started_at: Date.now(),
-        chunks_sent: 0,
-        accumulated_data: {},
-        accumulated_text: {}
-    };
-}
-/**
- * Create meta chunk (initial streaming response)
- */
-function createMetaChunk(session, meta) {
-    return {
-        ok: true,
-        streaming: true,
-        session_id: session.session_id,
-        meta
-    };
-}
-/**
- * Create delta chunk (incremental content)
- * Note: Delta chunks don't include session_id per v2.5 spec
- */
-function createDeltaChunk(session, field, delta) {
-    session.chunks_sent++;
-    return {
-        chunk: {
-            seq: session.chunks_sent,
-            type: 'delta',
-            field,
-            delta
-        }
-    };
-}
-/**
- * Create progress chunk
- * Note: Progress chunks don't include session_id per v2.5 spec
- */
-function createProgressChunk(_session, percent, stage, message) {
-    return {
-        progress: {
-            percent,
-            stage,
-            message
-        }
-    };
-}
-/**
- * Create final chunk (completion signal)
- * Note: Final chunks don't include session_id per v2.5 spec
- */
-function createFinalChunk(_session, meta, data, usage) {
-    return {
-        final: true,
-        meta,
-        data,
-        usage
-    };
-}
-/**
- * Create error chunk
- */
-function createErrorChunk(session, code, message, recoverable = false, partialData) {
-    return {
-        ok: false,
-        streaming: true,
-        session_id: session.session_id,
-        error: {
-            code,
-            message,
-            recoverable
-        },
-        partial_data: partialData
-    };
-}
-/**
- * Run module with streaming response
- *
- * @param module - The cognitive module to execute
- * @param provider - The LLM provider
- * @param options - Run options including streaming callbacks
- * @yields Streaming chunks
- */
-export async function* runModuleStream(module, provider, options = {}) {
-    const { onChunk, onProgress, heartbeatInterval = 15000, maxDuration = 300000, ...runOptions } = options;
-    // Create streaming session
-    const session = createStreamingSession(module.name);
-    const startTime = Date.now();
-    // Check if module supports streaming
-    if (!moduleSupportsStreaming(module)) {
-        // Fallback to sync execution
-        const result = await runModule(module, provider, runOptions);
-        // Emit as single final chunk
-        if (result.ok && 'meta' in result) {
-            const finalChunk = createFinalChunk(session, result.meta, result.data);
-            yield finalChunk;
-            onChunk?.(finalChunk);
-            return result;
-        }
-        return result;
-    }
-    // Check if provider supports streaming
-    if (!isProviderV25(provider) || !provider.supportsStreaming?.()) {
-        // Fallback to sync with warning
-        console.warn('[cognitive] Provider does not support streaming, falling back to sync');
-        const result = await runModule(module, provider, runOptions);
-        if (result.ok && 'meta' in result) {
-            const finalChunk = createFinalChunk(session, result.meta, result.data);
-            yield finalChunk;
-            onChunk?.(finalChunk);
-        }
-        return result;
-    }
-    // Emit initial meta chunk
-    const metaChunk = createMetaChunk(session, {
-        confidence: undefined,
-        risk: 'low',
-        explain: 'Processing...'
-    });
-    yield metaChunk;
-    onChunk?.(metaChunk);
-    // Build prompt and messages (same as sync)
-    const { input, args, verbose = false, useEnvelope, useV22 } = runOptions;
-    const shouldUseEnvelope = useEnvelope ?? (module.output?.envelope === true || module.format === 'v2');
-    const isV22Module = module.tier !== undefined || module.formatVersion === 'v2.2';
-    const shouldUseV22 = useV22 ?? (isV22Module || module.compat?.runtime_auto_wrap === true);
-    const riskRule = module.metaConfig?.risk_rule ?? 'max_changes_risk';
-    const inputData = input || {};
-    if (args && !inputData.code && !inputData.query) {
-        if (looksLikeCode(args)) {
-            inputData.code = args;
-        }
-        else {
-            inputData.query = args;
-        }
-    }
-    // Extract media from input
-    const mediaInputs = extractMediaInputs(inputData);
-    // Build prompt with media placeholders
-    const prompt = buildPromptWithMedia(module, inputData, mediaInputs);
-    // Build system message
-    const systemParts = buildSystemMessage(module, shouldUseEnvelope, shouldUseV22);
-    const messages = [
-        { role: 'system', content: systemParts.join('\n') },
-        { role: 'user', content: prompt },
-    ];
-    try {
-        // Start streaming invocation
-        const streamResult = await provider.invokeStream({
-            messages,
-            jsonSchema: module.outputSchema,
-            temperature: 0.3,
-            stream: true,
-            images: mediaInputs.images,
-            audio: mediaInputs.audio,
-            video: mediaInputs.video
-        });
-        let accumulatedContent = '';
-        let lastProgressTime = Date.now();
-        // Process stream
-        for await (const chunk of streamResult.stream) {
-            // Check timeout
-            if (Date.now() - startTime > maxDuration) {
-                const errorChunk = createErrorChunk(session, ErrorCodesV25.STREAM_TIMEOUT, `Stream exceeded max duration of ${maxDuration}ms`, false, { partial_content: accumulatedContent });
-                yield errorChunk;
-                onChunk?.(errorChunk);
-                return undefined;
-            }
-            // Accumulate content
-            accumulatedContent += chunk;
-            // Emit delta chunk
-            const deltaChunk = createDeltaChunk(session, 'data.rationale', chunk);
-            yield deltaChunk;
-            onChunk?.(deltaChunk);
-            // Emit progress periodically
-            const now = Date.now();
-            if (now - lastProgressTime > 1000) {
-                const elapsed = now - startTime;
-                const estimatedPercent = Math.min(90, Math.floor(elapsed / maxDuration * 100));
-                const progressChunk = createProgressChunk(session, estimatedPercent, 'generating', 'Generating response...');
-                yield progressChunk;
-                onProgress?.(estimatedPercent, 'Generating response...');
-                lastProgressTime = now;
-            }
-        }
-        // Parse accumulated response
-        let parsed;
-        try {
-            const jsonMatch = accumulatedContent.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
-            const jsonStr = jsonMatch ? jsonMatch[1] : accumulatedContent;
-            parsed = JSON.parse(jsonStr.trim());
-        }
-        catch {
-            // Try to extract partial JSON
-            const errorChunk = createErrorChunk(session, 'E3001', `Failed to parse JSON response`, false, { raw: accumulatedContent });
-            yield errorChunk;
-            onChunk?.(errorChunk);
-            return undefined;
-        }
-        // Process parsed response
-        let result;
-        if (shouldUseEnvelope && typeof parsed === 'object' && parsed !== null && 'ok' in parsed) {
-            const response = parseEnvelopeResponseLocal(parsed, accumulatedContent);
-            if (shouldUseV22 && response.ok && !('meta' in response && response.meta)) {
-                const upgraded = wrapV21ToV22Local(parsed, riskRule);
-                result = {
-                    ok: true,
-                    meta: upgraded.meta,
-                    data: upgraded.data,
-                    raw: accumulatedContent
-                };
-            }
-            else {
-                result = response;
-            }
-        }
-        else {
-            result = parseLegacyResponseLocal(parsed, accumulatedContent);
-            if (shouldUseV22 && result.ok) {
-                const data = (result.data ?? {});
-                result = {
-                    ok: true,
-                    meta: {
-                        confidence: data.confidence ?? 0.5,
-                        risk: aggregateRisk(data, riskRule),
-                        explain: (data.rationale ?? '').slice(0, 280) || 'No explanation provided'
-                    },
-                    data: result.data,
-                    raw: accumulatedContent
-                };
-            }
-        }
-        // Emit final chunk
-        if (result.ok && 'meta' in result) {
-            const finalChunk = createFinalChunk(session, result.meta, result.data, streamResult.usage ? {
-                input_tokens: streamResult.usage.promptTokens,
-                output_tokens: streamResult.usage.completionTokens,
-                total_tokens: streamResult.usage.totalTokens
-            } : undefined);
-            yield finalChunk;
-            onChunk?.(finalChunk);
-            onProgress?.(100, 'Complete');
-        }
-        return result;
-    }
-    catch (error) {
-        const errorChunk = createErrorChunk(session, ErrorCodesV25.STREAM_INTERRUPTED, error instanceof Error ? error.message : 'Stream interrupted', true);
-        yield errorChunk;
-        onChunk?.(errorChunk);
-        return undefined;
-    }
-}
-// Local versions of helper functions to avoid circular issues
-function parseEnvelopeResponseLocal(response, raw) {
-    if (isV22Envelope(response)) {
-        if (response.ok) {
-            return {
-                ok: true,
-                meta: response.meta,
-                data: response.data,
-                raw,
-            };
-        }
-        else {
-            return {
-                ok: false,
-                meta: response.meta,
-                error: response.error,
-                partial_data: response.partial_data,
-                raw,
-            };
-        }
-    }
-    if (response.ok) {
-        const data = (response.data ?? {});
-        return {
-            ok: true,
-            data: {
-                ...data,
-                confidence: typeof data.confidence === 'number' ? data.confidence : 0.5,
-                rationale: typeof data.rationale === 'string' ? data.rationale : '',
-                behavior_equivalence: data.behavior_equivalence,
-            },
-            raw,
-        };
-    }
-    else {
-        return {
-            ok: false,
-            error: response.error,
-            partial_data: response.partial_data,
-            raw,
-        };
-    }
-}
-function wrapV21ToV22Local(response, riskRule = 'max_changes_risk') {
-    if (isV22Envelope(response)) {
-        return response;
-    }
-    if (response.ok) {
-        const data = (response.data ?? {});
-        const confidence = data.confidence ?? 0.5;
-        const rationale = data.rationale ?? '';
-        return {
-            ok: true,
-            meta: {
-                confidence,
-                risk: aggregateRisk(data, riskRule),
-                explain: rationale.slice(0, 280) || 'No explanation provided'
-            },
-            data: data
-        };
-    }
-    else {
-        const errorMsg = response.error?.message ?? 'Unknown error';
-        return {
-            ok: false,
-            meta: {
-                confidence: 0,
-                risk: 'high',
-                explain: errorMsg.slice(0, 280)
-            },
-            error: response.error ?? { code: 'UNKNOWN', message: errorMsg },
-            partial_data: response.partial_data
-        };
-    }
-}
-function parseLegacyResponseLocal(output, raw) {
-    const outputObj = output;
-    const confidence = typeof outputObj.confidence === 'number' ? outputObj.confidence : 0.5;
-    const rationale = typeof outputObj.rationale === 'string' ? outputObj.rationale : '';
-    const behaviorEquivalence = typeof outputObj.behavior_equivalence === 'boolean'
-        ? outputObj.behavior_equivalence
-        : undefined;
-    if (outputObj.error && typeof outputObj.error === 'object') {
-        const errorObj = outputObj.error;
-        if (typeof errorObj.code === 'string') {
-            return {
-                ok: false,
-                error: {
-                    code: errorObj.code,
-                    message: typeof errorObj.message === 'string' ? errorObj.message : 'Unknown error',
-                },
-                raw,
-            };
-        }
-    }
-    return {
-        ok: true,
-        data: {
-            ...outputObj,
-            confidence,
-            rationale,
-            behavior_equivalence: behaviorEquivalence,
-        },
-        raw,
-    };
-}
-/**
- * Extract media inputs from module input data
- */
-function extractMediaInputs(input) {
-    const images = [];
-    const audio = [];
-    const video = [];
-    // Check for images array
-    if (Array.isArray(input.images)) {
-        for (const img of input.images) {
-            if (isValidMediaInput(img)) {
-                images.push(img);
-            }
-        }
-    }
-    // Check for audio array
-    if (Array.isArray(input.audio)) {
-        for (const aud of input.audio) {
-            if (isValidMediaInput(aud)) {
-                audio.push(aud);
-            }
-        }
-    }
-    // Check for video array
-    if (Array.isArray(input.video)) {
-        for (const vid of input.video) {
-            if (isValidMediaInput(vid)) {
-                video.push(vid);
-            }
-        }
-    }
-    return { images, audio, video };
-}
-/**
- * Validate media input structure
- */
-function isValidMediaInput(input) {
-    if (typeof input !== 'object' || input === null)
-        return false;
-    const obj = input;
-    if (obj.type === 'url' && typeof obj.url === 'string')
-        return true;
-    if (obj.type === 'base64' && typeof obj.data === 'string' && typeof obj.media_type === 'string')
-        return true;
-    if (obj.type === 'file' && typeof obj.path === 'string')
-        return true;
-    return false;
-}
-/**
- * Build prompt with media placeholders
- */
-function buildPromptWithMedia(module, input, media) {
-    let prompt = buildPrompt(module, input);
-    // Replace $MEDIA_INPUTS placeholder
-    if (prompt.includes('$MEDIA_INPUTS')) {
-        const mediaSummary = buildMediaSummary(media);
-        prompt = prompt.replace(/\$MEDIA_INPUTS/g, mediaSummary);
-    }
-    return prompt;
-}
-/**
- * Build summary of media inputs for prompt
- */
-function buildMediaSummary(media) {
-    const parts = [];
-    if (media.images.length > 0) {
-        parts.push(`[${media.images.length} image(s) attached]`);
-    }
-    if (media.audio.length > 0) {
-        parts.push(`[${media.audio.length} audio file(s) attached]`);
-    }
-    if (media.video.length > 0) {
-        parts.push(`[${media.video.length} video file(s) attached]`);
-    }
-    return parts.length > 0 ? parts.join('\n') : '[No media attached]';
-}
-/**
- * Build system message for module execution
- */
-function buildSystemMessage(module, shouldUseEnvelope, shouldUseV22) {
-    const systemParts = [
-        `You are executing the "${module.name}" Cognitive Module.`,
-        '',
-        `RESPONSIBILITY: ${module.responsibility}`,
-    ];
-    if (module.excludes.length > 0) {
-        systemParts.push('', 'YOU MUST NOT:');
-        module.excludes.forEach(e => systemParts.push(`- ${e}`));
-    }
-    if (module.constraints) {
-        systemParts.push('', 'CONSTRAINTS:');
-        if (module.constraints.no_network)
-            systemParts.push('- No network access');
-        if (module.constraints.no_side_effects)
-            systemParts.push('- No side effects');
-        if (module.constraints.no_file_write)
-            systemParts.push('- No file writes');
-        if (module.constraints.no_inventing_data)
-            systemParts.push('- Do not invent data');
-    }
-    if (module.output?.require_behavior_equivalence) {
-        systemParts.push('', 'BEHAVIOR EQUIVALENCE:');
-        systemParts.push('- You MUST set behavior_equivalence=true ONLY if the output is functionally identical');
-        systemParts.push('- If unsure, set behavior_equivalence=false and explain in rationale');
-        const maxConfidence = module.constraints?.behavior_equivalence_false_max_confidence ?? 0.7;
-        systemParts.push(`- If behavior_equivalence=false, confidence MUST be <= ${maxConfidence}`);
-    }
-    // Add multimodal instructions if module supports it
-    if (isModuleV25(module) && moduleSupportsMultimodal(module)) {
-        const inputModalities = getModuleInputModalities(module);
-        systemParts.push('', 'MULTIMODAL INPUT:');
-        systemParts.push(`- This module accepts: ${inputModalities.join(', ')}`);
-        systemParts.push('- Analyze any attached media carefully');
-        systemParts.push('- Reference specific elements from the media in your analysis');
-    }
-    // Add envelope format instructions
-    if (shouldUseEnvelope) {
-        if (shouldUseV22) {
-            systemParts.push('', 'RESPONSE FORMAT (Envelope v2.2):');
-            systemParts.push('- Wrap your response in the v2.2 envelope format with separate meta and data');
-            systemParts.push('- Success: { "ok": true, "meta": { "confidence": 0.9, "risk": "low", "explain": "short summary" }, "data": { ...payload... } }');
-            systemParts.push('- Error: { "ok": false, "meta": { "confidence": 0.0, "risk": "high", "explain": "error summary" }, "error": { "code": "ERROR_CODE", "message": "..." } }');
-            systemParts.push('- meta.explain must be ≤280 characters. data.rationale can be longer for detailed reasoning.');
-            systemParts.push('- meta.risk must be one of: "none", "low", "medium", "high"');
-        }
-        else {
-            systemParts.push('', 'RESPONSE FORMAT (Envelope):');
-            systemParts.push('- Wrap your response in the envelope format');
-            systemParts.push('- Success: { "ok": true, "data": { ...your output... } }');
-            systemParts.push('- Error: { "ok": false, "error": { "code": "ERROR_CODE", "message": "..." } }');
-            systemParts.push('- Include "confidence" (0-1) and "rationale" in data');
-        }
-        if (module.output?.require_behavior_equivalence) {
-            systemParts.push('- Include "behavior_equivalence" (boolean) in data');
-        }
-    }
-    else {
-        systemParts.push('', 'OUTPUT FORMAT:');
-        systemParts.push('- Respond with ONLY valid JSON');
-        systemParts.push('- Include "confidence" (0-1) and "rationale" fields');
-        if (module.output?.require_behavior_equivalence) {
-            systemParts.push('- Include "behavior_equivalence" (boolean) field');
-        }
-    }
-    return systemParts;
-}
-/**
- * Load media file as base64
- */
-export async function loadMediaAsBase64(path) {
-    try {
-        if (!existsSync(path)) {
-            return null;
-        }
-        const buffer = await readFile(path);
-        const data = buffer.toString('base64');
-        const media_type = getMediaTypeFromExtension(extname(path));
-        return { data, media_type };
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Get MIME type from file extension
- */
-function getMediaTypeFromExtension(ext) {
-    const mimeTypes = {
-        '.jpg': 'image/jpeg',
-        '.jpeg': 'image/jpeg',
-        '.png': 'image/png',
-        '.gif': 'image/gif',
-        '.webp': 'image/webp',
-        '.mp3': 'audio/mpeg',
-        '.wav': 'audio/wav',
-        '.ogg': 'audio/ogg',
-        '.webm': 'audio/webm',
-        '.mp4': 'video/mp4',
-        '.mov': 'video/quicktime',
-        '.pdf': 'application/pdf'
-    };
-    return mimeTypes[ext.toLowerCase()] ?? 'application/octet-stream';
-}
-/**
- * Validate media input against module constraints
- */
-export function validateMediaInput(media, module, maxSizeMb = 20) {
-    // Check if module supports multimodal
-    if (!moduleSupportsMultimodal(module)) {
-        return {
-            valid: false,
-            error: 'Module does not support multimodal input',
-            code: ErrorCodesV25.MULTIMODAL_NOT_SUPPORTED
-        };
-    }
-    // Validate media type
-    if (media.type === 'base64') {
-        const mediaType = media.media_type;
-        if (!isValidMediaType(mediaType)) {
-            return {
-                valid: false,
-                error: `Unsupported media type: ${mediaType}`,
-                code: ErrorCodesV25.UNSUPPORTED_MEDIA_TYPE
-            };
-        }
-    }
-    // Size validation would require fetching/checking actual data
-    // This is a placeholder for the check
-    return { valid: true };
-}
-/**
- * Check if media type is supported
- */
-function isValidMediaType(mediaType) {
-    const supported = [
-        'image/jpeg', 'image/png', 'image/webp', 'image/gif',
-        'audio/mpeg', 'audio/wav', 'audio/ogg', 'audio/webm',
-        'video/mp4', 'video/webm', 'video/quicktime',
-        'application/pdf'
-    ];
-    return supported.includes(mediaType);
-}
-/**
- * Get runtime capabilities
- */
-export function getRuntimeCapabilities() {
-    return { ...DEFAULT_RUNTIME_CAPABILITIES };
-}
-/**
- * Check if runtime supports a specific modality
- */
-export function runtimeSupportsModality(modality, direction = 'input') {
-    const caps = getRuntimeCapabilities();
-    return caps.multimodal[direction].includes(modality);
-}