cognitive-runtime 0.3.0 → 0.5.0

package/dist/types.d.ts

@@ -1,5 +1,6 @@
 /**
  * Cognitive Runtime - Core Types
+ * Version 2.1 - With envelope format, tools policy, failure contract
  */
 export interface Provider {
     name: string;
@@ -29,16 +30,91 @@ export interface CognitiveModule {
     version: string;
     responsibility: string;
     excludes: string[];
+    constraints?: ModuleConstraints;
+    policies?: ModulePolicies;
+    tools?: ToolsPolicy;
+    output?: OutputContract;
+    failure?: FailureContract;
+    runtimeRequirements?: RuntimeRequirements;
     context?: 'fork' | 'main';
     prompt: string;
     inputSchema?: object;
     outputSchema?: object;
+    errorSchema?: object;
     location: string;
+    format: 'v1' | 'v2';
+}
+export interface ModuleConstraints {
+    no_network?: boolean;
+    no_side_effects?: boolean;
+    no_file_write?: boolean;
+    no_inventing_data?: boolean;
+    behavior_equivalence_false_max_confidence?: number;
+}
+export interface ModulePolicies {
+    network?: 'allow' | 'deny';
+    filesystem_write?: 'allow' | 'deny';
+    side_effects?: 'allow' | 'deny';
+    code_execution?: 'allow' | 'deny';
+}
+export interface ToolsPolicy {
+    policy?: 'allow_by_default' | 'deny_by_default';
+    allowed: string[];
+    denied?: string[];
+}
+export interface OutputContract {
+    format?: 'json_strict' | 'json_lenient' | 'text';
+    envelope?: boolean;
+    require?: string[];
+    require_confidence?: boolean;
+    require_rationale?: boolean;
+    require_behavior_equivalence?: boolean;
+}
+export interface FailureContract {
+    contract?: 'error_union' | 'throw';
+    partial_allowed?: boolean;
+    must_return_error_schema?: boolean;
+    schema?: object;
+}
+export interface RuntimeRequirements {
+    structured_output?: boolean;
+    max_input_tokens?: number;
+    preferred_capabilities?: string[];
+}
+export interface EnvelopeSuccess<T = unknown> {
+    ok: true;
+    data: T;
+}
+export interface EnvelopeError {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+    partial_data?: unknown;
+}
+export type EnvelopeResponse<T = unknown> = EnvelopeSuccess<T> | EnvelopeError;
+export interface ModuleResultData {
+    [key: string]: unknown;
+    confidence: number;
+    rationale: string;
+    behavior_equivalence?: boolean;
 }
 export interface ModuleResult {
+    ok: boolean;
+    data?: ModuleResultData;
+    error?: {
+        code: string;
+        message: string;
+    };
+    partial_data?: unknown;
+    raw?: string;
+}
+export interface LegacyModuleResult {
     output: unknown;
     confidence: number;
     rationale: string;
+    behaviorEquivalence?: boolean;
     raw?: string;
 }
 export interface CommandContext {
@@ -51,3 +127,10 @@ export interface CommandResult {
     data?: unknown;
     error?: string;
 }
+export interface ModuleInput {
+    code?: string;
+    query?: string;
+    language?: string;
+    options?: Record<string, unknown>;
+    [key: string]: unknown;
+}

package/dist/types.js

@@ -1,4 +1,5 @@
 /**
  * Cognitive Runtime - Core Types
+ * Version 2.1 - With envelope format, tools policy, failure contract
  */
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cognitive-runtime",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Cognitive Runtime - Structured AI Task Execution",
   "type": "module",
   "main": "dist/index.js",

package/src/cli.ts

@@ -13,7 +13,7 @@ import { getProvider, listProviders } from './providers/index.js';
 import { run, list, pipe, init } from './commands/index.js';
 import type { CommandContext } from './types.js';
 
-const VERSION = '0.3.0';
+const VERSION = '0.5.0';
 
 async function main() {
   const args = process.argv.slice(2);

package/src/commands/pipe.ts

@@ -52,20 +52,22 @@ export async function pipe(
     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/src/commands/run.ts

@@ -47,15 +47,30 @@ export async function run(
     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 {
       success: false,

package/src/index.ts

@@ -12,6 +12,11 @@ export type {
   Message,
   CognitiveModule,
   ModuleResult,
+  ModuleInput,
+  ModuleConstraints,
+  ToolsPolicy,
+  OutputContract,
+  FailureContract,
   CommandContext,
   CommandResult,
 } from './types.js';

package/src/modules/loader.ts

@@ -1,15 +1,88 @@
 /**
  * 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';
-import type { CognitiveModule } from '../types.js';
+import type { CognitiveModule, ModuleConstraints, ModulePolicies, ToolsPolicy, OutputContract, FailureContract, RuntimeRequirements } from '../types.js';
 
 const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n([\s\S]*))?/;
 
-export async function loadModule(modulePath: string): Promise<CognitiveModule> {
+/**
+ * Detect module format version
+ */
+async function detectFormat(modulePath: string): Promise<'v1' | 'v2'> {
+  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: string): Promise<CognitiveModule> {
+  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) as Record<string, unknown>;
+
+  // 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: object | undefined;
+  let outputSchema: object | undefined;
+  let errorSchema: object | undefined;
+  
+  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 as string || path.basename(modulePath),
+    version: manifest.version as string || '1.0.0',
+    responsibility: manifest.responsibility as string || '',
+    excludes: (manifest.excludes as string[]) || [],
+    constraints: manifest.constraints as ModuleConstraints | undefined,
+    policies: manifest.policies as ModulePolicies | undefined,
+    tools: manifest.tools as ToolsPolicy | undefined,
+    output: manifest.output as OutputContract | undefined,
+    failure: manifest.failure as FailureContract | undefined,
+    runtimeRequirements: manifest.runtime_requirements as RuntimeRequirements | undefined,
+    context: manifest.context as 'fork' | 'main' | undefined,
+    prompt,
+    inputSchema,
+    outputSchema,
+    errorSchema,
+    location: modulePath,
+    format: 'v2',
+  };
+}
+
+/**
+ * Load v1 format module (MODULE.md with frontmatter)
+ */
+async function loadModuleV1(modulePath: string): Promise<CognitiveModule> {
   const moduleFile = path.join(modulePath, 'MODULE.md');
   const schemaFile = path.join(modulePath, 'schema.json');
 
@@ -38,29 +111,69 @@ export async function loadModule(modulePath: string): Promise<CognitiveModule> {
     // Schema file is optional
   }
 
+  // Extract constraints from v1 format
+  const constraints: ModuleConstraints = {};
+  const v1Constraints = frontmatter.constraints as Record<string, boolean> | undefined;
+  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 as string || path.basename(modulePath),
     version: frontmatter.version as string || '1.0.0',
     responsibility: frontmatter.responsibility as string || '',
     excludes: (frontmatter.excludes as string[]) || [],
+    constraints: Object.keys(constraints).length > 0 ? constraints : undefined,
     context: frontmatter.context as 'fork' | 'main' | undefined,
     prompt,
     inputSchema,
     outputSchema,
     location: modulePath,
+    format: 'v1',
   };
 }
 
+/**
+ * Load a Cognitive Module (auto-detects format)
+ */
+export async function loadModule(modulePath: string): Promise<CognitiveModule> {
+  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: string): Promise<boolean> {
+  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: string, searchPaths: string[]): Promise<CognitiveModule | null> {
   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
     }
   }
   
@@ -77,14 +190,14 @@ export async function listModules(searchPaths: string[]): Promise<CognitiveModul
       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
+            }
           }
         }
       }