cognitive-modules-cli 1.2.0 → 1.4.0

package/dist/server/http.js

@@ -0,0 +1,243 @@
+/**
+ * Cognitive Modules HTTP API Server
+ *
+ * Provides RESTful API interface for workflow platform integration.
+ *
+ * Start with:
+ *   cog serve --port 8000
+ *
+ * Environment variables:
+ *   COGNITIVE_API_KEY - API Key authentication (optional)
+ *   OPENAI_API_KEY, ANTHROPIC_API_KEY, etc. - LLM provider keys
+ */
+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 { getProvider } from '../providers/index.js';
+// =============================================================================
+// Helpers
+// =============================================================================
+function jsonResponse(res, status, data) {
+    res.writeHead(status, {
+        'Content-Type': 'application/json',
+        'Access-Control-Allow-Origin': '*',
+        'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+        'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+    });
+    res.end(JSON.stringify(data, null, 2));
+}
+function parseBody(req) {
+    return new Promise((resolve, reject) => {
+        let body = '';
+        req.on('data', (chunk) => (body += chunk));
+        req.on('end', () => resolve(body));
+        req.on('error', reject);
+    });
+}
+function verifyApiKey(req) {
+    const expectedKey = process.env.COGNITIVE_API_KEY;
+    if (!expectedKey)
+        return true; // No auth required
+    const authHeader = req.headers.authorization;
+    if (!authHeader)
+        return false;
+    const token = authHeader.startsWith('Bearer ') ? authHeader.slice(7) : authHeader;
+    return token === expectedKey;
+}
+// =============================================================================
+// Request Handlers
+// =============================================================================
+async function handleRoot(res) {
+    jsonResponse(res, 200, {
+        name: 'Cognitive Modules API',
+        version: '1.3.0',
+        docs: '/docs',
+        endpoints: {
+            run: 'POST /run',
+            modules: 'GET /modules',
+            module_info: 'GET /modules/{name}',
+            health: 'GET /health',
+        },
+    });
+}
+async function handleHealth(res) {
+    const providers = {
+        openai: Boolean(process.env.OPENAI_API_KEY),
+        anthropic: Boolean(process.env.ANTHROPIC_API_KEY),
+        minimax: Boolean(process.env.MINIMAX_API_KEY),
+        deepseek: Boolean(process.env.DEEPSEEK_API_KEY),
+        gemini: Boolean(process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY),
+        qwen: Boolean(process.env.QWEN_API_KEY || process.env.DASHSCOPE_API_KEY),
+    };
+    jsonResponse(res, 200, {
+        status: 'healthy',
+        version: '1.3.0',
+        providers,
+    });
+}
+async function handleModules(res, searchPaths) {
+    const modules = await listModules(searchPaths);
+    const moduleInfos = modules.map((m) => ({
+        name: m.name,
+        version: m.version,
+        description: m.responsibility,
+        format: m.format,
+        path: m.location,
+        responsibility: m.responsibility,
+        tier: m.tier,
+    }));
+    jsonResponse(res, 200, {
+        modules: moduleInfos,
+        count: moduleInfos.length,
+    });
+}
+async function handleModuleInfo(res, moduleName, searchPaths) {
+    const moduleData = await findModule(moduleName, searchPaths);
+    if (!moduleData) {
+        jsonResponse(res, 404, { error: `Module '${moduleName}' not found` });
+        return;
+    }
+    jsonResponse(res, 200, {
+        name: moduleData.name,
+        version: moduleData.version,
+        description: moduleData.responsibility,
+        format: moduleData.format,
+        path: moduleData.location,
+        responsibility: moduleData.responsibility,
+        tier: moduleData.tier,
+        inputSchema: moduleData.inputSchema,
+        outputSchema: moduleData.outputSchema,
+    });
+}
+async function handleRun(req, res, searchPaths) {
+    // Verify API key
+    if (!verifyApiKey(req)) {
+        jsonResponse(res, 401, {
+            error: 'Missing or invalid API Key. Use header: Authorization: Bearer <your-api-key>',
+        });
+        return;
+    }
+    // Parse request body
+    let request;
+    try {
+        const body = await parseBody(req);
+        request = JSON.parse(body);
+    }
+    catch {
+        jsonResponse(res, 400, { error: 'Invalid JSON body' });
+        return;
+    }
+    // Validate request
+    if (!request.module || !request.args) {
+        jsonResponse(res, 400, { error: 'Missing required fields: module, args' });
+        return;
+    }
+    // Find module
+    const moduleData = await findModule(request.module, searchPaths);
+    if (!moduleData) {
+        jsonResponse(res, 404, { error: `Module '${request.module}' not found` });
+        return;
+    }
+    try {
+        // Create provider
+        const provider = getProvider(request.provider, request.model);
+        // Run module
+        const result = await runModule(moduleData, provider, {
+            input: { query: request.args, code: request.args },
+            useV22: true,
+        });
+        const response = {
+            ok: result.ok,
+            module: request.module,
+            provider: request.provider || process.env.LLM_PROVIDER || 'openai',
+        };
+        if (result.ok) {
+            if ('meta' in result)
+                response.meta = result.meta;
+            if ('data' in result)
+                response.data = result.data;
+        }
+        else {
+            if ('error' in result)
+                response.error = result.error?.message;
+        }
+        jsonResponse(res, 200, response);
+    }
+    catch (error) {
+        jsonResponse(res, 500, {
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+            module: request.module,
+        });
+    }
+}
+export function createServer(options = {}) {
+    const { cwd = process.cwd() } = options;
+    const searchPaths = getDefaultSearchPaths(cwd);
+    const server = http.createServer(async (req, res) => {
+        const url = new URL(req.url || '/', `http://${req.headers.host}`);
+        const path = url.pathname;
+        const method = req.method?.toUpperCase();
+        // Handle CORS preflight
+        if (method === 'OPTIONS') {
+            res.writeHead(204, {
+                'Access-Control-Allow-Origin': '*',
+                'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+                'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+            });
+            res.end();
+            return;
+        }
+        try {
+            // Route requests
+            if (path === '/' && method === 'GET') {
+                await handleRoot(res);
+            }
+            else if (path === '/health' && method === 'GET') {
+                await handleHealth(res);
+            }
+            else if (path === '/modules' && method === 'GET') {
+                await handleModules(res, searchPaths);
+            }
+            else if (path.startsWith('/modules/') && method === 'GET') {
+                const moduleName = path.slice('/modules/'.length);
+                await handleModuleInfo(res, moduleName, searchPaths);
+            }
+            else if (path === '/run' && method === 'POST') {
+                await handleRun(req, res, searchPaths);
+            }
+            else {
+                jsonResponse(res, 404, { error: 'Not found' });
+            }
+        }
+        catch (error) {
+            console.error('Server error:', error);
+            jsonResponse(res, 500, {
+                error: error instanceof Error ? error.message : 'Internal server error',
+            });
+        }
+    });
+    return server;
+}
+export async function serve(options = {}) {
+    const { host = '0.0.0.0', port = 8000 } = options;
+    const server = createServer(options);
+    return new Promise((resolve, reject) => {
+        server.on('error', reject);
+        server.listen(port, host, () => {
+            console.log(`Cognitive Modules HTTP Server running at http://${host}:${port}`);
+            console.log('Endpoints:');
+            console.log('  GET  /          - API info');
+            console.log('  GET  /health    - Health check');
+            console.log('  GET  /modules   - List modules');
+            console.log('  GET  /modules/:name - Module info');
+            console.log('  POST /run       - Run module');
+            resolve();
+        });
+    });
+}
+// Allow running directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+    serve().catch(console.error);
+}

