cognitive-runtime 0.3.0 → 0.5.0

package/README.md

@@ -65,6 +65,45 @@ echo "review this code" | cog pipe --module code-reviewer
 cog doctor
 ```
 
+## Module Formats
+
+### v2 (Recommended)
+
+```
+my-module/
+├── module.yaml      # Machine-readable manifest
+├── prompt.md        # Human-readable prompt
+├── schema.json      # IO contract
+└── tests/
+    ├── case1.input.json
+    └── case1.expected.json
+```
+
+**module.yaml**:
+```yaml
+name: my-module
+version: 2.0.0
+responsibility: What this module does
+constraints:
+  no_network: true
+  no_side_effects: true
+output:
+  mode: json_strict
+  require_confidence: true
+  require_rationale: true
+  require_behavior_equivalence: true
+tools:
+  allowed: []
+```
+
+### v1 (Legacy, still supported)
+
+```
+my-module/
+├── MODULE.md        # Frontmatter + prompt combined
+└── schema.json
+```
+
 ## Providers
 
 | Provider   | Environment Variable   | Default Model        |

package/dist/cli.js

@@ -10,7 +10,7 @@
 import { parseArgs } from 'node:util';
 import { getProvider, listProviders } from './providers/index.js';
 import { run, list, pipe, init } from './commands/index.js';
-const VERSION = '0.3.0';
+const VERSION = '0.5.0';
 async function main() {
     const args = process.argv.slice(2);
     const command = args[0];

package/dist/commands/pipe.js

@@ -36,19 +36,21 @@ export async function pipe(ctx, options) {
         const result = await runModule(module, ctx.provider, {
             args: inputData ? undefined : input,
             input: inputData,
-            validateInput: !options.noValidate,
-            validateOutput: !options.noValidate,
         });
-        // Output JSON to stdout
-        console.log(JSON.stringify(result.output));
+        // Output envelope format to stdout
+        console.log(JSON.stringify(result));
         return {
-            success: true,
+            success: result.ok,
             data: result,
         };
     }
     catch (e) {
         const error = e instanceof Error ? e.message : String(e);
-        console.error(JSON.stringify({ error }));
+        // Output error in envelope format
+        console.log(JSON.stringify({
+            ok: false,
+            error: { code: 'RUNTIME_ERROR', message: error }
+        }));
         return {
             success: false,
             error,

package/dist/commands/run.js

@@ -30,14 +30,31 @@ export async function run(moduleName, ctx, options = {}) {
         const result = await runModule(module, ctx.provider, {
             args: options.args,
             input: inputData,
-            validateInput: !options.noValidate,
-            validateOutput: !options.noValidate,
             verbose: options.verbose || ctx.verbose,
         });
-        return {
-            success: true,
-            data: options.pretty ? result : result.output,
-        };
+        // Return envelope format or extracted data
+        if (options.pretty) {
+            return {
+                success: result.ok,
+                data: result,
+            };
+        }
+        else {
+            // For non-pretty mode, return data (success) or error (failure)
+            if (result.ok) {
+                return {
+                    success: true,
+                    data: result.data,
+                };
+            }
+            else {
+                return {
+                    success: false,
+                    error: `${result.error?.code}: ${result.error?.message}`,
+                    data: result.partial_data,
+                };
+            }
+        }
     }
     catch (e) {
         return {

package/dist/index.d.ts

@@ -3,7 +3,7 @@
  *
  * Exports all public APIs for programmatic use.
  */
-export type { Provider, InvokeParams, InvokeResult, Message, CognitiveModule, ModuleResult, CommandContext, CommandResult, } from './types.js';
+export type { Provider, InvokeParams, InvokeResult, Message, CognitiveModule, ModuleResult, ModuleInput, ModuleConstraints, ToolsPolicy, OutputContract, FailureContract, CommandContext, CommandResult, } from './types.js';
 export { getProvider, listProviders, GeminiProvider, OpenAIProvider, AnthropicProvider, BaseProvider, } from './providers/index.js';
 export { loadModule, findModule, listModules, getDefaultSearchPaths, runModule, } from './modules/index.js';
 export { run, list, pipe } from './commands/index.js';

package/dist/modules/loader.d.ts

@@ -1,7 +1,11 @@
 /**
  * Module Loader - Load and parse Cognitive Modules
+ * Supports both v1 (MODULE.md) and v2 (module.yaml + prompt.md) formats
  */
 import type { CognitiveModule } from '../types.js';
+/**
+ * Load a Cognitive Module (auto-detects format)
+ */
 export declare function loadModule(modulePath: string): Promise<CognitiveModule>;
 export declare function findModule(name: string, searchPaths: string[]): Promise<CognitiveModule | null>;
 export declare function listModules(searchPaths: string[]): Promise<CognitiveModule[]>;

package/dist/modules/loader.js

@@ -1,11 +1,80 @@
 /**
  * Module Loader - Load and parse Cognitive Modules
+ * Supports both v1 (MODULE.md) and v2 (module.yaml + prompt.md) formats
  */
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import yaml from 'js-yaml';
 const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n([\s\S]*))?/;
-export async function loadModule(modulePath) {
+/**
+ * Detect module format version
+ */
+async function detectFormat(modulePath) {
+    const v2Manifest = path.join(modulePath, 'module.yaml');
+    try {
+        await fs.access(v2Manifest);
+        return 'v2';
+    }
+    catch {
+        return 'v1';
+    }
+}
+/**
+ * Load v2 format module (module.yaml + prompt.md)
+ */
+async function loadModuleV2(modulePath) {
+    const manifestFile = path.join(modulePath, 'module.yaml');
+    const promptFile = path.join(modulePath, 'prompt.md');
+    const schemaFile = path.join(modulePath, 'schema.json');
+    // Read module.yaml
+    const manifestContent = await fs.readFile(manifestFile, 'utf-8');
+    const manifest = yaml.load(manifestContent);
+    // Read prompt.md
+    let prompt = '';
+    try {
+        prompt = await fs.readFile(promptFile, 'utf-8');
+    }
+    catch {
+        // prompt.md is optional, manifest may include inline prompt
+    }
+    // Read schema.json
+    let inputSchema;
+    let outputSchema;
+    let errorSchema;
+    try {
+        const schemaContent = await fs.readFile(schemaFile, 'utf-8');
+        const schema = JSON.parse(schemaContent);
+        inputSchema = schema.input;
+        outputSchema = schema.output;
+        errorSchema = schema.error;
+    }
+    catch {
+        // Schema file is optional but recommended
+    }
+    return {
+        name: manifest.name || path.basename(modulePath),
+        version: manifest.version || '1.0.0',
+        responsibility: manifest.responsibility || '',
+        excludes: manifest.excludes || [],
+        constraints: manifest.constraints,
+        policies: manifest.policies,
+        tools: manifest.tools,
+        output: manifest.output,
+        failure: manifest.failure,
+        runtimeRequirements: manifest.runtime_requirements,
+        context: manifest.context,
+        prompt,
+        inputSchema,
+        outputSchema,
+        errorSchema,
+        location: modulePath,
+        format: 'v2',
+    };
+}
+/**
+ * Load v1 format module (MODULE.md with frontmatter)
+ */
+async function loadModuleV1(modulePath) {
     const moduleFile = path.join(modulePath, 'MODULE.md');
     const schemaFile = path.join(modulePath, 'schema.json');
     // Read MODULE.md
@@ -29,29 +98,66 @@ export async function loadModule(modulePath) {
     catch {
         // Schema file is optional
     }
+    // Extract constraints from v1 format
+    const constraints = {};
+    const v1Constraints = frontmatter.constraints;
+    if (v1Constraints) {
+        constraints.no_network = v1Constraints.no_network;
+        constraints.no_side_effects = v1Constraints.no_side_effects;
+        constraints.no_inventing_data = v1Constraints.no_inventing_data;
+    }
     return {
         name: frontmatter.name || path.basename(modulePath),
         version: frontmatter.version || '1.0.0',
         responsibility: frontmatter.responsibility || '',
         excludes: frontmatter.excludes || [],
+        constraints: Object.keys(constraints).length > 0 ? constraints : undefined,
         context: frontmatter.context,
         prompt,
         inputSchema,
         outputSchema,
         location: modulePath,
+        format: 'v1',
     };
 }
+/**
+ * Load a Cognitive Module (auto-detects format)
+ */
+export async function loadModule(modulePath) {
+    const format = await detectFormat(modulePath);
+    if (format === 'v2') {
+        return loadModuleV2(modulePath);
+    }
+    else {
+        return loadModuleV1(modulePath);
+    }
+}
+/**
+ * Check if a directory contains a valid module
+ */
+async function isValidModule(modulePath) {
+    const v2Manifest = path.join(modulePath, 'module.yaml');
+    const v1Module = path.join(modulePath, 'MODULE.md');
+    try {
+        await fs.access(v2Manifest);
+        return true;
+    }
+    catch {
+        try {
+            await fs.access(v1Module);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
 export async function findModule(name, searchPaths) {
     for (const basePath of searchPaths) {
         const modulePath = path.join(basePath, name);
-        const moduleFile = path.join(modulePath, 'MODULE.md');
-        try {
-            await fs.access(moduleFile);
+        if (await isValidModule(modulePath)) {
             return await loadModule(modulePath);
         }
-        catch {
-            // Module not found in this path, continue
-        }
     }
     return null;
 }
@@ -63,14 +169,14 @@ export async function listModules(searchPaths) {
             for (const entry of entries) {
                 if (entry.isDirectory()) {
                     const modulePath = path.join(basePath, entry.name);
-                    const moduleFile = path.join(modulePath, 'MODULE.md');
-                    try {
-                        await fs.access(moduleFile);
-                        const module = await loadModule(modulePath);
-                        modules.push(module);
-                    }
-                    catch {
-                        // Not a valid module, skip
+                    if (await isValidModule(modulePath)) {
+                        try {
+                            const module = await loadModule(modulePath);
+                            modules.push(module);
+                        }
+                        catch {
+                            // Skip invalid modules
+                        }
                     }
                 }
             }

package/dist/modules/runner.d.ts

@@ -1,12 +1,12 @@
 /**
  * Module Runner - Execute Cognitive Modules
+ * v2.1: Envelope format support, clean input mapping
  */
-import type { Provider, CognitiveModule, ModuleResult } from '../types.js';
+import type { Provider, CognitiveModule, ModuleResult, ModuleInput } from '../types.js';
 export interface RunOptions {
+    input?: ModuleInput;
     args?: string;
-    input?: Record<string, unknown>;
-    validateInput?: boolean;
-    validateOutput?: boolean;
     verbose?: boolean;
+    useEnvelope?: boolean;
 }
 export declare function runModule(module: CognitiveModule, provider: Provider, options?: RunOptions): Promise<ModuleResult>;

package/dist/modules/runner.js

@@ -1,43 +1,86 @@
 /**
  * Module Runner - Execute Cognitive Modules
+ * v2.1: Envelope format support, clean input mapping
  */
 export async function runModule(module, provider, options = {}) {
-    const { args, input, verbose = false } = options;
-    // Build input data
-    let inputData = input || {};
-    if (args) {
-        inputData = { $ARGUMENTS: args, query: args };
+    const { args, input, verbose = false, useEnvelope } = options;
+    // Determine if we should use envelope format
+    const shouldUseEnvelope = useEnvelope ?? (module.output?.envelope === true || module.format === 'v2');
+    // Build clean input data (v2 style: no $ARGUMENTS pollution)
+    const inputData = input || {};
+    // Map legacy --args to clean input
+    if (args && !inputData.code && !inputData.query) {
+        // Determine if args looks like code or natural language
+        if (looksLikeCode(args)) {
+            inputData.code = args;
+        }
+        else {
+            inputData.query = args;
+        }
     }
-    // Build prompt
+    // Build prompt with clean substitution
     const prompt = buildPrompt(module, inputData);
     if (verbose) {
+        console.error('--- Module ---');
+        console.error(`Name: ${module.name} (${module.format})`);
+        console.error(`Responsibility: ${module.responsibility}`);
+        console.error(`Envelope: ${shouldUseEnvelope}`);
+        console.error('--- Input ---');
+        console.error(JSON.stringify(inputData, null, 2));
         console.error('--- Prompt ---');
         console.error(prompt);
-        console.error('--- End Prompt ---');
+        console.error('--- End ---');
+    }
+    // Build system message based on module config
+    const systemParts = [
+        `You are executing the "${module.name}" Cognitive Module.`,
+        '',
+        `RESPONSIBILITY: ${module.responsibility}`,
+    ];
+    if (module.excludes.length > 0) {
+        systemParts.push('', 'YOU MUST NOT:');
+        module.excludes.forEach(e => systemParts.push(`- ${e}`));
+    }
+    if (module.constraints) {
+        systemParts.push('', 'CONSTRAINTS:');
+        if (module.constraints.no_network)
+            systemParts.push('- No network access');
+        if (module.constraints.no_side_effects)
+            systemParts.push('- No side effects');
+        if (module.constraints.no_file_write)
+            systemParts.push('- No file writes');
+        if (module.constraints.no_inventing_data)
+            systemParts.push('- Do not invent data');
+    }
+    if (module.output?.require_behavior_equivalence) {
+        systemParts.push('', 'BEHAVIOR EQUIVALENCE:');
+        systemParts.push('- You MUST set behavior_equivalence=true ONLY if the output is functionally identical');
+        systemParts.push('- If unsure, set behavior_equivalence=false and explain in rationale');
+        const maxConfidence = module.constraints?.behavior_equivalence_false_max_confidence ?? 0.7;
+        systemParts.push(`- If behavior_equivalence=false, confidence MUST be <= ${maxConfidence}`);
+    }
+    // Add envelope format instructions
+    if (shouldUseEnvelope) {
+        systemParts.push('', 'RESPONSE FORMAT (Envelope):');
+        systemParts.push('- Wrap your response in the envelope format');
+        systemParts.push('- Success: { "ok": true, "data": { ...your output... } }');
+        systemParts.push('- Error: { "ok": false, "error": { "code": "ERROR_CODE", "message": "..." } }');
+        systemParts.push('- Include "confidence" (0-1) and "rationale" in data');
+        if (module.output?.require_behavior_equivalence) {
+            systemParts.push('- Include "behavior_equivalence" (boolean) in data');
+        }
+    }
+    else {
+        systemParts.push('', 'OUTPUT FORMAT:');
+        systemParts.push('- Respond with ONLY valid JSON');
+        systemParts.push('- Include "confidence" (0-1) and "rationale" fields');
+        if (module.output?.require_behavior_equivalence) {
+            systemParts.push('- Include "behavior_equivalence" (boolean) field');
+        }
     }
-    // Build messages
     const messages = [
-        {
-            role: 'system',
-            content: `You are executing the "${module.name}" Cognitive Module.
-
-RESPONSIBILITY: ${module.responsibility}
-
-YOU MUST NOT:
-${module.excludes.map(e => `- ${e}`).join('\n')}
-
-REQUIRED OUTPUT FORMAT:
-You MUST respond with a valid JSON object. Include these fields:
-- All fields required by the output schema
-- "confidence": a number between 0 and 1
-- "rationale": a string explaining your reasoning
-
-Respond with ONLY valid JSON, no markdown code blocks.`,
-        },
-        {
-            role: 'user',
-            content: prompt,
-        },
+        { role: 'system', content: systemParts.join('\n') },
+        { role: 'user', content: prompt },
     ];
     // Invoke provider
     const result = await provider.invoke({
@@ -51,43 +94,136 @@ Respond with ONLY valid JSON, no markdown code blocks.`,
         console.error('--- End Response ---');
     }
     // Parse response
