cognitive-modules 0.6.0

package/src/modules/loader.ts

@@ -0,0 +1,219 @@
+/**
+ * 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, ModuleConstraints, ModulePolicies, ToolsPolicy, OutputContract, FailureContract, RuntimeRequirements } from '../types.js';
+
+const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n([\s\S]*))?/;
+
+/**
+ * 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');
+
+  // Read MODULE.md
+  const moduleContent = await fs.readFile(moduleFile, 'utf-8');
+  
+  // Parse frontmatter
+  const match = moduleContent.match(FRONTMATTER_REGEX);
+  if (!match) {
+    throw new Error(`Invalid MODULE.md: missing YAML frontmatter in ${moduleFile}`);
+  }
+
+  const frontmatter = yaml.load(match[1]) as Record<string, unknown>;
+  const prompt = (match[2] || '').trim();
+
+  // Read schema.json
+  let inputSchema: object | undefined;
+  let outputSchema: object | undefined;
+  
+  try {
+    const schemaContent = await fs.readFile(schemaFile, 'utf-8');
+    const schema = JSON.parse(schemaContent);
+    inputSchema = schema.input;
+    outputSchema = schema.output;
+  } catch {
+    // 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);
+    
+    if (await isValidModule(modulePath)) {
+      return await loadModule(modulePath);
+    }
+  }
+  
+  return null;
+}
+
+export async function listModules(searchPaths: string[]): Promise<CognitiveModule[]> {
+  const modules: CognitiveModule[] = [];
+  
+  for (const basePath of searchPaths) {
+    try {
+      const entries = await fs.readdir(basePath, { withFileTypes: true });
+      
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          const modulePath = path.join(basePath, entry.name);
+          
+          if (await isValidModule(modulePath)) {
+            try {
+              const module = await loadModule(modulePath);
+              modules.push(module);
+            } catch {
+              // Skip invalid modules
+            }
+          }
+        }
+      }
+    } catch {
+      // Path doesn't exist, skip
+    }
+  }
+  
+  return modules;
+}
+
+export function getDefaultSearchPaths(cwd: string): string[] {
+  const home = process.env.HOME || '';
+  return [
+    path.join(cwd, 'cognitive', 'modules'),
+    path.join(cwd, '.cognitive', 'modules'),
+    path.join(home, '.cognitive', 'modules'),
+  ];
+}

package/src/modules/runner.ts

@@ -0,0 +1,278 @@
+/**
+ * Module Runner - Execute Cognitive Modules
+ * v2.1: Envelope format support, clean input mapping
+ */
+
+import type { 
+  Provider, 
+  CognitiveModule, 
+  ModuleResult, 
+  Message, 
+  ModuleInput,
+  EnvelopeResponse,
+  ModuleResultData
+} from '../types.js';
+
+export interface RunOptions {
+  // Clean input (v2 style)
+  input?: ModuleInput;
+  
+  // Legacy CLI args (v1 compatibility) - mapped to input.code or input.query
+  args?: string;
+  
+  // Runtime options
+  verbose?: boolean;
+  
+  // Force envelope format (default: auto-detect from module.output.envelope)
+  useEnvelope?: boolean;
+}
+
+export async function runModule(
+  module: CognitiveModule,
+  provider: Provider,
+  options: RunOptions = {}
+): Promise<ModuleResult> {
+  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: ModuleInput = 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 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 ---');
+  }
+
+  // Build system message based on module config
+  const systemParts: string[] = [
+    `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');
+    }
+  }
+
+  const messages: Message[] = [
+    { role: 'system', content: systemParts.join('\n') },
+    { role: 'user', content: prompt },
+  ];
+
+  // Invoke provider
+  const result = await provider.invoke({
+    messages,
+    jsonSchema: module.outputSchema,
+    temperature: 0.3,
+  });
+
+  if (verbose) {
+    console.error('--- Response ---');
+    console.error(result.content);
+    console.error('--- End Response ---');
+  }
+
+  // Parse response
+  let parsed: unknown;
+  try {
+    const jsonMatch = result.content.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
+    const jsonStr = jsonMatch ? jsonMatch[1] : result.content;
+    parsed = JSON.parse(jsonStr.trim());
+  } catch {
+    throw new Error(`Failed to parse JSON response: ${result.content.substring(0, 500)}`);
+  }
+
+  // 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: unknown): obj is EnvelopeResponse {
+  if (typeof obj !== 'object' || obj === null) return false;
+  const o = obj as Record<string, unknown>;
+  return typeof o.ok === 'boolean';
+}
+
+/**
+ * Parse envelope format response
+ */
+function parseEnvelopeResponse(response: EnvelopeResponse, raw: string): ModuleResult {
+  if (response.ok) {
+    const data = response.data as ModuleResultData;
+    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: unknown, raw: string): ModuleResult {
+  const outputObj = output as Record<string, unknown>;
+  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 as Record<string, unknown>;
+    if (typeof errorObj.code === 'string') {
+      return {
+        ok: false,
+        error: {
+          code: errorObj.code,
+          message: typeof errorObj.message === 'string' ? errorObj.message : 'Unknown error',
+        },
+        raw,
+      };
+    }
+  }
+
+  return {
+    ok: true,
+    data: {
+      ...outputObj,
+      confidence,
+      rationale,
+      behavior_equivalence: behaviorEquivalence,
+    } as ModuleResultData,
+    raw,
+  };
+}
+
+/**
+ * Build prompt with clean variable substitution
+ */
+function buildPrompt(module: CognitiveModule, input: ModuleInput): string {
+  let prompt = module.prompt;
+
+  // 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 (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: string): boolean {
+  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));
+}

package/src/providers/anthropic.ts

@@ -0,0 +1,89 @@
+/**
+ * Anthropic Provider - Claude API
+ */
+
+import { BaseProvider } from './base.js';
+import type { InvokeParams, InvokeResult } from '../types.js';
+
+export class AnthropicProvider extends BaseProvider {
+  name = 'anthropic';
+  private apiKey: string;
+  private model: string;
+  private baseUrl = 'https://api.anthropic.com/v1';
+
+  constructor(apiKey?: string, model = 'claude-sonnet-4-5-20250929') {
+    super();
+    this.apiKey = apiKey || process.env.ANTHROPIC_API_KEY || '';
+    this.model = model;
+  }
+
+  isConfigured(): boolean {
+    return !!this.apiKey;
+  }
+
+  async invoke(params: InvokeParams): Promise<InvokeResult> {
+    if (!this.isConfigured()) {
+      throw new Error('Anthropic API key not configured. Set ANTHROPIC_API_KEY environment variable.');
+    }
+
+    const url = `${this.baseUrl}/messages`;
+
+    // Extract system message
+    const systemMessage = params.messages.find(m => m.role === 'system');
+    const otherMessages = params.messages.filter(m => m.role !== 'system');
+
+    // Add JSON schema instruction if provided
+    let messages = otherMessages;
+    if (params.jsonSchema) {
+      const lastUserIdx = messages.findLastIndex(m => m.role === 'user');
+      if (lastUserIdx >= 0) {
+        messages = [...messages];
+        messages[lastUserIdx] = {
+          ...messages[lastUserIdx],
+          content: messages[lastUserIdx].content + this.buildJsonPrompt(params.jsonSchema),
+        };
+      }
+    }
+
+    const body: Record<string, unknown> = {
+      model: this.model,
+      messages: messages.map(m => ({ role: m.role, content: m.content })),
+      max_tokens: params.maxTokens ?? 4096,
+    };
+
+    if (systemMessage) {
+      body.system = systemMessage.content;
+    }
+
+    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}`);
+    }
+
+    const data = await response.json() as {
+      content?: Array<{ text?: string }>;
+      usage?: { input_tokens?: number; output_tokens?: number };
+    };
+    
+    const content = data.content?.[0]?.text || '';
+    
+    return {
+      content,
+      usage: data.usage ? {
+        promptTokens: data.usage.input_tokens || 0,
+        completionTokens: data.usage.output_tokens || 0,
+        totalTokens: (data.usage.input_tokens || 0) + (data.usage.output_tokens || 0),
+      } : undefined,
+    };
+  }
+}

