vektor-slipstream 1.2.2 → 1.3.0

package/index.js

@@ -0,0 +1,480 @@
+/**
+ * cloak/index.js
+ * MCP server — exposes all 4 CLOAK tools to Claude Code.
+ * Wires cortex, axon, cerebellum, and token into a single MCP endpoint.
+ *
+ * Usage:
+ *   node index.js                    # stdio MCP server (Claude Code)
+ *   CLOAK_HTTP=1 node index.js       # HTTP MCP server (port 3747)
+ *
+ * Claude Code .claude/settings.json:
+ * {
+ *   "mcpServers": {
+ *     "cloak": {
+ *       "command": "node",
+ *       "args": ["/path/to/cloak/index.js"],
+ *       "env": {
+ *         "VEKTOR_LICENCE_KEY": "your-key",
+ *         "CLOAK_PROJECT_PATH": "/path/to/your/project"
+ *       }
+ *     }
+ *   },
+ *   "hooks": {
+ *     "SessionStart": [{ "type": "command", "command": "node /path/to/cloak/index.js --hook SessionStart" }],
+ *     "Stop":         [{ "type": "command", "command": "node /path/to/cloak/index.js --hook Stop" }],
+ *     "PreToolUse":   [{ "type": "command", "command": "node /path/to/cloak/index.js --hook PreToolUse" }],
+ *     "PostToolUse":  [{ "type": "command", "command": "node /path/to/cloak/index.js --hook PostToolUse" }]
+ *   }
+ * }
+ */
+
+'use strict';
+
+const { createMemory }  = require('vektor-slipstream');
+const cortex            = require('./cortex');
+const axon              = require('./axon');
+const cerebellum        = require('./cerebellum');
+const token             = require('./token');
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+const CONFIG = {
+  projectPath : process.env.CLOAK_PROJECT_PATH || process.cwd(),
+  licenceKey  : process.env.VEKTOR_LICENCE_KEY || '',
+  agentId     : process.env.CLOAK_AGENT_ID || 'cloak-agent',
+  httpPort    : parseInt(process.env.CLOAK_PORT || '3747'),
+  debug       : process.env.CLOAK_DEBUG === '1',
+};
+
+// ---------------------------------------------------------------------------
+// Vektor memory instance — singleton, shared across all tools
+// ---------------------------------------------------------------------------
+let _memory = null;
+
+async function getMemory() {
+  if (_memory) return _memory;
+  _memory = await createMemory({
+    agentId    : CONFIG.agentId,
+    licenceKey : CONFIG.licenceKey,
+  });
+  return _memory;
+}
+
+// ---------------------------------------------------------------------------
+// MCP Tool definitions
+// ---------------------------------------------------------------------------
+const TOOLS = [
+  {
+    name       : 'cloak_cortex',
+    description: 'Scan project files and build a token-aware anatomy index in Vektor entity graph. Call once on project init and after major refactors. Returns file count, total tokens, and anatomy summary.',
+    inputSchema: {
+      type      : 'object',
+      properties: {
+        force: {
+          type       : 'boolean',
+          description: 'Re-scan all files even if unchanged since last scan. Default: false.',
+          default    : false,
+        },
+        projectPath: {
+          type       : 'string',
+          description: 'Override project path. Defaults to CLOAK_PROJECT_PATH env var.',
+        },
+      },
+    },
+  },
+  {
+    name       : 'cloak_axon',
+    description: 'Session boundary handler. Call on session start to load last context, call on session stop to save a MemCell summary. Also accepts hook payloads from Claude Code.',
+    inputSchema: {
+      type      : 'object',
+      properties: {
+        action: {
+          type       : 'string',
+          enum       : ['start', 'stop'],
+          description: 'start: load last session context and seed new session. stop: save session MemCell summary to memory.',
+        },
+        narrative: {
+          type       : 'string',
+          description: 'Optional: brief description of what this session accomplished and why. Stored as session intent in the MemCell. Example: "Refactored auth module to fix null reference bug on empty DB responses."',
+        },
+      },
+      required: ['action'],
+    },
+  },
+  {
+    name       : 'cloak_cerebellum',
+    description: 'Pre-write enforcer. Check a write against known error patterns before executing. Also records new errors and Do-Not-Repeat rules. Auto-detects [RESOLVED_BY] relationships.',
+    inputSchema: {
+      type      : 'object',
+      properties: {
+        action: {
+          type : 'string',
+          enum : ['check', 'record_error', 'add_dnr'],
+          description: 'check: check content before write. record_error: store a new error pattern. add_dnr: add a Do-Not-Repeat rule.',
+        },
+        content: {
+          type       : 'string',
+          description: 'Content to check or write (required for check action).',
+        },
+        filePath: {
+          type       : 'string',
+          description: 'File path being written.',
+        },
+        description: {
+          type       : 'string',
+          description: 'Error description (required for record_error).',
+        },
+        errorType: {
+          type       : 'string',
+          description: 'Error category e.g. null_reference, type_mismatch.',
+        },
+        fix: {
+          type       : 'string',
+          description: 'What fixed the error (optional).',
+        },
+        severity: {
+          type       : 'string',
+          enum       : ['warn', 'block'],
+          description: 'Warning severity. Default: warn.',
+        },
+        keyword: {
+          type       : 'string',
+          description: 'Trigger keyword for DNR rule (required for add_dnr).',
+        },
+        rule: {
+          type       : 'string',
+          description: 'DNR rule description (required for add_dnr).',
+        },
+        alternative: {
+          type       : 'string',
+          description: 'What to do instead (optional for add_dnr).',
+        },
+      },
+      required: ['action'],
+    },
+  },
+  {
+    name       : 'cloak_token',
+    description: 'Token ledger. Track reads/writes, detect waste patterns, get session summary and historical waste report.',
+    inputSchema: {
+      type      : 'object',
+      properties: {
+        action: {
+          type : 'string',
+          enum : ['summary', 'waste_report'],
+          description: 'summary: get current session token stats. waste_report: get historical waste analysis over N days.',
+        },
+        days: {
+          type       : 'integer',
+          description: 'Lookback days for waste report. Default: 30.',
+          default    : 30,
+        },
+      },
+      required: ['action'],
+    },
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Tool handlers
+// ---------------------------------------------------------------------------
+async function handleTool(name, input) {
+  const memory = await getMemory();
+
+  switch (name) {
+
+    // ── cloak_cortex ────────────────────────────────────────────────────────
+    case 'cloak_cortex': {
+      const result = await cortex.runCortex({
+        projectPath: input.projectPath || CONFIG.projectPath,
+        memory,
+        force: input.force || false,
+      });
+      return {
+        success   : true,
+        scanned   : result.scanned,
+        skipped   : result.skipped,
+        written   : result.written,
+        totalTokens: result.totalTokens,
+        topFiles  : result.anatomy
+          .sort((a,b) => b.tokens - a.tokens)
+          .slice(0, 10)
+          .map(f => `${f.path}: ~${f.tokens}t`),
+        message   : `Anatomy indexed: ${result.written} new nodes, ${result.skipped} unchanged, ~${result.totalTokens} total tokens`,
+      };
+    }
+
+    // ── cloak_axon ──────────────────────────────────────────────────────────
+    case 'cloak_axon': {
+      switch (input.action) {
+
+        case 'start': {
+          const result = await axon.onSessionStart({
+            projectPath: CONFIG.projectPath,
+            memory,
+          });
+          // Start token ledger in sync
+          token.startSession(result.sessionId);
+          return {
+            success     : true,
+            sessionId   : result.sessionId,
+            hasLastContext: !!result.lastContext,
+            lastContext : result.lastContext || null,
+            message     : result.lastContext
+              ? `Session ${result.sessionId} started. Last session context loaded.`
+              : `Session ${result.sessionId} started. No prior context (first run or new project).`,
+          };
+        }
+
+        case 'stop': {
+          // Get token summary before stopping session
+          const tokenSummary = token.getSessionSummary();
+          const tokenCount   = tokenSummary?.totalTokens || 0;
+
+          // Write token ledger node to Vektor if there was activity
+          if (tokenSummary && tokenCount > 0) {
+            const tokenNode = token.buildTokenNode(tokenSummary);
+            try { await memory.remember(tokenNode); } catch {}
+          }
+
+          const result = await axon.onSessionStop({
+            memory,
+            tokenCount,
+            narrative: input.narrative || '',
+          });
+          return {
+            success   : true,
+            sessionId : result.sessionId,
+            written   : result.written,
+            events    : result.events,
+            duration  : `${result.duration}min`,
+            tokenCount,
+            wasteRate : tokenSummary?.wasteRate || '0%',
+            message   : result.written
+              ? `Session MemCell written. ${result.events} events, ~${tokenCount} tokens, ${tokenSummary?.wasteRate || '0%'} waste.`
+              : `Session ended but MemCell write failed.`,
+          };
+        }
+
+        case 'hook': {
+          if (!input.hookPayload) return { success: false, error: 'hookPayload required for hook action' };
+          const result = await axon.handleHookPayload({
+            payload    : input.hookPayload,
+            memory,
+            projectPath: CONFIG.projectPath,
+            tokenCount : token.getSessionSummary()?.totalTokens || 0,
+          });
+          return { success: true, result };
+        }
+
+        default:
+          return { success: false, error: `Unknown axon action: ${input.action}` };
+      }
+    }
+
+    // ── cloak_cerebellum ────────────────────────────────────────────────────
+    case 'cloak_cerebellum': {
+      switch (input.action) {
+
+        case 'check': {
+          if (!input.content) return { success: false, error: 'content required for check action' };
+          const result = await cerebellum.checkWrite({
+            content : input.content,
+            filePath: input.filePath,
+            memory,
+          });
+          return {
+            success     : true,
+            warnings    : result.warnings,
+            hasBlockers : result.hasBlockers,
+            shouldProceed: result.shouldProceed,
+            message     : result.warnings.length > 0
+              ? `${result.warnings.length} pattern(s) matched. Review warnings before proceeding.`
+              : 'No known error patterns matched. Safe to proceed.',
+          };
+        }
+
+        case 'record_error': {
+          if (!input.description) return { success: false, error: 'description required for record_error' };
+          const result = await cerebellum.recordError({
+            description: input.description,
+            filePath   : input.filePath,
+            errorType  : input.errorType,
+            fix        : input.fix,
+            severity   : input.severity,
+            memory,
+          });
+          return { success: result.written, message: result.written ? 'Error pattern recorded.' : result.error };
+        }
+
+        case 'add_dnr': {
+          if (!input.keyword || !input.rule) return { success: false, error: 'keyword and rule required for add_dnr' };
+          const result = await cerebellum.addDNRRule({
+            keyword    : input.keyword,
+            rule       : input.rule,
+            alternative: input.alternative,
+            memory,
+          });
+          return { success: result.written, message: result.written ? `DNR rule added for keyword: ${input.keyword}` : result.error };
+        }
+
+        case 'hook': {
+          if (!input.hookPayload) return { success: false, error: 'hookPayload required for hook action' };
+          const result = await cerebellum.handleHookPayload({ payload: input.hookPayload, memory });
+          return { success: true, result };
+        }
+
+        default:
+          return { success: false, error: `Unknown cerebellum action: ${input.action}` };
+      }
+    }
+
+    // ── cloak_token ─────────────────────────────────────────────────────────
+    case 'cloak_token': {
+      switch (input.action) {
+
+        case 'summary': {
+          const summary = token.getSessionSummary();
+          if (!summary) return { success: false, error: 'No active session. Call cloak_axon start first.' };
+          return { success: true, ...summary };
+        }
+
+        case 'waste_report': {
+          const report = await token.getWasteReport({ memory, days: input.days || 30 });
+          return { success: true, ...report };
+        }
+
+        case 'hook': {
+          if (!input.hookPayload) return { success: false, error: 'hookPayload required for hook action' };
+          token.handleHookPayload({
+            payload  : input.hookPayload,
+            sessionId: axon._sessionLog.sessionId,
+          });
+          return { success: true };
+        }
+
+        default:
+          return { success: false, error: `Unknown token action: ${input.action}` };
+      }
+    }
+
+    default:
+      return { success: false, error: `Unknown tool: ${name}` };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Hook-only mode — called from Claude Code hook scripts (not MCP)
+// Usage: node index.js --hook PreToolUse
+// Claude Code pipes JSON payload via stdin
+// ---------------------------------------------------------------------------
+async function runHookMode(hookName) {
+  let payload = {};
+
+  try {
+    const stdin = fs.readFileSync('/dev/stdin', 'utf8');
+    if (stdin.trim()) payload = JSON.parse(stdin);
+  } catch {
+    // stdin not available or not JSON — use empty payload
+  }
+
+  payload.hook_event_name = hookName;
+
+  const memory = await getMemory();
+
+  // Route to all relevant handlers
+  await Promise.allSettled([
+    axon.handleHookPayload({ payload, memory, projectPath: CONFIG.projectPath,
+      tokenCount: token.getSessionSummary()?.totalTokens || 0 }),
+    cerebellum.handleHookPayload({ payload, memory }),
+    Promise.resolve(token.handleHookPayload({ payload,
+      sessionId: axon._sessionLog.sessionId })),
+  ]);
+
+  process.exit(0);
+}
+
+// ---------------------------------------------------------------------------
+// MCP stdio server (standard Claude Code MCP protocol)
+// ---------------------------------------------------------------------------
+const readline = require('readline');
+const fs       = require('fs');
+
+function sendResponse(response) {
+  process.stdout.write(JSON.stringify(response) + '\n');
+}
+
+async function runMCPServer() {
+  const rl = readline.createInterface({ input: process.stdin, terminal: false });
+
+  rl.on('line', async line => {
+    let request;
+    try { request = JSON.parse(line); } catch { return; }
+
+    const { id, method, params } = request;
+
+    try {
+      switch (method) {
+
+        case 'initialize':
+          sendResponse({
+            jsonrpc: '2.0', id,
+            result: {
+              protocolVersion: '2024-11-05',
+              capabilities   : { tools: {} },
+              serverInfo     : { name: 'cloak', version: '1.0.0' },
+            },
+          });
+          break;
+
+        case 'tools/list':
+          sendResponse({ jsonrpc: '2.0', id, result: { tools: TOOLS } });
+          break;
+
+        case 'tools/call': {
+          const { name, arguments: args } = params;
+          const result = await handleTool(name, args || {});
+          sendResponse({
+            jsonrpc: '2.0', id,
+            result: {
+              content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            },
+          });
+          break;
+        }
+
+        default:
+          sendResponse({
+            jsonrpc: '2.0', id,
+            error: { code: -32601, message: `Method not found: ${method}` },
+          });
+      }
+    } catch (err) {
+      if (CONFIG.debug) console.error('[cloak]', err);
+      sendResponse({
+        jsonrpc: '2.0', id,
+        error: { code: -32603, message: err.message },
+      });
+    }
+  });
+
+  process.stderr.write('[cloak] MCP server ready\n');
+}
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+const args = process.argv.slice(2);
+
+if (args[0] === '--hook' && args[1]) {
+  runHookMode(args[1]).catch(err => {
+    process.stderr.write(`[cloak] Hook error: ${err.message}\n`);
+    process.exit(1);
+  });
+} else {
+  runMCPServer().catch(err => {
+    process.stderr.write(`[cloak] Fatal: ${err.message}\n`);
+    process.exit(1);
+  });
+}