-    let output;
+    let parsed;
     try {
-        // Try to extract JSON from markdown code blocks
         const jsonMatch = result.content.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
         const jsonStr = jsonMatch ? jsonMatch[1] : result.content;
-        output = JSON.parse(jsonStr.trim());
+        parsed = JSON.parse(jsonStr.trim());
     }
     catch {
         throw new Error(`Failed to parse JSON response: ${result.content.substring(0, 500)}`);
     }
-    // Extract confidence and rationale
+    // Handle envelope format
+    if (shouldUseEnvelope && isEnvelopeResponse(parsed)) {
+        return parseEnvelopeResponse(parsed, result.content);
+    }
+    // Handle legacy format (non-envelope)
+    return parseLegacyResponse(parsed, result.content);
+}
+/**
+ * Check if response is in envelope format
+ */
+function isEnvelopeResponse(obj) {
+    if (typeof obj !== 'object' || obj === null)
+        return false;
+    const o = obj;
+    return typeof o.ok === 'boolean';
+}
+/**
+ * Parse envelope format response
+ */
+function parseEnvelopeResponse(response, raw) {
+    if (response.ok) {
+        const data = response.data;
+        return {
+            ok: true,
+            data: {
+                ...data,
+                confidence: typeof data.confidence === 'number' ? data.confidence : 0.5,
+                rationale: typeof data.rationale === 'string' ? data.rationale : '',
+                behavior_equivalence: data.behavior_equivalence,
+            },
+            raw,
+        };
+    }
+    else {
+        return {
+            ok: false,
+            error: response.error,
+            partial_data: response.partial_data,
+            raw,
+        };
+    }
+}
+/**
+ * Parse legacy (non-envelope) format response
+ */
+function parseLegacyResponse(output, raw) {
     const outputObj = output;
     const confidence = typeof outputObj.confidence === 'number' ? outputObj.confidence : 0.5;
     const rationale = typeof outputObj.rationale === 'string' ? outputObj.rationale : '';
+    const behaviorEquivalence = typeof outputObj.behavior_equivalence === 'boolean'
+        ? outputObj.behavior_equivalence
+        : undefined;
+    // Check if this is an error response (has error.code)
+    if (outputObj.error && typeof outputObj.error === 'object') {
+        const errorObj = outputObj.error;
+        if (typeof errorObj.code === 'string') {
+            return {
+                ok: false,
+                error: {
+                    code: errorObj.code,
+                    message: typeof errorObj.message === 'string' ? errorObj.message : 'Unknown error',
+                },
+                raw,
+            };
+        }
+    }
     return {
-        output,
-        confidence,
-        rationale,
-        raw: result.content,
+        ok: true,
+        data: {
+            ...outputObj,
+            confidence,
+            rationale,
+            behavior_equivalence: behaviorEquivalence,
+        },
+        raw,
     };
 }
