cognitive-modules-cli 1.2.0 → 1.3.0

package/src/mcp/server.ts

@@ -0,0 +1,403 @@
+/**
+ * Cognitive Modules MCP Server
+ * 
+ * Provides MCP (Model Context Protocol) interface for Claude Code, Cursor, etc.
+ * 
+ * Start with:
+ *   cog mcp
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+
+import { loadModule, findModule, listModules, getDefaultSearchPaths } from '../modules/loader.js';
+import { runModule } from '../modules/runner.js';
+import { getProvider } from '../providers/index.js';
+import type { CognitiveModule, ModuleResult } from '../types.js';
+
+// =============================================================================
+// Server Setup
+// =============================================================================
+
+const server = new Server(
+  {
+    name: 'cognitive-modules',
+    version: '1.2.0',
+  },
+  {
+    capabilities: {
+      tools: {},
+      resources: {},
+      prompts: {},
+    },
+  }
+);
+
+const cwd = process.cwd();
+const searchPaths = getDefaultSearchPaths(cwd);
+
+// =============================================================================
+// Tools
+// =============================================================================
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: 'cognitive_run',
+        description: 'Run a Cognitive Module to get structured AI analysis results',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            module: {
+              type: 'string',
+              description: 'Module name, e.g. "code-reviewer", "task-prioritizer"',
+            },
+            args: {
+              type: 'string',
+              description: 'Input arguments, e.g. code snippet or task list',
+            },
+            provider: {
+              type: 'string',
+              description: 'LLM provider (optional), e.g. "openai", "anthropic"',
+            },
+            model: {
+              type: 'string',
+              description: 'Model name (optional), e.g. "gpt-4o", "claude-3-5-sonnet"',
+            },
+          },
+          required: ['module', 'args'],
+        },
+      },
+      {
+        name: 'cognitive_list',
+        description: 'List all installed Cognitive Modules',
+        inputSchema: {
+          type: 'object',
+          properties: {},
+        },
+      },
+      {
+        name: 'cognitive_info',
+        description: 'Get detailed information about a Cognitive Module',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            module: {
+              type: 'string',
+              description: 'Module name',
+            },
+          },
+          required: ['module'],
+        },
+      },
+    ],
+  };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case 'cognitive_run': {
+        const { module: moduleName, args: inputArgs, provider: providerName, model } = args as {
+          module: string;
+          args: string;
+          provider?: string;
+          model?: string;
+        };
+
+        // Find module
+        const moduleData = await findModule(moduleName, searchPaths);
+        if (!moduleData) {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: JSON.stringify({ ok: false, error: `Module '${moduleName}' not found` }),
+              },
+            ],
+          };
+        }
+
+        // Create provider
+        const provider = getProvider(providerName, model);
+
+        // Run module
+        const result = await runModule(moduleData, provider, {
+          input: { query: inputArgs, code: inputArgs },
+          useV22: true,
+        });
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      }
+
+      case 'cognitive_list': {
+        const modules = await listModules(searchPaths);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(
+                {
+                  modules: modules.map((m) => ({
+                    name: m.name,
+                    location: m.location,
+                    format: m.format,
+                    tier: m.tier,
+                  })),
+                  count: modules.length,
+                },
+                null,
+                2
+              ),
+            },
+          ],
+        };
+      }
+
+      case 'cognitive_info': {
+        const { module: moduleName } = args as { module: string };
+
+        const moduleData = await findModule(moduleName, searchPaths);
+        if (!moduleData) {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: JSON.stringify({ ok: false, error: `Module '${moduleName}' not found` }),
+              },
+            ],
+          };
+        }
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(
+                {
+                  ok: true,
+                  name: moduleData.name,
+                  version: moduleData.version,
+                  responsibility: moduleData.responsibility,
+                  tier: moduleData.tier,
+                  format: moduleData.format,
+                  inputSchema: moduleData.inputSchema,
+                  outputSchema: moduleData.outputSchema,
+                },
+                null,
+                2
+              ),
+            },
+          ],
+        };
+      }
+
+      default:
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify({ ok: false, error: `Unknown tool: ${name}` }),
+            },
+          ],
+        };
+    }
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify({
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+          }),
+        },
+      ],
+    };
+  }
+});
+
+// =============================================================================
+// Resources
+// =============================================================================
+
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+  const modules = await listModules(searchPaths);
+  
+  return {
+    resources: [
+      {
+        uri: 'cognitive://modules',
+        name: 'All Modules',
+        description: 'List of all installed Cognitive Modules',
+        mimeType: 'application/json',
+      },
+      ...modules.map((m) => ({
+        uri: `cognitive://module/${m.name}`,
+        name: m.name,
+        description: m.responsibility || `Cognitive Module: ${m.name}`,
+        mimeType: 'text/markdown',
+      })),
+    ],
+  };
+});
+
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  const { uri } = request.params;
+
+  if (uri === 'cognitive://modules') {
+    const modules = await listModules(searchPaths);
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: 'application/json',
+          text: JSON.stringify(modules.map((m) => m.name), null, 2),
+        },
+      ],
+    };
+  }
+
+  const match = uri.match(/^cognitive:\/\/module\/(.+)$/);
+  if (match) {
+    const moduleName = match[1];
+    const moduleData = await findModule(moduleName, searchPaths);
+
+    if (!moduleData) {
+      return {
+        contents: [
+          {
+            uri,
+            mimeType: 'text/plain',
+            text: `Module '${moduleName}' not found`,
+          },
+        ],
+      };
+    }
+
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: 'text/markdown',
+          text: moduleData.prompt,
+        },
+      ],
+    };
+  }
+
+  return {
+    contents: [
+      {
+        uri,
+        mimeType: 'text/plain',
+        text: `Unknown resource: ${uri}`,
+      },
+    ],
+  };
+});
+
+// =============================================================================
+// Prompts
+// =============================================================================
+
+server.setRequestHandler(ListPromptsRequestSchema, async () => {
+  return {
+    prompts: [
+      {
+        name: 'code_review',
+        description: 'Generate a code review prompt',
+        arguments: [
+          {
+            name: 'code',
+            description: 'The code to review',
+            required: true,
+          },
+        ],
+      },
+      {
+        name: 'task_prioritize',
+        description: 'Generate a task prioritization prompt',
+        arguments: [
+          {
+            name: 'tasks',
+            description: 'The tasks to prioritize',
+            required: true,
+          },
+        ],
+      },
+    ],
+  };
+});
+
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  switch (name) {
+    case 'code_review': {
+      const code = args?.code ?? '';
+      return {
+        messages: [
+          {
+            role: 'user',
+            content: {
+              type: 'text',
+              text: `Please use the cognitive_run tool to review the following code:\n\n\`\`\`\n${code}\n\`\`\`\n\nCall: cognitive_run("code-reviewer", "${code.slice(0, 100)}...")`,
+            },
+          },
+        ],
+      };
+    }
+
+    case 'task_prioritize': {
+      const tasks = args?.tasks ?? '';
+      return {
+        messages: [
+          {
+            role: 'user',
+            content: {
+              type: 'text',
+              text: `Please use the cognitive_run tool to prioritize the following tasks:\n\n${tasks}\n\nCall: cognitive_run("task-prioritizer", "${tasks}")`,
+            },
+          },
+        ],
+      };
+    }
+
+    default:
+      throw new Error(`Unknown prompt: ${name}`);
+  }
+});
+
+// =============================================================================
+// Server Start
+// =============================================================================
+
+export async function serve(): Promise<void> {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('Cognitive Modules MCP Server started');
+}
+
+// Allow running directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  serve().catch(console.error);
+}

package/src/modules/index.ts

@@ -4,3 +4,4 @@
 
 export * from './loader.js';
 export * from './runner.js';
+export * from './subagent.js';

package/src/modules/loader.ts

@@ -131,11 +131,17 @@ async function loadModuleV2(modulePath: string): Promise<CognitiveModule> {
     schema_output_alias: (compatRaw.schema_output_alias as 'data' | 'output') ?? 'data'
   };
   
-  // Parse meta config (including risk_rule)
+  // Parse meta config (including risk_rule) with validation
   const metaRaw = (manifest.meta as Record<string, unknown>) || {};
+  const rawRiskRule = metaRaw.risk_rule as string | undefined;
+  const validRiskRules = ['max_changes_risk', 'max_issues_risk', 'explicit'];
+  const validatedRiskRule = rawRiskRule && validRiskRules.includes(rawRiskRule)
+    ? rawRiskRule as 'max_changes_risk' | 'max_issues_risk' | 'explicit'
+    : undefined;
+  
   const metaConfig: MetaConfig = {
     required: metaRaw.required as string[] | undefined,
-    risk_rule: metaRaw.risk_rule as 'max_changes_risk' | 'max_issues_risk' | 'explicit' | undefined,
+    risk_rule: validatedRiskRule,
   };
 
   return {

package/src/modules/runner.ts

@@ -80,9 +80,13 @@ function repairEnvelope(
   if (!meta.risk) {
     meta.risk = aggregateRisk(data, riskRule);
   }
-  // Trim whitespace only (lossless), do NOT invent new values
+  // Trim whitespace only (lossless), validate is valid RiskLevel
   if (typeof meta.risk === 'string') {
-    meta.risk = meta.risk.trim().toLowerCase();
+    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

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