@geraldmaron/construct 1.0.6 → 1.0.8

package/lib/maintenance/cleanup.mjs

@@ -0,0 +1,315 @@
+/**
+ * lib/maintenance/cleanup.mjs — Construct's self-maintenance primitives.
+ *
+ * Every artifact Construct writes has a lifecycle. This module collects the
+ * primitives that enforce that lifecycle: rotate oversized logs, prune
+ * rotated segments, age-out cache directories. Each primitive is pure and
+ * returns a structured summary; runFullCleanup orchestrates them with sane
+ * defaults.
+ *
+ * Triggered from two entry points:
+ *   - `construct cleanup`            — manual sweep, optionally --dry-run
+ *   - bin/construct startup check    — automatic when the installed version
+ *                                       differs from ~/.construct/.cleanup-stamp,
+ *                                       so an upgrade reclaims disk without
+ *                                       requiring a manual command.
+ *
+ * Scope is deliberately narrow: only artifacts whose retention is owned by
+ * the runtime (logs, caches, rotated segments). Knowledge stores
+ * (.cx/observations/, .cx/handoffs/, .cx/intake/) require explicit retention
+ * policy and are left for a follow-up after policy is agreed.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const HARD_BUDGET_MS = 5000;
+
+// Size caps in bytes. Each entry: [filename relative to ~/.cx/, maxBytes].
+// Files that exceed maxBytes are truncated (head-preserving rotation is not
+// useful for append-only event logs — the most-recent events are what matter,
+// not the oldest; tail-preserving truncation keeps the last N% by recopying).
+const JSONL_LOG_CAPS_BYTES = {
+  'audit.jsonl': 25 * 1024 * 1024,
+  'contract-violations.jsonl': 25 * 1024 * 1024,
+  'doctor-log.jsonl': 25 * 1024 * 1024,
+  'role-pending.jsonl': 5 * 1024 * 1024,
+  'role-events.jsonl': 25 * 1024 * 1024,
+};
+
+const EMBED_LOG_DEFAULT_MAX_MB = 50;
+const EMBED_LOG_DEFAULT_KEEP = 3;
+const EMBED_LOG_HARD_CAP_MAX_MB = 500;
+const EMBED_LOG_HARD_CAP_KEEP = 20;
+
+function fileSizeOrZero(p) {
+  try { return fs.statSync(p).size; } catch { return 0; }
+}
+
+function rmSafe(p, dryRun) {
+  if (dryRun) return;
+  try { fs.rmSync(p, { force: true }); } catch (err) {
+    process.stderr.write(`[cleanup] failed to remove ${p}: ${err.message}\n`);
+  }
+}
+
+/**
+ * Tail-preserving truncate: keeps the last `keepBytes` of `file`, drops the
+ * rest. Used for append-only event logs where recent events are valuable but
+ * historical bloat is not.
+ */
+function tailTruncate(file, keepBytes, dryRun) {
+  if (dryRun) return;
+  let stat;
+  try { stat = fs.statSync(file); } catch { return; }
+  if (stat.size <= keepBytes) return;
+  const start = stat.size - keepBytes;
+  const buf = Buffer.alloc(keepBytes);
+  const fd = fs.openSync(file, 'r');
+  try { fs.readSync(fd, buf, 0, keepBytes, start); } finally { fs.closeSync(fd); }
+  // Find the first newline so we don't start mid-record.
+  const nl = buf.indexOf(0x0a);
+  const payload = nl >= 0 && nl < buf.length - 1 ? buf.subarray(nl + 1) : buf;
+  fs.writeFileSync(file, payload);
+}
+
+function rotationConfig(env = process.env) {
+  const maxMbRaw = Number.parseInt(env.CONSTRUCT_EMBED_LOG_MAX_MB ?? '', 10);
+  const keepRaw = Number.parseInt(env.CONSTRUCT_EMBED_LOG_KEEP ?? '', 10);
+  const maxMb = Number.isFinite(maxMbRaw) && maxMbRaw > 0 ? Math.min(maxMbRaw, EMBED_LOG_HARD_CAP_MAX_MB) : EMBED_LOG_DEFAULT_MAX_MB;
+  const keep = Number.isFinite(keepRaw) && keepRaw >= 0 ? Math.min(keepRaw, EMBED_LOG_HARD_CAP_KEEP) : EMBED_LOG_DEFAULT_KEEP;
+  return { maxBytes: maxMb * 1024 * 1024, keep };
+}
+
+/**
+ * Walk the embed log + every rotated segment (.1, .2, ...) and drop the ones
+ * that exceed the per-segment cap OR sit beyond the keep count.
+ *
+ * Unlike rotateEmbedLogIfNeeded in lib/embed/cli.mjs (which is called at
+ * daemon spawn time and only rotates the live log), this is the post-upgrade
+ * cleanup: it handles the case where an existing install has segments that
+ * were oversized before the cap existed.
+ */
+export function cleanupEmbedLog({ homeDir = os.homedir(), env = process.env, dryRun = false } = {}) {
+  const dir = path.join(homeDir, '.cx', 'runtime');
+  const baseLog = path.join(dir, 'embed-daemon.log');
+  const { maxBytes, keep } = rotationConfig(env);
+
+  const summary = { removed: [], truncated: [], freedBytes: 0, baseLog };
+
+  // Every existing segment (.log, .log.1, .log.2, ...)
+  if (!fs.existsSync(dir)) return summary;
+  const entries = fs.readdirSync(dir).filter(n => n === 'embed-daemon.log' || n.startsWith('embed-daemon.log.'));
+
+  for (const name of entries) {
+    const full = path.join(dir, name);
+    const size = fileSizeOrZero(full);
+
+    // Drop segments beyond the keep horizon entirely.
+    const dotMatch = name.match(/^embed-daemon\.log\.(\d+)$/);
+    if (dotMatch && Number.parseInt(dotMatch[1], 10) > keep) {
+      summary.removed.push({ path: full, size });
+      summary.freedBytes += size;
+      rmSafe(full, dryRun);
+      continue;
+    }
+
+    // The live log: if oversized, truncate to 0 (it will rotate cleanly on next
+    // daemon spawn via rotateEmbedLogIfNeeded). Truncating in place keeps any
+    // open daemon FDs valid (writes resume at byte 0 on next O_APPEND write).
+    if (name === 'embed-daemon.log' && size > maxBytes) {
+      summary.truncated.push({ path: full, sizeWas: size });
+      summary.freedBytes += size;
+      if (!dryRun) {
+        try {
+          fs.truncateSync(full, 0);
+        } catch (err) {
+          process.stderr.write(`[cleanup] failed to truncate ${full}: ${err.message}\n`);
+        }
+      }
+      continue;
+    }
+
+    // Rotated segments that are individually oversized: drop them. They are
+    // archived noise; keeping them around defeats the cap.
+    if (dotMatch && size > maxBytes) {
+      summary.removed.push({ path: full, size });
+      summary.freedBytes += size;
+      rmSafe(full, dryRun);
+    }
+  }
+
+  return summary;
+}
+
+/**
+ * Apply per-file size caps to the user-level JSONL event logs at ~/.cx/.
+ * Truncates oldest events rather than removing the whole file so the most
+ * recent records survive.
+ */
+export function cleanupJsonlLogs({ homeDir = os.homedir(), dryRun = false } = {}) {
+  const dir = path.join(homeDir, '.cx');
+  const summary = { truncated: [], freedBytes: 0 };
+  if (!fs.existsSync(dir)) return summary;
+
+  for (const [name, capBytes] of Object.entries(JSONL_LOG_CAPS_BYTES)) {
+    const file = path.join(dir, name);
+    const size = fileSizeOrZero(file);
+    if (size <= capBytes) continue;
+    // Retain the most recent half-cap so headroom exists before next truncate.
+    const keepBytes = Math.floor(capBytes / 2);
+    summary.truncated.push({ path: file, sizeWas: size, sizeNow: keepBytes });
+    summary.freedBytes += size - keepBytes;
+    tailTruncate(file, keepBytes, dryRun);
+  }
+
+  return summary;
+}
+
+/**
+ * Age out ~/.construct/cache/ entries older than `maxAgeDays`. Cache hits are
+ * idempotent and re-fetched on demand, so pruning is safe.
+ */
+export function cleanupCacheDir({ homeDir = os.homedir(), maxAgeDays = 30, dryRun = false } = {}) {
+  const dir = path.join(homeDir, '.construct', 'cache');
+  const summary = { removed: [], freedBytes: 0 };
+  if (!fs.existsSync(dir)) return summary;
+
+  const cutoff = Date.now() - (maxAgeDays * 24 * 60 * 60 * 1000);
+  const walk = (current) => {
+    let entries;
+    try { entries = fs.readdirSync(current, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) { walk(full); continue; }
+      let stat;
+      try { stat = fs.statSync(full); } catch { continue; }
+      if (stat.mtimeMs < cutoff) {
+        summary.removed.push({ path: full, size: stat.size });
+        summary.freedBytes += stat.size;
+        rmSafe(full, dryRun);
+      }
+    }
+  };
+  walk(dir);
+  return summary;
+}
+
+/**
+ * Orchestrator. Runs each primitive under a hard time budget and returns an
+ * aggregated summary. Individual failures are non-fatal: a primitive that
+ * throws is recorded as an error in the summary but does not block the rest.
+ */
+export function runFullCleanup({ homeDir = os.homedir(), env = process.env, dryRun = false } = {}) {
+  const startedAt = Date.now();
+  const summary = {
+    dryRun,
+    startedAt: new Date(startedAt).toISOString(),
+    durationMs: 0,
+    freedBytes: 0,
+    embedLog: null,
+    jsonlLogs: null,
+    cacheDir: null,
+    errors: [],
+  };
+
+  const safelyRun = (label, fn) => {
+    if (Date.now() - startedAt > HARD_BUDGET_MS) {
+      summary.errors.push({ step: label, error: 'time budget exceeded; skipped' });
+      return null;
+    }
+    try { return fn(); }
+    catch (err) { summary.errors.push({ step: label, error: err.message }); return null; }
+  };
+
+  summary.embedLog = safelyRun('embedLog', () => cleanupEmbedLog({ homeDir, env, dryRun }));
+  summary.jsonlLogs = safelyRun('jsonlLogs', () => cleanupJsonlLogs({ homeDir, dryRun }));
+  summary.cacheDir = safelyRun('cacheDir', () => cleanupCacheDir({ homeDir, dryRun }));
+
+  for (const part of [summary.embedLog, summary.jsonlLogs, summary.cacheDir]) {
+    if (part?.freedBytes) summary.freedBytes += part.freedBytes;
+  }
+  summary.durationMs = Date.now() - startedAt;
+  return summary;
+}
+
+/**
+ * Format bytes for one-line operator output. 1234567 → "1.2 MB".
+ */
+export function formatBytes(bytes) {
+  if (!bytes || bytes < 0) return '0 B';
+  const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+  let n = bytes;
+  let unit = 0;
+  while (n >= 1024 && unit < units.length - 1) { n /= 1024; unit += 1; }
+  return `${n.toFixed(unit === 0 ? 0 : 1)} ${units[unit]}`;
+}
+
+// ---------------------------------------------------------------------------
+// Version stamp — drives automatic cleanup on upgrade.
+//
+// ~/.construct/.cleanup-stamp records the last version that ran cleanup.
+// On every CLI invocation, bin/construct compares the current package
+// version to the stamp. A mismatch triggers a single cleanup pass and
+// writes the new version into the stamp. The first ever invocation also
+// triggers cleanup (no stamp present) — this is what unblocks existing
+// installs that already have 34 GB logs sitting around.
+// ---------------------------------------------------------------------------
+
+const STAMP_RELATIVE = path.join('.construct', '.cleanup-stamp');
+
+export function stampPath(homeDir = os.homedir()) {
+  return path.join(homeDir, STAMP_RELATIVE);
+}
+
+export function readVersionStamp({ homeDir = os.homedir() } = {}) {
+  const p = stampPath(homeDir);
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); }
+  catch { return null; }
+}
+
+export function writeVersionStamp({ homeDir = os.homedir(), version, summary } = {}) {
+  const p = stampPath(homeDir);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const payload = {
+    version,
+    ranAt: new Date().toISOString(),
+    freedBytes: summary?.freedBytes ?? 0,
+    durationMs: summary?.durationMs ?? 0,
+  };
+  fs.writeFileSync(p, JSON.stringify(payload, null, 2));
+}
+
+/**
+ * Run cleanup if and only if the installed version differs from the stamp.
+ * Returns { ran: bool, reason, summary?, previousVersion? }.
+ *
+ * Designed to be called at CLI startup. Never throws — cleanup failures are
+ * surfaced via the returned summary and never block the actual command.
+ */
+export function maybeRunCleanupOnUpgrade({
+  homeDir = os.homedir(),
+  env = process.env,
+  currentVersion,
+  force = false,
+} = {}) {
+  if (env.CONSTRUCT_DISABLE_AUTO_CLEANUP === '1') {
+    return { ran: false, reason: 'disabled via CONSTRUCT_DISABLE_AUTO_CLEANUP' };
+  }
+  const stamp = readVersionStamp({ homeDir });
+  if (!force && stamp && stamp.version === currentVersion) {
+    return { ran: false, reason: 'version matches stamp' };
+  }
+  let summary;
+  try { summary = runFullCleanup({ homeDir, env, dryRun: false }); }
+  catch (err) { return { ran: false, reason: `cleanup threw: ${err.message}` }; }
+  try { writeVersionStamp({ homeDir, version: currentVersion, summary }); }
+  catch (err) { /* stamp write failure is non-fatal */ void err; }
+  return {
+    ran: true,
+    reason: stamp ? 'version changed' : 'first run',
+    previousVersion: stamp?.version ?? null,
+    summary,
+  };
+}

