@getmarrow/mcp 3.9.56 → 3.9.58

package/dist/runtime-contract.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidRuntimeResult = isValidRuntimeResult;
+exports.normalizeRuntimeResult = normalizeRuntimeResult;
+exports.highRiskRuntimeCanClose = highRiskRuntimeCanClose;
+const RUNTIME_GATE_DECISIONS = new Set([
+    'allow',
+    'proceed',
+    'warn',
+    'review_required',
+    'owner_approval_required',
+    'block',
+    'deny',
+    'denied',
+]);
+const RUNTIME_RISK_LEVELS = new Set(['low', 'medium', 'high', 'critical']);
+function isValidRuntimeResult(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const riskGate = value.risk_gate;
+    if (!riskGate || typeof riskGate !== 'object' || Array.isArray(riskGate))
+        return false;
+    const gate = riskGate;
+    return typeof gate.allow === 'boolean'
+        && typeof gate.decision === 'string'
+        && RUNTIME_GATE_DECISIONS.has(gate.decision);
+}
+function normalizeRuntimeResult(value) {
+    if (isValidRuntimeResult(value))
+        return value;
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const slim = value;
+    if (slim.response_mode !== 'slim'
+        || typeof slim.decision !== 'string'
+        || !RUNTIME_GATE_DECISIONS.has(slim.decision)
+        || typeof slim.risk_level !== 'string'
+        || !RUNTIME_RISK_LEVELS.has(slim.risk_level)
+        || typeof slim.gate_required !== 'boolean'
+        || typeof slim.proof_required !== 'boolean'
+        || typeof slim.proof_complete !== 'boolean') {
+        return null;
+    }
+    const allow = ['allow', 'proceed', 'warn'].includes(slim.decision);
+    const gateReceiptId = typeof slim.gate_receipt_id === 'string' && slim.gate_receipt_id
+        ? slim.gate_receipt_id
+        : null;
+    return {
+        ...slim,
+        ok: slim.ok !== false,
+        action: '',
+        agent_id: typeof slim.agent_id === 'string' ? slim.agent_id : null,
+        session_id: typeof slim.session_id === 'string' ? slim.session_id : null,
+        status: { health: slim.health || null, missed_hooks: slim.missed_hooks || [] },
+        decision_brief: {},
+        risk_gate: {
+            allow,
+            decision: slim.decision === 'proceed' ? 'allow' : slim.decision,
+            risk_level: slim.risk_level,
+            reasons: [],
+            gate_receipt_id: gateReceiptId,
+        },
+        relevant_lessons: [],
+        deployment_playbooks: [],
+        template_suggestion: {},
+        gate_receipt_id: gateReceiptId,
+        gate_receipt: gateReceiptId ? {
+            id: gateReceiptId,
+            required: slim.gate_required,
+            decision: slim.decision,
+        } : null,
+        proof_pack: {
+            required: slim.proof_required,
+            enforced: slim.proof_required,
+            fields: [],
+            missing: slim.proof_complete ? [] : ['required_proof'],
+            complete: slim.proof_complete,
+            commit_endpoint: '/v1/agent/commit',
+            rule: slim.proof_required ? 'proof_required_before_complete' : 'outcome_commit_required',
+        },
+        before_you_act: typeof slim.before_you_act === 'string' ? slim.before_you_act : null,
+        exact_next_action: typeof slim.exact_next_action === 'string' ? slim.exact_next_action : null,
+        auto_outcome_closure: null,
+    };
+}
+function highRiskRuntimeCanClose(runtime, proof, explicitReceiptId, now = Date.now()) {
+    const decision = String(runtime.risk_gate?.decision || '').toLowerCase();
+    const receiptDecision = String(runtime.gate_receipt?.decision || decision).toLowerCase();
+    const receiptId = typeof explicitReceiptId === 'string' && explicitReceiptId.trim()
+        ? explicitReceiptId.trim()
+        : runtime.gate_receipt?.id || runtime.gate_receipt_id || '';
+    const receiptExpired = runtime.gate_receipt?.expires_at
+        ? Date.parse(runtime.gate_receipt.expires_at) <= now
+        : false;
+    return Boolean(proof
+        && Object.keys(proof).length > 0
+        && runtime.risk_gate?.allow === true
+        && ['allow', 'proceed', 'warn'].includes(decision)
+        && ['allow', 'proceed', 'warn'].includes(receiptDecision)
+        && runtime.proof_pack?.complete === true
+        && receiptId
+        && !receiptExpired
+        && runtime.gate_receipt?.owner_approval_required !== true
+        && runtime.intervention?.must_stop !== true
+        && runtime.intervention?.allow !== false);
+}
+//# sourceMappingURL=runtime-contract.js.map