package/dist/server/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Server - Re-export all server functionality
+ */
+export { serve, createServer } from './http.js';
+export type { ServeOptions } from './http.js';

package/dist/server/index.js

@@ -0,0 +1,4 @@
+/**
+ * Server - Re-export all server functionality
+ */
+export { serve, createServer } from './http.js';

package/dist/types.d.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
  */
 export interface Provider {
     name: string;
@@ -282,3 +282,210 @@ export declare function extractMeta<T>(response: EnvelopeResponse<T>, riskRule?:
 export declare function aggregateRisk(data: Record<string, unknown>, riskRule?: RiskRule): RiskLevel;
 /** Check if result should be escalated to human review */
 export declare function shouldEscalate<T>(response: EnvelopeResponse<T>, confidenceThreshold?: number): boolean;
+/** 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;
+    meta: Partial<EnvelopeMeta>;
+}
+/** Delta chunk - incremental content */
+export interface DeltaChunk {
+    chunk: {
+        seq: number;
+        type: 'delta';
+        field?: string;
+        delta: string;
+    };
+}
+/** 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;
+    };
+}
+/** Error chunk during streaming */
+export interface ErrorChunk {
+    ok: false;
+    streaming: true;
+    session_id?: string;
+    error: {
+        code: string;
+        message: string;
+        recoverable?: boolean;
+    };
+    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>;
+}
+/** 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;
+}
+/** Union of media input types */
+export type MediaInput = UrlMediaInput | Base64MediaInput | FileMediaInput;
+/** 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 declare const SUPPORTED_IMAGE_TYPES: readonly ["image/jpeg", "image/png", "image/webp", "image/gif"];
+/** Supported audio MIME types */
+export declare const SUPPORTED_AUDIO_TYPES: readonly ["audio/mpeg", "audio/wav", "audio/ogg", "audio/webm"];
+/** Supported video MIME types */
+export declare const SUPPORTED_VIDEO_TYPES: readonly ["video/mp4", "video/webm", "video/quicktime"];
+/** v2.5 Error codes for streaming and multimodal */
+export declare const ErrorCodesV25: {
+    readonly UNSUPPORTED_MEDIA_TYPE: "E1010";
+    readonly MEDIA_TOO_LARGE: "E1011";
+    readonly MEDIA_FETCH_FAILED: "E1012";
+    readonly MEDIA_DECODE_FAILED: "E1013";
+    readonly STREAM_INTERRUPTED: "E2010";
+    readonly STREAM_TIMEOUT: "E2011";
+    readonly STREAMING_NOT_SUPPORTED: "E4010";
+    readonly MULTIMODAL_NOT_SUPPORTED: "E4011";
+};
+export type ErrorCodeV25 = typeof ErrorCodesV25[keyof typeof ErrorCodesV25];
+/** 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 declare const DEFAULT_RUNTIME_CAPABILITIES: RuntimeCapabilities;
+/** 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 declare function isProviderV25(provider: Provider): provider is ProviderV25;
+/** 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 declare function isModuleV25(module: CognitiveModule): module is CognitiveModuleV25;
+/** Check if module supports streaming */
+export declare function moduleSupportsStreaming(module: CognitiveModule): boolean;
+/** Check if module supports multimodal input */
+export declare function moduleSupportsMultimodal(module: CognitiveModule): boolean;
+/** Get supported input modalities for module */
+export declare function getModuleInputModalities(module: CognitiveModule): ModalityType[];
+/** Get supported output modalities for module */
+export declare function getModuleOutputModalities(module: CognitiveModule): ModalityType[];

package/dist/types.js

@@ -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
  */
 // =============================================================================
 // Utility Types
@@ -90,3 +90,84 @@ export function shouldEscalate(response, confidenceThreshold = 0.7) {
     }
     return false;
 }
+/** Supported image MIME types */
+export const SUPPORTED_IMAGE_TYPES = [
+    'image/jpeg',
+    'image/png',
+    'image/webp',
+    'image/gif'
+];
+/** Supported audio MIME types */
+export const SUPPORTED_AUDIO_TYPES = [
+    'audio/mpeg',
+    'audio/wav',
+    'audio/ogg',
+    'audio/webm'
+];
+/** Supported video MIME types */
+export const SUPPORTED_VIDEO_TYPES = [
+    'video/mp4',
+    'video/webm',
+    'video/quicktime'
+];
+// =============================================================================
+// 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',
+    // Streaming errors (E2xxx)
+    STREAM_INTERRUPTED: 'E2010',
+    STREAM_TIMEOUT: 'E2011',
+    // Capability errors (E4xxx)
+    STREAMING_NOT_SUPPORTED: 'E4010',
+    MULTIMODAL_NOT_SUPPORTED: 'E4011',
+};
+/** Default runtime capabilities */
+export const DEFAULT_RUNTIME_CAPABILITIES = {
+    streaming: true,
+    multimodal: {
+        input: ['text', 'image'],
+        output: ['text']
+    },
+    max_media_size_mb: 20,
+    supported_transports: ['sse', 'ndjson']
+};
+/** Type guard for v2.5 provider */
+export function isProviderV25(provider) {
+    return 'invokeStream' in provider || 'supportsStreaming' in provider;
+}
+/** Type guard for v2.5 module */
+export function isModuleV25(module) {
+    return 'response' in module || 'modalities' in module;
+}
+/** Check if module supports streaming */
+export function moduleSupportsStreaming(module) {
+    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) {
+    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) {
+    if (!isModuleV25(module))
+        return ['text'];
+    return module.modalities?.input ?? ['text'];
+}
+/** Get supported output modalities for module */
+export function getModuleOutputModalities(module) {
+    if (!isModuleV25(module))
+        return ['text'];
+    return module.modalities?.output ?? ['text'];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cognitive-modules-cli",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Cognitive Modules - Structured AI Task Execution with version management",
   "type": "module",
   "main": "dist/index.js",
@@ -39,6 +39,9 @@
   "dependencies": {
     "js-yaml": "^4.1.1"
   },
+  "optionalDependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",

package/src/cli.ts

@@ -19,7 +19,7 @@ import { getProvider, listProviders } from './providers/index.js';
 import { run, list, pipe, init, add, update, remove, versions } from './commands/index.js';
 import type { CommandContext } from './types.js';
 
-const VERSION = '1.0.1';
+const VERSION = '1.3.0';
 
 async function main() {
   const args = process.argv.slice(2);
@@ -52,6 +52,9 @@ async function main() {
       tag: { type: 'string', short: 't' },
       branch: { type: 'string', short: 'b' },
       limit: { type: 'string', short: 'l' },
+      // Server options
+      host: { type: 'string', short: 'H' },
+      port: { type: 'string', short: 'P' },
     },
     allowPositionals: true,
   });