package/src/providers/base.ts

@@ -0,0 +1,29 @@
+/**
+ * Base Provider - Abstract class for all LLM providers
+ */
+
+import type { Provider, InvokeParams, InvokeResult } from '../types.js';
+
+export abstract class BaseProvider implements Provider {
+  abstract name: string;
+  
+  abstract invoke(params: InvokeParams): Promise<InvokeResult>;
+  
+  abstract isConfigured(): boolean;
+
+  protected buildJsonPrompt(schema: object): string {
+    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.`;
+  }
+
+  protected parseJsonResponse(content: string): unknown {
+    // Try to extract JSON from markdown code blocks
+    const jsonMatch = content.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
+    const jsonStr = jsonMatch ? jsonMatch[1] : content;
+    
+    try {
+      return JSON.parse(jsonStr.trim());
+    } catch {
+      throw new Error(`Failed to parse JSON response: ${content.substring(0, 200)}`);
+    }
+  }
+}

package/src/providers/deepseek.ts

@@ -0,0 +1,83 @@
+/**
+ * DeepSeek Provider - DeepSeek API
+ */
+
+import { BaseProvider } from './base.js';
+import type { InvokeParams, InvokeResult } from '../types.js';
+
+export class DeepSeekProvider extends BaseProvider {
+  name = 'deepseek';
+  private apiKey: string;
+  private model: string;
+  private baseUrl = 'https://api.deepseek.com/v1';
+
+  constructor(apiKey?: string, model = 'deepseek-chat') {
+    // deepseek-chat 自动映射到最新的 DeepSeek-V3.2
+    super();
+    this.apiKey = apiKey || process.env.DEEPSEEK_API_KEY || '';
+    this.model = model;
+  }
+
+  isConfigured(): boolean {
+    return !!this.apiKey;
+  }
+
+  async invoke(params: InvokeParams): Promise<InvokeResult> {
+    if (!this.isConfigured()) {
+      throw new Error('DeepSeek API key not configured. Set DEEPSEEK_API_KEY environment variable.');
+    }
+
+    const url = `${this.baseUrl}/chat/completions`;
+
+    const body: Record<string, unknown> = {
+      model: this.model,
+      messages: params.messages.map(m => ({ role: m.role, content: m.content })),
+      temperature: params.temperature ?? 0.7,
+      max_tokens: params.maxTokens ?? 4096,
+    };
+
+    // Add JSON mode if schema provided
+    if (params.jsonSchema) {
+      body.response_format = { type: 'json_object' };
+      const lastUserIdx = params.messages.findLastIndex(m => m.role === 'user');
+      if (lastUserIdx >= 0) {
+        const messages = [...params.messages];
+        messages[lastUserIdx] = {
+          ...messages[lastUserIdx],
+          content: messages[lastUserIdx].content + this.buildJsonPrompt(params.jsonSchema),
+        };
+        body.messages = messages.map(m => ({ role: m.role, content: m.content }));
+      }
+    }
+
+    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(`DeepSeek API error: ${response.status} - ${error}`);
+    }
+
+    const data = await response.json() as {
+      choices?: Array<{ message?: { content?: string } }>;
+      usage?: { prompt_tokens?: number; completion_tokens?: number; total_tokens?: number };
+    };
+    
+    const content = data.choices?.[0]?.message?.content || '';
+    
+    return {
+      content,
+      usage: data.usage ? {
+        promptTokens: data.usage.prompt_tokens || 0,
+        completionTokens: data.usage.completion_tokens || 0,
+        totalTokens: data.usage.total_tokens || 0,
+      } : undefined,
+    };
+  }
+}