@getmarrow/mcp 3.9.54 → 3.9.56

package/README.md

@@ -97,11 +97,33 @@ npx -y @getmarrow/install@latest doctor
 
 # Manual MCP-only setup
 npx -y @getmarrow/mcp@latest setup
+
+# Verify live read latency, last success, and local backlog
+npx -y @getmarrow/mcp@latest ping
 ```
 
 Detection and notification are automatic. After explicit installer activation, the local controller may restore only Marrow-managed hooks/configuration. Package upgrades, owner policy, credentials, and unrelated configuration remain explicit and subject to the operator's normal change policy.
 
-## What's New in v3.9.54
+## What's New in v3.9.56
+
+v3.9.56 adds tenant-scoped coordination and evidence-only replay to the existing MCP governance surface:
+
+- each normal user prompt performs one compact `/v1/agent/context` read; risky or mutating prompts perform one `/v1/agent/runtime` call instead;
+- prompt lifecycle receipts are accepted into the owner-only local spool immediately and delivered asynchronously by later lifecycle activity;
+- the prompt read deadline is 400 ms, injected guidance is limited to 3–8 concise lines, and raw prompts are not stored in the guidance cache;
+- transient failures can use an owner-only, account/key/agent-scoped last-known brief for at most one hour, clearly labeled with its age;
+- 401 and 403 responses never use cached guidance, and cached runtime guidance cannot authorize high-risk work;
+- `marrow_ask` now maps to the canonical decision brief contract instead of a separate route;
+- `npx -y @getmarrow/mcp@latest ping` reports current latency, rolling measured p50/p99, last success, and lifecycle backlog health;
+- `marrow_coordinate` acquires/releases tenant-scoped resource leases and carries compact child proof packets without sharing transcripts;
+- `marrow_replay_compare` compares already-recorded baseline and candidate outcomes with durable proof and never executes either model;
+- both new tools preserve agent-bound key scope, reject unsafe path identifiers, and return unavailable or incomplete evidence rather than manufacturing a winner.
+
+The package remains backward compatible with supported server aliases while advertising only implemented tools.
+
+This release accepts `@getmarrow/sdk@^3.7.54` and is released after SDK `3.7.55`. The deterministic release order is SDK `3.7.55` first, MCP `3.9.56` second, and installer `0.1.40` last.
+
+## Previous: v3.9.54
 
 v3.9.54 makes Marrow's intervention visible through the existing decision-trace workflow:
 
@@ -111,8 +133,6 @@ v3.9.54 makes Marrow's intervention visible through the existing decision-trace
 
 It preserves the bounded MCP lifecycle recovery introduced in v3.9.53.
 
-This release is certified against `@getmarrow/sdk@3.7.53`. The deterministic release order is SDK `3.7.53` first, MCP `3.9.54` second, and installer `0.1.38` last.
-
 ## Previous: v3.9.53
 
 v3.9.53 adds exact lifecycle backlog visibility and bounded recovery for MCP-routed agent activity:
@@ -265,6 +285,16 @@ URLs, paths, credentials, or customer content. The arbitration response owns the
 session; pass its short-lived, single-use `owner_approval_receipt_id` to
 `marrow_commit`. An agent cannot authorize itself with a proof field.
 
+Use `marrow_coordinate` when parallel agents could edit the same file, service,
+deployment, or workflow. An acquired lease returns a one-time release capability.
+Child agents can then create a compact proof packet containing only a bounded
+summary and opaque durable evidence references. Complete is accepted only when
+the linked outcome and required proof are actually closed.
+
+Use `marrow_replay_compare` after two model or workflow variants have each
+recorded an outcome. It compares that existing evidence under one tenant task;
+it does not run models, retain prompts, or infer a winner from labels.
+
 ## Passive Use
 
 `npx @getmarrow/mcp setup` installs supported prompt, tool-result, and session-stop hooks so the agent can receive before-action context, record meaningful tool outcomes, and keep unfinished closure visible without the owner repeatedly prompting it to use Marrow.
@@ -294,6 +324,8 @@ Status diagnostics distinguish missing keys, invalid keys, wrong bound-agent ide
 | --- | --- |
 | `marrow_agent_runtime` | One-call pre-action status, policy gate, relevant lessons, proof requirements, and exact next action |
 | `marrow_arbitrate` | Resolve conflicting agent proposals before execution and return an explainable arbitration receipt |
+| `marrow_coordinate` | Acquire/release resource leases and exchange compact child proof packets across tenant agents |
+| `marrow_replay_compare` | Compare two existing proof-backed outcomes without executing a model |
 | `marrow_decision_brief` | Compact operating brief for meaningful work |
 | `marrow_think` | Record intent and retrieve relevant governance intelligence |
 | `marrow_commit` | Close an action with outcome, receipt, and proof |

package/dist/cli.js

@@ -17,6 +17,7 @@ const hook_session_1 = require("./hook-session");
 const hook_pre_action_1 = require("./hook-pre-action");
 const env_1 = require("./env");
 const lifecycle_spool_1 = require("./lifecycle-spool");
+const ping_state_1 = require("./ping-state");
 const redact_1 = require("./redact");
 // Parse CLI args
 function parseArgs() {
@@ -48,9 +49,62 @@ function parseArgs() {
         if (args[i] === 'drain-spool' || args[i] === '--drain-spool') {
             result.drainSpool = true;
         }
+        if (args[i] === 'ping' || args[i] === '--ping') {
+            result.ping = true;
+        }
     }
     return result;
 }
+async function runPingCommand() {
+    if (cliArgs.apiKey) {
+        process.stderr.write('Error: ping requires MARROW_API_KEY from trusted environment or owner configuration; --key is not accepted.\n');
+        process.exitCode = 1;
+        return;
+    }
+    const resolved = (0, env_1.resolveMarrowEnv)({ trustedOnly: true });
+    if (!resolved.apiKey) {
+        process.stdout.write(JSON.stringify({ ok: false, error: 'missing_key', exact_fix: resolved.exactFix }) + '\n');
+        process.exitCode = 1;
+        return;
+    }
+    const baseUrl = (0, index_1.validateBaseUrl)(resolved.baseUrl || 'https://api.getmarrow.ai');
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 400);
+    timer.unref?.();
+    const started = Date.now();
+    try {
+        const status = await (0, index_1.marrowRuntimeStatus)(resolved.apiKey, baseUrl, true, resolved.sessionId, resolved.agentId, controller.signal);
+        const latencyMs = Date.now() - started;
+        const history = (0, ping_state_1.updatePingState)({ apiKey: resolved.apiKey, baseUrl, agentId: resolved.agentId, latencyMs, success: true });
+        process.stdout.write(JSON.stringify({
+            ok: status.ok === true,
+            health: status.health || 'available',
+            current_ms: latencyMs,
+            p50_ms: history.p50_ms,
+            p99_ms: history.p99_ms,
+            sample_count: history.sample_count,
+            last_success_at: history.last_success_at,
+            lifecycle_spool: (0, lifecycle_spool_1.lifecycleSpoolStatus)({ apiKey: resolved.apiKey, agentId: resolved.agentId }),
+        }, null, 2) + '\n');
+    }
+    catch (error) {
+        const history = (0, ping_state_1.updatePingState)({ apiKey: resolved.apiKey, baseUrl, agentId: resolved.agentId, success: false });
+        const message = error instanceof Error ? error.message : String(error);
+        process.stdout.write(JSON.stringify({
+            ok: false,
+            error: /401|unauthorized/i.test(message) ? 'authentication_failed' : /403|forbidden/i.test(message) ? 'permission_denied' : /abort|timeout/i.test(message) ? 'timeout' : 'unavailable',
+            p50_ms: history.p50_ms,
+            p99_ms: history.p99_ms,
+            sample_count: history.sample_count,
+            last_success_at: history.last_success_at,
+            lifecycle_spool: (0, lifecycle_spool_1.lifecycleSpoolStatus)({ apiKey: resolved.apiKey, agentId: resolved.agentId }),
+        }, null, 2) + '\n');
+        process.exitCode = 1;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 async function runSpoolCommand(drain) {
     if (cliArgs.apiKey) {
         process.stderr.write('Error: lifecycle spool commands require MARROW_API_KEY from trusted environment or owner configuration; --key is not accepted.\n');
@@ -288,6 +342,9 @@ if (process.argv[2] !== 'keys') {
     else if (cliArgs.drainSpool) {
         void runSpoolCommand(true);
     }
+    else if (cliArgs.ping) {
+        void runPingCommand();
+    }
     else if (cliArgs.setup) {
         runSetup();
     }
@@ -1117,6 +1174,75 @@ if (process.argv[2] !== 'keys') {
                     required: ['objective', 'proposals'],
                 },
             },
+            {
+                name: 'marrow_coordinate',
+                description: 'Coordinate tenant agents without sharing transcripts. Acquire or release a bounded resource lease, ' +
+                    'list current leases, or create/list compact evidence-backed child proof packets for a parent agent.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        action: {
+                            type: 'string',
+                            enum: ['list_leases', 'acquire_lease', 'release_lease', 'list_proof_packets', 'create_proof_packet'],
+                        },
+                        resource_type: { type: 'string', enum: ['file', 'directory', 'service', 'workflow', 'deployment', 'custom'] },
+                        resource: { type: 'string', maxLength: 160, description: 'Bounded tenant-visible resource label. Do not send secrets.' },
+                        workflow_id: { type: 'string' },
+                        ttl_seconds: { type: 'number', minimum: 30, maximum: 3600 },
+                        lease_id: { type: 'string' },
+                        lease_token: { type: 'string', description: 'One-time lease capability returned by acquire_lease.' },
+                        status: { type: 'string', enum: ['active', 'released', 'expired', 'incomplete', 'complete', 'failed'] },
+                        limit: { type: 'number', minimum: 1, maximum: 100 },
+                        decision_id: { type: 'string' },
+                        proof_pack_id: { type: 'string' },
+                        summary: { type: 'string', maxLength: 280, description: 'Compact result summary; no raw transcript.' },
+                        evidence_refs: {
+                            type: 'array', maxItems: 20, items: { type: 'string' },
+                            description: 'Opaque durable evidence identifiers only.',
+                        },
+                    },
+                    required: ['action'],
+                },
+            },
+            {
+                name: 'marrow_replay_compare',
+                description: 'Compare two already-recorded outcomes for the same tenant task using durable proof. ' +
+                    'This does not run a model or replay customer content; it returns complete or insufficient_evidence.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        comparison_id: { type: 'string', description: 'Fetch a prior replay comparison by id.' },
+                        source_decision_id: { type: 'string', description: 'Original task decision used to bind the comparison.' },
+                        workspace_binding_id: { type: 'string', description: 'Optional privacy-safe workspace binding from runtime.' },
+                        constraints: {
+                            type: 'object',
+                            additionalProperties: false,
+                            maxProperties: 7,
+                            description: 'Allowlisted comparison labels only; prompts, code, transcripts, credentials, and nested content are rejected.',
+                            properties: {
+                                environment: { type: 'string', maxLength: 80 },
+                                tests: { type: 'string', maxLength: 80 },
+                                policy_profile_id: { type: 'string', maxLength: 80 },
+                                workflow_type: { type: 'string', maxLength: 80 },
+                                task_type: { type: 'string', maxLength: 80 },
+                                required_proof: { type: 'boolean' },
+                                same_workspace: { type: 'boolean' },
+                            },
+                        },
+                        baseline: {
+                            type: 'object',
+                            properties: { label: { type: 'string' }, decision_id: { type: 'string' } },
+                            required: ['decision_id'],
+                        },
+                        candidate: {
+                            type: 'object',
+                            properties: { label: { type: 'string' }, decision_id: { type: 'string' } },
+                            required: ['decision_id'],
+                        },
+                    },
+                    required: [],
+                },
+            },
             {
                 name: 'marrow_governance_control_plane',
                 description: 'Return Marrow control-plane proof: governance, runtime gates, proof packs, fleet intelligence, supported harnesses, and exact next action.',
@@ -1411,7 +1537,7 @@ if (process.argv[2] !== 'keys') {
                     success(id, {
                         protocolVersion: '2024-11-05',
                         capabilities: { tools: {}, prompts: {} },
-                        serverInfo: { name: 'marrow', version: '3.9.54' },
+                        serverInfo: { name: 'marrow', version: '3.9.56' },
                     });
                     // Auto-enroll: emit enrollment notification on connection
                     if (AUTO_ENROLL) {
@@ -1962,6 +2088,19 @@ Marrow is not a replacement agent or a standalone memory app. Context and prior
                         success(id, { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] });
                         return;
                     }
+                    if (toolName === 'marrow_coordinate') {
+                        const coordinationArgs = { ...args };
+                        delete coordinationArgs.agent_id;
+                        delete coordinationArgs.source_agent_id;
+                        const result = await (0, index_1.marrowCoordinate)(API_KEY, BASE_URL, coordinationArgs, SESSION_ID, FLEET_AGENT_ID);
+                        success(id, { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] });
+                        return;
+                    }
+                    if (toolName === 'marrow_replay_compare') {
+                        const result = await (0, index_1.marrowReplayCompare)(API_KEY, BASE_URL, args, SESSION_ID, FLEET_AGENT_ID);
+                        success(id, { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] });
+                        return;
+                    }
                     if (toolName === 'marrow_governance_control_plane') {
                         const result = await (0, index_1.marrowGovernanceControlPlane)(API_KEY, BASE_URL, SESSION_ID, FLEET_AGENT_ID);
                         success(id, { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] });