@getmarrow/mcp 3.9.32 → 3.9.34

package/README.md

@@ -11,9 +11,15 @@
 
 Marrow gives your agent a memory that compounds.
 
-With `@getmarrow/mcp`, any MCP-compatible client can log intent before acting, inspect live loop state during work, and commit outcomes back to the hive when the work is done. That means your agent stops operating like an amnesiac and starts carrying forward real decision history.
+With `@getmarrow/mcp`, any MCP-compatible client can log intent before acting, inspect live loop state during work, and commit outcomes back to Marrow when the work is done. That means your agent stops operating like an amnesiac and starts carrying forward real decision history.
 
-**Your agent stops repeating the same mistakes. It learns from prior sessions — and from the wider Marrow hive — through a clean MCP tool surface.**
+**Your agent stops repeating the same mistakes. It learns from prior sessions — and from authorized fleet memory plus sanitized shared signals — through a clean MCP tool surface.**
+
+## Trust and Data Boundaries
+
+Marrow is tenant-aware by design. Private account, fleet, memory, workflow, and proof-pack data stays scoped to the authenticated account and authorized agent-bound keys. Shared/hive learning uses visibility-controlled, sanitized aggregate signals; it is not raw cross-customer decision sharing.
+
+For business pilots, review the live trust notes before production rollout: https://getmarrow.ai/docs#trust-boundaries
 
 ---
 
