cognitive-modules-cli 1.2.0 → 1.4.0

package/dist/modules/subagent.js

@@ -0,0 +1,185 @@
+/**
+ * Subagent - Orchestrate module calls with isolated execution contexts.
+ *
+ * Supports:
+ * - @call:module-name - Call another module
+ * - @call:module-name(args) - Call with arguments
+ * - context: fork - Isolated execution (no shared state)
+ * - context: main - Shared execution (default)
+ */
+import { findModule, getDefaultSearchPaths } from './loader.js';
+import { runModule } from './runner.js';
+// =============================================================================
+// Context Management
+// =============================================================================
+/**
+ * Create a new root context
+ */
+export function createContext(maxDepth = 5) {
+    return {
+        parentId: null,
+        depth: 0,
+        maxDepth,
+        results: {},
+        isolated: false
+    };
+}
+/**
+ * Fork context (isolated - no inherited results)
+ */
+export function forkContext(ctx, moduleName) {
+    return {
+        parentId: moduleName,
+        depth: ctx.depth + 1,
+        maxDepth: ctx.maxDepth,
+        results: {},
+        isolated: true
+    };
+}
+/**
+ * Extend context (shared - inherits results)
+ */
+export function extendContext(ctx, moduleName) {
+    return {
+        parentId: moduleName,
+        depth: ctx.depth + 1,
+        maxDepth: ctx.maxDepth,
+        results: { ...ctx.results },
+        isolated: false
+    };
+}
+// =============================================================================
+// Call Parsing
+// =============================================================================
+// Pattern to match @call:module-name or @call:module-name(args)
+const CALL_PATTERN = /@call:([a-zA-Z0-9_-]+)(?:\(([^)]*)\))?/g;
+/**
+ * Parse @call directives from text
+ */
+export function parseCalls(text) {
+    const calls = [];
+    let match;
+    // Reset regex state
+    CALL_PATTERN.lastIndex = 0;
+    while ((match = CALL_PATTERN.exec(text)) !== null) {
+        calls.push({
+            module: match[1],
+            args: match[2] || '',
+            match: match[0]
+        });
+    }
+    return calls;
+}
+/**
+ * Replace @call directives with their results
+ */
+export function substituteCallResults(text, callResults) {
+    let result = text;
+    for (const [callStr, callResult] of Object.entries(callResults)) {
+        const resultStr = typeof callResult === 'object'
+            ? JSON.stringify(callResult, null, 2)
+            : String(callResult);
+        result = result.replace(callStr, `[Result from ${callStr}]:\n${resultStr}`);
+    }
+    return result;
+}
+// =============================================================================
+// Orchestrator
+// =============================================================================
+export class SubagentOrchestrator {
+    provider;
+    running = new Set();
+    cwd;
+    constructor(provider, cwd = process.cwd()) {
+        this.provider = provider;
+        this.cwd = cwd;
+    }
+    /**
+     * Run a module with subagent support.
+     * Recursively resolves @call directives before final execution.
+     */
+    async run(moduleName, options = {}, context) {
+        const { input = {}, validateInput = true, validateOutput = true, maxDepth = 5 } = options;
+        // Initialize context
+        const ctx = context ?? createContext(maxDepth);
+        // Check depth limit
+        if (ctx.depth > ctx.maxDepth) {
+            throw new Error(`Max subagent depth (${ctx.maxDepth}) exceeded. Check for circular calls.`);
+        }
+        // Prevent circular calls
+        if (this.running.has(moduleName)) {
+            throw new Error(`Circular call detected: ${moduleName}`);
+        }
+        this.running.add(moduleName);
+        try {
+            // Find and load module
+            const searchPaths = getDefaultSearchPaths(this.cwd);
+            const module = await findModule(moduleName, searchPaths);
+            if (!module) {
+                throw new Error(`Module not found: ${moduleName}`);
+            }
+            // Check if this module wants isolated execution
+            const moduleContextMode = module.context ?? 'main';
+            // Parse @call directives from prompt
+            const calls = parseCalls(module.prompt);
+            const callResults = {};
+            // Resolve each @call directive
+            for (const call of calls) {
+                const childModule = call.module;
+                const childArgs = call.args;
+                // Prepare child input
+                const childInput = childArgs
+                    ? { query: childArgs, code: childArgs }
+                    : { ...input };
+                // Determine child context
+                const childContext = moduleContextMode === 'fork'
+                    ? forkContext(ctx, moduleName)
+                    : extendContext(ctx, moduleName);
+                // Recursively run child module
+                const childResult = await this.run(childModule, {
+                    input: childInput,
+                    validateInput: false, // Skip validation for @call args
+                    validateOutput
+                }, childContext);
+                // Store result
+                if (childResult.ok && 'data' in childResult) {
+                    callResults[call.match] = childResult.data;
+                }
+                else if ('error' in childResult) {
+                    callResults[call.match] = { error: childResult.error };
+                }
+            }
+            // Substitute call results into prompt
+            let modifiedModule = module;
+            if (Object.keys(callResults).length > 0) {
+                const modifiedPrompt = substituteCallResults(module.prompt, callResults);
+                modifiedModule = {
+                    ...module,
+                    prompt: modifiedPrompt + '\n\n## Subagent Results Available\nThe @call results have been injected above. Use them in your response.\n'
+                };
+            }
+            // Run the module
+            const result = await runModule(modifiedModule, this.provider, {
+                input,
+                verbose: false,
+                useV22: true
+            });
+            // Store result in context
+            if (result.ok && 'data' in result) {
+                ctx.results[moduleName] = result.data;
+            }
+            return result;
+        }
+        finally {
+            this.running.delete(moduleName);
+        }
+    }
+}
+/**
+ * Convenience function to run a module with subagent support
+ */
+export async function runWithSubagents(moduleName, provider, options = {}) {
+    const { cwd = process.cwd(), ...runOptions } = options;
+    const orchestrator = new SubagentOrchestrator(provider, cwd);
+    return orchestrator.run(moduleName, runOptions);
+}

