@monoes/monomindcli 2.16.1 → 2.16.3

package/.claude/helpers/handlers/pick-core.cjs

@@ -0,0 +1,445 @@
+'use strict';
+// Agent/skill pick delivery, route records and pick adherence.
+//
+// Used by route-handler.cjs (UserPromptSubmit: decide + [PICK] line + route
+// record), hook-handler.cjs 'pre-agent' (PreToolUse Task|Agent: adherence),
+// capture/session handlers (outcome joins) and session-restore-handler.cjs
+// (skill-registry refresh). Agents come only from .monomind/registry.json via
+// jev-picker.cjs: a pick names the agent's frontmatter `name`, which is the
+// value Claude Code's Task tool accepts as subagent_type.
+
+const path = require('path');
+const fs = require('fs');
+const crypto = require('crypto');
+const fsHelpers = require('../utils/fs-helpers.cjs');
+
+var redaction = null;
+try { redaction = require('../redact-secrets.cjs'); } catch (e) { /* preview falls back to no redaction of the cut text */ }
+var pickStats = null;
+try { pickStats = require('../pick-stats.cjs'); } catch (e) { /* no outcome prior: keyword order stands */ }
+var pickRank = null;
+try { pickRank = require('../pick-rank.cjs'); } catch (e) { /* no trivial-prompt check */ }
+
+// A keyword pick needs this score (pick-rank.cjs: idf-weighted BM25 times the
+// share of task words matched) AND a lead of KEYWORD_AGENT_LEAD over the
+// runner-up. Ties and weak overlap print nothing: a wrong pick in Claude's
+// context costs more than none. Tuned on the 40-task pick benchmark: 25/40
+// shown, 23 of them correct.
+var KEYWORD_MIN_AGENT_SCORE = 2;
+var KEYWORD_AGENT_LEAD = 1.5;
+// A keyword skill pick (pick-rank.cjs over the shared skill catalog) needs
+// this score AND a KEYWORD_SKILL_LEAD lead over the runner-up. Calibrated on
+// tests/pick-eval (59 tasks, 514 skills): 34 shown, 31 of them correct (91%).
+var KEYWORD_MIN_SKILL_SCORE = 3;
+var KEYWORD_SKILL_LEAD = 1.25;
+var MAX_CANDIDATES = 5;
+var PREVIEW_CHARS = 120;
+// A prompt with fewer content words ("hi", "thanks", "ok, go ahead") is a
+// reply, not a task: no pick, and the session keeps its earlier route.
+var MIN_PICK_TOKENS = 3;
+var MAX_OUTCOMES_BYTES = 512 * 1024;
+var KEEP_OUTCOMES = 500;
+var MAX_JOIN_BYTES = 2 * 1024 * 1024;
+var MAX_ROUTE_FILE_BYTES = 64 * 1024;
+var ROUTE_FILE_TTL_MS = 7 * 24 * 3600 * 1000;
+// route-outcomes.jsonl is shared by every session of the project: appends,
+// joins and rotation all run under one lock file so a rewrite never drops a
+// line another session appended meanwhile. Held for milliseconds; a lock
+// older than LOCK_STALE_MS belongs to a dead process and is broken.
+var LOCK_WAIT_MS = 1000;
+var LOCK_STALE_MS = 10000;
+
+/** Prompts Claude Code (not the user) submits: notifications, reminder-only
+ *  turns, slash-command expansions and local-command output. */
+function isSystemPrompt(prompt) {
+  if (typeof prompt !== 'string') return true;
+  var s = prompt.trim();
+  if (!s) return true;
+  if (/<task-notification>/i.test(s)) return true;
+  if (/<(command-name|command-message|command-args|local-command-stdout|local-command-stderr)>/i.test(s)) return true;
+  if (/^Caveat: The messages below were generated by the user while running local commands/i.test(s)) return true;
+  return s.replace(/<system-reminder>[\s\S]*?<\/system-reminder>/gi, '').trim() === '';
+}
+
+/** True for a prompt with fewer than MIN_PICK_TOKENS content words
+ *  (pick-rank tokens: stopwords dropped, any script). */
+function isTrivialPrompt(prompt) {
+  if (!pickRank || typeof prompt !== 'string') return false;
+  var text = prompt.replace(/<system-reminder>[\s\S]*?<\/system-reminder>/gi, ' ').slice(0, 2000);
+  return pickRank.tokens(text).length < MIN_PICK_TOKENS;
+}
+
+function promptHash(prompt) {
+  return crypto.createHash('sha256').update(String(prompt || '')).digest('hex').slice(0, 16);
+}
+
+/** First 120 chars, secrets masked BEFORE the cut so a straddling key is whole when matched. */
+function promptPreview(prompt) {
+  var head = String(prompt || '').slice(0, 2000);
+  if (redaction) head = redaction.redactHead(head);
+  return head.replace(/\s+/g, ' ').trim().slice(0, PREVIEW_CHARS);
+}
+
+function normName(name) {
+  return String(name || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+}
+
+/** Registry agents ranked by the jev-picker keyword ranker (keywordRank when it
+ *  exists, else shortlist), re-ordered by the outcome prior from `stats`
+ *  (pick-stats.cjs; each candidate then carries baseScore and prior). Same-name
+ *  duplicates collapse; at most 5 return. */
+function rankAgents(jp, prompt, agents, stats) {
+  if (!jp || !Array.isArray(agents) || agents.length === 0) return [];
+  var ranked = null;
+  try {
+    ranked = typeof jp.keywordRank === 'function'
+      ? jp.keywordRank(prompt, agents, 25)
+      : jp.shortlist(prompt, agents, 25);
+  } catch (e) { return []; }
+  if (!Array.isArray(ranked)) return [];
+  if (stats && pickStats) ranked = pickStats.applyPriors(ranked, stats);
+  var byId = {};
+  agents.forEach(function (a) { byId[a.id] = a; });
+  var out = [];
+  var seen = new Set();
+  for (var i = 0; i < ranked.length && out.length < MAX_CANDIDATES; i++) {
+    var r = ranked[i];
+    var item = r && byId[r.id];
+    if (!item || !Number.isFinite(r.score)) continue;
+    var key = normName(item.name);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    var cand = { id: item.id, name: item.name, score: r.score };
+    if (r.prior !== undefined) { cand.baseScore = r.baseScore; cand.prior = r.prior; }
+    out.push(cand);
+  }
+  return out;
+}
+
+/** Skills of the shared catalog (jev-picker loadSkillCatalog: platform and
+ *  Org skills) ranked by pick-rank's shortlist, which honours `pick: low`;
+ *  zero-overlap entries dropped, at most 5. */
+function rankSkills(jp, prompt, skills) {
+  if (!jp || typeof jp.shortlist !== 'function' || !Array.isArray(skills) || skills.length === 0) return [];
+  var ranked;
+  try { ranked = jp.shortlist(prompt, skills, MAX_CANDIDATES); } catch (e) { return []; }
+  return (Array.isArray(ranked) ? ranked : [])
+    .filter(function (s) { return s && Number.isFinite(s.score) && s.score > 0; })
+    .map(function (s) {
+      return { skill: s.id, invoke: s.invoke || s.id, description: s.description || '', score: s.score, source: s.source };
+    });
+}
+
+/** The top entry when it clears `min` and leads the runner-up by `ratio`. The
+ *  floor is on keyword relevance alone (baseScore when a prior re-ranked). */
+function leads(list, min, ratio) {
+  var top = list && list[0];
+  if (!top || !((top.baseScore !== undefined ? top.baseScore : top.score) >= min)) return null;
+  var second = list[1];
+  if (!second || !(second.score > 0)) return top;
+  return top.score >= second.score * (ratio || 1) && top.score > second.score ? top : null;
+}
+
+/**
+ * The prompt's pick. A Jev agent answer (already past acceptAgent) wins, else a
+ * strong keyword agent; a confident Jev skill answer (including "none fits")
+ * wins, else a strong keyword skill. Agent ids are resolved to registry names.
+ */
+function decide(opts) {
+  var agents = opts.agents || [];
+  var jev = opts.jev || null;
+  var byId = {};
+  agents.forEach(function (a) { byId[a.id] = a; });
+  var out = { agent: null, skill: null, method: 'none', provider: null, confidence: null, candidates: [] };
+  var viaJev = false;
+  var viaKeyword = false;
+
+  if (jev && jev.agent && byId[jev.agent]) {
+    out.agent = { id: jev.agent, name: byId[jev.agent].name };
+    out.confidence = jev.agentConfidence;
+    viaJev = true;
+  } else {
+    var kw = leads(opts.keywordCands, KEYWORD_MIN_AGENT_SCORE, KEYWORD_AGENT_LEAD);
+    if (kw) { out.agent = { id: kw.id, name: kw.name }; viaKeyword = true; }
+  }
+
+  if (jev && jev.skillAnswered) {
+    var js = (jev.skills || [])[0];
+    if (js) out.skill = { skill: js.id, invoke: js.invoke };
+    viaJev = true;
+  } else {
+    var ks = leads(opts.skillMatches, KEYWORD_MIN_SKILL_SCORE, KEYWORD_SKILL_LEAD);
+    if (ks) { out.skill = { skill: ks.skill, invoke: ks.invoke }; viaKeyword = true; }
+  }
+
+  if (jev && Array.isArray(jev.agentRanked) && jev.agentRanked.length > 0) {
+    out.candidates = jev.agentRanked.filter(function (r) { return byId[r.id]; }).slice(0, MAX_CANDIDATES)
+      .map(function (r) { return { name: byId[r.id].name, score: r.probability }; });
+  } else {
+    out.candidates = (opts.keywordCands || []).slice(0, MAX_CANDIDATES)
+      .map(function (c) { return c.prior !== undefined && c.prior !== 1 ? { name: c.name, score: c.score, prior: c.prior } : { name: c.name, score: c.score }; });
+  }
+  if (viaJev) { out.method = 'jev'; out.provider = jev.provider || null; }
+  else if (viaKeyword) out.method = 'keyword';
+  return out;
+}
+
+/** The one line Claude sees: `[PICK] agent: <name> · skill: <invoke>`, '' when nothing is confident. */
+function formatPickLine(pick) {
+  var parts = [];
+  if (pick && pick.agent) parts.push('agent: ' + pick.agent.name);
+  if (pick && pick.skill) parts.push('skill: ' + pick.skill.invoke);
+  return parts.length ? '[PICK] ' + parts.join(' · ') : '';
+}
+
+// ── Route records ───────────────────────────────────────────────────────────
+
+function safeSessionId(sid) {
+  var s = String(sid || '').replace(/[^A-Za-z0-9_-]/g, '').slice(0, 128);
+  return s || null;
+}
+
+function monoDir(CWD) { return path.join(CWD, '.monomind'); }
+function routeFile(CWD, sid) { return path.join(monoDir(CWD), 'routes', sid + '.json'); }
+
+function atomicWrite(file, text) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  var tmp = file + '.' + process.pid + '.' + Date.now() + '.tmp';
+  fs.writeFileSync(tmp, text, 'utf-8');
+  fs.renameSync(tmp, file);
+}
+
+function readJson(file, maxBytes) {
+  try {
+    if (fs.statSync(file).size > maxBytes) return null;
+    return JSON.parse(fs.readFileSync(file, 'utf-8'));
+  } catch (e) { return null; }
+}
+
+function pruneRouteFiles(dir) {
+  try {
+    var names = fs.readdirSync(dir);
+    if (names.length <= 50) return;
+    var cutoff = Date.now() - ROUTE_FILE_TTL_MS;
+    names.slice(0, 500).forEach(function (n) {
+      var f = path.join(dir, n);
+      try { if (fs.statSync(f).mtimeMs < cutoff) fs.unlinkSync(f); } catch (e) { /* raced */ }
+    });
+  } catch (e) { /* best effort */ }
+}
+
+function outcomesFile(CWD) { return path.join(monoDir(CWD), 'route-outcomes.jsonl'); }
+
+/** Run `fn(locked)` holding route-outcomes.jsonl.lock, waiting up to
+ *  LOCK_WAIT_MS. `locked` is false when the wait ran out: the caller decides
+ *  whether its work is safe without the lock. */
+function withOutcomesLock(CWD, fn) {
+  var lock = outcomesFile(CWD) + '.lock';
+  var deadline = Date.now() + LOCK_WAIT_MS;
+  var locked = fsHelpers.claimLock(lock, LOCK_STALE_MS, 3);
+  while (!locked && Date.now() < deadline) {
+    fsHelpers.sleepSync(2 + Math.floor(Math.random() * 4));
+    locked = fsHelpers.claimLock(lock, LOCK_STALE_MS, 3);
+  }
+  try {
+    return fn(locked);
+  } finally {
+    if (locked) fsHelpers.releaseLock(lock);
+  }
+}
+
+/** Append one record; past MAX_OUTCOMES_BYTES keep the newest KEEP_OUTCOMES
+ *  lines, at most half the byte cap. Both under the lock; an append that could
+ *  not get it still lands (O_APPEND), rotation then waits for the next one. */
+function appendOutcome(CWD, rec) {
+  var file = outcomesFile(CWD);
+  withOutcomesLock(CWD, function (locked) {
+    fs.appendFileSync(file, JSON.stringify(rec) + '\n', 'utf-8');
+    if (!locked) return;
+    try {
+      if (fs.statSync(file).size <= MAX_OUTCOMES_BYTES) return;
+      var lines = fs.readFileSync(file, 'utf-8').split('\n').filter(Boolean).slice(-KEEP_OUTCOMES);
+      var bytes = 0;
+      var from = lines.length;
+      while (from > 0 && bytes + Buffer.byteLength(lines[from - 1]) + 1 <= MAX_OUTCOMES_BYTES / 2) {
+        bytes += Buffer.byteLength(lines[--from]) + 1;
+      }
+      atomicWrite(file, lines.slice(from).join('\n') + '\n');
+    } catch (e) { /* rotation is best effort */ }
+  });
+}
+
+/** Record the pick: route-outcomes.jsonl line, per-session route file and the
+ *  latest-route file the statusline reads. Returns the routeId. */
+function persistRoute(CWD, opts) {
+  var pick = opts.pick;
+  var sid = safeSessionId(opts.sessionId);
+  var routeId = typeof crypto.randomUUID === 'function'
+    ? crypto.randomUUID()
+    : 'route-' + Date.now() + '-' + Math.random().toString(36).slice(2, 8);
+  var preview = promptPreview(opts.prompt);
+  var agentName = pick.agent ? pick.agent.name : null;
+  fs.mkdirSync(monoDir(CWD), { recursive: true });
+  appendOutcome(CWD, {
+    routeId: routeId,
+    sessionId: sid,
+    ts: Date.now(),
+    promptHash: promptHash(opts.prompt),
+    promptPreview: preview,
+    agentName: agentName,
+    agentId: pick.agent ? pick.agent.id : null,
+    skill: pick.skill ? pick.skill.invoke : null,
+    method: pick.method,
+    provider: pick.provider,
+    confidence: pick.confidence,
+    candidates: pick.candidates,
+    shown: !!opts.shown,
+    // Field names route-outcomes.ts (doctor accuracy/adherence) reads.
+    task: preview,
+    recommendedAgent: agentName,
+    routingMethod: pick.method,
+    learningMode: 'js',
+  });
+  var route = JSON.stringify({
+    routeId: routeId,
+    sessionId: sid,
+    agent: agentName,
+    name: agentName,
+    agentSlug: pick.agent ? pick.agent.id : null,
+    skill: pick.skill ? pick.skill.invoke : null,
+    confidence: pick.confidence,
+    reason: pick.method === 'none' ? 'no confident pick' : pick.method + (pick.provider ? ' (' + pick.provider + ')' : ''),
+    prompt: preview,
+    updatedAt: new Date().toISOString(),
+  });
+  if (sid) {
+    atomicWrite(routeFile(CWD, sid), route);
+    pruneRouteFiles(path.join(monoDir(CWD), 'routes'));
+  }
+  atomicWrite(path.join(monoDir(CWD), 'last-route.json'), route);
+  return routeId;
+}
+
+/** A slash command's route: no agent recommendation (the command is the
+ *  skill) and no routeId, so it never counts as a pick to follow. It replaces
+ *  the session's route so spawns the command makes are not scored against an
+ *  earlier prompt's pick. */
+function persistCommandRoute(CWD, opts) {
+  var sid = safeSessionId(opts.sessionId);
+  var route = JSON.stringify({
+    sessionId: sid,
+    agent: null,
+    name: null,
+    skill: String(opts.command || '').slice(0, 200) || null,
+    confidence: 1.0,
+    reason: 'predefined command — no routing needed',
+    updatedAt: new Date().toISOString(),
+  });
+  if (sid) atomicWrite(routeFile(CWD, sid), route);
+  atomicWrite(path.join(monoDir(CWD), 'last-route.json'), route);
+}
+
+/** The session's latest route: its own route file, else the shared
+ *  last-route.json when that names this session. Never another session's
+ *  route, nor one that names no session. */
+function readSessionRoute(CWD, sessionId) {
+  var sid = safeSessionId(sessionId);
+  if (!sid) return null;
+  var own = readJson(routeFile(CWD, sid), MAX_ROUTE_FILE_BYTES);
+  if (own) return own;
+  var last = readJson(path.join(monoDir(CWD), 'last-route.json'), MAX_ROUTE_FILE_BYTES);
+  return last && last.sessionId === sid ? last : null;
+}
+
+/** Merge `patch` into the last route-outcomes record with `routeId`, never
+ *  overwriting a field that is already set. Returns true when a record changed. */
+function joinOutcome(CWD, routeId, patch) {
+  if (!routeId) return false;
+  var file = outcomesFile(CWD);
+  // Without the lock a rewrite could drop a concurrent append: skip the join.
+  return withOutcomesLock(CWD, function (locked) {
+    if (!locked) return false;
+    try {
+      if (fs.statSync(file).size > MAX_JOIN_BYTES) return false;
+      var lines = fs.readFileSync(file, 'utf-8').split('\n').filter(Boolean);
+      for (var i = lines.length - 1; i >= 0; i--) {
+        var rec;
+        try { rec = JSON.parse(lines[i]); } catch (e) { continue; }
+        if (rec.routeId !== routeId) continue;
+        var changed = false;
+        Object.keys(patch).forEach(function (k) {
+          if (patch[k] !== undefined && patch[k] !== null && rec[k] === undefined) { rec[k] = patch[k]; changed = true; }
+        });
+        if (!changed) return false;
+        lines[i] = JSON.stringify(rec);
+        atomicWrite(file, lines.join('\n') + '\n');
+        return true;
+      }
+    } catch (e) { /* no outcomes yet */ }
+    return false;
+  });
+}
+
+/** PreToolUse Task|Agent: did the spawn follow this session's latest pick? */
+function recordAdherence(CWD, hookInput) {
+  var toolInput = (hookInput && (hookInput.tool_input || hookInput.toolInput)) || {};
+  var sid = safeSessionId(hookInput && (hookInput.session_id || hookInput.sessionId));
+  var actual = typeof toolInput.subagent_type === 'string' && toolInput.subagent_type ? toolInput.subagent_type.slice(0, 128) : null;
+  var route = readSessionRoute(CWD, sid);
+  // Only a recorded pick (routeId) that named an agent is a recommendation.
+  if (route && !route.routeId) route = null;
+  var recommended = route && route.agent ? route.agent : null;
+  var recommendedId = recommended && route.agentSlug ? route.agentSlug : null;
+  var rec = {
+    ts: Date.now(),
+    routeId: route && route.routeId ? route.routeId : null,
+    sessionId: sid,
+    tool: (hookInput && (hookInput.tool_name || hookInput.toolName)) || null,
+    recommended: recommended,
+    recommendedId: recommendedId,
+    actual: actual,
+    followed: recommended ? !!actual && (actual === recommended || actual === recommendedId) : null,
+  };
+  fs.mkdirSync(monoDir(CWD), { recursive: true });
+  require('../utils/fs-helpers.cjs').appendJsonlWithRotation(
+    path.join(monoDir(CWD), 'pick-adherence.jsonl'), JSON.stringify(rec), 1000);
+  if (rec.routeId && actual) joinOutcome(CWD, rec.routeId, { agentActuallyUsed: actual });
+  return rec;
+}
+
+// ── SessionStart: keep skill-registry.json in step with its sources ────────
+
+/** Rebuild .claude/helpers/skill-registry.json when build-skill-registry.cjs
+ *  says it is stale (missing, or older than any of its sources: skills,
+ *  commands, org skills, the catalog state). Returns what it did. */
+function ensureSkillRegistryFresh(root, builder) {
+  if (builder === undefined) {
+    try { builder = require('../build-skill-registry.cjs'); } catch (e) { builder = null; }
+  }
+  if (!builder || typeof builder.isStale !== 'function' || typeof builder.ensure !== 'function') return 'no-builder';
+  if (!builder.isStale(root)) return 'fresh';
+  builder.ensure(root);
+  return 'rebuilt';
+}
+
+module.exports = {
+  KEYWORD_MIN_AGENT_SCORE: KEYWORD_MIN_AGENT_SCORE,
+  KEYWORD_AGENT_LEAD: KEYWORD_AGENT_LEAD,
+  KEYWORD_MIN_SKILL_SCORE: KEYWORD_MIN_SKILL_SCORE,
+  KEYWORD_SKILL_LEAD: KEYWORD_SKILL_LEAD,
+  isSystemPrompt: isSystemPrompt,
+  isTrivialPrompt: isTrivialPrompt,
+  promptHash: promptHash,
+  promptPreview: promptPreview,
+  rankAgents: rankAgents,
+  rankSkills: rankSkills,
+  decide: decide,
+  formatPickLine: formatPickLine,
+  safeSessionId: safeSessionId,
+  persistRoute: persistRoute,
+  persistCommandRoute: persistCommandRoute,
+  readSessionRoute: readSessionRoute,
+  joinOutcome: joinOutcome,
+  recordAdherence: recordAdherence,
+  ensureSkillRegistryFresh: ensureSkillRegistryFresh,
+};