@@ -26,6 +32,7 @@ npx @getmarrow/install --yes
 ```
 
 The installer detects your MCP client, agent instructions, Node project, and runtime surfaces, then wires the safest passive setup automatically.
+It now also includes a governed runner: `npx @getmarrow/install run --agent <agent-id> -- <command>`, which gives MCP and non-MCP agents the same pre-action Marrow risk gate and automatic outcome closure for existing shell, deploy, publish, merge, and migration commands.
 MCP clients can also call `marrow_first_value` to show the first five-minute proof payload directly inside the agent.
 
 Use this MCP package directly when you want manual MCP server/hook setup for Claude Code, Claude Desktop, Cursor, or another MCP-compatible client. Use `@getmarrow/sdk` when you are building a custom Node/TypeScript integration in code.
@@ -37,6 +44,7 @@ Marrow auto-logs at three layers — transparent to your agent, invisible to you
 | Layer | How | Agent effort |
 |-------|-----|-------------|
 | Server-side | Every authenticated API call auto-logged as a decision | Zero |
+| Governed runner | `npx @getmarrow/install run --agent <id> -- <command>` — pre-action gate + outcome proof around existing commands | Minimal |
 | SDK | `marrow.think()` / `marrow.commit()` — explicit control | Minimal |
 | MCP hooks | `npx @getmarrow/mcp setup` — PostToolUse + UserPromptSubmit hooks | Zero |
 
@@ -76,14 +84,35 @@ Accounts with <7 days of activity AND <20 decisions get an onboarding payload sh
 
 ---
 
-## What's New in v3.9.32
+## What's New in v3.9.33
 
-v3.9.32 is a docs-sync release for Marrow's enterprise readiness contract. Runtime behavior is unchanged from v3.9.31.
+v3.9.33 adds MCP tools for adaptive governance recommendations and explicit policy profiles, while keeping the enterprise readiness contract documented for business pilots.
 
-- MCP agents can call the Marrow API endpoint `GET /v1/agent/enterprise-readiness?agents=20` when an owner asks whether Marrow is ready for a fleet rollout.
+- `marrow_mode_recommend` returns an explainable `passive`, `pilot`, or `enforce` recommendation for the current project/workflow.
+- `marrow_policy_profiles` lists saved account policy profiles, including the default business starter profile.
+- `marrow_create_policy_profile` creates or updates explicit rules such as local=passive, staging=pilot, production deploys=enforce.
+- `marrow_assign_project_policy_profile` binds an active profile to a project key so future resolves use it automatically.
+- `marrow_policy_resolve` resolves the current workflow mode from saved policy profiles, falling back to recommendation.
+- Marrow does not silently auto-switch modes. The agent/user must accept or override the recommendation.
+- MCP agents can call `GET /v1/agent/enterprise-readiness?agents=20` when an owner asks whether Marrow is ready for a fleet rollout.
 - The response is owner-safe and covers tenant isolation, data boundaries, fail behavior, policy controls, scale proof, and a 30-day pilot package.
-- Marrow is explicit about readiness: controlled business pilots are supported when production gates pass; regulated enterprise use still requires formal SOC 2/legal/SLA completion.
-- The source-of-truth docs now include the enterprise trust and scale readiness page at [getmarrow.ai/docs](https://getmarrow.ai/docs/).
+- The source-of-truth docs include the enterprise trust and scale readiness page at [getmarrow.ai/docs](https://getmarrow.ai/docs/).
+
+```json
+{
+  "project": {
+    "name": "agent-api",
+    "type": "node",
+    "frameworks": ["edge-service"],
+    "signals": ["package_json", "platform_config", "github_actions"]
+  },
+  "workflow": {
+    "action": "deploy production service",
+    "type": "deploy",
+    "environment": "production"
+  }
+}
+```
 
 ## What's New in v3.9.31
 
@@ -114,9 +143,9 @@ Previous agent-native runtime behavior remains current:
 
 ```json
 {
-  "action": "deploy Cloudflare Worker to production",
+  "action": "deploy edge service to production",
   "type": "deploy",
-  "surfaces": ["github", "cloudflare", "production"]
+  "surfaces": ["github", "deployment-platform", "production"]
 }
 ```
 
@@ -124,6 +153,31 @@ Full feature history, examples, and API reference live at [getmarrow.ai/docs](ht
 
 ---
 
+### Gated Commit Proof
+
+For risky actions, call `marrow_agent_runtime` before acting and pass the receipt plus proof into `marrow_commit`:
+
+```json
+{
+  "decision_id": "...",
+  "success": true,
+  "outcome": "Deploy succeeded and production smoke passed",
+  "gate_receipt_id": "runtime.gate_receipt.id",
+  "proof": {
+    "summary": "Production deploy completed",
+    "checks": ["tests passed", "smoke passed"],
+    "outcome": "success",
+    "blockers": "none",
+    "commits_prs_shas": "abc123",
+    "rollback_target": "previous release version",
+    "handoff_result_file": "/tmp/marrow-handoffs/release/result.md",
+    "deployment_and_smoke": "production smoke passed"
+  }
+}
+```
+
+If you provide `action` and omit `gate_receipt_id`, `marrow_commit` can fetch a matching runtime gate receipt automatically.
+
 ## Human-Directed Attribution Status
 
 The Marrow API supports privacy-preserving provenance fields on direct `POST /v1/decisions` calls: `source_kind`, `human_directed`, `source_confidence`, `instruction_ref`, `instruction_hash`, and `source_meta`. These fields classify instruction source class without identifying the human or storing raw prompts/PII.
@@ -184,7 +238,7 @@ Use it before deploys, publishes, merges, DB migrations, key rotation, destructi
 
 ```json
 {
-  "action": "rotate Cloudflare deploy token and verify production",
+  "action": "rotate deployment token and verify production",
   "riskTolerance": "medium",
   "requiresApproval": true
 }
@@ -204,7 +258,7 @@ Marrow now tells the agent exactly what it contributed to each decision, so the
 
 Three new fields:
 
-- `marrow_think` returns `marrow_contributed` describing what intelligence Marrow surfaced for this decision (warnings consulted, hive patterns, similar decisions, workflow templates, loop detection, collective insight).
+- `marrow_think` returns `marrow_contributed` describing what intelligence Marrow surfaced for this decision (warnings consulted, shared patterns, similar decisions, workflow templates, loop detection, collective insight).
 - `marrow_commit` returns `marrow_contributed` describing concrete signals on the commit itself (pattern reused, warning avoided, workflow step).
 - `marrow_session_end` returns `session_summary` aggregating Marrow's contribution across the session, plus a one-line `narrative` for the agent to surface as it wraps up.
 

package/dist/cli.js

