cognitive-modules-cli 2.2.5 → 2.2.7

package/dist/server/http.js

@@ -13,12 +13,13 @@
 import http from 'node:http';
 import { URL } from 'node:url';
 import { findModule, listModules, getDefaultSearchPaths } from '../modules/loader.js';
-import { runModule } from '../modules/runner.js';
+import { runModule, runModuleStream } from '../modules/runner.js';
 import { getProvider } from '../providers/index.js';
 import { VERSION } from '../version.js';
-import { ErrorCodes, makeErrorEnvelope, makeHttpError } from '../errors/index.js';
+import { ErrorCodes, attachContext, makeErrorEnvelope, makeHttpError, httpStatusForErrorCode } from '../errors/index.js';
+import { encodeSseFrame } from './sse.js';
 // Supported protocol versions
-const SUPPORTED_VERSIONS = ['2.2', '2.1'];
+const SUPPORTED_VERSIONS = ['2.2'];
 const DEFAULT_VERSION = '2.2';
 /**
  * Get requested protocol version from request
@@ -185,7 +186,9 @@ async function handleRun(req, res, searchPaths, url) {
     };
     // Verify API key
     if (!verifyApiKey(req)) {
-        jsonResponse(res, 401, buildHttpError(ErrorCodes.PERMISSION_DENIED, 'Missing or invalid API Key', { suggestion: 'Use header: Authorization: Bearer <your-api-key>' }), protocolVersion);
+        const [status, body] = buildHttpError(ErrorCodes.PERMISSION_DENIED, 'Missing or invalid API Key', { suggestion: 'Use header: Authorization: Bearer <your-api-key>' });
+        // Auth failures are better represented as 401 even if the CEP code is permission-related.
+        jsonResponse(res, 401, body, protocolVersion);
         return;
     }
     // Parse request body
@@ -213,6 +216,13 @@ async function handleRun(req, res, searchPaths, url) {
     const reqBody = request;
     // Determine protocol version (body > header > query > default)
     protocolVersion = getRequestedVersion(req, url, reqBody.version);
+    // If the client explicitly requested an unsupported version, return a structured error.
+    const requested = reqBody.version ?? req.headers['x-cognitive-version'] ?? url.searchParams.get('version') ?? undefined;
+    if (requested && !SUPPORTED_VERSIONS.includes(requested)) {
+        const [status, body] = buildHttpError(ErrorCodes.UNSUPPORTED_VALUE, `Unsupported protocol version: ${requested}`, { suggestion: `Use version=${DEFAULT_VERSION}` });
+        jsonResponse(res, status, body, protocolVersion);
+        return;
+    }
     // Validate request
     if (!reqBody.module || !reqBody.args) {
         const [status, body] = buildHttpError(ErrorCodes.MISSING_REQUIRED_FIELD, 'Missing required fields: module, args', {
@@ -241,45 +251,18 @@ async function handleRun(req, res, searchPaths, url) {
             args: reqBody.args,
             useV22: true,
         });
-        // Build response envelope with requested protocol version
-        if (result.ok && 'data' in result) {
-            const v22Result = result;
-            const response = {
-                ok: true,
-                version: protocolVersion,
-                meta: v22Result.meta ?? {
-                    confidence: 0.5,
-                    risk: 'medium',
-                    explain: 'No meta provided',
-                },
-                data: v22Result.data,
-                module: reqBody.module,
-                provider: providerName,
-            };
-            jsonResponse(res, 200, response, protocolVersion);
-        }
-        else {
-            // Error response - must include meta and full error object
-            const errorResult = result;
-            const response = {
-                ok: false,
-                version: protocolVersion,
-                meta: errorResult.meta ?? {
-                    confidence: 0.0,
-                    risk: 'high',
-                    explain: errorResult.error?.message ?? 'An error occurred',
-                },
-                error: errorResult.error ?? {
-                    code: ErrorCodes.INTERNAL_ERROR,
-                    message: 'Unknown error',
-                    recoverable: false,
-                },
-                partial_data: errorResult.partial_data,
-                module: reqBody.module,
-                provider: providerName,
-            };
-            jsonResponse(res, 200, response, protocolVersion);
+        // Attach transport context but do not rebuild the envelope.
+        const contextual = attachContext(result, {
+            module: reqBody.module,
+            provider: providerName,
+        });
+        if (contextual.ok) {
+            jsonResponse(res, 200, contextual, protocolVersion);
+            return;
         }
+        const errorCode = (contextual.error?.code ?? ErrorCodes.INTERNAL_ERROR);
+        const status = httpStatusForErrorCode(errorCode);
+        jsonResponse(res, status, contextual, protocolVersion);
     }
     catch (error) {
         // Infrastructure error - still return envelope
@@ -292,6 +275,144 @@ async function handleRun(req, res, searchPaths, url) {
         jsonResponse(res, status, response, protocolVersion);
     }
 }
+async function handleRunStream(req, res, searchPaths, url) {
+    let protocolVersion = DEFAULT_VERSION;
+    let sseStarted = false;
+    const beginSse = (version) => {
+        if (sseStarted)
+            return;
+        sseStarted = true;
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream; charset=utf-8',
+            'Cache-Control': 'no-cache, no-transform',
+            'Connection': 'keep-alive',
+            'X-Accel-Buffering': 'no',
+            'Access-Control-Allow-Origin': '*',
+            'Access-Control-Allow-Methods': 'POST, OPTIONS',
+            'Access-Control-Allow-Headers': 'Content-Type, Authorization, X-Cognitive-Version',
+            'Access-Control-Expose-Headers': 'X-Cognitive-Version',
+            'X-Cognitive-Version': version,
+        });
+    };
+    const writeEvent = (ev, id) => {
+        const type = typeof ev.type === 'string' ? ev.type : 'message';
+        res.write(encodeSseFrame(ev, { event: type, id }));
+    };
+    // Helper: send an error as CEP events (start + error + end).
+    const sendErrorStream = (envelope) => {
+        beginSse(protocolVersion);
+        let id = 1;
+        writeEvent({ type: 'start', version: protocolVersion, timestamp_ms: 0, module: envelope.module ?? 'unknown' }, id++);
+        const err = envelope.error ?? { code: ErrorCodes.INTERNAL_ERROR, message: 'Unknown error' };
+        writeEvent({ type: 'error', version: protocolVersion, timestamp_ms: 0, module: envelope.module ?? 'unknown', provider: envelope.provider, error: err }, id++);
+        writeEvent({ type: 'end', version: protocolVersion, timestamp_ms: 0, module: envelope.module ?? 'unknown', provider: envelope.provider, result: envelope }, id++);
+        res.end();
+    };
+    // Verify API key
+    if (!verifyApiKey(req)) {
+        // Auth failures should still be structured; SSE payload carries the error.
+        const envelope = attachContext(makeErrorEnvelope({
+            code: ErrorCodes.PERMISSION_DENIED,
+            message: 'Missing or invalid API Key',
+            suggestion: 'Use header: Authorization: Bearer <your-api-key>',
+            version: protocolVersion,
+        }), { module: 'unknown', provider: 'unknown' });
+        sendErrorStream(envelope);
+        return;
+    }
+    // Parse request body
+    let request;
+    try {
+        const body = await parseBody(req);
+        request = JSON.parse(body);
+    }
+    catch (e) {
+        const err = e;
+        const code = err?.code === 'PAYLOAD_TOO_LARGE' ? ErrorCodes.INPUT_TOO_LARGE : ErrorCodes.PARSE_ERROR;
+        const message = err?.code === 'PAYLOAD_TOO_LARGE' ? 'Payload too large' : 'Invalid JSON body';
+        const envelope = attachContext(makeErrorEnvelope({
+            code,
+            message,
+            suggestion: code === ErrorCodes.INPUT_TOO_LARGE ? 'Reduce input size to under 1MB' : 'Ensure request body is valid JSON',
+            version: protocolVersion,
+        }), { module: 'unknown', provider: 'unknown' });
+        sendErrorStream(envelope);
+        return;
+    }
+    if (!request || typeof request !== 'object') {
+        const envelope = attachContext(makeErrorEnvelope({
+            code: ErrorCodes.INVALID_INPUT,
+            message: 'Invalid request body',
+            suggestion: 'Ensure request body is a JSON object',
+            version: protocolVersion,
+        }), { module: 'unknown', provider: 'unknown' });
+        sendErrorStream(envelope);
+        return;
+    }
+    const reqBody = request;
+    protocolVersion = getRequestedVersion(req, url, reqBody.version);
+    // If the client explicitly requested an unsupported version, return a structured error.
+    const requested = reqBody.version ?? req.headers['x-cognitive-version'] ?? url.searchParams.get('version') ?? undefined;
+    if (requested && !SUPPORTED_VERSIONS.includes(requested)) {
+        const envelope = attachContext(makeErrorEnvelope({
+            code: ErrorCodes.UNSUPPORTED_VALUE,
+            message: `Unsupported protocol version: ${requested}`,
+            suggestion: `Use version=${DEFAULT_VERSION}`,
+            version: protocolVersion,
+        }), { module: reqBody?.module ?? 'unknown', provider: reqBody?.provider ?? 'unknown' });
+        sendErrorStream(envelope);
+        return;
+    }
+    // Validate request
+    if (!reqBody.module || !reqBody.args) {
+        const envelope = attachContext(makeErrorEnvelope({
+            code: ErrorCodes.MISSING_REQUIRED_FIELD,
+            message: 'Missing required fields: module, args',
+            suggestion: 'Provide both "module" and "args" fields in request body',
+            version: protocolVersion,
+        }), { module: reqBody?.module ?? 'unknown', provider: reqBody?.provider ?? 'unknown' });
+        sendErrorStream(envelope);
+        return;
+    }
+    // Find module
+    const moduleData = await findModule(reqBody.module, searchPaths);
+    if (!moduleData) {
+        const envelope = attachContext(makeErrorEnvelope({
+            code: ErrorCodes.MODULE_NOT_FOUND,
+            message: `Module '${reqBody.module}' not found`,
+            suggestion: 'Use GET /modules to list available modules',
+            version: protocolVersion,
+        }), { module: reqBody.module, provider: reqBody.provider ?? 'unknown' });
+        sendErrorStream(envelope);
+        return;
+    }
+    // Create provider
+    const provider = getProvider(reqBody.provider, reqBody.model);
+    const providerName = provider.name;
+    // Stream events
+    beginSse(protocolVersion);
+    let id = 1;
+    let closed = false;
+    const onClose = () => { closed = true; };
+    req.on('close', onClose);
+    res.on('close', onClose);
+    for await (const ev of runModuleStream(moduleData, provider, {
+        args: reqBody.args,
+        useV22: true,
+    })) {
+        if (closed)
+            break;
+        const contextualEv = {
+            ...ev,
+            module: reqBody.module,
+            provider: providerName,
+        };
+        writeEvent(contextualEv, id++);
+    }
+    if (!closed) {
+        res.end();
+    }
+}
 export function createServer(options = {}) {
     const { cwd = process.cwd() } = options;
     const searchPaths = getDefaultSearchPaths(cwd);
@@ -328,6 +449,9 @@ export function createServer(options = {}) {
             else if (path === '/run' && method === 'POST') {
                 await handleRun(req, res, searchPaths, url);
             }
+            else if (path === '/run/stream' && method === 'POST') {
+                await handleRunStream(req, res, searchPaths, url);
+            }
             else {
                 const envelope = makeErrorEnvelope({
                     code: ErrorCodes.ENDPOINT_NOT_FOUND,
@@ -364,6 +488,7 @@ export async function serve(options = {}) {
             console.log('  GET  /modules   - List modules');
             console.log('  GET  /modules/:name - Module info');
             console.log('  POST /run       - Run module');
+            console.log('  POST /run/stream - Run module (SSE stream)');
             resolve();
         });
     });

package/dist/server/index.d.ts

@@ -3,3 +3,5 @@
  */
 export { serve, createServer } from './http.js';
 export type { ServeOptions } from './http.js';
