monomind 1.16.6 → 1.16.8

package/packages/@monomind/cli/.claude/helpers/hook-handler.cjs

@@ -0,0 +1,400 @@
+#!/usr/bin/env node
+/**
+ * Monomind Hook Handler (Cross-Platform)
+ * Dispatches hook events to the appropriate helper modules.
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+const helpersDir = __dirname;
+const CWD = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+const telemetry = require('./utils/telemetry.cjs');
+const monograph = require('./utils/monograph.cjs');
+const microAgents = require('./utils/micro-agents.cjs');
+
+const {
+  _recordRecentEdit, _getRecentEdits, _recordToolCall,
+  _getBudgetStatus, _recordHookLatency, _recordDecisionMarkers,
+} = telemetry;
+
+const {
+  _requireMonograph, _openMonographDb,
+  getMonographSuggestions, getMonographNeighbors,
+  _recordGraphTelemetry, _injectCompactGraphMap,
+  _findAffectedTests, _maybeRebuildMonograph,
+} = monograph;
+
+const {
+  safeRequire,
+  _triggerExtractYamlValue, _triggerFinalize, _triggerExtractFromFrontmatter,
+  _triggerCollectMdFiles, _triggerBuildIndex, scanMicroAgentTriggers,
+  _buildKnowledgeSearchFn, _autoIndexKnowledge,
+} = microAgents;
+
+// ── LearningService module-level singleton ─────────────────────────────────────
+// Singleton contract: one LearningService instance is created per hook-handler
+// process. initialize() opens the SQLite DB; consolidate() is called at
+// session-end. Hoisting to module scope ensures the DB is not reopened on every
+// session-end invocation (which would create a fresh in-memory-only instance
+// each time, discarding any state accumulated during the session).
+//
+// We cache the Promise (not the resolved value) so that concurrent callers all
+// await the same initialization. Caching only the resolved value allowed two
+// concurrent callers to both enter the `if (!_learningService)` branch and
+// construct separate LearningService instances, leaving an orphaned DB handle.
+var _learningServicePromise = null;
+async function getLearningService() {
+  if (!_learningServicePromise) {
+    _learningServicePromise = (async function() {
+      try {
+        var lsMod = await import('file://' + path.join(__dirname, 'learning-service.mjs'));
+        var LearningService = lsMod.LearningService || (lsMod.default && lsMod.default.LearningService);
+        if (!LearningService) return null;
+        var svc = new LearningService();
+        if (typeof svc.initialize === 'function') await svc.initialize();
+        return svc;
+      } catch (e) {
+        _learningServicePromise = null; // allow retry on error
+        return null;
+      }
+    })();
+  }
+  return _learningServicePromise;
+}
+
+
+const router = safeRequire(path.join(helpersDir, 'router.cjs'));
+const session = safeRequire(path.join(helpersDir, 'session.cjs'));
+const memory = safeRequire(path.join(helpersDir, 'memory.cjs'));
+const intelligence = safeRequire(path.join(helpersDir, 'intelligence.cjs'));
+
+// Module-level reference to @monomind/hooks — populated at session-restore,
+// then used by pre-task / post-task to bridge into the hook registry (Tasks 26, 39).
+let _hooksModule = null;
+
+// ── Intelligence timeout protection (fixes #1530, #1531) ───────────────────
+var INTELLIGENCE_TIMEOUT_MS = 1500;
+function runWithTimeout(fn, label) {
+  return new Promise(function(resolve) {
+    var settled = false;
+    var timer = setTimeout(function() {
+      if (!settled) {
+        settled = true;
+        process.stderr.write("[WARN] " + label + " timed out after " + INTELLIGENCE_TIMEOUT_MS + "ms, skipping\n");
+        resolve(null);
+      }
+    }, INTELLIGENCE_TIMEOUT_MS);
+    Promise.resolve().then(fn).then(
+      function(result) { if (!settled) { settled = true; clearTimeout(timer); resolve(result); } },
+      function()       { if (!settled) { settled = true; clearTimeout(timer); resolve(null); } }
+    );
+  });
+}
+
+
+const [,, command, ...args] = process.argv;
+
+// Read stdin — Claude Code sends hook data as JSON via stdin
+// Uses a timeout to prevent hanging when stdin is in an ambiguous state
+// (not TTY, not a proper pipe) which happens with Claude Code hook invocations.
+// Hard cap at 1 MiB: a legitimate hook payload (tool name + input) is at most
+// a few KB; anything larger is either a bug or an adversarial OOM attempt.
+const MAX_STDIN_BYTES = 1 * 1024 * 1024; // 1 MiB
+async function readStdin() {
+  if (process.stdin.isTTY) return '';
+  return new Promise((resolve) => {
+    let data = '';
+    let byteCount = 0;
+    let truncated = false;
+    const timer = setTimeout(() => {
+      process.stdin.removeAllListeners();
+      process.stdin.pause();
+      resolve(data);
+    }, 500);
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      if (truncated) return;
+      byteCount += Buffer.byteLength(chunk, 'utf8');
+      if (byteCount > MAX_STDIN_BYTES) {
+        truncated = true;
+        process.stdin.pause();
+        clearTimeout(timer);
+        resolve(''); // discard oversized input to prevent OOM
+        return;
+      }
+      data += chunk;
+    });
+    process.stdin.on('end', () => { clearTimeout(timer); resolve(data); });
+    process.stdin.on('error', () => { clearTimeout(timer); resolve(data); });
+    process.stdin.resume();
+  });
+}
+
+async function main() {
+  // Global safety timeout: hooks must NEVER hang (#1530, #1531)
+  var safetyTimer = setTimeout(function() {
+    process.stderr.write("[WARN] Hook handler global timeout (5s), forcing exit\n");
+    process.exit(0);
+  }, 5000);
+  safetyTimer.unref();
+
+  let stdinData = '';
+  try { stdinData = await readStdin(); } catch (e) { /* ignore stdin errors */ }
+
+  let hookInput = {};
+  if (stdinData.trim()) {
+    try {
+      const parsed = JSON.parse(stdinData);
+      if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        hookInput = parsed;
+      }
+    } catch (e) { /* ignore parse errors */ }
+  }
+
+  // Merge stdin data into prompt resolution: prefer stdin fields, then env vars.
+  // NEVER fall back to argv args — shell glob expansion of braces in bash output
+  // creates junk files (#1342). Use env vars or stdin only.
+  // Normalize snake_case/camelCase: Claude Code sends tool_input/tool_name (snake_case)
+  var toolInput = hookInput.toolInput || hookInput.tool_input || {};
+  var toolName = hookInput.toolName || hookInput.tool_name || '';
+
+  var prompt = hookInput.prompt || hookInput.command
+    || (typeof toolInput === 'string' ? toolInput : (toolInput.command || toolInput.prompt || ''))
+    || process.env.PROMPT || process.env.TOOL_INPUT_command || '';
+
+  // Detect prompts that are predefined single-action commands that don't
+  // need agent routing or skill suggestions — invoking those adds token
+  // overhead without any benefit.
+  function isSimpleCommand(p) {
+    if (typeof p !== 'string') return false;
+    var s = p.trim();
+    // Slash commands: /ts, /list-agents, /commit, /help, /use-agent etc.
+    if (/^\/[a-z0-9_-]+(\s|$)/i.test(s)) return true;
+    // Short single-word operator tokens (toggle, list, status)
+    if (/^(ts|ls|ps|pwd|help|clear|exit|quit|status|toggle|refresh)$/i.test(s)) return true;
+    // Already-resolved command messages (Claude Code sends hook with command-name context)
+    var cmdName = hookInput.commandName || hookInput.command_name || '';
+    if (cmdName && cmdName.length > 0) return true;
+    return false;
+  }
+
+// Build shared hook context — passed to extracted handler modules so they
+// don't need to capture main()-scoped or module-scoped variables via closure.
+var hCtx = {
+  hookInput: hookInput,
+  toolInput: toolInput,
+  toolName: toolName,
+  prompt: prompt,
+  args: args,
+  CWD: CWD,
+  session: session,
+  router: router,
+  intelligence: intelligence,
+  getLearningService: getLearningService,
+  isSimpleCommand: isSimpleCommand,
+  // Module-level singleton (populated by session-restore handler)
+  get _hooksModule() { return _hooksModule; },
+  set _hooksModule(v) { _hooksModule = v; },
+  // Utility functions
+  _recordRecentEdit: _recordRecentEdit,
+  _getRecentEdits: _getRecentEdits,
+  _findAffectedTests: _findAffectedTests,
+  _recordHookLatency: _recordHookLatency,
+  _getBudgetStatus: _getBudgetStatus,
+  _injectCompactGraphMap: _injectCompactGraphMap,
+  _maybeRebuildMonograph: _maybeRebuildMonograph,
+  _buildKnowledgeSearchFn: _buildKnowledgeSearchFn,
+  getMonographSuggestions: getMonographSuggestions,
+  getMonographNeighbors: getMonographNeighbors,
+  runWithTimeout: runWithTimeout,
+  safeRequire: safeRequire,
+  scanMicroAgentTriggers: scanMicroAgentTriggers,
+  _recordGraphTelemetry: _recordGraphTelemetry,
+  _recordDecisionMarkers: _recordDecisionMarkers,
+  _recordToolCall: _recordToolCall,
+  _openMonographDb: _openMonographDb,
+  _requireMonograph: _requireMonograph,
+  _triggerExtractYamlValue: _triggerExtractYamlValue,
+  _triggerFinalize: _triggerFinalize,
+  _triggerExtractFromFrontmatter: _triggerExtractFromFrontmatter,
+  _triggerCollectMdFiles: _triggerCollectMdFiles,
+  _triggerBuildIndex: _triggerBuildIndex,
+  _autoIndexKnowledge: _autoIndexKnowledge,
+  helpersDir: helpersDir,
+  fs: fs,
+  path: path,
+};
+
+const handlers = {
+  'route': async () => {
+    const h = require('./handlers/route-handler.cjs');
+    await h.handle(hCtx);
+  },
+
+  'post-edit': async () => {
+    const h = require('./handlers/edit-handler.cjs');
+    await h.handle(hCtx);
+  },
+
+
+  'session-restore': async () => {
+    const h = require('./handlers/session-restore-handler.cjs');
+    await h.handleRestore(hCtx);
+  },
+
+
+  'session-end': async () => {
+    const h = require('./handlers/session-handler.cjs');
+    await h.handleEnd(hCtx);
+  },
+
+
+  'pre-task': async () => {
+    const h = require('./handlers/task-handler.cjs');
+    await h.handlePreTask(hCtx);
+  },
+
+
+  'post-task': async () => {
+    const h = require('./handlers/task-handler.cjs');
+    await h.handlePostTask(hCtx);
+  },
+
+
+  'compact-manual': async () => {
+    const h = require('./handlers/compact-handler.cjs');
+    await h.handle(hCtx, 'manual');
+  },
+
+  'compact-auto': async () => {
+    const h = require('./handlers/compact-handler.cjs');
+    await h.handle(hCtx, 'auto');
+  },
+
+  'agent-start': () => {
+    const h = require('./handlers/agent-start-handler.cjs');
+    h.handle(hCtx);
+  },
+
+  'adr-draft': () => {
+    const h = require('./handlers/adr-draft-handler.cjs');
+    h.handle(hCtx);
+  },
+
+  'pre-bash': () => {
+    // Record bash grep/find calls for graph-vs-grep telemetry
+    var cmd = (hCtx.toolInput && (hCtx.toolInput.command || hCtx.toolInput.cmd)) || '';
+    if (/\bgrep\b/.test(cmd)) _recordGraphTelemetry('bash_grep_call');
+    else if (/\bfind\b/.test(cmd)) _recordGraphTelemetry('bash_find_call');
+    // Enforcement gate: destructive operations
+    var gates = require('./handlers/gates-handler.cjs');
+    gates.handlePreBash(hCtx);
+  },
+
+  'pre-write': () => {
+    // Enforcement gate: secrets detection before Write/Edit/MultiEdit lands on disk
+    var gates = require('./handlers/gates-handler.cjs');
+    gates.handlePreWrite(hCtx);
+  },
+
+  'pre-search': () => {
+    // Record Grep/Glob tool calls for graph-vs-grep telemetry
+    var tool = hCtx.toolName || '';
+    if (tool === 'Grep') _recordGraphTelemetry('grep_call');
+    else if (tool === 'Glob') _recordGraphTelemetry('glob_call');
+
+    // Monograph symbol hint: when the Grep pattern looks like a plain symbol name
+    // (no regex metacharacters), look it up directly in the graph index and print
+    // the file:line so the LLM may skip or narrow the Grep.
+    // Session-level cache prevents repeated identical DB lookups across Grep bursts.
+    try {
+      var grepPattern = (typeof toolInput === 'object' && toolInput !== null)
+        ? (toolInput.pattern || toolInput.query || '')
+        : '';
+      // Only attempt lookup for clean identifiers — skip regexes and paths
+      var isCleanSymbol = grepPattern.length >= 3 && grepPattern.length <= 80
+        && /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(grepPattern);
+      if (isCleanSymbol) {
+        if (!hCtx._preSearchCache) hCtx._preSearchCache = {};
+        var cacheKey = 'presearch:' + grepPattern;
+        if (!(cacheKey in hCtx._preSearchCache)) {
+          var db = _openMonographDb();
+          var hint = null;
+          if (db) {
+            try {
+              var row = db.prepare(
+                'SELECT n.name, n.label, n.file_path, n.start_line FROM nodes n ' +
+                'WHERE n.name = ? AND n.label NOT IN (\'Concept\',\'Community\',\'Folder\') ' +
+                'AND n.file_path IS NOT NULL LIMIT 1'
+              ).get(grepPattern);
+              if (row) {
+                hint = row.file_path + (row.start_line != null ? ':' + row.start_line : '');
+              }
+            } catch (e) { /* non-fatal */ }
+          }
+          hCtx._preSearchCache[cacheKey] = hint;
+        }
+        var cachedHint = hCtx._preSearchCache[cacheKey];
+        if (cachedHint) {
+          // Use the correct MCP tool name — monograph_context does not exist;
+          // the callable tool is mcp__monomind__monograph_query
+          console.log('[MONOGRAPH_HINT] ' + grepPattern + ' found at ' + cachedHint + ' — use mcp__monomind__monograph_query instead of Grep for better results');
+        }
+      }
+    } catch (e) { /* non-fatal — telemetry always proceeds */ }
+  },
+
+  'post-graph-tool': () => {
+    // Record monograph MCP tool calls as graph wins
+    _recordGraphTelemetry('monograph_call');
+  },
+
+  'graph-status': () => {
+    const h = require('./handlers/graph-status-handler.cjs');
+    h.handle(hCtx);
+  },
+
+  'budget-status': () => {
+    const h = require('./handlers/budget-status-handler.cjs');
+    h.handle(hCtx);
+  },
+
+  'loops-status': () => {
+    const h = require('./handlers/loops-status-handler.cjs');
+    h.handle(hCtx);
+  },
+
+  'status': () => {
+    console.log('[OK] Status check');
+  },
+
+  'stats': async () => {
+    const h = require('./handlers/stats-handler.cjs');
+    await h.handle(hCtx);
+  },
+};
+
+if (command && handlers[command]) {
+    var _hookStart = Date.now();
+    try {
+      await Promise.resolve(handlers[command]());
+    } catch (e) {
+      console.log('[WARN] Hook ' + command + ' encountered an error: ' + e.message);
+    } finally {
+      try { _recordHookLatency(command, Date.now() - _hookStart); } catch (_) {}
+    }
+  } else if (command) {
+    console.log('[OK] Hook: ' + command);
+  } else {
+    console.log('Usage: hook-handler.cjs <route|pre-bash|pre-search|post-edit|post-read|post-graph-tool|session-restore|session-end|pre-task|post-task|compact-manual|compact-auto|status|stats>');
+  }
+}
+
+main().catch(function(e) {
+  console.log('[WARN] Hook handler error: ' + e.message);
+}).finally(function() {
+  // Use process.exitCode if a gate set it (exit 2 = block), otherwise clean exit
+  process.exit(process.exitCode || 0);
+});