@@ -296,7 +296,7 @@ if (process.argv[2] !== 'keys') {
                         decision_id: lastDecisionId,
                         success: false,
                         outcome: 'Session ended without explicit commit',
-                    }, SESSION_ID);
+                    }, SESSION_ID, FLEET_AGENT_ID);
                 }
                 catch (err) {
                     const msg = err instanceof Error ? err.message : String(err);
@@ -572,6 +572,15 @@ if (process.argv[2] !== 'keys') {
                         success: { type: 'boolean', description: 'Did the action succeed?' },
                         outcome: { type: 'string', description: 'What happened — be specific, this trains the hive' },
                         caused_by: { type: 'string', description: 'Optional: what caused this action' },
+                        proof: {
+                            type: 'object',
+                            description: 'Optional required proof pack for gated work: summary, checks, outcome, blockers, commits_prs_shas, rollback_target, handoff_result_file, deployment_and_smoke.',
+                        },
+                        gate_receipt_id: { type: 'string', description: 'Receipt id from marrow_agent_runtime.gate_receipt.id for risky work.' },
+                        action: { type: 'string', description: 'Optional original action. If provided and gate_receipt_id is omitted, MCP can fetch a matching runtime gate receipt before commit.' },
+                        type: { type: 'string', description: 'Optional original action type for auto gate lookup, e.g. deploy, publish, merge, handoff, implementation.' },
+                        surfaces: { type: 'array', items: { type: 'string' }, description: 'Optional surfaces for auto gate receipt, e.g. github, cloudflare, npm, production.' },
+                        auto_gate: { type: 'boolean', description: 'If true/default and action is provided, call marrow_agent_runtime to obtain gate_receipt_id before commit.' },
                     },
                     required: ['decision_id', 'success', 'outcome'],
                 },
@@ -959,6 +968,66 @@ if (process.argv[2] !== 'keys') {
                     required: ['action'],
                 },
             },
