@mindrian_os/cli 2.0.0-beta.3 → 2.0.0-beta.33

package/lib/mcp/brain-router.cjs

@@ -0,0 +1,551 @@
+'use strict';
+
+/**
+ * MindrianOS Brain-Driven Router
+ *
+ * 3-tier fallback for framework recommendations:
+ *   Tier 1: In-memory cache (instant, 10-min TTL)
+ *   Tier 2: Local heuristic from problem-types.md (~100ms)
+ *   Tier 3: Brain API via brain-client.cjs (2s hard timeout)
+ *
+ * RECOMMENDS only -- never executes frameworks.
+ * Called by orchestration router for act*, suggest-next commands.
+ */
+
+const path = require('path');
+const { safeReadFile } = require('../core/index.cjs');
+
+// ---------------------------------------------------------------------------
+// Cache (Tier 1)
+// ---------------------------------------------------------------------------
+
+const CACHE_TTL = 600000; // 10 minutes
+const CACHE_EVICT = CACHE_TTL * 2; // evict entries older than 20 min
+
+/** @type {Map<string, { result: object, timestamp: number }>} */
+const cache = new Map();
+
+/** Counters for cache performance monitoring */
+let cacheHits = 0;
+let recommendCalls = 0;
+const EVICT_INTERVAL = 100; // Sweep expired entries every 100 recommend() calls
+
+// ---------------------------------------------------------------------------
+// Phase 339 Plan 05 (D-03b), 2026-09-03: Tier-3 shape-miss disclosure carrier
+// ---------------------------------------------------------------------------
+// A closed-vocabulary note (never free prose, never interpolated from
+// brainResult) naming the ONE new distinguishable cause of a Tier-3 miss:
+// the Brain answered but its response carried no `next_gate` shape. `null`
+// means either "no miss occurred" or "the miss was some other, already-
+// disclosed cause" (e.g. no_key, handled separately by the Phase 252-01
+// block below). brainRoute() resets this to null at its own entry and sets
+// it only immediately before returning null for THIS specific cause;
+// recommend() reads and clears it in the SAME synchronous continuation
+// right after its own Promise.race settles, so a value can only ever be
+// read back by the SAME recommend() call whose brainRoute() invocation set
+// it. Best-effort, diagnostic only: never blocks a return, never replaces
+// an existing key.
+const BRAIN_ROUTE_NOTE_NO_NEXT_GATE = 'answered_no_next_gate';
+let _lastBrainRouteMissNote = null;
+
+/**
+ * Simple string hash (djb2). Fast, non-crypto, sufficient for cache keys.
+ * @param {string} str
+ * @returns {string}
+ */
+function fastHash(str) {
+  let hash = 5381;
+  for (let i = 0; i < str.length; i++) {
+    hash = ((hash << 5) + hash + str.charCodeAt(i)) | 0;
+  }
+  return hash.toString(36);
+}
+
+/**
+ * Build cache key from room path + STATE.md content hash.
+ * @param {string} roomDir
+ * @param {string} stateContent
+ * @returns {string}
+ */
+function buildCacheKey(roomDir, stateContent) {
+  return `${roomDir}:${fastHash(stateContent || '')}`;
+}
+
+/**
+ * Get a non-expired entry from cache.
+ * @param {string} key
+ * @returns {object|null}
+ */
+function getFromCache(key) {
+  const entry = cache.get(key);
+  if (!entry) return null;
+  if (Date.now() - entry.timestamp >= CACHE_TTL) {
+    cache.delete(key);
+    return null;
+  }
+  return entry.result;
+}
+
+/**
+ * Store a result in cache.
+ * @param {string} key
+ * @param {object} result
+ */
+function setCache(key, result) {
+  cache.set(key, { result, timestamp: Date.now() });
+}
+
+/**
+ * Evict expired entries (called on each recommend()).
+ */
+function evictExpired() {
+  const now = Date.now();
+  for (const [key, entry] of cache) {
+    if (now - entry.timestamp >= CACHE_EVICT) {
+      cache.delete(key);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Local Heuristic (Tier 2)
+// ---------------------------------------------------------------------------
+
+/**
+ * Known methodology names for validation.
+ */
+const KNOWN_METHODOLOGIES = [
+  'lean-canvas', 'think-hats', 'structure-argument', 'beautiful-question',
+  'build-knowledge', 'challenge-assumptions', 'validate', 'map-unknowns',
+  'diagnose', 'score-innovation', 'explore-domains', 'analyze-needs',
+  'user-needs', 'analyze-systems', 'analyze-timing', 'find-bottlenecks',
+  'root-cause', 'systems-thinking', 'macro-trends', 'explore-trends',
+  'explore-futures', 'dominant-designs', 'scenario-plan',
+  'find-connections', 'build-thesis', 'compare-ventures', 'research',
+  'deep-grade', 'grade', 'leadership'
+];
+
+/**
+ * Parse the 2D classification matrix from problem-types.md.
+ * Returns a map: `${definition}:${complexity}` -> [methodology1, methodology2]
+ * @returns {Map<string, string[]>}
+ */
+function parseRoutingTable() {
+  const problemTypesPath = path.resolve(__dirname, '../../references/methodology/problem-types.md');
+  const content = safeReadFile(problemTypesPath);
+  if (!content) return new Map();
+
+  const table = new Map();
+
+  // Parse the markdown table rows
+  // Format: | **Definition** | simple | complicated | complex | wicked |
+  const lines = content.split('\n');
+  const definitions = ['undefined', 'ill-defined', 'well-defined'];
+  const complexities = ['simple', 'complicated', 'complex', 'wicked'];
+
+  for (const line of lines) {
+    if (!line.startsWith('|')) continue;
+    // Check if this is a data row (contains ** for definition level)
+    const defMatch = line.match(/\*\*(Undefined|Ill-defined|Well-defined)\*\*/i);
+    if (!defMatch) continue;
+
+    const defLevel = defMatch[1].toLowerCase();
+    // Split cells by | and extract methodology lists
+    const cells = line.split('|').map(c => c.trim()).filter(Boolean);
+    // cells[0] = definition label, cells[1..4] = simple, complicated, complex, wicked
+
+    for (let i = 1; i < cells.length && i - 1 < complexities.length; i++) {
+      const cell = cells[i];
+      // Extract methodology names (comma-separated, possibly with backticks)
+      const methodNames = cell
+        .replace(/\*\*/g, '')
+        .split(',')
+        .map(m => m.trim().replace(/`/g, ''))
+        .filter(m => m && KNOWN_METHODOLOGIES.includes(m));
+
+      if (methodNames.length > 0) {
+        table.set(`${defLevel}:${complexities[i - 1]}`, methodNames);
+      }
+    }
+  }
+
+  return table;
+}
+
+/** @type {Map<string, string[]>|null} */
+let routingTableCache = null;
+
+/**
+ * Get the routing table (parsed once, cached in memory).
+ * @returns {Map<string, string[]>}
+ */
+function getRoutingTable() {
+  if (!routingTableCache) {
+    routingTableCache = parseRoutingTable();
+  }
+  return routingTableCache;
+}
+
+/**
+ * Extract definition level and complexity from STATE.md content.
+ * @param {string} stateContent
+ * @returns {{ definition: string, complexity: string }}
+ */
+function extractProblemType(stateContent) {
+  let definition = 'undefined';
+  let complexity = 'complex';
+
+  if (stateContent) {
+    // Look for frontmatter fields
+    const defMatch = stateContent.match(/definition_level:\s*(.+)/i)
+      || stateContent.match(/problem_definition:\s*(.+)/i);
+    if (defMatch) {
+      const val = defMatch[1].trim().toLowerCase();
+      if (val.includes('well')) definition = 'well-defined';
+      else if (val.includes('ill')) definition = 'ill-defined';
+      else if (val.includes('undef')) definition = 'undefined';
+    }
+
+    const compMatch = stateContent.match(/complexity:\s*(.+)/i)
+      || stateContent.match(/problem_type:\s*(.+)/i);
+    if (compMatch) {
+      const val = compMatch[1].trim().toLowerCase();
+      if (val.includes('simple')) complexity = 'simple';
+      else if (val.includes('complicated')) complexity = 'complicated';
+      else if (val.includes('wicked')) complexity = 'wicked';
+      else if (val.includes('complex')) complexity = 'complex';
+    }
+
+    // Infer from venture_stage if explicit fields not found
+    if (!defMatch) {
+      const stageMatch = stateContent.match(/venture_stage:\s*(.+)/i);
+      if (stageMatch) {
+        const stage = stageMatch[1].trim().toLowerCase();
+        if (stage === 'discovery' || stage === 'ideation') definition = 'undefined';
+        else if (stage === 'validation' || stage === 'problem-fit') definition = 'ill-defined';
+        else if (stage === 'growth' || stage === 'scaling' || stage === 'execution') definition = 'well-defined';
+      }
+    }
+  }
+
+  return { definition, complexity };
+}
+
+/**
+ * Local heuristic routing: match room state to problem-types.md matrix.
+ * @param {string} roomDir
+ * @param {string} stateContent
+ * @param {string} [intent]
+ * @returns {object} Recommendation result
+ */
+function localRoute(roomDir, stateContent, intent) {
+  const table = getRoutingTable();
+  const { definition, complexity } = extractProblemType(stateContent);
+  const key = `${definition}:${complexity}`;
+
+  const chain = table.get(key);
+
+  if (chain && chain.length > 0) {
+    return {
+      chain,
+      confidence: 0.6,
+      source: 'local',
+      reasoning: `Matched problem type: ${definition} definition, ${complexity} complexity. ` +
+        `Routing via problem-types.md classification matrix.`,
+      target_sections: []
+    };
+  }
+
+  // Fallback: could not match matrix cell
+  return {
+    chain: ['diagnose', 'lean-canvas'],
+    confidence: 0.3,
+    source: 'local-fallback',
+    reasoning: 'Default recommendation - could not parse room state or match to routing table. ' +
+      'Diagnose first, then lean-canvas for structure.',
+    target_sections: []
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Brain API (Tier 3)
+// ---------------------------------------------------------------------------
+
+/**
+ * Call Brain API for framework recommendation via brain_ask (ungated).
+ * Replaced the former raw-Cypher brain_query path (admin-gated, BUG 2)
+ * with brain.ask(question) -- valid for all API keys.
+ * Reads next_gate.options[].framework for the ranked chain.
+ * Canon Part 8: the NL question carries only the generic problem-type enum,
+ * never user content or artifact text.
+ *
+ * @param {string} roomDir
+ * @param {string} stateContent
+ * @param {string} [intent]
+ * @returns {Promise<object|null>}
+ */
+// Phase 254 (COMP-01): this call is enumerated in
+// lib/mcp/brain-composition-census.cjs as the 'orchestration (act,
+// act-chain, act-dry-run, act-swarm)' reaching site -- reaches_brain: true,
+// belt: 'callTool', bound_ms: 2000 (the Promise.race wrap in recommend()
+// below). D-01 (254-CONTEXT.md) ratified this as SHIPPED, released
+// behaviour, not a new decision. A new composed Brain call anywhere under
+// lib/mcp/ requires an entry there or the build fails
+// (tests/test-254-composition-census.cjs).
+async function brainRoute(roomDir, stateContent, intent) {
+  // Phase 339 Plan 05 (D-03b), 2026-09-03: reset at entry so a value read
+  // by a caller can only ever reflect THIS invocation's own outcome.
+  _lastBrainRouteMissNote = null;
+
+  let brainClient;
+  try {
+    brainClient = require('../core/brain-client.cjs');
+  } catch (_e) {
+    return null;
+  }
+
+  if (!brainClient.isAvailable()) return null;
+
+  // Build a generic NL question carrying only the problem-type enum.
+  // Canon Part 8: no user content, no artifact text, no proprietary numbers.
+  const { definition, complexity } = extractProblemType(stateContent);
+  const safeDefinition = definition.replace(/[^a-zA-Z-]/g, '') || 'undefined';
+  const safeComplexity = complexity.replace(/[^a-zA-Z-]/g, '') || 'complex';
+  const question = 'recommend a framework for a ' + safeDefinition + ' definition '
+    + safeComplexity + ' problem';
+
+  let brainResult;
+  try {
+    if (typeof brainClient.ask !== 'function') return null;
+    brainResult = await brainClient.ask(question);
+  } catch (_e) {
+    return null;
+  }
+
+  if (!brainResult) return null;
+
+  // Read next_gate.options[] for the ranked framework chain.
+  // Gracefully handle both presence and absence of next_gate.
+  const hasNextGateShape = !!(brainResult.next_gate && Array.isArray(brainResult.next_gate.options));
+  const options = hasNextGateShape ? brainResult.next_gate.options : [];
+
+  // Phase 339 Plan 05 (D-03b), 2026-09-03: `next_gate` is an INCUMBENT-ONLY
+  // shape -- no Theo tool emits it, per the recorded grep in
+  // docs/254-NOTE-theo-adaptation-list-additions.md section 2. The
+  // incumbent ALWAYS carries next_gate, so this branch is unreachable
+  // against the incumbent and safe to ship ahead of the flip. This is a
+  // DISCLOSURE, not a shape adaptation: reading Theo's own chain shape is a
+  // named follow-up (D-03 consumer 2, lib/brain/chain-recommender.cjs),
+  // deliberately out of this plan's scope. The Phase 252-01 block below
+  // does NOT cover this cause: it is gated on !isAvailable(), and
+  // availability stays TRUE post-flip -- precisely why this degrade is
+  // silent today and why a second, differently-gated disclosure is needed
+  // rather than a widening of the first.
+  if (!hasNextGateShape) {
+    _lastBrainRouteMissNote = BRAIN_ROUTE_NOTE_NO_NEXT_GATE;
+  }
+
+  const anchorFramework = (brainResult.directive && brainResult.directive.guided)
+    ? (brainResult.directive.guided.framework || null)
+    : null;
+
+  // Build the chain: anchor first (if present + not already in options), then
+  // options[].commands (Quick 260910-hni), then options[].framework.
+  //
+  // Quick 260910-hni: KNOWN_METHODOLOGIES holds BARE command slugs (e.g.
+  // `find-bottlenecks`), so a Theo framework name like "Design Thinking"
+  // normalizes to `designthinking` and matches nothing below, while a slug
+  // like `find-bottlenecks` matches itself exactly -- pushing the command
+  // slugs ahead of the framework name lets this chain route even when the
+  // framework name alone would not.
+  //
+  // The Phase 339 D-03b BRAIN_ROUTE_NOTE_NO_NEXT_GATE disclosure (:344-346)
+  // now stops firing on the Theo path because the composed envelope carries
+  // `next_gate` again (Task 1, quick/260910-hni): that is the INTENDED
+  // outcome of this quick task, not a regression. The disclosure stays in
+  // place for any origin that still returns no `next_gate`.
+  const rawChain = [];
+  if (anchorFramework && typeof anchorFramework === 'string') rawChain.push(anchorFramework);
+  for (const opt of options) {
+    if (opt && Array.isArray(opt.commands)) {
+      for (const slug of opt.commands) {
+        if (typeof slug === 'string' && slug.length > 0 && !rawChain.includes(slug)) {
+          rawChain.push(slug);
+        }
+      }
+    }
+    if (opt && typeof opt.framework === 'string' && opt.framework.length > 0) {
+      if (!rawChain.includes(opt.framework)) rawChain.push(opt.framework);
+    }
+  }
+
+  if (rawChain.length === 0) return null;
+
+  // Map Brain framework names to CLI methodology names (slug normalization).
+  // This mirrors the previous mapping in the old Cypher path.
+  const mappedChain = rawChain
+    .map(function (name) {
+      const normalized = name.toLowerCase().replace(/[^a-z-]/g, '');
+      return KNOWN_METHODOLOGIES.find(function (m) { return m === normalized || normalized.includes(m); })
+        || normalized;
+    })
+    .filter(Boolean)
+    .slice(0, 4);
+
+  if (mappedChain.length === 0) return null;
+
+  // Derive top confidence from the options array (or default 0.8).
+  const topConf = (options.length > 0 && typeof options[0].confidence === 'number')
+    ? options[0].confidence
+    : 0.8;
+
+  // A real chain came back despite the missing next_gate shape (e.g. built
+  // from anchorFramework alone) -- this was not actually a miss, clear the
+  // note so recommend() never discloses a non-event.
+  _lastBrainRouteMissNote = null;
+
+  return {
+    chain: mappedChain,
+    confidence: topConf,
+    source: 'brain',
+    chain_type: 'feeds_into',
+    reasoning: 'Brain recommends ' + mappedChain.join(' -> ') + ' for '
+      + safeDefinition + ' ' + safeComplexity + ' problem. '
+      + 'Chain derived from brain_ask FEEDS_INTO recommendations.',
+    target_sections: [],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Get a framework recommendation for a room.
+ * 3-tier fallback: cache -> local heuristic -> Brain API (2s timeout).
+ *
+ * @param {string} roomDir - Path to room directory
+ * @param {{ intent?: string, mode?: string }} [options]
+ * @returns {Promise<{ chain: string[], confidence: number, source: string, reasoning: string, target_sections: string[] }>}
+ */
+async function recommend(roomDir, options = {}) {
+  const { intent } = options;
+
+  // Periodic cache eviction (every 100 calls, sweep entries older than 2x TTL)
+  recommendCalls++;
+  if (recommendCalls % EVICT_INTERVAL === 0) {
+    evictExpired();
+  }
+
+  // Read current room state
+  let stateContent = '';
+  try {
+    const stateOps = require('../core/state-ops.cjs');
+    stateContent = stateOps.getState(roomDir) || '';
+  } catch (_e) {
+    // No state available - continue with empty
+  }
+
+  // Tier 1: Cache check (BEFORE any heuristic or Brain API call)
+  const cacheKey = buildCacheKey(roomDir, stateContent);
+  const cached = getFromCache(cacheKey);
+  if (cached) {
+    cacheHits++;
+    return { ...cached, source: 'cache' };
+  }
+
+  // Tier 2: Local heuristic (always computed as fallback)
+  const localRec = localRoute(roomDir, stateContent, intent);
+
+  // Tier 3: Brain API (2s timeout, non-blocking)
+  try {
+    const brainRec = await Promise.race([
+      brainRoute(roomDir, stateContent, intent),
+      new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), 2000))
+    ]);
+    if (brainRec) {
+      setCache(cacheKey, brainRec);
+      return brainRec;
+    }
+  } catch (_e) {
+    // Brain unavailable or timeout - use local
+  }
+
+  // Phase 252-01 (SWEEP-01): the Tier-3 miss above (brainRoute() returned
+  // null on Brain-unavailable, or timed out) previously fell through to
+  // localRec silently -- true recommend() behavior (the honest Tier-2
+  // heuristic already carries source:'local-fallback'/'routing-table' etc.),
+  // but WHY Brain was skipped was never disclosed. When the cause is
+  // specifically no_key (not merely "no local edges"), attach the rail's
+  // typed refusal as an ADDITIVE field -- never replaces localRec's shape,
+  // never a new field any existing consumer reads today, so this cannot
+  // regress anyone destructuring {chain, confidence, source, reasoning,
+  // target_sections}. Best-effort; never blocks the return.
+  //
+  // Phase 254 (COMP-01): this require is the SWEEP-01 DISCLOSURE-only leg --
+  // enumerated in lib/mcp/brain-composition-census.cjs with reaches_brain:
+  // false, because it makes no tools/call of its own; it exists so a reader
+  // does not count this as a third wire. The reaching leg is brainRoute()
+  // above, which IS census-declared with reaches_brain: true.
+  try {
+    const brainClient = require('../core/brain-client.cjs');
+    if (typeof brainClient.isAvailable === 'function' && !brainClient.isAvailable()) {
+      const { refusalResponse } = require('../core/refusal-messaging.cjs');
+      localRec.brain_refusal = refusalResponse('no_key', { tool: 'brain_route' });
+    }
+  } catch (_e) {
+    // Disclosure is best-effort; never blocks the local recommendation.
+  }
+
+  // Phase 339 Plan 05 (D-03b), 2026-09-03: a SECOND, differently-gated
+  // disclosure, additive alongside the Phase 252-01 block above (which it
+  // does not touch or widen). Covers the cause that block cannot see: the
+  // Brain ANSWERED (isAvailable() stays true post-flip) but its response
+  // carried no `next_gate` shape, so brainRoute() above returned null with
+  // no readable reason. `_lastBrainRouteMissNote` was set (or left null) by
+  // THIS call's own already-awaited brainRoute() invocation; reading it
+  // here is synchronous, not a fresh async probe, so no extra await or
+  // network reach happens. ADDITIVE field only: never replaces localRec's
+  // shape, never a field any existing consumer reads today, so this cannot
+  // regress anyone destructuring {chain, confidence, source, reasoning,
+  // target_sections}. Best-effort; never blocks the return.
+  try {
+    if (_lastBrainRouteMissNote && !localRec.brain_refusal) {
+      localRec.brain_router_note = _lastBrainRouteMissNote;
+    }
+  } catch (_e) {
+    // Disclosure is best-effort; never blocks the local recommendation.
+  } finally {
+    _lastBrainRouteMissNote = null;
+  }
+
+  setCache(cacheKey, localRec);
+  return localRec;
+}
+
+/**
+ * Validate a framework chain.
+ * Checks that each methodology name is known.
+ *
+ * @param {string} roomDir - Path to room directory (unused currently, reserved for future)
+ * @param {string[]} chain - Array of methodology names
+ * @returns {{ valid: boolean, reason?: string }}
+ */
+function validateChain(roomDir, chain) {
+  if (!Array.isArray(chain) || chain.length === 0) {
+    return { valid: false, reason: 'Chain must be a non-empty array of methodology names.' };
+  }
+
+  const unknown = chain.filter(m => !KNOWN_METHODOLOGIES.includes(m));
+  if (unknown.length > 0) {
+    return {
+      valid: false,
+      reason: `Unknown methodologies: ${unknown.join(', ')}. ` +
+        `Known: ${KNOWN_METHODOLOGIES.join(', ')}`
+    };
+  }
+
+  return { valid: true };
+}
+
+module.exports = { recommend, validateChain };

package/lib/mcp/capability-registry.cjs

@@ -0,0 +1,62 @@
+'use strict';
+
+/**
+ * Capability Registry for MindrianOS MCP Server
+ *
+ * Surface-aware feature registration. Conditionally enables
+ * MCP Apps, Tasks, hooks, and scripts based on detected surface.
+ *
+ * MCP Apps registration (ext-apps) is Phase 60 -- this module
+ * creates the hook point for future capability expansion.
+ */
+
+const { CAPABILITY_MAP } = require('./surface-detect.cjs');
+const { registerAppViews } = require('./app-views.cjs');
+
+/**
+ * Get capability flags for a given surface.
+ *
+ * @param {'cli'|'desktop'|'cowork'} surface
+ * @returns {{ hooks: boolean, apps: boolean, tasks: boolean, scripts: boolean }}
+ */
+function getCapabilities(surface) {
+  return CAPABILITY_MAP[surface] || CAPABILITY_MAP.desktop;
+}
+
+/**
+ * Conditionally register surface-specific features on the MCP server.
+ *
+ * Currently logs active capabilities. MCP Apps tool/resource registration
+ * will be added in Phase 60 when capabilities.apps === true.
+ *
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {{ hooks: boolean, apps: boolean, tasks: boolean, scripts: boolean }} capabilities
+ * @param {string} roomDir
+ * @param {string} pluginRoot
+ */
+function registerCapabilities(server, capabilities, roomDir, pluginRoot) {
+  const active = Object.entries(capabilities)
+    .filter(([, v]) => v)
+    .map(([k]) => k);
+  const inactive = Object.entries(capabilities)
+    .filter(([, v]) => !v)
+    .map(([k]) => k);
+
+  process.stderr.write(
+    `[mindrian-os] Capabilities: active=[${active.join(', ')}] inactive=[${inactive.join(', ')}]\n`
+  );
+
+  // Phase 60: MCP Apps registration when capabilities.apps === true (Desktop/Cowork)
+  if (capabilities.apps) {
+    try {
+      registerAppViews(server, roomDir);
+    } catch (err) {
+      process.stderr.write(`[mindrian-os] MCP Apps registration failed (non-fatal): ${err.message}\n`);
+    }
+  }
+
+  // Phase 58: MCP Tasks registration when capabilities.tasks === true
+  // if (capabilities.tasks) { registerTasksTools(server, roomDir, pluginRoot); }
+}
+
+module.exports = { getCapabilities, registerCapabilities };

package/lib/mcp/contract-version.cjs

@@ -0,0 +1,59 @@
+'use strict';
+// Phase 198-04 (SPEC-2) -- the mindrian-core contract_version tool.
+//
+// CONTRACT_VERSION is the semver of the TOOL CONTRACT SHAPE (the room/graph/
+// chain/gate/... zod schemas this server exposes), pinned INDEPENDENTLY of the
+// plugin release version in package.json. The plugin can ship many patch
+// releases (1.15.3-beta.N...) while the contract itself stays 1.0.0, and the
+// contract only bumps when a tool's schema shape actually changes -- the whole
+// point of a versioned contract (198-SPEC.md requirement 2).
+//
+// Canon Part 8: trust_boundaries are GENERIC enum handles only, never room
+// content. Canon Part 11: this tool is a pure read (hitl_shape 'none') --
+// declared below in `connectors`, the born-wired SOURCE of truth
+// scripts/build-connector-registry.cjs discovers.
+
+// quick task 260903-h27: minor bump, 1.0.0 -> 1.1.0. Additive, backward-
+// compatible optional zod params (subject_node_id / evidence_node_ids) added
+// to three tool schemas: gate_render, chain_run, framework_run.
+const CONTRACT_VERSION = '1.1.0';
+
+// The trust boundaries this server's tool surface spans (198-SPEC.md
+// Background: "two MCP servers ship today... split by trust boundary").
+// Generic handles only -- never a room-specific string.
+const TRUST_BOUNDARIES = Object.freeze(['local', 'brain-proxy']);
+
+function getContractVersion() {
+  return CONTRACT_VERSION;
+}
+
+function registerContractVersion(server) {
+  server.tool(
+    'contract_version',
+    'Return the mindrian-core tool contract version (semver) and the trust boundaries its tool surface spans. Pure read, no side effects, no fork.',
+    {},
+    async () => {
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({ version: CONTRACT_VERSION, trust_boundaries: TRUST_BOUNDARIES }, null, 2),
+        }],
+      };
+    }
+  );
+}
+
+// Born-wired SOURCE of truth (Part 11 R1/R16). scripts/build-connector-registry.cjs
+// discovers this export and folds it into data/mcp-tool-connectors.json +
+// data/connector-registry.json. Never hand-edit either generated file.
+const connectors = [
+  {
+    tool: 'contract_version',
+    surface: 'contract_version',
+    connector: 'mcp-tool',
+    hitl_shape: 'none',
+    hitl_why: 'Pure read of a pinned version constant and a static trust-boundary enum; no fork, no side effects.',
+  },
+];
+
+module.exports = { CONTRACT_VERSION, getContractVersion, registerContractVersion, connectors };