package/lib/mcp/memory-bridge.mjs

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+/**
+ * lib/mcp/memory-bridge.mjs — stdio MCP bridge for cass-memory (cm).
+ *
+ * Editor MCP clients (OpenCode, Claude Code) expect a host to satisfy the MCP
+ * HTTP+SSE handshake — GET with `Accept: text/event-stream`, POST `initialize`,
+ * `notifications/initialized`, `ping`. cass-memory v0.2.x ships an HTTP server
+ * that answers `tools/list`, `tools/call`, `resources/list`, `resources/read`
+ * over POST but rejects the handshake calls (405 on GET, "Unsupported method"
+ * on POST initialize/ping). That single gap surfaces in editors as
+ * "memory SSE error: Non-200 status code (405)" and the memory tools never
+ * register.
+ *
+ * Sits between editor and cm. Speaks the canonical 2026 MCP stdio transport
+ * (newline-delimited JSON-RPC on stdin/stdout, logs on stderr), answers the
+ * handshake natively, and forwards real work (tools/resources) to cm over its
+ * existing HTTP API. Stays up across cm restarts; surfaces backend outages as
+ * JSON-RPC `-32603` errors rather than crashing, so the editor can retry
+ * without losing the channel.
+ *
+ * Env:
+ *   CONSTRUCT_MEMORY_BRIDGE_URL       cm base URL (default http://127.0.0.1:8765/)
+ *   CONSTRUCT_MEMORY_BRIDGE_AUTOSTART set to 1 to spawn `cm serve` if unreachable
+ *   CONSTRUCT_MEMORY_BRIDGE_TIMEOUT_MS   per-request timeout (default 5000)
+ *
+ * Stdout is reserved for protocol frames. All diagnostic output goes to stderr.
+ */
+
+import { createInterface } from 'node:readline';
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PROTOCOL_VERSION = '2024-11-05';
+const SERVER_NAME = 'construct-memory-bridge';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+function readPackageVersion() {
+  try {
+    const pkgPath = join(__dirname, '..', '..', 'package.json');
+    return JSON.parse(readFileSync(pkgPath, 'utf8')).version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+const SERVER_VERSION = readPackageVersion();
+
+function normalizeBackendUrl(raw) {
+  const value = (raw && String(raw).trim()) || 'http://127.0.0.1:8765/';
+  return value.endsWith('/') ? value : `${value}/`;
+}
+
+const BACKEND_URL = normalizeBackendUrl(process.env.CONSTRUCT_MEMORY_BRIDGE_URL);
+const REQUEST_TIMEOUT_MS = (() => {
+  const raw = Number(process.env.CONSTRUCT_MEMORY_BRIDGE_TIMEOUT_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : 5000;
+})();
+const AUTOSTART = process.env.CONSTRUCT_MEMORY_BRIDGE_AUTOSTART === '1';
+
+const FORWARDED_METHODS = new Set([
+  'tools/list',
+  'tools/call',
+  'resources/list',
+  'resources/read',
+  'prompts/list',
+  'prompts/get',
+]);
+
+function log(...parts) {
+  process.stderr.write(`[memory-bridge] ${parts.join(' ')}\n`);
+}
+
+function writeFrame(frame) {
+  process.stdout.write(`${JSON.stringify(frame)}\n`);
+}
+
+function jsonRpcResult(id, result) {
+  return { jsonrpc: '2.0', id, result };
+}
+
+function jsonRpcError(id, code, message, data) {
+  const err = { code, message };
+  if (data !== undefined) err.data = data;
+  return { jsonrpc: '2.0', id, error: err };
+}
+
+// cm forwarding uses fetch with an AbortController so a stuck backend never
+// strands the editor. Failed call returns a JSON-RPC -32603 error frame, not a
+// thrown exception, so the bridge process stays available for retries.
+
+async function forwardToBackend(method, params, id) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  try {
+    const body = { jsonrpc: '2.0', id: id ?? 0, method, params: params ?? {} };
+    const res = await fetch(BACKEND_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+    if (!res.ok) {
+      return jsonRpcError(
+        id,
+        -32603,
+        `memory backend returned HTTP ${res.status} for ${method}`,
+        { backend: BACKEND_URL, status: res.status },
+      );
+    }
+    const text = await res.text();
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      return jsonRpcError(id, -32603, `memory backend returned non-JSON for ${method}`, { backend: BACKEND_URL });
+    }
+    if (parsed && Object.prototype.hasOwnProperty.call(parsed, 'error')) {
+      return { jsonrpc: '2.0', id, error: parsed.error };
+    }
+    return jsonRpcResult(id, parsed && parsed.result !== undefined ? parsed.result : parsed);
+  } catch (err) {
+    const reason = err?.name === 'AbortError' ? 'timeout' : (err?.message || String(err));
+    return jsonRpcError(id, -32603, `memory backend unreachable at ${BACKEND_URL} (${reason})`, { backend: BACKEND_URL });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Autostart only fires when CONSTRUCT_MEMORY_BRIDGE_AUTOSTART=1. Detached
+// spawn keeps cm alive after the editor disconnects.
+
+let autostartAttempted = false;
+
+function maybeAutostartCm() {
+  if (!AUTOSTART || autostartAttempted) return;
+  autostartAttempted = true;
+  try {
+    const port = (() => {
+      try {
+        const u = new URL(BACKEND_URL);
+        return u.port || '8765';
+      } catch {
+        return '8765';
+      }
+    })();
+    const child = spawn('cm', ['serve', '--port', String(port)], {
+      detached: true,
+      stdio: 'ignore',
+    });
+    child.unref();
+    log(`autostart: spawned cm serve --port ${port}`);
+  } catch (err) {
+    log(`autostart failed: ${err?.message || err}`);
+  }
+}
+
+// Handshake methods resolve natively. cm cannot answer them; forwarding would
+// return the same "Unsupported method" surface that triggered this bug.
+
+function handleInitialize(id) {
+  return jsonRpcResult(id, {
+    protocolVersion: PROTOCOL_VERSION,
+    capabilities: { tools: {}, resources: {} },
+    serverInfo: { name: SERVER_NAME, version: SERVER_VERSION },
+  });
+}
+
+function handlePing(id) {
+  return jsonRpcResult(id, {});
+}
+
+async function handleShutdown(id) {
+  try { process.stderr.write(''); } catch { /* stderr already closed */ }
+  if (id !== undefined && id !== null) writeFrame(jsonRpcResult(id, null));
+  setImmediate(() => process.exit(0));
+}
+
+async function dispatch(message) {
+  if (!message || typeof message !== 'object') return null;
+  if (message.jsonrpc !== '2.0') return null;
+
+  const { id, method, params } = message;
+  const isNotification = id === undefined || id === null;
+
+  if (method === 'notifications/initialized' || method === 'notifications/cancelled') {
+    return null;
+  }
+  if (method === 'initialize') return handleInitialize(id);
+  if (method === 'ping') return handlePing(id);
+  if (method === 'shutdown') return handleShutdown(id);
+
+  if (FORWARDED_METHODS.has(method)) {
+    maybeAutostartCm();
+    return forwardToBackend(method, params, id);
+  }
+
+  if (isNotification) return null;
+  return jsonRpcError(id, -32601, `Method not found: ${method}`);
+}
+
+async function handleLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed) return;
+  let message;
+  try {
+    message = JSON.parse(trimmed);
+  } catch (err) {
+    writeFrame(jsonRpcError(null, -32700, `Parse error: ${err?.message || err}`));
+    return;
+  }
+  try {
+    const response = await dispatch(message);
+    if (response) writeFrame(response);
+  } catch (err) {
+    if (message && message.id !== undefined && message.id !== null) {
+      writeFrame(jsonRpcError(message.id, -32603, `Internal bridge error: ${err?.message || err}`));
+    } else {
+      log(`unhandled error on notification: ${err?.message || err}`);
+    }
+  }
+}
+
+export function startBridge({ input = process.stdin, output = process.stdout } = {}) {
+  if (output !== process.stdout) {
+    const writer = (frame) => output.write(`${JSON.stringify(frame)}\n`);
+    return runLoop(input, writer);
+  }
+  return runLoop(input, (frame) => process.stdout.write(`${JSON.stringify(frame)}\n`));
+}
+
+function runLoop(input, writer) {
+  const rl = createInterface({ input, crlfDelay: Infinity });
+  rl.on('line', async (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+    let message;
+    try {
+      message = JSON.parse(trimmed);
+    } catch (err) {
+      writer(jsonRpcError(null, -32700, `Parse error: ${err?.message || err}`));
+      return;
+    }
+    try {
+      const response = await dispatch(message);
+      if (response) writer(response);
+    } catch (err) {
+      if (message && message.id !== undefined && message.id !== null) {
+        writer(jsonRpcError(message.id, -32603, `Internal bridge error: ${err?.message || err}`));
+      } else {
+        log(`unhandled error on notification: ${err?.message || err}`);
+      }
+    }
+  });
+  rl.on('close', () => process.exit(0));
+  return rl;
+}
+
+const isMain = (() => {
+  try { return import.meta.url === `file://${process.argv[1]}`; } catch { return false; }
+})();
+
+if (isMain) {
+  log(`starting (backend=${BACKEND_URL}, autostart=${AUTOSTART ? 'on' : 'off'})`);
+  startBridge();
+}
+
+export const _testing = {
+  dispatch,
+  handleLine,
+  BACKEND_URL,
+  SERVER_VERSION,
+};

package/lib/mcp/server.mjs

@@ -14,6 +14,7 @@ import { fileURLToPath } from 'node:url';
 import { realpathSync } from 'node:fs';
 import { loadToolkitEnv } from '../toolkit-env.mjs';
 import { loadConstructEnv } from '../env-config.mjs';
+import { withGenAiSpan, GenAiAttrs, extractTraceContext, injectTraceContext } from '../telemetry/otel-tracer.mjs';
 
 // Apply config.env values to process.env, letting config.env win over shell env
 // so telemetry/OpenRouter credentials are always correct regardless of host env.
@@ -40,6 +41,7 @@ import {
 import {
   workflowInit, workflowAddTask, workflowUpdateTask,
   workflowNeedsMainInput, workflowValidate, workflowImportPlan,
+  workflowContractValidate,
 } from './tools/workflow.mjs';
 import {
   cxTrace, cxTraceUpdate, cxScore, sessionUsage, efficiencySnapshot,
@@ -414,11 +416,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'broker_check',
-      description: 'Queries the MCP broker policy gate for a pending action without executing it. Agents call this BEFORE attempting a high-risk action so the response (allowed / approvalRequired / reason / source) can be surfaced to the user in the agent\'s voice rather than triggering a denial after the fact. In solo mode the broker is off by default — returns `brokerActive: false` with `allowed: true` so the call is cheap and agents don\'t waste tokens on an inactive gate. Always emits a `tool.called` trace event for audit-trail parity. Reads agents/role-manifests.json fence rules in team / enterprise mode.',
+      description: 'Queries the MCP broker policy gate for a pending action without executing it. Agents call this BEFORE attempting a high-risk action so the response (allowed / approvalRequired / reason / source) can be surfaced to the user in the agent\'s voice rather than triggering a denial after the fact. In solo mode the broker is off by default — returns `brokerActive: false` with `allowed: true` so the call is cheap and agents don\'t waste tokens on an inactive gate. Always emits a `tool.called` trace event for audit-trail parity. Reads specialists/role-manifests.json fence rules in team / enterprise mode.',
       inputSchema: {
         type: 'object',
         properties: {
-          role: { type: 'string', description: 'Persona name (e.g. `engineer`, `security`). Must match a key in agents/role-manifests.json for team / enterprise mode.' },
+          role: { type: 'string', description: 'Persona name (e.g. `engineer`, `security`). Must match a key in specialists/role-manifests.json for team / enterprise mode.' },
           project: { type: 'string', description: 'Optional project scope for the decision.' },
           tool: { type: 'string', description: 'The tool the agent wants to invoke (e.g. `github`, `fs`).' },
           action: { type: 'string', description: 'The action on that tool (e.g. `create_pr`, `edit:lib/foo.mjs`).' },
@@ -430,7 +432,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'agent_contract',
-      description: 'Looks up explicit agent-to-agent service contracts (from agents/contracts.json). Specialists should call this at the start of a handoff to see the expected input shape, preconditions, and what postconditions they must satisfy. Use without args to get all contracts; pass producer/consumer to narrow; pass id for a specific contract.',
+      description: 'Looks up explicit agent-to-agent service contracts (from specialists/contracts.json). Specialists should call this at the start of a handoff to see the expected input shape, preconditions, and what postconditions they must satisfy. Use without args to get all contracts; pass producer/consumer to narrow; pass id for a specific contract.',
       inputSchema: {
         type: 'object',
         properties: {
@@ -874,6 +876,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           cwd: { type: 'string', description: 'Project root (default: server cwd).' },
           top_k: { type: 'number', description: 'Max communities to return (default 5).' },
           min_size: { type: 'number', description: 'Skip communities smaller than this (default 2).' },
+          tags: { type: 'array', items: { type: 'string' }, description: 'Restrict entity extraction to observations carrying these tags.' },
+          tag_match: { type: 'string', enum: ['any', 'all'], description: 'Tag match mode: any (default) or all.' },
         },
       },
     },
@@ -905,6 +909,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args = {} } = request.params;
 
+  // Extract W3C traceparent from params._meta (SEP-414 propagation).
+  const parentCtx = await extractTraceContext(request.params?._meta || {});
+
   let result;
   try {
     if (name === 'agent_health') result = agentHealth(args);
@@ -934,6 +941,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     else if (name === 'workflow_update_task') result = workflowUpdateTask(args);
     else if (name === 'workflow_needs_main_input') result = workflowNeedsMainInput(args);
     else if (name === 'workflow_validate') result = workflowValidate(args);
+    else if (name === 'workflow_contract_validate') result = await workflowContractValidate(args);
     else if (name === 'workflow_import_plan') result = workflowImportPlan(args);
     else if (name === 'list_teams') result = listTeams(opts);
     else if (name === 'get_team') result = getTeam(args, opts);