+            {
+                name: 'marrow_mode_recommend',
+                description: 'Recommend passive, pilot, or enforce mode from project/workflow signals. Marrow never auto-switches here; the agent/user must accept or override.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        project: { type: 'object', description: 'Project signals: name, type, frameworks, signals, package_scripts, config_files.' },
+                        workflow: { type: 'object', description: 'Workflow context: action, type, branch, environment.' },
+                        agent: { type: 'object', description: 'Agent context: id and role.' },
+                        selected_mode: { type: 'string', enum: ['passive', 'pilot', 'enforce'], description: 'Optional final user-selected mode to log.' },
+                        selection_source: { type: 'string', enum: ['accepted', 'overridden', 'ignored', 'system'], description: 'How the final mode was selected.' },
+                    },
+                    required: [],
+                },
+            },
+            {
+                name: 'marrow_policy_profiles',
+                description: 'List saved Marrow governance policy profiles for this account. Returns default-business when none are saved.',
+                inputSchema: { type: 'object', properties: {}, required: [] },
+            },
+            {
+                name: 'marrow_create_policy_profile',
+                description: 'Create or update an explicit governance policy profile. Mutating call; requires a key with full scope.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        name: { type: 'string', description: 'Profile name, e.g. default-business or production-agents.' },
+                        description: { type: 'string', description: 'Optional profile description.' },
+                        rules: { type: 'array', items: { type: 'object' }, description: 'Rules with match fields and mode passive/pilot/enforce.' },
+                    },
+                    required: ['name'],
+                },
+            },
+            {
+                name: 'marrow_assign_project_policy_profile',
+                description: 'Assign an active governance policy profile to a project key. Mutating call; requires a key with full scope.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        project_key: { type: 'string', description: 'Stable project key, e.g. marrow-api or clinic-api.' },
+                        profile_id: { type: 'string', description: 'Active policy profile id.' },
+                    },
+                    required: ['project_key', 'profile_id'],
+                },
+            },
+            {
+                name: 'marrow_policy_resolve',
+                description: 'Resolve the explicit mode for a project/workflow from saved policy profiles, falling back to recommendation. Does not auto-apply.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        profile_id: { type: 'string', description: 'Optional policy profile id.' },
+                        profile_name: { type: 'string', description: 'Optional policy profile name.' },
+                        project: { type: 'object', description: 'Project signals: name, type, frameworks, signals, package_scripts, config_files.' },
+                        workflow: { type: 'object', description: 'Workflow context: action, type, branch, environment.' },
+                        agent: { type: 'object', description: 'Agent context: id and role.' },
+                    },
+                    required: [],
+                },
+            },
             {
                 name: 'marrow_workflow_gate',
                 description: 'Pre-action risk gate for deploys, publishes, merges, DB migrations, key rotation, destructive commands, and production work. ' +
@@ -1263,13 +1332,13 @@ This is not optional overhead — it's how you stop repeating the same failures.
                         let result;
                         const wantAutoWarn = args.autoWarn ?? true;
                         try {
-                            result = await (0, index_1.marrowOrient)(API_KEY, BASE_URL, { taskType: args.taskType, autoWarn: wantAutoWarn }, SESSION_ID);
+                            result = await (0, index_1.marrowOrient)(API_KEY, BASE_URL, { taskType: args.taskType, autoWarn: wantAutoWarn }, SESSION_ID, FLEET_AGENT_ID);
                         }
                         catch (e) {
                             // autoWarn endpoint may not be deployed yet — fall back to legacy orient
                             if (wantAutoWarn) {
                                 process.stderr.write(`[marrow] autoWarn orient not available, falling back to legacy\n`);
-                                result = await (0, index_1.marrowOrient)(API_KEY, BASE_URL, { taskType: args.taskType, autoWarn: false }, SESSION_ID);
+                                result = await (0, index_1.marrowOrient)(API_KEY, BASE_URL, { taskType: args.taskType, autoWarn: false }, SESSION_ID, FLEET_AGENT_ID);
                             }
                             else {
                                 throw e;
@@ -1354,7 +1423,13 @@ This is not optional overhead — it's how you stop repeating the same failures.
                             success: args.success,
                             outcome,
                             caused_by: args.caused_by,
-                        }, SESSION_ID);
+                            proof: args.proof,
+                            gate_receipt_id: args.gate_receipt_id,
+                            action: args.action,
+                            type: args.type,
+                            surfaces: args.surfaces,
+                            auto_gate: args.auto_gate,
+                        }, SESSION_ID, FLEET_AGENT_ID);
                         const commitResult = { ...result, narrative: result.narrative ?? null };
                         lastCommitted = true;
                         lastDecisionId = null;
@@ -1386,7 +1461,19 @@ This is not optional overhead — it's how you stop repeating the same failures.
                                 decision_id: thinkResult.decision_id,
                                 success: args.success ?? true,
                                 outcome,
-                            }, SESSION_ID);
+                                proof: {
+                                    summary: description,
+                                    checks: ['marrow_run completed'],
+                                    outcome,
+                                    blockers: (args.success ?? true) ? 'none' : 'see outcome',
+                                    commits_prs_shas: 'not applicable',
+                                    rollback_target: 'not applicable',
+                                    handoff_result_file: 'not applicable',
+                                    deployment_and_smoke: 'not applicable',
+                                },
+                                action: description,
+                                type: args.type || 'general',
+                            }, SESSION_ID, FLEET_AGENT_ID);
                         }
                         catch (err) {
                             const msg = err instanceof Error ? err.message : String(err);
@@ -1435,7 +1522,23 @@ This is not optional overhead — it's how you stop repeating the same failures.
                                 }
                                 else {
                                     const thinkResult = await (0, index_1.marrowThink)(API_KEY, BASE_URL, { action, type }, SESSION_ID, FLEET_AGENT_ID);
-                                    await (0, index_1.marrowCommit)(API_KEY, BASE_URL, { decision_id: thinkResult.decision_id, success: outcomeSuccess, outcome }, SESSION_ID);
+                                    await (0, index_1.marrowCommit)(API_KEY, BASE_URL, {
+                                        decision_id: thinkResult.decision_id,
+                                        success: outcomeSuccess,
+                                        outcome,
+                                        proof: {
+                                            summary: action,
+                                            checks: ['marrow_auto completed'],
+                                            outcome,
+                                            blockers: outcomeSuccess ? 'none' : 'see outcome',
+                                            commits_prs_shas: 'not applicable',
+                                            rollback_target: 'not applicable',
+                                            handoff_result_file: 'not applicable',
+                                            deployment_and_smoke: 'not applicable',
+                                        },
+                                        action,
+                                        type,
+                                    }, SESSION_ID, FLEET_AGENT_ID);
                                 }
                             }
                             catch (err) {
@@ -1652,6 +1755,62 @@ This is not optional overhead — it's how you stop repeating the same failures.
                         success(id, { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] });
                         return;
                     }