@@ -288,6 +291,30 @@ async function main() {
         break;
       }
 
+      case 'serve': {
+        const { serve } = await import('./server/http.js');
+        const port = values.port ? parseInt(values.port as string, 10) : 8000;
+        const host = (values.host as string) || '0.0.0.0';
+        console.log('Starting Cognitive Modules HTTP Server...');
+        await serve({ host, port, cwd: ctx.cwd });
+        break;
+      }
+
+      case 'mcp': {
+        try {
+          const { serve: serveMcp } = await import('./mcp/server.js');
+          await serveMcp();
+        } catch (e) {
+          if (e instanceof Error && e.message.includes('Cannot find module')) {
+            console.error('MCP dependencies not installed.');
+            console.error('Install with: npm install @modelcontextprotocol/sdk');
+            process.exit(1);
+          }
+          throw e;
+        }
+        break;
+      }
+
       default:
         console.error(`Unknown command: ${command}`);
         console.error('Run "cog --help" for usage.');
@@ -319,6 +346,8 @@ COMMANDS:
   versions <url>    List available versions
   pipe              Pipe mode (stdin/stdout)
   init [name]       Initialize project or create module
+  serve             Start HTTP API server
+  mcp               Start MCP server (for Claude Code, Cursor)
   doctor            Check configuration
 
 OPTIONS:
@@ -333,6 +362,8 @@ OPTIONS:
   --pretty              Pretty-print JSON output
   -V, --verbose         Verbose output
   --no-validate         Skip schema validation
+  -H, --host <host>     Server host (default: 0.0.0.0)
+  -P, --port <port>     Server port (default: 8000)
   -v, --version         Show version
   -h, --help            Show this help
 
@@ -351,6 +382,10 @@ EXAMPLES:
   cog run code-reviewer --provider openai --model gpt-4o --args "..."
   cog list
 
+  # Servers
+  cog serve --port 8080
+  cog mcp
+
   # Other
   echo "review this code" | cog pipe --module code-reviewer
   cog init my-module

package/src/index.ts

@@ -38,7 +38,18 @@ export {
   listModules,
   getDefaultSearchPaths,
   runModule,
+  // Subagent
+  SubagentOrchestrator,
+  runWithSubagents,
+  parseCalls,
+  createContext,
 } from './modules/index.js';
 
+// Server
+export { serve as serveHttp, createServer } from './server/index.js';
+
+// MCP
+export { serve as serveMcp } from './mcp/index.js';
+
 // Commands
 export { run, list, pipe } from './commands/index.js';

package/src/mcp/index.ts

@@ -0,0 +1,5 @@
+/**
+ * MCP Server - Re-export all MCP functionality
+ */
+
+export { serve } from './server.js';