package/packages/@monomind/cli/.claude/helpers/intelligence.cjs

@@ -0,0 +1,164 @@
+'use strict';
+/**
+ * Intelligence context module for hook-handler.cjs
+ * Provides context injection, trajectory logging, feedback recording,
+ * edit tracking, consolidation, and stats.
+ *
+ * Data directory: $CLAUDE_PROJECT_DIR/.monomind/data/
+ *   auto-memory-store.json      — persisted memory entries
+ *   ranked-context.json         — ranked view written by init()
+ *   pending-insights.jsonl      — pending entries to consolidate
+ *   intelligence-outcomes.jsonl — feedback records
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+// Resolve base dir at require-time so tests can inject CLAUDE_PROJECT_DIR
+// per fresh require() call.
+const CWD = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const DATA_DIR = path.join(CWD, '.monomind', 'data');
+const STORE_FILE = path.join(DATA_DIR, 'auto-memory-store.json');
+const RANKED_FILE = path.join(DATA_DIR, 'ranked-context.json');
+const PENDING_FILE = path.join(DATA_DIR, 'pending-insights.jsonl');
+const OUTCOMES_FILE = path.join(DATA_DIR, 'intelligence-outcomes.jsonl');
+
+const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10 MiB guard
+const RING_BUFFER_MAX = 50;
+
+var _entries = [];        // deduplicated memory entries loaded from store
+var _recentEdits = [];    // ring buffer of recently edited paths
+
+function ensureDataDir() {
+  try { fs.mkdirSync(DATA_DIR, { recursive: true }); } catch (_) {}
+}
+
+function safeReadJson(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    var st = fs.statSync(filePath);
+    if (st.size > MAX_FILE_SIZE) return null;
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  } catch (_) { return null; }
+}
+
+function safeReadLines(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return [];
+    var st = fs.statSync(filePath);
+    if (st.size > MAX_FILE_SIZE) return [];
+    return fs.readFileSync(filePath, 'utf-8')
+      .split('\n')
+      .filter(function(l) { return l.trim().length > 0; });
+  } catch (_) { return []; }
+}
+
+// ── init ───────────────────────────────────────────────────────────────────────
+
+function init() {
+  ensureDataDir();
+
+  // Load entries from store, deduplicate by id
+  var raw = safeReadJson(STORE_FILE);
+  var arr = Array.isArray(raw) ? raw : [];
+  var seen = new Set();
+  _entries = arr.filter(function(e) {
+    var key = e && e.id ? String(e.id) : null;
+    if (!key) return true;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+
+  // Write ranked-context.json (sorted by confidence desc) with version envelope
+  var ranked = _entries.slice().sort(function(a, b) {
+    return (b.confidence || 0) - (a.confidence || 0);
+  });
+  try {
+    fs.writeFileSync(RANKED_FILE, JSON.stringify({ version: 1, entries: ranked }, null, 2), 'utf-8');
+  } catch (_) {}
+
+  return { nodes: _entries.length, edges: 0 };
+}
+
+// ── getContext ─────────────────────────────────────────────────────────────────
+
+function getContext(prompt) {
+  if (!prompt || typeof prompt !== 'string' || prompt.trim() === '') return null;
+  if (_entries.length === 0) return null;
+
+  var promptWords = prompt.toLowerCase().split(/\W+/).filter(Boolean);
+  var promptSet = new Set(promptWords);
+
+  var matches = _entries.filter(function(e) {
+    var content = ((e.content || '') + ' ' + (e.summary || '')).toLowerCase();
+    var words = content.split(/\W+/).filter(Boolean);
+    return words.some(function(w) { return promptSet.has(w); });
+  });
+
+  if (matches.length === 0) return null;
+
+  var top = matches[0];
+  return '[INTELLIGENCE] ' + (top.summary || top.content || top.id || 'context match');
+}
+
+// ── recordEdit ────────────────────────────────────────────────────────────────
+
+function recordEdit(filePath) {
+  _recentEdits.push({ path: String(filePath || ''), ts: Date.now() });
+  if (_recentEdits.length > RING_BUFFER_MAX) {
+    _recentEdits = _recentEdits.slice(-RING_BUFFER_MAX);
+  }
+}
+
+// ── consolidate ───────────────────────────────────────────────────────────────
+
+function consolidate() {
+  ensureDataDir();
+  var lines = safeReadLines(PENDING_FILE);
+  var count = lines.length;
+
+  // Clear the pending file
+  try { fs.writeFileSync(PENDING_FILE, '', 'utf-8'); } catch (_) {}
+
+  return { entries: count, edges: 0, newEntries: count };
+}
+
+// ── feedback ──────────────────────────────────────────────────────────────────
+
+function feedback(success) {
+  ensureDataDir();
+  var record = JSON.stringify({
+    ts: Date.now(),
+    success: !!success,
+    context: null,
+    recentEdits: _recentEdits.slice(),
+  }) + '\n';
+  try { fs.appendFileSync(OUTCOMES_FILE, record, 'utf-8'); } catch (_) {}
+}
+
+// ── stats ─────────────────────────────────────────────────────────────────────
+
+function stats(asJson) {
+  var result = {
+    entries: _entries.length,
+    recentEdits: _recentEdits.length,
+    pending: safeReadLines(PENDING_FILE).length,
+  };
+  if (asJson) return JSON.stringify(result);
+  return result;
+}
+
+// ── legacy ────────────────────────────────────────────────────────────────────
+
+function logTrajectory(step) {
+  // no-op stub for backward compatibility
+  void step;
+}
+
+function storePattern(pattern) {
+  // no-op stub for backward compatibility
+  void pattern;
+}
+
+module.exports = { init, getContext, recordEdit, consolidate, feedback, stats, logTrajectory, storePattern };

package/packages/@monomind/cli/.claude/helpers/learning-service.mjs

@@ -0,0 +1,60 @@
+/**
+ * LearningService — session-scoped learning consolidation
+ * Used as a module-level singleton by hook-handler.cjs (getLearningService()).
+ *
+ * Contract:
+ *   new LearningService()
+ *   await svc.initialize()   — open DB / load state
+ *   await svc.consolidate()  — flush accumulated learnings to persistent store
+ */
+
+import path from 'path';
+import fs from 'fs/promises';
+import { existsSync, mkdirSync } from 'fs';
+
+const CWD = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const LEARN_DIR = path.join(CWD, '.monomind', 'learning');
+const LEARN_FILE = path.join(LEARN_DIR, 'session-learnings.json');
+
+export class LearningService {
+  constructor() {
+    this._entries = [];
+    this._initialized = false;
+  }
+
+  async initialize() {
+    try {
+      mkdirSync(LEARN_DIR, { recursive: true });
+      if (existsSync(LEARN_FILE)) {
+        const raw = await fs.readFile(LEARN_FILE, 'utf-8');
+        const data = JSON.parse(raw);
+        this._entries = Array.isArray(data) ? data : [];
+      }
+    } catch (_) {
+      this._entries = [];
+    }
+    this._initialized = true;
+  }
+
+  record(entry) {
+    if (!this._initialized) return;
+    this._entries.push(Object.assign({ ts: new Date().toISOString() }, entry));
+  }
+
+  async consolidate() {
+    if (!this._initialized || this._entries.length === 0) return;
+    try {
+      mkdirSync(LEARN_DIR, { recursive: true });
+      // Keep last 1000 entries
+      const trimmed = this._entries.slice(-1000);
+      await fs.writeFile(LEARN_FILE, JSON.stringify(trimmed, null, 2), 'utf-8');
+      this._entries = trimmed;
+    } catch (_) {}
+  }
+
+  getEntries() {
+    return this._entries.slice();
+  }
+}
+
+export default { LearningService };