-function buildPrompt(module, inputData) {
+/**
+ * Build prompt with clean variable substitution
+ */
+function buildPrompt(module, input) {
     let prompt = module.prompt;
-    // Substitute $ARGUMENTS
-    const argsValue = String(inputData.$ARGUMENTS || inputData.query || '');
+    // v2 style: substitute ${variable} placeholders
+    for (const [key, value] of Object.entries(input)) {
+        const strValue = typeof value === 'string' ? value : JSON.stringify(value);
+        prompt = prompt.replace(new RegExp(`\\$\\{${key}\\}`, 'g'), strValue);
+    }
+    // v1 compatibility: substitute $ARGUMENTS
+    const argsValue = input.code || input.query || '';
     prompt = prompt.replace(/\$ARGUMENTS/g, argsValue);
-    // Substitute $N placeholders
-    const argsList = argsValue.split(/\s+/);
-    argsList.forEach((arg, i) => {
-        prompt = prompt.replace(new RegExp(`\\$${i}`, 'g'), arg);
-        prompt = prompt.replace(new RegExp(`\\$ARGUMENTS\\[${i}\\]`, 'g'), arg);
-    });
-    // Substitute other input fields
-    for (const [key, value] of Object.entries(inputData)) {
-        if (key !== '$ARGUMENTS' && key !== 'query') {
-            prompt = prompt.replace(new RegExp(`\\$\\{${key}\\}`, 'g'), String(value));
+    // Substitute $N placeholders (v1 compatibility)
+    if (typeof argsValue === 'string') {
+        const argsList = argsValue.split(/\s+/);
+        argsList.forEach((arg, i) => {
+            prompt = prompt.replace(new RegExp(`\\$${i}\\b`, 'g'), arg);
+        });
+    }
+    // Append input summary if not already in prompt
+    if (!prompt.includes(argsValue) && argsValue) {
+        prompt += '\n\n## Input\n\n';
+        if (input.code) {
+            prompt += '```\n' + input.code + '\n```\n';
+        }
+        if (input.query) {
+            prompt += input.query + '\n';
+        }
+        if (input.language) {
+            prompt += `\nLanguage: ${input.language}\n`;
         }
     }
     return prompt;
 }
+/**
+ * Heuristic to detect if input looks like code
+ */
+function looksLikeCode(str) {
+    const codeIndicators = [
+        /^(def|function|class|const|let|var|import|export|public|private)\s/,
+        /[{};()]/,
+        /=>/,
+        /\.(py|js|ts|go|rs|java|cpp|c|rb)$/,
+    ];
+    return codeIndicators.some(re => re.test(str));
+}