cognitive-modules-cli 1.1.0 → 1.3.0

package/src/modules/runner.ts

@@ -1,6 +1,6 @@
 /**
  * Module Runner - Execute Cognitive Modules
- * v2.1: Envelope format support, clean input mapping
+ * v2.2: Envelope format with meta/data separation, risk_rule, repair pass
  */
 
 import type { 
@@ -8,11 +8,17 @@ import type {
   CognitiveModule, 
   ModuleResult, 
   ModuleResultV21,
+  ModuleResultV22,
   Message, 
   ModuleInput,
   EnvelopeResponse,
-  ModuleResultData
+  EnvelopeResponseV22,
+  EnvelopeMeta,
+  ModuleResultData,
+  RiskLevel,
+  RiskRule
 } from '../types.js';
+import { aggregateRisk, isV22Envelope } from '../types.js';
 
 export interface RunOptions {
   // Clean input (v2 style)
@@ -26,6 +32,134 @@ export interface RunOptions {
   
   // Force envelope format (default: auto-detect from module.output.envelope)
   useEnvelope?: boolean;
+  
+  // Force v2.2 format (default: auto-detect from module.tier)
+  useV22?: boolean;
+  
+  // Enable repair pass for validation failures (default: true)
+  enableRepair?: boolean;
+}
+
+// =============================================================================
+// Repair Pass (v2.2)
+// =============================================================================
+
+/**
+ * Attempt to repair envelope format issues without changing semantics.
+ * 
+ * Repairs (lossless only):
+ * - Missing meta fields (fill with conservative defaults)
+ * - Truncate explain if too long
+ * - Trim whitespace from string fields
+ * 
+ * Does NOT repair:
+ * - Invalid enum values (treated as validation failure)
+ */
+function repairEnvelope(
+  response: Record<string, unknown>,
+  riskRule: RiskRule = 'max_changes_risk',
+  maxExplainLength: number = 280
+): EnvelopeResponseV22<unknown> {
+  const repaired = { ...response };
+  
+  // Ensure meta exists
+  if (!repaired.meta || typeof repaired.meta !== 'object') {
+    repaired.meta = {};
+  }
+  
+  const meta = repaired.meta as Record<string, unknown>;
+  const data = (repaired.data ?? {}) as Record<string, unknown>;
+  
+  // Repair confidence
+  if (typeof meta.confidence !== 'number') {
+    meta.confidence = (data.confidence as number) ?? 0.5;
+  }
+  meta.confidence = Math.max(0, Math.min(1, meta.confidence as number));
+  
+  // Repair risk using configurable aggregation rule
+  if (!meta.risk) {
+    meta.risk = aggregateRisk(data, riskRule);
+  }
+  // Trim whitespace only (lossless), validate is valid RiskLevel
+  if (typeof meta.risk === 'string') {
+    const trimmedRisk = meta.risk.trim().toLowerCase();
+    const validRisks = ['none', 'low', 'medium', 'high'];
+    meta.risk = validRisks.includes(trimmedRisk) ? trimmedRisk : 'medium';
+  } else {
+    meta.risk = 'medium'; // Default for invalid type
+  }
+  
+  // Repair explain
+  if (typeof meta.explain !== 'string') {
+    const rationale = data.rationale as string | undefined;
+    meta.explain = rationale ? String(rationale).slice(0, maxExplainLength) : 'No explanation provided';
+  }
+  // Trim whitespace (lossless)
+  const explainStr = meta.explain as string;
+  meta.explain = explainStr.trim();
+  if ((meta.explain as string).length > maxExplainLength) {
+    meta.explain = (meta.explain as string).slice(0, maxExplainLength - 3) + '...';
+  }
+  
+  // Build proper v2.2 response
+  const builtMeta: EnvelopeMeta = {
+    confidence: meta.confidence as number,
+    risk: meta.risk as RiskLevel,
+    explain: meta.explain as string
+  };
+  
+  const result: EnvelopeResponseV22<unknown> = repaired.ok === false ? {
+    ok: false,
+    meta: builtMeta,
+    error: (repaired.error as { code: string; message: string }) ?? { code: 'UNKNOWN', message: 'Unknown error' },
+    partial_data: repaired.partial_data
+  } : {
+    ok: true,
+    meta: builtMeta,
+    data: repaired.data
+  };
+  
+  return result;
+}
+
+/**
+ * Wrap v2.1 response to v2.2 format
+ */
+function wrapV21ToV22(
+  response: EnvelopeResponse<unknown>,
+  riskRule: RiskRule = 'max_changes_risk'
+): EnvelopeResponseV22<unknown> {
+  if (isV22Envelope(response)) {
+    return response;
+  }
+  
+  if (response.ok) {
+    const data = (response.data ?? {}) as Record<string, unknown>;
+    const confidence = (data.confidence as number) ?? 0.5;
+    const rationale = (data.rationale as string) ?? '';
+    
+    return {
+      ok: true,
+      meta: {
+        confidence,
+        risk: aggregateRisk(data, riskRule),
+        explain: rationale.slice(0, 280) || 'No explanation provided'
+      },
+      data: data as ModuleResultData
+    };
+  } else {
+    const errorMsg = response.error?.message ?? 'Unknown error';
+    return {
+      ok: false,
+      meta: {
+        confidence: 0,
+        risk: 'high',
+        explain: errorMsg.slice(0, 280)
+      },
+      error: response.error ?? { code: 'UNKNOWN', message: errorMsg },
+      partial_data: response.partial_data
+    };
+  }
 }
 
 export async function runModule(
@@ -33,10 +167,17 @@ export async function runModule(
   provider: Provider,
   options: RunOptions = {}
 ): Promise<ModuleResult> {
-  const { args, input, verbose = false, useEnvelope } = options;
+  const { args, input, verbose = false, useEnvelope, useV22, enableRepair = true } = options;
 
   // Determine if we should use envelope format
   const shouldUseEnvelope = useEnvelope ?? (module.output?.envelope === true || module.format === 'v2');
+  
+  // Determine if we should use v2.2 format
+  const isV22Module = module.tier !== undefined || module.formatVersion === 'v2.2';
+  const shouldUseV22 = useV22 ?? (isV22Module || module.compat?.runtime_auto_wrap === true);
+  
+  // Get risk_rule from module config
+  const riskRule: RiskRule = module.metaConfig?.risk_rule ?? 'max_changes_risk';
 
   // Build clean input data (v2 style: no $ARGUMENTS pollution)
   const inputData: ModuleInput = input || {};
@@ -97,11 +238,20 @@ export async function runModule(
 
   // 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 (shouldUseV22) {
+      systemParts.push('', 'RESPONSE FORMAT (Envelope v2.2):');
+      systemParts.push('- Wrap your response in the v2.2 envelope format with separate meta and data');
+      systemParts.push('- Success: { "ok": true, "meta": { "confidence": 0.9, "risk": "low", "explain": "short summary" }, "data": { ...payload... } }');
+      systemParts.push('- Error: { "ok": false, "meta": { "confidence": 0.0, "risk": "high", "explain": "error summary" }, "error": { "code": "ERROR_CODE", "message": "..." } }');
+      systemParts.push('- meta.explain must be ≤280 characters. data.rationale can be longer for detailed reasoning.');
+      systemParts.push('- meta.risk must be one of: "none", "low", "medium", "high"');
+    } else {
+      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');
     }
@@ -144,11 +294,55 @@ export async function runModule(
 
   // Handle envelope format
   if (shouldUseEnvelope && isEnvelopeResponse(parsed)) {
-    return parseEnvelopeResponse(parsed, result.content);
+    let response = parseEnvelopeResponse(parsed, result.content);
+    
+    // Upgrade to v2.2 if needed
+    if (shouldUseV22 && response.ok && !('meta' in response && response.meta)) {
+      const upgraded = wrapV21ToV22(parsed as EnvelopeResponse<unknown>, riskRule);
+      response = {
+        ok: true,
+        meta: upgraded.meta as EnvelopeMeta,
+        data: (upgraded as { data?: ModuleResultData }).data,
+        raw: result.content
+      } as ModuleResultV22;
+    }
+    
+    // Apply repair pass if enabled and response needs it
+    if (enableRepair && response.ok && shouldUseV22) {
+      const repaired = repairEnvelope(
+        response as unknown as Record<string, unknown>,
+        riskRule
+      );
+      response = {
+        ok: true,
+        meta: repaired.meta as EnvelopeMeta,
+        data: (repaired as { data?: ModuleResultData }).data,
+        raw: result.content
+      } as ModuleResultV22;
+    }
+    
+    return response;
   }
 
   // Handle legacy format (non-envelope)
-  return parseLegacyResponse(parsed, result.content);
+  const legacyResult = parseLegacyResponse(parsed, result.content);
+  
+  // Upgrade to v2.2 if requested
+  if (shouldUseV22 && legacyResult.ok) {
+    const data = (legacyResult.data ?? {}) as Record<string, unknown>;
+    return {
+      ok: true,
+      meta: {
+        confidence: (data.confidence as number) ?? 0.5,
+        risk: aggregateRisk(data, riskRule),
+        explain: ((data.rationale as string) ?? '').slice(0, 280) || 'No explanation provided'
+      },
+      data: legacyResult.data,
+      raw: result.content
+    } as ModuleResultV22;
+  }
+  
+  return legacyResult;
 }
 
 /**
@@ -161,11 +355,32 @@ function isEnvelopeResponse(obj: unknown): obj is EnvelopeResponse {
 }
 
 /**
- * Parse envelope format response
+ * Parse envelope format response (supports both v2.1 and v2.2)
  */
-function parseEnvelopeResponse(response: EnvelopeResponse, raw: string): ModuleResult {
+function parseEnvelopeResponse(response: EnvelopeResponse<unknown>, raw: string): ModuleResult {
+  // Check if v2.2 format (has meta)
+  if (isV22Envelope(response)) {
+    if (response.ok) {
+      return {
+        ok: true,
+        meta: response.meta,
+        data: response.data as ModuleResultData,
+        raw,
+      } as ModuleResultV22;
+    } else {
+      return {
+        ok: false,
+        meta: response.meta,
+        error: response.error,
+        partial_data: response.partial_data,
+        raw,
+      } as ModuleResultV22;
+    }
+  }
+  
+  // v2.1 format
   if (response.ok) {
-    const data = response.data as ModuleResultData;
+    const data = (response.data ?? {}) as ModuleResultData & { confidence?: number };
     return {
       ok: true,
       data: {
@@ -175,14 +390,14 @@ function parseEnvelopeResponse(response: EnvelopeResponse, raw: string): ModuleR
         behavior_equivalence: data.behavior_equivalence,
       },
       raw,
-    };
+    } as ModuleResultV21;
   } else {
     return {
       ok: false,
       error: response.error,
       partial_data: response.partial_data,
       raw,
-    };
+    } as ModuleResultV21;
   }
 }
 

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);
+}