cognitive-modules-cli 1.2.0 → 1.4.0

package/src/modules/subagent.ts

@@ -0,0 +1,275 @@
+/**
+ * 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 type { 
+  CognitiveModule, 
+  ModuleResult, 
+  ModuleInput,
+  Provider,
+  EnvelopeResponseV22
+} from '../types.js';
+import { loadModule, findModule, getDefaultSearchPaths } from './loader.js';
+import { runModule } from './runner.js';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface SubagentContext {
+  parentId: string | null;
+  depth: number;
+  maxDepth: number;
+  results: Record<string, unknown>;
+  isolated: boolean;
+}
+
+export interface CallDirective {
+  module: string;
+  args: string;
+  match: string;
+}
+
+export interface SubagentRunOptions {
+  input?: ModuleInput;
+  validateInput?: boolean;
+  validateOutput?: boolean;
+  maxDepth?: number;
+}
+
+// =============================================================================
+// Context Management
+// =============================================================================
+
+/**
+ * Create a new root context
+ */
+export function createContext(maxDepth: number = 5): SubagentContext {
+  return {
+    parentId: null,
+    depth: 0,
+    maxDepth,
+    results: {},
+    isolated: false
+  };
+}
+
+/**
+ * Fork context (isolated - no inherited results)
+ */
+export function forkContext(ctx: SubagentContext, moduleName: string): SubagentContext {
+  return {
+    parentId: moduleName,
+    depth: ctx.depth + 1,
+    maxDepth: ctx.maxDepth,
+    results: {},
+    isolated: true
+  };
+}
+
+/**
+ * Extend context (shared - inherits results)
+ */
+export function extendContext(ctx: SubagentContext, moduleName: string): SubagentContext {
+  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: string): CallDirective[] {
+  const calls: CallDirective[] = [];
+  let match: RegExpExecArray | null;
+  
+  // 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: string, 
+  callResults: Record<string, unknown>
+): string {
+  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 {
+  private provider: Provider;
+  private running: Set<string> = new Set();
+  private cwd: string;
+  
+  constructor(provider: Provider, cwd: string = process.cwd()) {
+    this.provider = provider;
+    this.cwd = cwd;
+  }
+  
+  /**
+   * Run a module with subagent support.
+   * Recursively resolves @call directives before final execution.
+   */
+  async run(
+    moduleName: string,
+    options: SubagentRunOptions = {},
+    context?: SubagentContext
+  ): Promise<ModuleResult> {
+    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: Record<string, unknown> = {};
+      
+      // Resolve each @call directive
+      for (const call of calls) {
+        const childModule = call.module;
+        const childArgs = call.args;
+        
+        // Prepare child input
+        const childInput: ModuleInput = 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: string,
+  provider: Provider,
+  options: SubagentRunOptions & { cwd?: string } = {}
+): Promise<ModuleResult> {
+  const { cwd = process.cwd(), ...runOptions } = options;
+  const orchestrator = new SubagentOrchestrator(provider, cwd);
+  return orchestrator.run(moduleName, runOptions);
+}

package/src/providers/base.ts

@@ -1,8 +1,17 @@
 /**
  * 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 abstract class BaseProvider implements Provider {
   abstract name: string;
@@ -27,3 +36,79 @@ export abstract class BaseProvider implements Provider {
     }
   }
 }
+
+/**
+ * Base Provider with v2.5 streaming and multimodal support
+ */
+export abstract class BaseProviderV25 extends BaseProvider implements ProviderV25 {
+  /**
+   * Check if this provider supports streaming
+   * Override in subclass to enable streaming
+   */
+  supportsStreaming(): boolean {
+    return false;
+  }
+  
+  /**
+   * Check if this provider supports multimodal input/output
+   * Override in subclass to enable multimodal
+   */
+  supportsMultimodal(): { input: ModalityType[]; output: ModalityType[] } {
+    return {
+      input: ['text'],
+      output: ['text']
+    };
+  }
+  
+  /**
+   * Invoke with streaming response
+   * Override in subclass to implement streaming
+   */
+  async invokeStream(params: InvokeParamsV25): Promise<StreamingInvokeResult> {
+    // Default: fallback to non-streaming with async generator wrapper
+    const result = await this.invoke(params);
+    
+    async function* generateChunks(): AsyncIterable<string> {
+      yield result.content;
+    }
+    
+    return {
+      stream: generateChunks(),
+      usage: result.usage
+    };
+  }
+  
+  /**
+   * 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[] {
+    // 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/src/providers/openai.ts

@@ -1,17 +1,35 @@
 /**
  * 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';
+import { BaseProviderV25 } from './base.js';
+import type { 
+  InvokeParams, 
+  InvokeResult, 
+  InvokeParamsV25, 
+  StreamingInvokeResult,
+  ModalityType,
+  MediaInput
+} from '../types.js';
 
-export class OpenAIProvider extends BaseProvider {
+// Type for OpenAI message content
+type OpenAIContentPart = 
+  | { type: 'text'; text: string }
+  | { type: 'image_url'; image_url: { url: string; detail?: 'low' | 'high' | 'auto' } };
+
+type OpenAIMessage = {
+  role: 'system' | 'user' | 'assistant';
+  content: string | OpenAIContentPart[];
+};
+
+export class OpenAIProvider extends BaseProviderV25 {
   name = 'openai';
   private apiKey: string;
   private model: string;
   private baseUrl: string;
 
-  constructor(apiKey?: string, model = 'gpt-5.2', baseUrl = 'https://api.openai.com/v1') {
+  constructor(apiKey?: string, model = 'gpt-4o', baseUrl = 'https://api.openai.com/v1') {
     super();
     this.apiKey = apiKey || process.env.OPENAI_API_KEY || '';
     this.model = model;
@@ -22,6 +40,27 @@ export class OpenAIProvider extends BaseProvider {
     return !!this.apiKey;
   }
 
+  /**
+   * Check if streaming is supported (always true for OpenAI)
+   */
+  supportsStreaming(): boolean {
+    return true;
+  }
+
+  /**
+   * Check multimodal support (vision models)
+   */
+  supportsMultimodal(): { input: ModalityType[]; output: ModalityType[] } {
+    // 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: InvokeParams): Promise<InvokeResult> {
     if (!this.isConfigured()) {
       throw new Error('OpenAI API key not configured. Set OPENAI_API_KEY environment variable.');
@@ -81,4 +120,187 @@ export class OpenAIProvider extends BaseProvider {
       } : undefined,
     };
   }
+
+  /**
+   * Invoke with streaming response
+   */
+  async invokeStream(params: InvokeParamsV25): Promise<StreamingInvokeResult> {
+    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: Record<string, unknown> = {
+      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: { promptTokens: number; completionTokens: number; totalTokens: number } | undefined;
+
+    // Capture reader reference for closure
+    const reader = bodyReader;
+
+    // Create async generator for streaming
+    async function* streamGenerator(): AsyncIterable<string> {
+      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) as {
+                choices?: Array<{ delta?: { content?: string } }>;
+                usage?: { prompt_tokens?: number; completion_tokens?: number; total_tokens?: number };
+              };
+              
+              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)
+   */
+  private buildMessagesWithMedia(params: InvokeParamsV25): OpenAIMessage[] {
+    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: OpenAIMessage[] = [];
+    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: OpenAIContentPart[] = [
+          { 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
+   */
+  private mediaInputToUrl(media: MediaInput): string | null {
+    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;
+    }
+  }
 }