cognitive-modules-cli 2.2.1 → 2.2.7

package/dist/modules/subagent.js

@@ -75,11 +75,15 @@ export function parseCalls(text) {
  */
 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}`);
+    for (const entry of callResults) {
+        const resultStr = typeof entry.result === 'object'
+            ? JSON.stringify(entry.result, null, 2)
+            : String(entry.result);
+        const replacement = `[Result from ${entry.module}]:\n${resultStr}`;
+        const idx = result.indexOf(entry.match);
+        if (idx !== -1) {
+            result = result.slice(0, idx) + replacement + result.slice(idx + entry.match.length);
+        }
     }
     return result;
 }
@@ -99,7 +103,7 @@ export class SubagentOrchestrator {
      * Recursively resolves @call directives before final execution.
      */
     async run(moduleName, options = {}, context) {
-        const { input = {}, validateInput = true, validateOutput = true, maxDepth = 5 } = options;
+        const { input = {}, args, validateInput = true, validateOutput = true, maxDepth = 5 } = options;
         // Initialize context
         const ctx = context ?? createContext(maxDepth);
         // Check depth limit
@@ -122,15 +126,14 @@ export class SubagentOrchestrator {
             const moduleContextMode = module.context ?? 'main';
             // Parse @call directives from prompt
             const calls = parseCalls(module.prompt);
-            const callResults = {};
+            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 };
+                const hasChildArgs = childArgs.length > 0;
+                const childInput = hasChildArgs ? {} : { ...input };
                 // Determine child context
                 const childContext = moduleContextMode === 'fork'
                     ? forkContext(ctx, moduleName)
@@ -138,20 +141,21 @@ export class SubagentOrchestrator {
                 // Recursively run child module
                 const childResult = await this.run(childModule, {
                     input: childInput,
+                    args: hasChildArgs ? childArgs : undefined,
                     validateInput: false, // Skip validation for @call args
                     validateOutput
                 }, childContext);
                 // Store result
                 if (childResult.ok && 'data' in childResult) {
-                    callResults[call.match] = childResult.data;
+                    callResults.push({ match: call.match, module: call.module, result: childResult.data });
                 }
                 else if ('error' in childResult) {
-                    callResults[call.match] = { error: childResult.error };
+                    callResults.push({ match: call.match, module: call.module, result: { error: childResult.error } });
                 }
             }
             // Substitute call results into prompt
             let modifiedModule = module;
-            if (Object.keys(callResults).length > 0) {
+            if (callResults.length > 0) {
                 const modifiedPrompt = substituteCallResults(module.prompt, callResults);
                 modifiedModule = {
                     ...module,
@@ -161,6 +165,7 @@ export class SubagentOrchestrator {
             // Run the module
             const result = await runModule(modifiedModule, this.provider, {
                 input,
+                args,
                 validateInput,
                 validateOutput,
                 verbose: false,

package/dist/modules/validator.js

@@ -45,7 +45,7 @@ export async function validateModule(modulePath, v22 = false) {
     else if (hasModuleMd) {
         // v1 format
         if (v22) {
-            errors.push("Module is v1 format. Use 'cogn migrate' to upgrade to v2.2");
+            errors.push("Module is v1 format. Use 'cog migrate' to upgrade to v2.2");
             return { valid: false, errors, warnings };
         }
         return validateV1Format(modulePath);
@@ -53,7 +53,7 @@ export async function validateModule(modulePath, v22 = false) {
     else if (hasOldModuleMd) {
         // v0 format
         if (v22) {
-            errors.push("Module is v0 format. Use 'cogn migrate' to upgrade to v2.2");
+            errors.push("Module is v0 format. Use 'cog migrate' to upgrade to v2.2");
             return { valid: false, errors, warnings };
         }
         return validateV0Format(modulePath);
@@ -73,7 +73,8 @@ async function validateV22Format(modulePath) {
     let manifest;
     try {
         const content = await fs.readFile(moduleYamlPath, 'utf-8');
-        manifest = yaml.load(content);
+        const loaded = yaml.load(content);
+        manifest = loaded && typeof loaded === 'object' ? loaded : {};
     }
     catch (e) {
         errors.push(`Invalid YAML in module.yaml: ${e.message}`);
@@ -244,7 +245,8 @@ async function validateV2Format(modulePath) {
     let manifest;
     try {
         const content = await fs.readFile(moduleYamlPath, 'utf-8');
-        manifest = yaml.load(content);
+        const loaded = yaml.load(content);
+        manifest = loaded && typeof loaded === 'object' ? loaded : {};
     }
     catch (e) {
         errors.push(`Invalid YAML in module.yaml: ${e.message}`);
@@ -297,7 +299,7 @@ async function validateV2Format(modulePath) {
     }
     // Check for v2.2 features and suggest upgrade
     if (!manifest.tier) {
-        warnings.push("Consider adding 'tier' for v2.2 (use 'cogn validate --v22' for full check)");
+        warnings.push("Consider adding 'tier' for v2.2 (use 'cog validate --v22' for full check)");
     }
     return { valid: errors.length === 0, errors, warnings };
 }
@@ -573,6 +575,9 @@ export function validateV22Envelope(response) {
     if (!('meta' in response)) {
         errors.push("Missing 'meta' field (required for v2.2)");
     }
+    else if (typeof response.meta !== 'object' || response.meta === null || Array.isArray(response.meta)) {
+        errors.push("meta must be an object");
+    }
     else {
         const meta = response.meta;
         if (!('confidence' in meta)) {
@@ -596,8 +601,11 @@ export function validateV22Envelope(response) {
         if (!('explain' in meta)) {
             errors.push("meta missing 'explain'");
         }
+        else if (typeof meta.explain !== 'string') {
+            errors.push("meta.explain must be a string");
+        }
         else {
-            const explain = meta.explain ?? '';
+            const explain = meta.explain;
             if (explain.length > 280) {
                 errors.push(`meta.explain exceeds 280 chars (${explain.length} chars)`);
             }

package/dist/providers/anthropic.d.ts

@@ -1,5 +1,7 @@
 /**
  * Anthropic Provider - Claude API
+ *
+ * Supports both streaming and non-streaming invocation.
  */
 import { BaseProvider } from './base.js';
 import type { InvokeParams, InvokeResult } from '../types.js';
@@ -10,5 +12,18 @@ export declare class AnthropicProvider extends BaseProvider {
     private baseUrl;
     constructor(apiKey?: string, model?: string);
     isConfigured(): boolean;
+    /**
+     * Anthropic supports streaming.
+     */
+    supportsStreaming(): boolean;
+    /**
+     * Build request body for Anthropic API
+     */
+    private buildRequestBody;
     invoke(params: InvokeParams): Promise<InvokeResult>;
+    /**
+     * Stream-based invoke using Anthropic's streaming API.
+     * Yields content chunks as they arrive from the API.
+     */
+    invokeStream(params: InvokeParams): AsyncGenerator<string, InvokeResult, unknown>;
 }

package/dist/providers/anthropic.js

@@ -1,5 +1,7 @@
 /**
  * Anthropic Provider - Claude API
+ *
+ * Supports both streaming and non-streaming invocation.
  */
 import { BaseProvider } from './base.js';
 export class AnthropicProvider extends BaseProvider {
@@ -15,11 +17,16 @@ export class AnthropicProvider extends BaseProvider {
     isConfigured() {
         return !!this.apiKey;
     }
-    async invoke(params) {
-        if (!this.isConfigured()) {
-            throw new Error('Anthropic API key not configured. Set ANTHROPIC_API_KEY environment variable.');
-        }
-        const url = `${this.baseUrl}/messages`;
+    /**
+     * Anthropic supports streaming.
+     */
+    supportsStreaming() {
+        return true;
+    }
+    /**
+     * Build request body for Anthropic API
+     */
+    buildRequestBody(params, stream) {
         // Extract system message
         const systemMessage = params.messages.find(m => m.role === 'system');
         const otherMessages = params.messages.filter(m => m.role !== 'system');
@@ -39,10 +46,19 @@ export class AnthropicProvider extends BaseProvider {
             model: this.model,
             messages: messages.map(m => ({ role: m.role, content: m.content })),
             max_tokens: params.maxTokens ?? 4096,
+            stream,
         };
         if (systemMessage) {
             body.system = systemMessage.content;
         }
+        return { body, systemContent: systemMessage?.content };
+    }
+    async invoke(params) {
+        if (!this.isConfigured()) {
+            throw new Error('Anthropic API key not configured. Set ANTHROPIC_API_KEY environment variable.');
+        }
+        const url = `${this.baseUrl}/messages`;
+        const { body } = this.buildRequestBody(params, false);
         const response = await fetch(url, {
             method: 'POST',
             headers: {
@@ -67,4 +83,130 @@ export class AnthropicProvider extends BaseProvider {
             } : undefined,
         };
     }
+    /**
+     * Stream-based invoke using Anthropic's streaming API.
+     * Yields content chunks as they arrive from the API.
+     */
+    async *invokeStream(params) {
+        if (!this.isConfigured()) {
+            throw new Error('Anthropic API key not configured. Set ANTHROPIC_API_KEY environment variable.');
+        }
+        const url = `${this.baseUrl}/messages`;
+        const { body } = this.buildRequestBody(params, true);
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-api-key': this.apiKey,
+                'anthropic-version': '2023-06-01',
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`Anthropic API error: ${response.status} - ${error}`);
+        }
+        if (!response.body) {
+            throw new Error('Anthropic API returned no body for streaming request');
+        }
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder('utf-8');
+        const collectedChunks = [];
+        let usage;
+        let buffer = '';
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                // Process complete lines from the buffer
+                const lines = buffer.split('\n');
+                buffer = lines.pop() || ''; // Keep incomplete line in buffer
+                for (const line of lines) {
+                    const trimmed = line.trim();
+                    if (!trimmed || trimmed.startsWith(':'))
+                        continue; // Skip empty lines and comments
+                    if (trimmed.startsWith('data: ')) {
+                        try {
+                            const data = JSON.parse(trimmed.slice(6));
+                            // Extract content chunk (content_block_delta event)
+                            if (data.type === 'content_block_delta' && data.delta?.type === 'text_delta') {
+                                const text = data.delta.text || '';
+                                if (text) {
+                                    collectedChunks.push(text);
+                                    yield text;
+                                }
+                            }
+                            // Extract usage info (message_delta or message_stop event)
+                            if (data.type === 'message_delta' && data.usage) {
+                                usage = {
+                                    promptTokens: data.usage.input_tokens || 0,
+                                    completionTokens: data.usage.output_tokens || 0,
+                                    totalTokens: (data.usage.input_tokens || 0) + (data.usage.output_tokens || 0),
+                                };
+                            }
+                            // Also check message_start for input tokens
+                            if (data.type === 'message_start' && data.message?.usage) {
+                                const inputTokens = data.message.usage.input_tokens || 0;
+                                usage = {
+                                    promptTokens: inputTokens,
+                                    completionTokens: usage?.completionTokens || 0,
+                                    totalTokens: inputTokens + (usage?.completionTokens || 0),
+                                };
+                            }
+                        }
+                        catch {
+                            // Skip invalid JSON chunks
+                        }
+                    }
+                }
+            }
+            // Flush decoder and process trailing buffered data even without trailing newline.
+            buffer += decoder.decode();
+            for (const line of buffer.split('\n')) {
+                const trimmed = line.trim();
+                if (!trimmed || trimmed.startsWith(':'))
+                    continue;
+                if (trimmed.startsWith('data: ')) {
+                    try {
+                        const data = JSON.parse(trimmed.slice(6));
+                        if (data.type === 'content_block_delta' && data.delta?.type === 'text_delta') {
+                            const text = data.delta.text || '';
+                            if (text) {
+                                collectedChunks.push(text);
+                                yield text;
+                            }
+                        }
+                        if (data.type === 'message_delta' && data.usage) {
+                            usage = {
+                                promptTokens: data.usage.input_tokens || 0,
+                                completionTokens: data.usage.output_tokens || 0,
+                                totalTokens: (data.usage.input_tokens || 0) + (data.usage.output_tokens || 0),
+                            };
+                        }
+                        if (data.type === 'message_start' && data.message?.usage) {
+                            const inputTokens = data.message.usage.input_tokens || 0;
+                            usage = {
+                                promptTokens: inputTokens,
+                                completionTokens: usage?.completionTokens || 0,
+                                totalTokens: inputTokens + (usage?.completionTokens || 0),
+                            };
+                        }
+                    }
+                    catch {
+                        // Skip invalid JSON chunks
+                    }
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+        const fullContent = collectedChunks.join('');
+        return {
+            content: fullContent,
+            usage,
+        };
+    }
 }

package/dist/providers/base.d.ts

@@ -6,6 +6,17 @@ export declare abstract class BaseProvider implements Provider {
     abstract name: string;
     abstract invoke(params: InvokeParams): Promise<InvokeResult>;
     abstract isConfigured(): boolean;
+    /**
+     * Check if this provider supports streaming.
+     * Override in subclasses that implement streaming.
+     */
+    supportsStreaming(): boolean;
+    /**
+     * Stream-based invoke (optional).
+     * Default implementation falls back to non-streaming invoke.
+     * Override in subclasses that support streaming.
+     */
+    invokeStream(params: InvokeParams): AsyncGenerator<string, InvokeResult, unknown>;
     protected buildJsonPrompt(schema: object): string;
     protected parseJsonResponse(content: string): unknown;
 }

package/dist/providers/base.js

@@ -2,6 +2,24 @@
  * Base Provider - Abstract class for all LLM providers
  */
 export class BaseProvider {
+    /**
+     * Check if this provider supports streaming.
+     * Override in subclasses that implement streaming.
+     */
+    supportsStreaming() {
+        return false;
+    }
+    /**
+     * Stream-based invoke (optional).
+     * Default implementation falls back to non-streaming invoke.
+     * Override in subclasses that support streaming.
+     */
+    async *invokeStream(params) {
+        // Default fallback: use non-streaming invoke and yield the entire result at once
+        const result = await this.invoke(params);
+        yield result.content;
+        return result;
+    }
     buildJsonPrompt(schema) {
         return `\n\nYou MUST respond with valid JSON matching this schema:\n${JSON.stringify(schema, null, 2)}\n\nRespond with ONLY the JSON, no markdown code blocks.`;
     }

package/dist/providers/gemini.d.ts

@@ -1,5 +1,7 @@
 /**
  * Gemini Provider - Google Gemini API
+ *
+ * Supports both streaming and non-streaming invocation.
  */
 import { BaseProvider } from './base.js';
 import type { InvokeParams, InvokeResult } from '../types.js';
@@ -10,10 +12,23 @@ export declare class GeminiProvider extends BaseProvider {
     private baseUrl;
     constructor(apiKey?: string, model?: string);
     isConfigured(): boolean;
+    /**
+     * Gemini supports streaming.
+     */
+    supportsStreaming(): boolean;
     /**
      * Clean JSON Schema for Gemini API compatibility
      * Removes unsupported fields like additionalProperties
      */
     private cleanSchemaForGemini;
+    /**
+     * Build request body for Gemini API
+     */
+    private buildRequestBody;
     invoke(params: InvokeParams): Promise<InvokeResult>;
+    /**
+     * Stream-based invoke using Gemini's streaming API.
+     * Yields content chunks as they arrive from the API.
+     */
+    invokeStream(params: InvokeParams): AsyncGenerator<string, InvokeResult, unknown>;
 }

package/dist/providers/gemini.js

@@ -1,5 +1,7 @@
 /**
  * Gemini Provider - Google Gemini API
+ *
+ * Supports both streaming and non-streaming invocation.
  */
 import { BaseProvider } from './base.js';
 export class GeminiProvider extends BaseProvider {
@@ -15,6 +17,12 @@ export class GeminiProvider extends BaseProvider {
     isConfigured() {
         return !!this.apiKey;
     }
+    /**
+     * Gemini supports streaming.
+     */
+    supportsStreaming() {
+        return true;
+    }
     /**
      * Clean JSON Schema for Gemini API compatibility
      * Removes unsupported fields like additionalProperties
@@ -38,11 +46,10 @@ export class GeminiProvider extends BaseProvider {
         };
         return clean(schema);
     }
-    async invoke(params) {
-        if (!this.isConfigured()) {
-            throw new Error('Gemini API key not configured. Set GEMINI_API_KEY environment variable.');
-        }
-        const url = `${this.baseUrl}/models/${this.model}:generateContent?key=${this.apiKey}`;
+    /**
+     * Build request body for Gemini API
+     */
+    buildRequestBody(params) {
         // Convert messages to Gemini format
         const contents = params.messages
             .filter(m => m.role !== 'system')
@@ -71,6 +78,14 @@ export class GeminiProvider extends BaseProvider {
                 responseSchema: cleanedSchema,
             };
         }
+        return body;
+    }
+    async invoke(params) {
+        if (!this.isConfigured()) {
+            throw new Error('Gemini API key not configured. Set GEMINI_API_KEY environment variable.');
+        }
+        const url = `${this.baseUrl}/models/${this.model}:generateContent?key=${this.apiKey}`;
+        const body = this.buildRequestBody(params);
         const response = await fetch(url, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
@@ -91,4 +106,106 @@ export class GeminiProvider extends BaseProvider {
             } : undefined,
         };
     }
+    /**
+     * Stream-based invoke using Gemini's streaming API.
+     * Yields content chunks as they arrive from the API.
+     */
+    async *invokeStream(params) {
+        if (!this.isConfigured()) {
+            throw new Error('Gemini API key not configured. Set GEMINI_API_KEY environment variable.');
+        }
+        // Use streamGenerateContent endpoint
+        const url = `${this.baseUrl}/models/${this.model}:streamGenerateContent?key=${this.apiKey}&alt=sse`;
+        const body = this.buildRequestBody(params);
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`Gemini API error: ${response.status} - ${error}`);
+        }
+        if (!response.body) {
+            throw new Error('Gemini API returned no body for streaming request');
+        }
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder('utf-8');
+        const collectedChunks = [];
+        let usage;
+        let buffer = '';
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                // Process complete lines from the buffer
+                const lines = buffer.split('\n');
+                buffer = lines.pop() || ''; // Keep incomplete line in buffer
+                for (const line of lines) {
+                    const trimmed = line.trim();
+                    if (!trimmed)
+                        continue;
+                    if (trimmed.startsWith('data: ')) {
+                        try {
+                            const data = JSON.parse(trimmed.slice(6));
+                            // Extract content chunk
+                            const text = data.candidates?.[0]?.content?.parts?.[0]?.text;
+                            if (text) {
+                                collectedChunks.push(text);
+                                yield text;
+                            }
+                            // Extract usage info (usually in the last chunk)
+                            if (data.usageMetadata) {
+                                usage = {
+                                    promptTokens: data.usageMetadata.promptTokenCount || 0,
+                                    completionTokens: data.usageMetadata.candidatesTokenCount || 0,
+                                    totalTokens: data.usageMetadata.totalTokenCount || 0,
+                                };
+                            }
+                        }
+                        catch {
+                            // Skip invalid JSON chunks
+                        }
+                    }
+                }
+            }
+            // Flush decoder and process trailing buffered data even without trailing newline.
+            buffer += decoder.decode();
+            for (const line of buffer.split('\n')) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                if (trimmed.startsWith('data: ')) {
+                    try {
+                        const data = JSON.parse(trimmed.slice(6));
+                        const text = data.candidates?.[0]?.content?.parts?.[0]?.text;
+                        if (text) {
+                            collectedChunks.push(text);
+                            yield text;
+                        }
+                        if (data.usageMetadata) {
+                            usage = {
+                                promptTokens: data.usageMetadata.promptTokenCount || 0,
+                                completionTokens: data.usageMetadata.candidatesTokenCount || 0,
+                                totalTokens: data.usageMetadata.totalTokenCount || 0,
+                            };
+                        }
+                    }
+                    catch {
+                        // Skip invalid JSON chunks
+                    }
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+        const fullContent = collectedChunks.join('');
+        return {
+            content: fullContent,
+            usage,
+        };
+    }
 }

package/dist/providers/ollama.d.ts

@@ -1,5 +1,7 @@
 /**
  * Ollama Provider - Local LLM via Ollama
+ *
+ * Supports both streaming and non-streaming invocation.
  */
 import { BaseProvider } from './base.js';
 import type { InvokeParams, InvokeResult } from '../types.js';
@@ -9,5 +11,18 @@ export declare class OllamaProvider extends BaseProvider {
     private baseUrl;
     constructor(model?: string, baseUrl?: string);
     isConfigured(): boolean;
+    /**
+     * Ollama supports streaming.
+     */
+    supportsStreaming(): boolean;
+    /**
+     * Build request body for Ollama API
+     */
+    private buildRequestBody;
     invoke(params: InvokeParams): Promise<InvokeResult>;
+    /**
+     * Stream-based invoke using Ollama's streaming API.
+     * Yields content chunks as they arrive from the API.
+     */
+    invokeStream(params: InvokeParams): AsyncGenerator<string, InvokeResult, unknown>;
 }