package/dist/runtime-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-contract.js","sourceRoot":"","sources":["../src/runtime-contract.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@getmarrow/mcp",
-  "version": "3.9.56",
+  "version": "3.9.58",
   "mcpName": "io.github.getmarrow/marrow",
   "description": "Runtime control, proof, and fleet intelligence for MCP-compatible AI agents.",
   "bin": {
-    "marrow-mcp": "dist/cli.js"
+    "marrow-mcp": "dist/cli.js",
+    "marrow-mcp-canary": "scripts/control-path-canary.cjs"
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -13,7 +14,8 @@
     "dev": "tsc --watch",
     "test": "npm run build && node --test test/*.test.js",
     "registry:check": "node scripts/mcp-registry-check.cjs",
-    "registry:verify": "node scripts/mcp-registry-verify.cjs"
+    "registry:verify": "node scripts/mcp-registry-verify.cjs",
+    "canary:control-path": "node scripts/control-path-canary.cjs"
   },
   "keywords": [
     "mcp",
@@ -68,7 +70,8 @@
     "README.md",
     "server.json",
     "scripts/mcp-registry-check.cjs",
-    "scripts/mcp-registry-verify.cjs"
+    "scripts/mcp-registry-verify.cjs",
+    "scripts/control-path-canary.cjs"
   ],
   "dependencies": {
     "@getmarrow/sdk": "^3.7.54"

package/scripts/control-path-canary.cjs

@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+const { spawn } = require('node:child_process');
+const { performance } = require('node:perf_hooks');
+const { resolve } = require('node:path');
+const { version: packageVersion } = require('../package.json');
+
+const cases = [
+  ['marrow_status', {}],
+  ['marrow_runtime_status', { fast: true }],
+  ['marrow_orient', { autoWarn: true }],
+  ['marrow_ask', { query: 'What should this agent verify before a safe release?' }],
+  ['marrow_agent_runtime', { action: 'Review a local documentation note', type: 'general', surfaces: ['workspace'] }],
+  ['marrow_first_value', { action: 'Verify Marrow control-path availability', type: 'review', surfaces: ['api'] }],
+  ['marrow_buyer_proof', { periodDays: 7 }],
+  ['marrow_governance_control_plane', {}],
+  ['marrow_value_report', { period: '7d' }],
+  ['marrow_fleet_lessons', { query: 'safe release verification', limit: 3 }],
+];
+
+const HOT_PATH_TOOLS = new Set([
+  'marrow_status',
+  'marrow_runtime_status',
+  'marrow_orient',
+  'marrow_ask',
+  'marrow_agent_runtime',
+]);
+const OUTPUT_LIMIT_BYTES = 256 * 1024;
+
+function boundedMs(name, fallback, minimum = 100, maximum = 10_000, env = process.env) {
+  const parsed = Number(env[name] || fallback);
+  return Number.isFinite(parsed) ? Math.max(minimum, Math.min(maximum, Math.floor(parsed))) : fallback;
+}
+
+function percentile(values, quantile) {
+  if (!values.length) return null;
+  const ordered = [...values].sort((a, b) => a - b);
+  return ordered[Math.max(0, Math.ceil(quantile * ordered.length) - 1)];
+}
+
+function latencyGroup(rows) {
+  const values = rows.map((row) => row.latency_ms);
+  return {
+    count: values.length,
+    p50_ms: percentile(values, 0.5),
+    p95_ms: percentile(values, 0.95),
+    p99_ms: percentile(values, 0.99),
+    max_ms: values.length ? Math.max(...values) : null,
+  };
+}
+
+function toolPayload(message, name) {
+  if (!message) throw new Error(`${name} returned no MCP tool response`);
+  if (message.error) throw new Error(`${name} returned JSON-RPC error ${message.error.code}`);
+  const result = message.result || {};
+  const text = result.content?.[0]?.text;
+  if (typeof text !== 'string' || !text.trim()) throw new Error(`${name} returned no MCP tool payload`);
+  let payload;
+  try { payload = JSON.parse(text); } catch { throw new Error(`${name} returned invalid tool JSON`); }
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload) || Object.keys(payload).length === 0) {
+    throw new Error(`${name} returned an empty or invalid tool payload`);
+  }
+  if (result.isError || payload.ok === false || payload.available === false) {
+    const code = payload.error?.code || payload.error_code || 'tool_unavailable';
+    throw new Error(`${name} unavailable (${code})`);
+  }
+  return payload;
+}
+
+function validatePayload(name, payload) {
+  const requireField = (valid, field) => {
+    if (!valid) throw new Error(`${name} returned an invalid ${field} contract`);
+  };
+  if (name === 'marrow_status' || name === 'marrow_runtime_status') {
+    requireField(
+      typeof payload.status === 'string'
+        || typeof payload.health === 'string'
+        || typeof payload.active === 'boolean'
+        || (payload.runtime && typeof payload.runtime === 'object'),
+      'status',
+    );
+  } else if (name === 'marrow_orient') {
+    requireField(Array.isArray(payload.warnings) && typeof payload.shouldPause === 'boolean', 'orientation');
+  } else if (name === 'marrow_ask') {
+    requireField(typeof payload.answer === 'string' && payload.answer.trim().length > 0, 'answer');
+  } else if (name === 'marrow_agent_runtime') {
+    requireField(
+      payload.risk_gate
+        && typeof payload.risk_gate === 'object'
+        && typeof payload.risk_gate.allow === 'boolean'
+        && typeof payload.risk_gate.decision === 'string'
+        && payload.proof_pack
+        && typeof payload.proof_pack.complete === 'boolean',
+      'runtime gate',
+    );
+  } else if (name === 'marrow_first_value') {
+    requireField(typeof payload.active === 'boolean' && typeof payload.headline === 'string', 'first-value');
+  } else if (name === 'marrow_value_report') {
+    requireField(
+      payload.period
+        && typeof payload.period.days === 'number'
+        && payload.metrics
+        && typeof payload.metrics.decisions?.total === 'number'
+        && payload.fleet
+        && typeof payload.fleet.active_agents === 'number',
+      'value report',
+    );
+  }
+}
+
+class PersistentMcpClient {
+  constructor(input) {
+    this.command = input.command;
+    this.args = input.args;
+    this.env = input.env;
+    this.timeoutMs = input.timeoutMs;
+    this.spawnProcess = input.spawnProcess || spawn;
+    this.maxOutputBytes = input.maxOutputBytes || OUTPUT_LIMIT_BYTES;
+    this.nextId = 1;
+    this.pending = new Map();
+    this.stdoutBuffer = '';
+    this.stderrBytes = 0;
+    this.closed = false;
+  }
+
+  start() {
+    if (this.child) return;
+    this.child = this.spawnProcess(this.command, this.args, {
+      env: this.env,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    this.child.stdout.setEncoding('utf8');
+    this.child.stdout.on('data', (chunk) => this.onStdout(chunk));
+    this.child.stderr.on('data', (chunk) => {
+      this.stderrBytes += Buffer.byteLength(chunk);
+      if (this.stderrBytes > this.maxOutputBytes) this.abort(new Error('MCP child exceeded stderr limit'));
+    });
+    this.child.once('error', (error) => this.abort(new Error(`MCP child failed: ${error.code || 'process_error'}`)));
+    this.child.once('exit', (code, signal) => {
+      this.closed = true;
+      if (this.pending.size > 0) this.rejectAll(new Error(`MCP child exited ${code ?? signal ?? 'unknown'}`));
+    });
+  }
+
+  onStdout(chunk) {
+    this.stdoutBuffer += chunk;
+    if (Buffer.byteLength(this.stdoutBuffer) > this.maxOutputBytes) {
+      this.abort(new Error('MCP child exceeded stdout limit'));
+      return;
+    }
+    for (;;) {
+      const newline = this.stdoutBuffer.indexOf('\n');
+      if (newline < 0) break;
+      const line = this.stdoutBuffer.slice(0, newline).trim();
+      this.stdoutBuffer = this.stdoutBuffer.slice(newline + 1);
+      if (!line) continue;
+      let message;
+      try { message = JSON.parse(line); } catch {
+        this.abort(new Error('MCP child emitted malformed JSON'));
+        return;
+      }
+      if (!Number.isSafeInteger(message.id)) continue;
+      const pending = this.pending.get(message.id);
+      if (!pending) {
+        this.abort(new Error(`MCP child returned unexpected response id ${message.id}`));
+        return;
+      }
+      clearTimeout(pending.timer);
+      this.pending.delete(message.id);
+      pending.resolve(message);
+    }
+  }
+
+  request(method, params = {}, timeoutMs = this.timeoutMs) {
+    if (!this.child || this.closed || !this.child.stdin.writable) {
+      return Promise.reject(new Error('MCP child is not writable'));
+    }
+    const id = this.nextId++;
+    return new Promise((resolveRequest, rejectRequest) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        const error = new Error(`${method} timed out`);
+        rejectRequest(error);
+        this.abort(error);
+      }, timeoutMs);
+      this.pending.set(id, { resolve: resolveRequest, reject: rejectRequest, timer });
+      this.child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`, (error) => {
+        if (!error) return;
+        clearTimeout(timer);
+        this.pending.delete(id);
+        rejectRequest(new Error(`${method} write failed`));
+        this.abort(error);
+      });
+    });
+  }
+
+  rejectAll(error) {
+    for (const pending of this.pending.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(error);
+    }
+    this.pending.clear();
+  }
+
+  abort(error) {
+    this.rejectAll(error instanceof Error ? error : new Error('MCP child aborted'));
+    if (this.child && !this.closed) this.child.kill('SIGKILL');
+  }
+
+  async stop() {
+    if (!this.child || this.closed) return;
+    this.child.stdin.end();
+    await new Promise((resolveExit) => {
+      const timer = setTimeout(() => {
+        if (!this.closed) this.child.kill('SIGKILL');
+        resolveExit();
+      }, 500);
+      this.child.once('exit', () => {
+        clearTimeout(timer);
+        resolveExit();
+      });
+    });
+  }
+}
+
+async function runCanary(env = process.env, options = {}) {
+  const key = env.MARROW_API_KEY || '';
+  if (!key) throw new Error('MARROW_API_KEY is required for the authenticated MCP control-path canary');
+  const transportTimeoutMs = boundedMs('MARROW_REQUEST_TIMEOUT_MS', 2_500, 250, 10_000, env);
+  const totalTimeoutMs = boundedMs('MARROW_MCP_CANARY_TOTAL_TIMEOUT_MS', 30_000, 2_000, 60_000, env);
+  const expectedVersion = env.MARROW_EXPECTED_MCP_VERSION || packageVersion;
+  const childPath = env.MARROW_MCP_CANARY_CHILD || resolve(__dirname, '../dist/cli.js');
+  const childEnv = {
+    ...env,
+    MARROW_API_KEY: key,
+    MARROW_BASE_URL: env.MARROW_BASE_URL || 'https://api.getmarrow.ai',
+    MARROW_AUTO_ENROLL: 'false',
+    MARROW_TOOL_PROFILE: 'full',
+    MARROW_CONTROL_PATH_CANARY: '1',
+    MARROW_REQUEST_TIMEOUT_MS: String(transportTimeoutMs),
+  };
+  delete childEnv.NODE_TEST_CONTEXT;
+  const client = new PersistentMcpClient({
+    command: process.execPath,
+    args: [childPath],
+    timeoutMs: transportTimeoutMs,
+    env: childEnv,
+    spawnProcess: options.spawnProcess,
+  });
+  const totalTimer = setTimeout(() => client.abort(new Error('MCP canary total timeout')), totalTimeoutMs);
+  const processStarted = performance.now();
+  client.start();
+  try {
+    const initialized = await client.request('initialize', {}, transportTimeoutMs + 3_000);
+    if (initialized.error) throw new Error(`MCP initialize failed ${initialized.error.code}`);
+    const version = initialized.result?.serverInfo?.version;
+    if (!version) throw new Error('MCP initialize produced no version');
+    if (version !== expectedVersion) throw new Error(`MCP canary loaded ${version} instead of expected ${expectedVersion}`);
+    const listed = await client.request('tools/list', {});
+    if (listed.error) throw new Error(`MCP tools/list failed ${listed.error.code}`);
+    const names = new Set((listed.result?.tools || []).map((tool) => tool.name));
+    for (const [name] of cases) {
+      if (!names.has(name)) throw new Error(`${name} is missing from the full MCP contract`);
+    }
+    const initializationMs = Math.round(performance.now() - processStarted);
+    const results = [];
+    for (const [name, args] of cases) {
+      const callStarted = performance.now();
+      const called = await client.request('tools/call', { name, arguments: args });
+      const latencyMs = Math.round(performance.now() - callStarted);
+      const payload = toolPayload(called, name);
+      validatePayload(name, payload);
+      const live = payload.stale !== true && payload.source !== 'last_known' && payload.available !== false;
+      if (!live) throw new Error(`${name} returned cached or unavailable guidance`);
+      results.push({ tool: name, ok: true, live: true, latency_ms: latencyMs });
+    }
+    const hotPath = results.filter((row) => HOT_PATH_TOOLS.has(row.tool));
+    const reports = results.filter((row) => !HOT_PATH_TOOLS.has(row.tool));
+    return {
+      ok: true,
+      package_version: version,
+      process_count: 1,
+      initialization_ms: initializationMs,
+      per_tool_latency_excludes_initialization: true,
+      tools_checked: results.length,
+      latency_groups: {
+        hot_path: latencyGroup(hotPath),
+        reports: latencyGroup(reports),
+      },
+      results,
+    };
+  } finally {
+    clearTimeout(totalTimer);
+    await client.stop();
+  }
+}
+
+if (require.main === module) {
+  runCanary().then((result) => {
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+  }).catch((error) => {
+    process.stderr.write(`MCP_CONTROL_PATH_CANARY=FAIL ${error instanceof Error ? error.message : 'unknown_error'}\n`);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = { PersistentMcpClient, latencyGroup, percentile, runCanary };

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/getmarrow/marrow-mcp",
     "source": "github"
   },
-  "version": "3.9.56",
+  "version": "3.9.58",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@getmarrow/mcp",
-      "version": "3.9.56",
+      "version": "3.9.58",
       "transport": {
         "type": "stdio"
       },