+export { encodeSseFrame } from './sse.js';
+export type { SseFrameOptions } from './sse.js';

package/dist/server/index.js

@@ -2,3 +2,4 @@
  * Server - Re-export all server functionality
  */
 export { serve, createServer } from './http.js';
+export { encodeSseFrame } from './sse.js';

package/dist/server/sse.d.ts

@@ -0,0 +1,13 @@
+export interface SseFrameOptions {
+    event?: string;
+    id?: string | number;
+    retryMs?: number;
+}
+/**
+ * Encode a payload into an SSE frame.
+ *
+ * Notes:
+ * - SSE requires each data line to be prefixed with `data:`.
+ * - `event:` maps cleanly to CEP `type` to keep transport mapping deterministic.
+ */
+export declare function encodeSseFrame(data: unknown, options?: SseFrameOptions): string;

package/dist/server/sse.js

@@ -0,0 +1,22 @@
+/**
+ * Encode a payload into an SSE frame.
+ *
+ * Notes:
+ * - SSE requires each data line to be prefixed with `data:`.
+ * - `event:` maps cleanly to CEP `type` to keep transport mapping deterministic.
+ */
+export function encodeSseFrame(data, options = {}) {
+    const lines = [];
+    if (options.retryMs !== undefined)
+        lines.push(`retry: ${options.retryMs}`);
+    if (options.id !== undefined)
+        lines.push(`id: ${options.id}`);
+    if (options.event)
+        lines.push(`event: ${options.event}`);
+    const json = JSON.stringify(data);
+    for (const line of json.split('\n')) {
+        lines.push(`data: ${line}`);
+    }
+    lines.push(''); // End of event
+    return lines.join('\n') + '\n';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cognitive-modules-cli",
-  "version": "2.2.5",
+  "version": "2.2.7",
   "description": "Cognitive Modules - Structured AI Task Execution with version management",
   "type": "module",
   "main": "dist/index.js",