package/dist/providers/base.d.ts

@@ -1,7 +1,8 @@
 /**
  * Base Provider - Abstract class for all LLM providers
+ * v2.5: Added streaming and multimodal support
  */
-import type { Provider, InvokeParams, InvokeResult } from '../types.js';
+import type { Provider, InvokeParams, InvokeResult, ProviderV25, InvokeParamsV25, StreamingInvokeResult, ModalityType } from '../types.js';
 export declare abstract class BaseProvider implements Provider {
     abstract name: string;
     abstract invoke(params: InvokeParams): Promise<InvokeResult>;
@@ -9,3 +10,46 @@ export declare abstract class BaseProvider implements Provider {
     protected buildJsonPrompt(schema: object): string;
     protected parseJsonResponse(content: string): unknown;
 }
+/**
+ * Base Provider with v2.5 streaming and multimodal support
+ */
+export declare abstract class BaseProviderV25 extends BaseProvider implements ProviderV25 {
+    /**
+     * Check if this provider supports streaming
+     * Override in subclass to enable streaming
+     */
+    supportsStreaming(): boolean;
+    /**
+     * Check if this provider supports multimodal input/output
+     * Override in subclass to enable multimodal
+     */
+    supportsMultimodal(): {
+        input: ModalityType[];
+        output: ModalityType[];
+    };
+    /**
+     * Invoke with streaming response
+     * Override in subclass to implement streaming
+     */
+    invokeStream(params: InvokeParamsV25): Promise<StreamingInvokeResult>;
+    /**
+     * Format media inputs for the specific provider API
+     * Override in subclass for provider-specific formatting
+     */
+    protected formatMediaForProvider(images?: Array<{
+        type: string;
+        url?: string;
+        data?: string;
+        media_type?: string;
+    }>, _audio?: Array<{
+        type: string;
+        url?: string;
+        data?: string;
+        media_type?: string;
+    }>, _video?: Array<{
+        type: string;
+        url?: string;
+        data?: string;
+        media_type?: string;
+    }>): unknown[];
+}

package/dist/providers/base.js

@@ -1,5 +1,6 @@
 /**
  * Base Provider - Abstract class for all LLM providers
+ * v2.5: Added streaming and multimodal support
  */
 export class BaseProvider {
     buildJsonPrompt(schema) {
@@ -17,3 +18,69 @@ export class BaseProvider {
         }
     }
 }
+/**
+ * Base Provider with v2.5 streaming and multimodal support
+ */
+export class BaseProviderV25 extends BaseProvider {
+    /**
+     * Check if this provider supports streaming
+     * Override in subclass to enable streaming
+     */
+    supportsStreaming() {
+        return false;
+    }
+    /**
+     * Check if this provider supports multimodal input/output
+     * Override in subclass to enable multimodal
+     */
+    supportsMultimodal() {
+        return {
+            input: ['text'],
+            output: ['text']
+        };
+    }
+    /**
+     * Invoke with streaming response
+     * Override in subclass to implement streaming
+     */
+    async invokeStream(params) {
+        // Default: fallback to non-streaming with async generator wrapper
+        const result = await this.invoke(params);
+        async function* generateChunks() {
+            yield result.content;
+        }
+        return {
+            stream: generateChunks(),
+            usage: result.usage
+        };
+    }
+    /**
+     * Format media inputs for the specific provider API
+     * Override in subclass for provider-specific formatting
+     */
+    formatMediaForProvider(images, _audio, _video) {
+        // Default implementation for image-only providers (like OpenAI Vision)
+        if (!images || images.length === 0) {
+            return [];
+        }
+        return images.map(img => {
+            if (img.type === 'url' && img.url) {
+                return {
+                    type: 'image_url',
+                    image_url: {
+                        url: img.url
+                    }
+                };
+            }
+            else if (img.type === 'base64' && img.data && img.media_type) {
+                return {
+                    type: 'image_url',
+                    image_url: {
+                        url: `data:${img.media_type};base64,${img.data}`
+                    }
+                };
+            }
+            return null;
+        }).filter(Boolean);
+    }
+}

package/dist/providers/openai.d.ts

@@ -1,14 +1,38 @@
 /**
  * OpenAI Provider - OpenAI API (and compatible APIs)
+ * v2.5: Added streaming and multimodal (vision) support
  */
-import { BaseProvider } from './base.js';
-import type { InvokeParams, InvokeResult } from '../types.js';
-export declare class OpenAIProvider extends BaseProvider {
+import { BaseProviderV25 } from './base.js';
+import type { InvokeParams, InvokeResult, InvokeParamsV25, StreamingInvokeResult, ModalityType } from '../types.js';
+export declare class OpenAIProvider extends BaseProviderV25 {
     name: string;
     private apiKey;
     private model;
     private baseUrl;
     constructor(apiKey?: string, model?: string, baseUrl?: string);
     isConfigured(): boolean;
+    /**
+     * Check if streaming is supported (always true for OpenAI)
+     */
+    supportsStreaming(): boolean;
+    /**
+     * Check multimodal support (vision models)
+     */
+    supportsMultimodal(): {
+        input: ModalityType[];
+        output: ModalityType[];
+    };
     invoke(params: InvokeParams): Promise<InvokeResult>;
+    /**
+     * Invoke with streaming response
+     */
+    invokeStream(params: InvokeParamsV25): Promise<StreamingInvokeResult>;
+    /**
+     * Build messages with multimodal content (images)
+     */
+    private buildMessagesWithMedia;
+    /**
+     * Convert MediaInput to URL for OpenAI API
+     */
+    private mediaInputToUrl;
 }

package/dist/providers/openai.js

@@ -1,13 +1,14 @@
 /**
  * OpenAI Provider - OpenAI API (and compatible APIs)
+ * v2.5: Added streaming and multimodal (vision) support
  */
-import { BaseProvider } from './base.js';
-export class OpenAIProvider extends BaseProvider {
+import { BaseProviderV25 } from './base.js';
+export class OpenAIProvider extends BaseProviderV25 {
     name = 'openai';
     apiKey;
     model;
     baseUrl;
-    constructor(apiKey, model = 'gpt-5.2', baseUrl = 'https://api.openai.com/v1') {
+    constructor(apiKey, model = 'gpt-4o', baseUrl = 'https://api.openai.com/v1') {
         super();
         this.apiKey = apiKey || process.env.OPENAI_API_KEY || '';
         this.model = model;
@@ -16,6 +17,24 @@ export class OpenAIProvider extends BaseProvider {
     isConfigured() {
         return !!this.apiKey;
     }
+    /**
+     * Check if streaming is supported (always true for OpenAI)
+     */
+    supportsStreaming() {
+        return true;
+    }
+    /**
+     * Check multimodal support (vision models)
+     */
+    supportsMultimodal() {
+        // Vision models support image input
+        const visionModels = ['gpt-4o', 'gpt-4-vision', 'gpt-4-turbo', 'gpt-4o-mini'];
+        const supportsVision = visionModels.some(m => this.model.includes(m));
+        return {
+            input: supportsVision ? ['text', 'image'] : ['text'],
+            output: ['text'] // DALL-E would be separate
+        };
+    }
     async invoke(params) {
         if (!this.isConfigured()) {
             throw new Error('OpenAI API key not configured. Set OPENAI_API_KEY environment variable.');
@@ -64,4 +83,157 @@ export class OpenAIProvider extends BaseProvider {
             } : undefined,
         };
     }
+    /**
+     * Invoke with streaming response
+     */
+    async invokeStream(params) {
+        if (!this.isConfigured()) {
+            throw new Error('OpenAI API key not configured. Set OPENAI_API_KEY environment variable.');
+        }
+        const url = `${this.baseUrl}/chat/completions`;
+        // Build messages with multimodal content if present
+        const messages = this.buildMessagesWithMedia(params);
+        const body = {
+            model: this.model,
+            messages,
+            temperature: params.temperature ?? 0.7,
+            max_tokens: params.maxTokens ?? 4096,
+            stream: true,
+        };
+        // Add JSON mode if schema provided
+        if (params.jsonSchema) {
+            body.response_format = { type: 'json_object' };
+        }
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${this.apiKey}`,
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`OpenAI API error: ${response.status} - ${error}`);
+        }
+        const bodyReader = response.body?.getReader();
+        if (!bodyReader) {
+            throw new Error('No response body');
+        }
+        const decoder = new TextDecoder();
+        let usage;
+        // Capture reader reference for closure
+        const reader = bodyReader;
+        // Create async generator for streaming
+        async function* streamGenerator() {
+            let buffer = '';
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                // Parse SSE events
+                const lines = buffer.split('\n');
+                buffer = lines.pop() || '';
+                for (const line of lines) {
+                    if (line.startsWith('data: ')) {
+                        const data = line.slice(6);
+                        if (data === '[DONE]') {
+                            return;
+                        }
+                        try {
+                            const parsed = JSON.parse(data);
+                            const content = parsed.choices?.[0]?.delta?.content;
+                            if (content) {
+                                yield content;
+                            }
+                            // Capture usage if available
+                            if (parsed.usage) {
+                                usage = {
+                                    promptTokens: parsed.usage.prompt_tokens || 0,
+                                    completionTokens: parsed.usage.completion_tokens || 0,
+                                    totalTokens: parsed.usage.total_tokens || 0,
+                                };
+                            }
+                        }
+                        catch {
+                            // Skip malformed JSON
+                        }
+                    }
+                }
+            }
+        }
+        return {
+            stream: streamGenerator(),
+            usage
+        };
+    }
+    /**
+     * Build messages with multimodal content (images)
+     */
+    buildMessagesWithMedia(params) {
+        const hasImages = params.images && params.images.length > 0;
+        if (!hasImages) {
+            return params.messages;
+        }
+        // Find the last user message and add images to it
+        const messages = [];
+        const lastUserIdx = params.messages.findLastIndex(m => m.role === 'user');
+        for (let i = 0; i < params.messages.length; i++) {
+            const msg = params.messages[i];
+            if (i === lastUserIdx && hasImages) {
+                // Convert to multimodal content
+                const content = [
+                    { type: 'text', text: msg.content }
+                ];
+                // Add images
+                for (const img of params.images) {
+                    const imageUrl = this.mediaInputToUrl(img);
+                    if (imageUrl) {
+                        content.push({
+                            type: 'image_url',
+                            image_url: { url: imageUrl, detail: 'auto' }
+                        });
+                    }
+                }
+                messages.push({ role: msg.role, content });
+            }
+            else {
+                messages.push({ role: msg.role, content: msg.content });
+            }
+        }
+        // Add JSON schema instruction if needed
+        if (params.jsonSchema && lastUserIdx >= 0) {
+            const lastMsg = messages[lastUserIdx];
+            if (typeof lastMsg.content === 'string') {
+                lastMsg.content = lastMsg.content + this.buildJsonPrompt(params.jsonSchema);
+            }
+            else {
+                // Content is array, append to text part
+                const textPart = lastMsg.content.find(p => p.type === 'text');
+                if (textPart && textPart.type === 'text') {
+                    textPart.text = textPart.text + this.buildJsonPrompt(params.jsonSchema);
+                }
+            }
+        }
+        return messages;
+    }
+    /**
+     * Convert MediaInput to URL for OpenAI API
+     */
+    mediaInputToUrl(media) {
+        switch (media.type) {
+            case 'url':
+                return media.url;
+            case 'base64':
+                return `data:${media.media_type};base64,${media.data}`;
+            case 'file':
+                // File paths would need to be loaded first
+                // This should be handled by the runner before calling the provider
+                console.warn('[cognitive] File media input not pre-loaded, skipping');
+                return null;
+            default:
+                return null;
+        }
+    }
 }

package/dist/server/http.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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';
+export interface ServeOptions {
+    host?: string;
+    port?: number;
+    cwd?: string;
+}
+export declare function createServer(options?: ServeOptions): http.Server;
+export declare function serve(options?: ServeOptions): Promise<void>;