+                    if (toolName === 'marrow_mode_recommend') {
+                        const result = await (0, index_1.marrowRecommendGovernanceMode)(API_KEY, BASE_URL, {
+                            project: args.project && typeof args.project === 'object' && !Array.isArray(args.project)
+                                ? (0, redact_1.redactSensitiveValue)(args.project)
+                                : undefined,
+                            workflow: args.workflow && typeof args.workflow === 'object' && !Array.isArray(args.workflow)
+                                ? (0, redact_1.redactSensitiveValue)(args.workflow)
+                                : undefined,
+                            agent: args.agent && typeof args.agent === 'object' && !Array.isArray(args.agent)
+                                ? (0, redact_1.redactSensitiveValue)(args.agent)
+                                : { id: FLEET_AGENT_ID || AGENT_ID },
+                            selected_mode: args.selected_mode,
+                            selection_source: args.selection_source,
+                        }, SESSION_ID, FLEET_AGENT_ID);
+                        success(id, { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] });
+                        return;
+                    }
+                    if (toolName === 'marrow_policy_profiles') {
+                        const result = await (0, index_1.marrowListPolicyProfiles)(API_KEY, BASE_URL, SESSION_ID, FLEET_AGENT_ID);
+                        success(id, { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] });
+                        return;
+                    }
+                    if (toolName === 'marrow_create_policy_profile') {
+                        const result = await (0, index_1.marrowCreatePolicyProfile)(API_KEY, BASE_URL, {
+                            name: args.name,
+                            description: args.description,
+                            rules: Array.isArray(args.rules) ? args.rules : undefined,
+                        }, SESSION_ID, FLEET_AGENT_ID);
+                        success(id, { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] });
+                        return;
+                    }
+                    if (toolName === 'marrow_assign_project_policy_profile') {
+                        const result = await (0, index_1.marrowAssignProjectPolicyProfile)(API_KEY, BASE_URL, {
+                            project_key: args.project_key,
+                            profile_id: args.profile_id,
+                        }, SESSION_ID, FLEET_AGENT_ID);
+                        success(id, { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] });
+                        return;
+                    }
+                    if (toolName === 'marrow_policy_resolve') {
+                        const result = await (0, index_1.marrowResolvePolicy)(API_KEY, BASE_URL, {
+                            profile_id: args.profile_id,
+                            profile_name: args.profile_name,
+                            project: args.project && typeof args.project === 'object' && !Array.isArray(args.project)
+                                ? (0, redact_1.redactSensitiveValue)(args.project)
+                                : undefined,
+                            workflow: args.workflow && typeof args.workflow === 'object' && !Array.isArray(args.workflow)
+                                ? (0, redact_1.redactSensitiveValue)(args.workflow)
+                                : undefined,
+                            agent: args.agent && typeof args.agent === 'object' && !Array.isArray(args.agent)
+                                ? (0, redact_1.redactSensitiveValue)(args.agent)
+                                : { id: FLEET_AGENT_ID || AGENT_ID },
+                        }, SESSION_ID, FLEET_AGENT_ID);
+                        success(id, { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] });
+                        return;
+                    }
                     if (toolName === 'marrow_workflow_gate') {
                         const result = await (0, index_1.marrowWorkflowGate)(API_KEY, BASE_URL, {
                             action: (0, redact_1.redactSensitiveText)(args.action),