@getmarrow/mcp 3.9.76 → 3.9.78

package/README.md

@@ -87,6 +87,18 @@ For most new installations, start with the universal installer instead:
 npx @getmarrow/install activate
 ```
 
+## Tool Profiles
+
+Ordinary setup does not require `MARROW_TOOL_PROFILE`. When the variable is unset, Marrow uses the `primary` profile and exposes exactly the 17 tools in [Primary MCP Tools](#primary-mcp-tools).
+
+- `MARROW_TOOL_PROFILE=primary` explicitly selects the same 17-tool primary surface.
+- `MARROW_TOOL_PROFILE=core` preserves the seven-tool runtime, think, commit, ask, status, auto, and handoff-status surface.
+- `MARROW_TOOL_PROFILE=full` exposes the complete advanced and legacy catalog for integrations that require it.
+
+An invalid value returns a bounded configuration error with the exact allowed values; it never falls back to `full`. Restart the MCP process after changing the profile.
+
+Local visibility does not grant paid access. Every tool call continues through Marrow's backend authentication, tenant, key-permission, plan, proof, and policy enforcement. MCP status responses include `mcp_tool_profile` with the configured and effective profile, visible tool names/count, and a backend primary-tool entitlement projection when fresh authenticated evidence is provided. Missing or cached entitlement evidence is labeled unavailable and cannot authorize a call.
+
 ## Keeping MCP Current
 
 Marrow's hosted API, website, and dashboard update automatically; local MCP hooks, configuration, and pinned package commands do not silently rewrite themselves. Keeping them current delivers new client-side features, compatibility improvements, and any published security fixes. During authenticated status/runtime activity, Marrow returns a `client_update` notice when the package is behind or unknown, and passive context shows the agent the exact update and verification commands.
@@ -104,7 +116,15 @@ npx -y --package=@getmarrow/mcp@latest marrow-mcp 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.76
+## What's New in v3.9.78
+
+v3.9.78 separates durable post-action observation from action authorization. For outcome closure only, `marrow_commit` sends the existing `decision_id` to runtime and can use the backend's exact `outcome_observation_only` response to submit the already-completed result without forwarding its non-durable correlation ID as receipt evidence. That response never permits an action: it has `allow: false`, `durable: false`, and no authorization. The accepted result remains `committed: false`, `outcome_state: "observed_unverified"`, `authorization_granted: false`, and `trusted_learning_applied: false`; it is terminal delivery and is not retried from the local queue. Trusted promotion requires an explicit new commit attempt with the backend-required authorization and proof for the exact observed payload. Missing, malformed, conflicting, or cross-scope runtime truth still fails closed, and privacy-unsafe `instruction_ref` values such as dates and long numeric IDs now fail locally before any network call.
+
+## Previous: v3.9.77
+
+v3.9.77 makes `primary` the ordinary MCP profile when `MARROW_TOOL_PROFILE` is unset. The default surface now matches the 17 documented Primary MCP Tools, while explicit `core` preserves the seven-tool control loop and explicit `full` preserves the complete catalog. Invalid values fail with an exact bounded repair instead of broadening visibility. Status responses report the effective profile, visible names/count, and fresh backend-projected entitlement states when provided; local visibility and cached evidence never authorize access. The exact-version 11-tool control-path canary remains pinned to `full`.
+
+## Previous: v3.9.76
 
 v3.9.76 fixes owner-approved `marrow_auto` closeout by binding an arbitrated operation to the exact server-created arbitration decision, rejecting decision mismatches before commit, and returning an honest terminal action for non-arbitrated `review_required` gates. Chat and proof text cannot substitute for a dashboard-issued approval receipt, and only a backend `committed: true` response closes the operation.
 
@@ -197,7 +217,7 @@ v3.9.62 integrates four model-neutral reliability and capability contracts:
 - `spool-status` and `drain-spool` report the active credential namespace separately from isolated legacy debt, and a clear active namespace exits successfully without replaying, merging, editing, or deleting old-key files;
 - initialize, prompt, setup, and tool responses qualify coverage by `host_capability`: MCP tools are on demand, while client-self-reported hook activity remains visible but never certifies coverage or control.
 
-The default surface is seven tools (runtime, think, commit, ask, status, auto, handoff status) and the prompt remains named `marrow-always-on`. Host and model labels are display-only and never change auth, tenant, plan, policy, proof, schema, or API behavior. Grok hook activity is client-self-reported and does not certify observed coverage; the governed wrapper remains an explicit bounded fallback.
+In v3.9.62, the default surface was seven tools (runtime, think, commit, ask, status, auto, handoff status) and the prompt remained named `marrow-always-on`. Host and model labels are display-only and never change auth, tenant, plan, policy, proof, schema, or API behavior. Grok hook activity is client-self-reported and does not certify observed coverage; the governed wrapper remains an explicit bounded fallback.
 
 ## Previous: v3.9.61
 
@@ -251,7 +271,7 @@ The compact agent control path introduced in v3.9.57 remains the default:
 - `marrow_status`, `marrow_ask`, and `marrow_agent_runtime` use authenticated routes with bounded retries and typed failures;
 - transient read failures return an owner-only last-known brief when available, while cached guidance can never authorize high-risk work;
 - normal tool errors return structured `ok`, `error_code`, `exact_fix`, `stale_brief`, and `client_update` data instead of raw MCP `fetch failed` errors;
-- the default agent surface is seven tools: runtime, think, commit, ask, status, auto, and handoff status; set `MARROW_TOOL_PROFILE=full` only for legacy or advanced integrations;
+- the v3.9.58 default agent surface was seven tools: runtime, think, commit, ask, status, auto, and handoff status; `MARROW_TOOL_PROFILE=full` selected legacy or advanced integrations;
 - risky `marrow_auto` calls obtain a fresh runtime gate automatically and cannot self-close as successful without required proof;
 - `marrow_run` requires an explicit outcome and never invents proof or a successful result;
 - the package includes an exact-version control-path canary covering every route reported in the production incident.
@@ -357,6 +377,8 @@ Configured hooks can provide cooperative telemetry and context, but they are not
 
 `marrow_agent_runtime` returns `runtime_authorization` with the authoritative gate receipt. Ordinary runtime checks do not create a decision, so they omit `decision_id`; call `marrow_think` (or use `marrow_auto`) when a decision must be created and closed. An arbitration runtime that actually creates a decision returns that server-created `decision_id`. This contract is identical across MCP-compatible hosts and SDK-owned runtimes.
 
+A `review_required`, `block`, or `outcome_observation_only` result never permits the action. If the action already occurred and its real result must be preserved, `marrow_commit` can ask runtime to bind observation delivery to the existing decision, action, session, and agent. The exact backend `outcome_observation_only` correlation is non-durable and non-authorizing, so MCP never sends it as a gate, arbitration, or owner-approval receipt. An accepted observation reports `committed: false`, `outcome_state: "observed_unverified"`, `authorization_granted: false`, and `trusted_learning_applied: false`, plus the backend's `exact_next_action`. This is durable delivery, so do not retry or spool the same observation. To promote it into trusted learning, obtain the named authorization and proof, then make an explicit new commit attempt using the exact observed payload. Never synthesize a decision, receipt, approval, or authorization.
+
 `marrow_auto` returns an `operation_id`, phase, and resumable state. If a client deadline is reached before closure, retry with the same `operation_id`; Marrow reuses the same tenant-scoped runtime authorization, decision, and commit idempotency keys instead of opening another decision. When the phase is `proof_required`, add the requested proof and retry with that same operation ID and unchanged action/context/surfaces. An arbitrated runtime binds the operation directly to the arbitration response's server-created `decision_id`; `marrow_auto` does not open a separate decision. When an arbitrated result returns `owner_approval_required`, do not retry proof: approve that exact arbitration decision in an authenticated Marrow dashboard, then call `marrow_auto` once with the same operation ID, `arbitration_receipt_id`, and server-issued `owner_approval_receipt_id`. A non-arbitrated `review_required` result is terminal for that operation because the backend cannot issue a compatible dashboard receipt; start a new supported `marrow_arbitrate` review instead. Chat or proof text is never an approval receipt. Proof and receipts are validated and bound at commit; changing the tenant or action scope is rejected. A closed response reports `phase: "closed"`, `committed: true`, and `resumable: false`.
 
 Example pre-action request:

package/dist/cli.js

@@ -544,6 +544,7 @@ if (process.argv[2] !== 'keys') {
                     drain_command: 'npx -y --package=@getmarrow/mcp@latest marrow-mcp drain-spool',
                     legacy_namespaces: spool.other_namespaces?.count || 0,
                 },
+                mcp_tool_profile: mcpToolProfileStatus(payload),
             };
         }
         // [FIX #9] Runtime validation helper for required string params
@@ -840,7 +841,7 @@ if (process.argv[2] !== 'keys') {
                             description: 'Optional provenance source. Defaults to agent_autonomous for MCP calls.',
                         },
                         human_directed: { type: 'boolean', description: 'True only when the action is directly requested by the owner/user.' },
-                        instruction_ref: { type: 'string', description: 'Optional opaque non-PII instruction reference.' },
+                        instruction_ref: { type: 'string', description: 'Optional privacy-safe opaque reference. Dates, long digit runs, provider IDs, addresses, and domains are rejected locally; valid values are preserved exactly.' },
                         source_meta: { type: 'object', description: 'Optional provenance metadata. PII and raw provider IDs are rejected by the API.' },
                     },
                     required: ['action'],
@@ -851,7 +852,8 @@ if (process.argv[2] !== 'keys') {
                 description: 'Close a recorded action with success/failure, a specific outcome, and required proof. ' +
                     'decision_id comes from marrow_think, marrow_auto, or an arbitration runtime that actually created a decision. ' +
                     'Use the gate receipt from marrow_agent_runtime for consequential work. ' +
-                    'Outcome closure is required for accountable fleet learning.',
+                    'The exact non-authorizing outcome_observation_only runtime correlation may submit an observed_unverified result, but is never sent as receipt evidence and never authorizes action or trusted learning. ' +
+                    'Only committed:true closes trusted outcome learning.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -869,7 +871,7 @@ if (process.argv[2] !== 'keys') {
                         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.' },
+                        auto_gate: { type: 'boolean', description: 'If true/default and action is provided, fetch runtime truth bound to this existing decision. Authorizing receipts preserve normal closure; exact outcome_observation_only correlation can submit only an observed_unverified result and is omitted from receipt evidence.' },
                         model_usage: { type: 'object', description: 'Optional compact token/cost/latency counts. Do not include raw prompts or completions.' },
                     },
                     required: ['decision_id', 'success', 'outcome'],
@@ -1718,15 +1720,168 @@ if (process.argv[2] !== 'keys') {
             'marrow_auto',
             'marrow_handoff_status',
         ]);
+        const PRIMARY_TOOL_NAMES = new Set([
+            'marrow_agent_runtime',
+            'marrow_arbitrate',
+            'marrow_coordinate',
+            'marrow_replay_compare',
+            'marrow_decision_brief',
+            'marrow_think',
+            'marrow_commit',
+            'marrow_workflow_gate',
+            'marrow_completion_contracts',
+            'marrow_evaluate_completion_contract',
+            'marrow_agent_status',
+            'marrow_value_report',
+            'marrow_buyer_proof',
+            'marrow_governance_timeline',
+            'marrow_decision_trace',
+            'marrow_fleet_lessons',
+            'marrow_model_usage',
+        ]);
+        function activeToolProfile() {
+            const configured = process.env.MARROW_TOOL_PROFILE;
+            if (configured === undefined || configured === 'primary')
+                return 'primary';
+            if (configured === 'core' || configured === 'full')
+                return configured;
+            throw new Error('Invalid MARROW_TOOL_PROFILE value. Set MARROW_TOOL_PROFILE=primary, core, or full, '
+                + 'or unset it for primary; then restart MCP.');
+        }
+        function toolsForProfile(profile) {
+            if (profile === 'full')
+                return TOOLS;
+            const visibleNames = profile === 'primary' ? PRIMARY_TOOL_NAMES : CORE_TOOL_NAMES;
+            return TOOLS.filter((tool) => visibleNames.has(tool.name));
+        }
         function advertisedTools() {
-            return process.env.MARROW_TOOL_PROFILE === 'full'
-                ? TOOLS
-                : TOOLS.filter((tool) => CORE_TOOL_NAMES.has(tool.name));
+            return toolsForProfile(activeToolProfile());
         }
         function toolAllowedByActiveProfile(toolName) {
-            return process.env.MARROW_TOOL_PROFILE === 'full'
-                ? Boolean(toolName && TOOLS.some((tool) => tool.name === toolName))
-                : Boolean(toolName && CORE_TOOL_NAMES.has(toolName));
+            return Boolean(toolName && toolsForProfile(activeToolProfile()).some((tool) => tool.name === toolName));
+        }
+        function recordValue(value) {
+            return value && typeof value === 'object' && !Array.isArray(value)
+                ? value
+                : null;
+        }
+        function nonNegativeInteger(value) {
+            return Number.isInteger(value) && Number(value) >= 0;
+        }
+        function validatedPrimaryToolAvailability(value) {
+            const projection = recordValue(value);
+            const evidence = recordValue(projection?.entitlement_evidence);
+            const counts = recordValue(projection?.counts);
+            const tools = projection?.tools;
+            const expectedNames = [...PRIMARY_TOOL_NAMES];
+            if (!projection
+                || projection.profile !== 'primary'
+                || (projection.current_plan !== null && typeof projection.current_plan !== 'string')
+                || typeof projection.owner_management_url !== 'string'
+                || !evidence
+                || (evidence.state !== 'available' && evidence.state !== 'unavailable')
+                || typeof evidence.source !== 'string'
+                || typeof evidence.authoritative !== 'boolean'
+                || evidence.authorizing !== false
+                || !counts
+                || !nonNegativeInteger(counts.total)
+                || !nonNegativeInteger(counts.entitled)
+                || !nonNegativeInteger(counts.upgrade_required)
+                || !nonNegativeInteger(counts.unavailable)
+                || counts.total !== expectedNames.length
+                || counts.entitled + counts.upgrade_required + counts.unavailable !== counts.total
+                || !Array.isArray(tools)
+                || tools.length !== expectedNames.length) {
+                return null;
+            }
+            if ((evidence.state === 'available' && evidence.authoritative !== true)
+                || (evidence.state === 'unavailable' && evidence.authoritative !== false)) {
+                return null;
+            }
+            const derivedCounts = { entitled: 0, upgrade_required: 0, unavailable: 0 };
+            for (let index = 0; index < tools.length; index++) {
+                const tool = recordValue(tools[index]);
+                const state = tool?.state;
+                if (!tool
+                    || tool.name !== expectedNames[index]
+                    || (state !== 'entitled' && state !== 'upgrade_required' && state !== 'unavailable')
+                    || typeof tool.always_available !== 'boolean'
+                    || (tool.plan_feature !== null && typeof tool.plan_feature !== 'string')
+                    || (tool.minimum_plan !== null && typeof tool.minimum_plan !== 'string')
+                    || typeof tool.owner_management_url !== 'string') {
+                    return null;
+                }
+                derivedCounts[state]++;
+            }
+            if (derivedCounts.entitled !== counts.entitled
+                || derivedCounts.upgrade_required !== counts.upgrade_required
+                || derivedCounts.unavailable !== counts.unavailable) {
+                return null;
+            }
+            return {
+                projection,
+                evidenceState: evidence.state,
+            };
+        }
+        function backendPrimaryToolAvailability(value) {
+            const payload = recordValue(value);
+            if (!payload)
+                return null;
+            const data = recordValue(payload.data);
+            const status = recordValue(payload.status);
+            const entitlements = recordValue(payload.entitlements);
+            const entitlementProjection = recordValue(payload.entitlement_projection);
+            const statusEntitlements = recordValue(status?.entitlements);
+            const statusProjection = recordValue(status?.entitlement_projection);
+            const candidates = [
+                payload.primary_tool_availability,
+                data?.primary_tool_availability,
+                status?.primary_tool_availability,
+                entitlements?.primary_tool_availability,
+                entitlementProjection?.primary_tool_availability,
+                statusEntitlements?.primary_tool_availability,
+                statusProjection?.primary_tool_availability,
+            ];
+            for (const candidate of candidates) {
+                const validated = validatedPrimaryToolAvailability(candidate);
+                if (validated)
+                    return validated;
+            }
+            return null;
+        }
+        function mcpToolProfileStatus(value) {
+            const profile = activeToolProfile();
+            const visibleToolNames = toolsForProfile(profile).map((tool) => tool.name);
+            const payload = recordValue(value);
+            const cachedOrStale = payload?.cached === true
+                || payload?.stale === true
+                || payload?.status_freshness === 'stale';
+            const backendProjection = cachedOrStale ? null : backendPrimaryToolAvailability(payload);
+            const backendProjectionAvailable = backendProjection?.evidenceState === 'available';
+            return {
+                configured_profile: process.env.MARROW_TOOL_PROFILE ?? 'unset',
+                effective_profile: profile,
+                visible_tool_count: visibleToolNames.length,
+                visible_tool_names: visibleToolNames,
+                local_visibility_grants_entitlement: false,
+                backend_entitlement_projection: {
+                    evidence_state: backendProjectionAvailable ? 'available' : 'unavailable',
+                    source: cachedOrStale
+                        ? 'cached_or_stale_status'
+                        : backendProjection
+                            ? 'authenticated_backend'
+                            : 'backend_projection_not_provided',
+                    authorizes_calls: false,
+                    primary_tool_availability: backendProjectionAvailable ? backendProjection.projection : null,
+                },
+            };
+        }
+        function withMcpToolProfileStatus(value) {
+            const payload = recordValue(value) || { data: value };
+            return {
+                ...payload,
+                mcp_tool_profile: mcpToolProfileStatus(payload),
+            };
         }
         // Request handler
         async function handleRequest(req) {
@@ -1847,7 +2002,10 @@ Marrow is not a replacement agent or a standalone memory app. Context and prior
                     const toolName = params?.name;
                     const args = (params?.arguments || {});
                     if (!toolAllowedByActiveProfile(toolName)) {
-                        error(id, -32601, 'Tool is not available in the active Marrow tool profile. Set MARROW_TOOL_PROFILE=full and restart MCP for advanced operator tools.');
+                        const repair = toolName && PRIMARY_TOOL_NAMES.has(toolName)
+                            ? 'Unset MARROW_TOOL_PROFILE or set MARROW_TOOL_PROFILE=primary, then restart MCP.'
+                            : 'Set MARROW_TOOL_PROFILE=full, then restart MCP for the complete advanced/legacy catalog.';
+                        error(id, -32601, `Tool is not available in the active Marrow tool profile. ${repair}`);
                         return;
                     }
                     if (toolName === 'marrow_orient') {
@@ -2304,13 +2462,24 @@ Marrow is not a replacement agent or a standalone memory app. Context and prior
                         return;
                     }
                     if (toolName === 'marrow_agent_status') {
-                        const result = await (0, index_1.marrowAgentStatus)(API_KEY, BASE_URL, args.period || '7d', args.agentId || FLEET_AGENT_ID, SESSION_ID, FLEET_AGENT_ID);
-                        success(id, { content: [{ type: 'text', text: JSON.stringify({ ...result, local_control: (0, control_state_1.localControlEvidence)(Boolean(API_KEY)) }, null, 2) }] });
+                        const result = await withControlDeadline(async (signal) => {
+                            const [analyticsStatus, context] = await Promise.all([
+                                (0, index_1.marrowAgentStatus)(API_KEY, BASE_URL, args.period || '7d', args.agentId || FLEET_AGENT_ID, SESSION_ID, FLEET_AGENT_ID, signal),
+                                (0, index_1.marrowAgentContext)(API_KEY, BASE_URL, SESSION_ID, FLEET_AGENT_ID, signal)
+                                    .catch(() => null),
+                            ]);
+                            const contextProjection = recordValue(context)?.primary_tool_availability;
+                            return {
+                                ...analyticsStatus,
+                                ...(contextProjection === undefined ? {} : { primary_tool_availability: contextProjection }),
+                            };
+                        }, { cacheAware: false, toolName: 'marrow_agent_status' });
+                        success(id, { content: [{ type: 'text', text: JSON.stringify(withMcpToolProfileStatus({ ...result, local_control: (0, control_state_1.localControlEvidence)(Boolean(API_KEY)) }), null, 2) }] });
                         return;
                     }
                     if (toolName === 'marrow_runtime_status') {
                         const result = await withControlDeadline((signal) => (0, index_1.marrowRuntimeStatus)(API_KEY, BASE_URL, args.fast !== false, SESSION_ID, FLEET_AGENT_ID, signal), { cacheAware: false, toolName: 'marrow_runtime_status' });
-                        success(id, { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] });
+                        success(id, { content: [{ type: 'text', text: JSON.stringify(withMcpToolProfileStatus(result), null, 2) }] });
                         return;
                     }
                     if (toolName === 'marrow_value_report') {