pluribus-context 0.3.38 → 0.3.40

package/CHANGELOG.md

@@ -4,6 +4,15 @@
 
 All notable changes to Pluribus are documented here.
 
+## 0.3.40 - 2026-06-09
+
+- Added `pluribus demo tool-surface-diff`, a tiny npm-runnable MCP dynamic-discovery receipt demo for proving discovered, activated, withheld, and blocked runtime tool-surface changes without logging raw schemas, prompts, or results.
+- Expanded npm discovery keywords around MCP audit, gateways, security, tool discovery, and audit trails so the package is easier to find from the market lane now forming around MCP governance.
+
+## 0.3.39 - 2026-06-07
+
+- Added `pluribus demo mcp-telemetry-import`, a tiny npm-runnable converter from MCP `rpc-messages.jsonl`-style JSON-RPC traces into privacy-safe audit receipts that preserve attribution, redacted shapes, status, and timing gaps without storing raw tool payloads.
+
 ## 0.3.38 - 2026-06-06
 
 - Added `pluribus demo mcp-audit-receipt`, a tiny npm-runnable demo that validates privacy-safe MCP tool-call audit events and low-cardinality usage metrics without logging raw prompts, args, results, tokens, or row data.

package/README.md

@@ -14,7 +14,7 @@ The original sync workflow is still useful: Pluribus can keep project instructio
 
 It is **not** a persistent memory layer, retrieval system, agent orchestrator, enterprise ContextOps platform, or agent-merging framework. Think evidence for context boundaries: `CLAUDE.md`, `.cursorrules`, `copilot-instructions.md`, `AGENTS.md`, MCP Tool Search, Agent Skills, RAG/code-search, pruning, and compaction — with privacy-safe receipts instead of raw content dumps.
 
-**Reviewer shortcut:** evaluating Pluribus for a list, newsletter, package roundup, or tool directory? Use the [Community Review Packet](docs/community-review-packet.md) for copy-paste directory submission fields, safety/removability notes, feedback links, and disposable 60-second smoke tests. If you only run one command for the cross-tool audit, try `npx --yes pluribus-context@latest audit --json --fidelity-report` to see native discovery surfaces, generic fallbacks, load evidence, duplicate-load selection evidence, manual activation requirements, effective context scope, and semantic differences. For the agent-observability wedge, start with [context-budget receipts](docs/context-budget-receipts.md): privacy-safe evidence for what MCP schemas, skills, memory, subagents, CLI help, retrieval chunks, pruning runs, or compaction summaries crossed an agent boundary. If you want the same idea as a copyable skill, use the [context-receipts Agent Skill recipe](skills/context-receipts/). npm `latest` is currently aligned with the GitHub release; the review packet also documents a GitHub-release smoke fallback for future release-lag windows.
+**Reviewer shortcut:** evaluating Pluribus for a list, newsletter, package roundup, or tool directory? Use the [Community Review Packet](docs/community-review-packet.md) for copy-paste directory submission fields, safety/removability notes, feedback links, and disposable 60-second smoke tests. If you only run one command for the cross-tool audit, try `npx --yes pluribus-context@latest audit --json --fidelity-report` to see native discovery surfaces, generic fallbacks, load evidence, duplicate-load selection evidence, manual activation requirements, effective context scope, and semantic differences. For the agent-observability wedge, start with [context-budget receipts](docs/context-budget-receipts.md): privacy-safe evidence for what MCP schemas, skills, memory, subagents, CLI help, retrieval chunks, pruning runs, or compaction summaries crossed an agent boundary. It now explicitly covers the "Tool Search fixed MCP bloat" objection: the receipt proves which lane stayed deferred, which tool was expanded, and whether schemas leaked through `messages`/bootstrap anyway. For a 60-second runtime-discovery proof, run `npx --yes pluribus-context@latest demo tool-surface-diff --json`; it validates a receipt for discovered → activated → withheld/blocked MCP tools without raw schemas/prompts/results. If you want the same idea as a copyable skill, use the [context-receipts Agent Skill recipe](skills/context-receipts/). npm `latest` is currently aligned with the GitHub release; the review packet also documents a GitHub-release smoke fallback for future release-lag windows.
 
 ---
 

package/bin/pluribus.js

@@ -68,6 +68,7 @@ OPTIONS (watch)
 
 OPTIONS (demo)
   --receipt       Validate a custom demo receipt JSON file
+  --input         Import a custom demo input file, such as rpc-messages.jsonl
   --json          Print machine-readable demo results
 
 EXAMPLES
@@ -91,6 +92,10 @@ EXAMPLES
   pluribus demo skill-use-rate --json
   pluribus demo mcp-audit-receipt
   pluribus demo mcp-audit-receipt --json
+  pluribus demo mcp-telemetry-import
+  pluribus demo mcp-telemetry-import --json
+  pluribus demo tool-surface-diff
+  pluribus demo tool-surface-diff --json
 
 DOCS
   https://github.com/caioribeiroclw-pixel/pluribus
@@ -102,7 +107,7 @@ const COMMAND_FLAGS = {
   validate: new Set(['source', 'update-imports']),
   audit: new Set(['source', 'tools', 'update-imports', 'strict', 'ci', 'json', 'output', 'github-annotations', 'fidelity-report']),
   watch: new Set(['source', 'tools', 'update-imports', 'dry-run', 'once', 'debounce']),
-  demo: new Set(['receipt', 'json']),
+  demo: new Set(['receipt', 'input', 'json']),
 }
 
 function getFlagNames(argv) {

package/docs/context-budget-receipts.md

@@ -8,6 +8,49 @@ This is different from generic token accounting. A context-budget receipt should
 
 If you want a copyable Agent Skill recipe instead of a spec-style guide, see [`skills/context-receipts/`](../skills/context-receipts/). It turns the receipt pattern into a 60-second smoke checklist for Tool Search, skills, and subagent boundaries.
 
+## If Tool Search already fixed the bloat
+
+Modern hosts can defer large MCP catalogs behind Tool Search or similar lazy discovery. That changes the receipt question; it does not remove it.
+
+Do not use a context-budget receipt to re-prove that every schema was smaller than before. Use it to prove the boundary that lazy loading promised:
+
+- the catalog/index was loaded instead of full definitions;
+- the selected query loaded only the matching tool definitions;
+- unselected tool groups stayed deferred or withheld;
+- a schema did not enter a side lane such as `messages`, subagent bootstrap, skill preamble, or memory hydration; and
+- the receipt records what evidence is missing when only fallback client telemetry exists.
+
+This makes the receipt useful in the common objection case: "MCP context bloat is solved by Tool Search." A good receipt should answer: **solved where, for this turn, through which lane, and with what proof?**
+
+Runnable fixture for the normal happy path:
+
+```bash
+node examples/context-input-evidence/convert-mcp-tool-search-log.mjs
+```
+
+Public trace:
+
+- `examples/context-input-evidence/mcp-tool-search-otel-trace.json`
+
+Minimum hidden-bypass fields for managed seats or gateways:
+
+```json
+{
+  "event.name": "mcp.deferral.evaluated",
+  "mcp.defer_loading.enabled": true,
+  "mcp.catalog.deferred": true,
+  "mcp.tool_search.selected_tool_count": 0,
+  "context.messages.remote_mcp_schema_count_bucket": "over_25",
+  "context.messages.delta_token_bucket": "under_100k",
+  "context.attribution": "remote_mcp_schema_in_messages",
+  "expected_behavior": "deferred_until_tool_search_match",
+  "verdict": "deferral_bypassed",
+  "privacy.raw_schema_included": false
+}
+```
+
+That shape deliberately avoids raw schema bodies, connector names, private URLs, and prompt text. It proves attribution, not whether the selected tool was semantically optimal.
+
 ## When to use this receipt
 
 Use a context-budget receipt when a coding agent looks lazy, fails with `prompt is too long`, or returns a tiny summary after a subagent/tool-heavy step and you need to distinguish:

package/examples/mcp-telemetry-import/README.md

@@ -0,0 +1,27 @@
+# MCP telemetry import demo
+
+This example converts a tiny MCP `rpc-messages.jsonl`-style trace into the same privacy-safe audit receipt shape used by `pluribus demo mcp-audit-receipt`.
+
+Run from any directory after `pluribus-context@latest` includes this demo:
+
+```bash
+npx --yes pluribus-context@latest demo mcp-telemetry-import
+npx --yes pluribus-context@latest demo mcp-telemetry-import --json
+```
+
+Or convert your own log:
+
+```bash
+npx --yes pluribus-context@latest demo mcp-telemetry-import --input ./rpc-messages.jsonl --json
+```
+
+The point is not to store raw MCP payloads forever. The import keeps only:
+
+- request/session IDs;
+- hashed user/token subjects;
+- token scopes;
+- tool name;
+- redacted argument/result shape;
+- status, duration if timestamps exist, and error class.
+
+If only fallback `rpc-messages.jsonl` exists, the receipt can still prove tool-call attribution. If gateway telemetry is absent, latency/status coverage should be marked as a gap instead of silently implied.

package/examples/mcp-telemetry-import/sample-rpc-messages.jsonl

@@ -0,0 +1,4 @@
+{"timestamp":"2026-06-07T13:00:00.000Z","direction":"client_to_server","session_id":"sess_demo","user_id":"user-123","token_subject":"oauth-subject-456","token_scopes":["repo:read"],"message":{"jsonrpc":"2.0","id":"1","method":"tools/call","params":{"name":"github.search_issues","arguments":{"query":"repo:org/app label:bug MCP audit","limit":5}}}}
+{"timestamp":"2026-06-07T13:00:00.142Z","direction":"server_to_client","session_id":"sess_demo","message":{"jsonrpc":"2.0","id":"1","result":{"content":[{"type":"text","text":"2 issues found"}],"isError":false}}}
+{"timestamp":"2026-06-07T13:00:02.000Z","direction":"client_to_server","session_id":"sess_demo","user_id":"user-123","token_subject":"oauth-subject-456","token_scopes":["repo:read"],"message":{"jsonrpc":"2.0","id":"2","method":"tools/call","params":{"name":"github.create_issue","arguments":{"repo":"org/app","title":"Add audit log","body":"redacted before receipt export"}}}}
+{"timestamp":"2026-06-07T13:00:02.019Z","direction":"server_to_client","session_id":"sess_demo","message":{"jsonrpc":"2.0","id":"2","error":{"code":"insufficient_scope","message":"write scope required"}}}

package/examples/tool-surface-diff-receipts/tool-surface-diff-receipt.json

@@ -0,0 +1,61 @@
+{
+  "schema": "pluribus.mcp_tool_surface_diff_receipt.v1",
+  "run_id": "tool-surface-diff-demo",
+  "generated_at": "2026-06-09T13:00:00Z",
+  "platform": {
+    "name": "enterprise-mcp-dynamic-discovery",
+    "audit_sink": "admin-center-or-siem"
+  },
+  "catalog": {
+    "server_id": "mcp://sales-ops-gateway",
+    "previous_hash": "sha256:previous-catalog-redacted",
+    "current_hash": "sha256:current-catalog-redacted"
+  },
+  "runtime_discovery": {
+    "enabled": true,
+    "trigger": "runtime_tool_catalog_diff"
+  },
+  "privacy_boundary": {
+    "raw_schemas": "omitted_hash_only",
+    "raw_prompts": "omitted",
+    "raw_results": "omitted"
+  },
+  "tools": [
+    {
+      "tool_id": "tool:crm.search_accounts",
+      "name_hash": "sha256:0cc2efb4a26f4c5eb4f7d8c99e78d37adbdba07d50ee7873452c0216d02b1f48",
+      "schema_hash": "sha256:6f4fbe0a8be41b6e29c0c1c113aac38dfefdd12b89c6e9d4a996df2537acdb71",
+      "status": "activated",
+      "validation_outcome": "accepted",
+      "diff_summary": {
+        "added_fields": 1,
+        "removed_fields": 0,
+        "changed_fields": 0
+      }
+    },
+    {
+      "tool_id": "tool:crm.export_contacts",
+      "name_hash": "sha256:f38f53f9ba3c348e67332a24a7d15f5e7ab1c9253cf01f3451e15d9e15435e13",
+      "schema_hash": "sha256:95ddc9b86a0c2d8bc6f3ca0bcce93dca2469ced51b0d38c8f8c5aa88554e0032",
+      "status": "blocked",
+      "validation_outcome": "blocked_by_rai",
+      "diff_summary": {
+        "added_fields": 4,
+        "removed_fields": 0,
+        "changed_fields": 2
+      }
+    },
+    {
+      "tool_id": "tool:billing.refund_invoice",
+      "name_hash": "sha256:abfdaf6f0a3f33342aca6d8b0d63c303e99978481d26827843a901cb6237617d",
+      "schema_hash": "sha256:3b4fdc3ec15d2fa1cc589c1c7de280a19772d5745b4ef54d27806714be12bb8c",
+      "status": "withheld",
+      "validation_outcome": "entitlement_filtered",
+      "diff_summary": {
+        "added_fields": 0,
+        "removed_fields": 0,
+        "changed_fields": 0
+      }
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pluribus-context",
-  "version": "0.3.38",
+  "version": "0.3.40",
   "description": "AI context and rules sync CLI for Claude.md, Claude Code, Cursor, and Copilot instructions, with privacy-safe context receipts that prove what memory, tools, skills, compactions, and security findings crossed agent boundaries without logging raw content.",
   "type": "module",
   "homepage": "https://github.com/caioribeiroclw-pixel/pluribus#readme",
@@ -68,6 +68,11 @@
     "ai-agent-observability",
     "opentelemetry",
     "mcp",
+    "mcp-audit",
+    "mcp-gateway",
+    "mcp-security",
+    "tool-discovery",
+    "audit-trail",
     "drift-detection",
     "openclaw",
     "rules",

package/src/commands/demo.js

@@ -4,14 +4,18 @@
 
 import * as fs from 'fs'
 import * as path from 'path'
+import { createHash } from 'crypto'
 import { fileURLToPath } from 'url'
 
 const DEFAULT_DEMO = 'skill-use-rate'
 const SKILL_USE_RATE_DEMO = 'skill-use-rate'
 const MCP_AUDIT_RECEIPT_DEMO = 'mcp-audit-receipt'
-const AVAILABLE_DEMOS = [SKILL_USE_RATE_DEMO, MCP_AUDIT_RECEIPT_DEMO]
+const MCP_TELEMETRY_IMPORT_DEMO = 'mcp-telemetry-import'
+const TOOL_SURFACE_DIFF_DEMO = 'tool-surface-diff'
+const AVAILABLE_DEMOS = [SKILL_USE_RATE_DEMO, MCP_AUDIT_RECEIPT_DEMO, MCP_TELEMETRY_IMPORT_DEMO, TOOL_SURFACE_DIFF_DEMO]
 const SKILL_USE_RATE_SCHEMA = 'pluribus.skill_use_rate_receipt.v1'
 const MCP_AUDIT_RECEIPT_SCHEMA = 'pluribus.mcp_tool_call_audit_receipt.v1'
+const TOOL_SURFACE_DIFF_SCHEMA = 'pluribus.mcp_tool_surface_diff_receipt.v1'
 
 /**
  * @param {Record<string, string | boolean>} args
@@ -25,6 +29,10 @@ export async function runDemo(args, positional = []) {
       return runSkillUseRateDemo(args)
     case MCP_AUDIT_RECEIPT_DEMO:
       return runMcpAuditReceiptDemo(args)
+    case MCP_TELEMETRY_IMPORT_DEMO:
+      return runMcpTelemetryImportDemo(args)
+    case TOOL_SURFACE_DIFF_DEMO:
+      return runToolSurfaceDiffDemo(args)
     default:
       console.error(`❌ Unknown demo: ${demoName}`)
       console.error(`   Available demos: ${AVAILABLE_DEMOS.join(', ')}`)
@@ -82,6 +90,12 @@ function runSkillUseRateDemo(args) {
   if (result.errors.length > 0) process.exit(1)
 }
 
+function selectedInputPath(args, defaultPath) {
+  return typeof args.input === 'string' && args.input.trim()
+    ? path.resolve(process.cwd(), args.input)
+    : defaultPath
+}
+
 function runMcpAuditReceiptDemo(args) {
   const receiptPath = selectedReceiptPath(args, bundledMcpAuditReceiptPath())
   const receipt = readReceipt(receiptPath, 'MCP audit')
@@ -116,6 +130,56 @@ function runMcpAuditReceiptDemo(args) {
   if (result.errors.length > 0) process.exit(1)
 }
 
+
+function runMcpTelemetryImportDemo(args) {
+  const inputPath = selectedInputPath(args, bundledMcpTelemetryJsonlPath())
+  let logText
+  try {
+    logText = fs.readFileSync(inputPath, 'utf8')
+  } catch (err) {
+    console.error(`❌ Could not read MCP telemetry JSONL at ${inputPath}: ${err.message}`)
+    process.exit(1)
+  }
+
+  const imported = importMcpTelemetryJsonl(logText)
+  const result = validateMcpAuditReceipt(imported.receipt)
+  const warnings = [...imported.warnings, ...result.warnings]
+
+  if (Boolean(args.json)) {
+    console.log(JSON.stringify({
+      ok: result.errors.length === 0,
+      demo: MCP_TELEMETRY_IMPORT_DEMO,
+      input: path.relative(process.cwd(), inputPath) || inputPath,
+      summary: {
+        ...result.summary,
+        parsedEntryCount: imported.summary.parsedEntryCount,
+        matchedResponseCount: imported.summary.matchedResponseCount,
+        missingGatewayLatency: imported.summary.missingGatewayLatency,
+      },
+      receipt: imported.receipt,
+      warnings,
+      errors: result.errors,
+    }, null, 2))
+  } else {
+    console.log('🧪 Pluribus demo: MCP telemetry import')
+    console.log(`   Input: ${path.relative(process.cwd(), inputPath) || inputPath}`)
+    console.log('')
+
+    if (result.errors.length === 0) {
+      console.log(`✅ MCP telemetry imported: ${imported.summary.parsedEntryCount} JSONL entries → ${result.summary.toolCallCount} audit receipt tool calls`)
+      if (warnings.length > 0) for (const warning of warnings) console.log(`   • ${warning}`)
+      console.log('')
+      console.log('Why this matters: rpc-messages.jsonl is a useful fallback, but it usually proves tool-call attribution before it proves gateway latency. Convert raw JSON-RPC traces into privacy-safe receipts, then mark missing gateway evidence explicitly.')
+      console.log('Try your own log: pluribus demo mcp-telemetry-import --input path/to/rpc-messages.jsonl --json')
+    } else {
+      console.error('❌ MCP telemetry import produced an invalid receipt:')
+      for (const error of result.errors) console.error(`   • ${error}`)
+    }
+  }
+
+  if (result.errors.length > 0) process.exit(1)
+}
+
 function bundledSkillUseRateReceiptPath() {
   return fileURLToPath(new URL('../../examples/skill-use-rate-receipts/skill-use-rate-receipt.json', import.meta.url))
 }
@@ -124,6 +188,48 @@ function bundledMcpAuditReceiptPath() {
   return fileURLToPath(new URL('../../examples/mcp-audit-receipts/mcp-audit-receipt.json', import.meta.url))
 }
 
+function bundledMcpTelemetryJsonlPath() {
+  return fileURLToPath(new URL('../../examples/mcp-telemetry-import/sample-rpc-messages.jsonl', import.meta.url))
+}
+
+function bundledToolSurfaceDiffReceiptPath() {
+  return fileURLToPath(new URL('../../examples/tool-surface-diff-receipts/tool-surface-diff-receipt.json', import.meta.url))
+}
+
+function runToolSurfaceDiffDemo(args) {
+  const receiptPath = selectedReceiptPath(args, bundledToolSurfaceDiffReceiptPath())
+  const receipt = readReceipt(receiptPath, 'tool-surface diff')
+  const result = validateToolSurfaceDiffReceipt(receipt)
+
+  if (Boolean(args.json)) {
+    console.log(JSON.stringify({
+      ok: result.errors.length === 0,
+      demo: TOOL_SURFACE_DIFF_DEMO,
+      receipt: path.relative(process.cwd(), receiptPath) || receiptPath,
+      summary: result.summary,
+      warnings: result.warnings,
+      errors: result.errors,
+    }, null, 2))
+  } else {
+    console.log('🧪 Pluribus demo: MCP tool-surface diff receipt')
+    console.log(`   Receipt: ${path.relative(process.cwd(), receiptPath) || receiptPath}`)
+    console.log('')
+
+    if (result.errors.length === 0) {
+      console.log(`✅ tool-surface diff receipt ok: ${result.summary.discoveredCount} discovered, ${result.summary.activatedCount} activated, ${result.summary.withheldCount} withheld/blocked`)
+      for (const warning of result.warnings) console.log(`   • ${warning}`)
+      console.log('')
+      console.log('Why this matters: runtime MCP discovery changes the active tool surface. Persist a low-cardinality receipt of discovered → activated → withheld/blocked tools without logging raw schemas, prompts, or results.')
+      console.log('Try your own receipt: pluribus demo tool-surface-diff --receipt path/to/tool-surface-diff-receipt.json --json')
+    } else {
+      console.error('❌ tool-surface diff receipt invalid:')
+      for (const error of result.errors) console.error(`   • ${error}`)
+    }
+  }
+
+  if (result.errors.length > 0) process.exit(1)
+}
+
 export function validateSkillUseRateReceipt(receipt) {
   const errors = []
   const warnings = []
@@ -209,6 +315,172 @@ export function validateSkillUseRateReceipt(receipt) {
   }
 }
 
+
+export function importMcpTelemetryJsonl(logText) {
+  const warnings = []
+  const entries = []
+  const pending = new Map()
+  const toolCalls = []
+  let matchedResponseCount = 0
+  let missingGatewayLatency = true
+
+  for (const [lineIndex, rawLine] of logText.split(/\r?\n/).entries()) {
+    const line = rawLine.trim()
+    if (!line) continue
+    try {
+      const entry = JSON.parse(line)
+      entries.push(entry)
+      const message = unwrapMcpMessage(entry)
+      const timestamp = entry.timestamp || entry.time || message.timestamp || null
+
+      if (isToolCallRequest(message)) {
+        pending.set(String(message.id), { entry, message, timestamp, lineIndex })
+      } else if (message.id != null && pending.has(String(message.id))) {
+        const request = pending.get(String(message.id))
+        pending.delete(String(message.id))
+        matchedResponseCount++
+        const durationMs = durationBetween(request.timestamp, timestamp)
+        if (durationMs > 0) missingGatewayLatency = false
+        toolCalls.push(toolCallFromRequestResponse(request, message, durationMs))
+      }
+    } catch (err) {
+      warnings.push(`line ${lineIndex + 1} was skipped: invalid JSON (${err.message})`)
+    }
+  }
+
+  for (const request of pending.values()) {
+    toolCalls.push(toolCallFromRequestResponse(request, null, 0))
+  }
+
+  if (toolCalls.length === 0) warnings.push('no tools/call request/response pairs were found')
+  if (missingGatewayLatency) warnings.push('gateway.jsonl-style latency/status evidence is missing; fallback rpc-messages.jsonl can still prove tool-call attribution')
+
+  const receipt = {
+    schema: MCP_AUDIT_RECEIPT_SCHEMA,
+    run_id: 'mcp-telemetry-import-demo',
+    generated_at: '2026-06-07T13:00:00Z',
+    server: {
+      name: 'mcp-gateway-or-fallback-log',
+      transport: 'jsonrpc-jsonl',
+      version: 'unknown',
+    },
+    client: {
+      name: 'unknown-mcp-client',
+      workspace: 'redacted',
+    },
+    audit_policy: {
+      raw_arguments: 'redacted_shape_only',
+      raw_results: 'redacted_shape_only',
+      privacy_boundary: 'source JSONL may contain raw protocol data; receipt keeps only shapes, hashes, status, and timing evidence',
+    },
+    telemetry_source: {
+      kind: missingGatewayLatency ? 'rpc-messages.jsonl-fallback' : 'gateway-or-timestamped-jsonl',
+      parsed_entries: entries.length,
+      matched_responses: matchedResponseCount,
+    },
+    tool_calls: toolCalls,
+    usage_metrics: buildMcpUsageMetrics(toolCalls),
+  }
+
+  return {
+    receipt,
+    warnings,
+    summary: {
+      parsedEntryCount: entries.length,
+      matchedResponseCount,
+      missingGatewayLatency,
+    },
+  }
+}
+
+function unwrapMcpMessage(entry) {
+  return entry.message || entry.msg || entry.rpc || entry.jsonrpc_message || entry
+}
+
+function isToolCallRequest(message) {
+  return message && message.id != null && ['tools/call', 'tools.call', 'mcp.tools.call'].includes(message.method)
+}
+
+function toolCallFromRequestResponse(request, response, durationMs) {
+  const params = request.message.params || {}
+  const toolName = params.name || params.tool_name || params.tool || 'unknown_tool'
+  const status = response == null ? 'empty' : response.error ? 'error' : 'ok'
+  const resultShape = response == null ? 'missing_response' : response.error ? `error:${response.error.code || 'unknown'}` : shapeLabel(response.result)
+  const userSource = request.entry.user_id || request.entry.actor || request.entry.principal || request.entry.session_id || 'unknown-user'
+  const tokenSource = request.entry.token_subject || request.entry.token_id || request.entry.principal || 'unknown-token'
+
+  return {
+    event: 'mcp.tool_call',
+    request_id: String(request.message.id),
+    session_id: String(request.entry.session_id || request.entry.run_id || 'unknown-session'),
+    user_id_hash: privacyHash(userSource),
+    token_subject_hash: privacyHash(tokenSource),
+    token_scopes: Array.isArray(request.entry.token_scopes) && request.entry.token_scopes.length > 0 ? request.entry.token_scopes : ['unknown'],
+    tool_name: String(toolName),
+    args_shape: shapeObject(params.arguments || params.args || {}),
+    status,
+    duration_ms: Math.max(0, durationMs),
+    result_shape: resultShape,
+    error_class: response?.error ? String(response.error.code || response.error.message || 'mcp_error') : null,
+  }
+}
+
+function buildMcpUsageMetrics(toolCalls) {
+  const callsByStatus = new Map()
+  for (const call of toolCalls) {
+    const key = `${call.tool_name}:${call.status}:${call.token_scopes[0] || 'unknown'}`
+    callsByStatus.set(key, (callsByStatus.get(key) || 0) + 1)
+  }
+  const metrics = [...callsByStatus.entries()].map(([key, value]) => ({
+    name: 'mcp_tool_calls_total',
+    type: 'counter',
+    value: String(value),
+    labels: ['tool_name', 'status', 'token_scope'],
+    dimensions: key,
+  }))
+  const durations = toolCalls.filter((call) => call.duration_ms > 0)
+  if (durations.length > 0) {
+    metrics.push({
+      name: 'mcp_tool_call_duration_ms',
+      type: 'histogram',
+      value: String(Math.round(durations.reduce((sum, call) => sum + call.duration_ms, 0) / durations.length)),
+      labels: ['tool_name', 'status'],
+    })
+  }
+  return metrics.length > 0 ? metrics : [{ name: 'mcp_tool_calls_total', type: 'counter', value: '0', labels: ['tool_name', 'status'] }]
+}
+
+function durationBetween(start, end) {
+  if (!start || !end) return 0
+  const started = Date.parse(start)
+  const ended = Date.parse(end)
+  if (Number.isNaN(started) || Number.isNaN(ended) || ended < started) return 0
+  return ended - started
+}
+
+function privacyHash(value) {
+  return `sha256:${createHash('sha256').update(String(value)).digest('hex')}`
+}
+
+function shapeObject(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {}
+  return Object.fromEntries(Object.entries(value).map(([key, nested]) => [key, shapeLabel(nested)]))
+}
+
+function shapeLabel(value) {
+  if (value === null) return 'null'
+  if (Array.isArray(value)) return `array:${value.length}`
+  if (typeof value === 'object') return `object:${Object.keys(value).length}`
+  if (typeof value === 'string') return looksSensitive(value) ? 'redacted_string' : 'string'
+  if (typeof value === 'number') return 'number'
+  if (typeof value === 'boolean') return 'boolean'
+  return typeof value
+}
+
+function looksSensitive(value) {
+  return /select\s|insert\s|update\s|delete\s|token|secret|password|bearer/i.test(value)
+}
+
 export function validateMcpAuditReceipt(receipt) {
   const errors = []
   const warnings = []
@@ -307,3 +579,80 @@ export function validateMcpAuditReceipt(receipt) {
     },
   }
 }
+
+
+export function validateToolSurfaceDiffReceipt(receipt) {
+  const errors = []
+  const warnings = []
+
+  function requireString(value, field) {
+    if (typeof value !== 'string' || value.trim() === '') errors.push(`${field} must be a non-empty string`)
+  }
+  function requireBoolean(value, field) {
+    if (typeof value !== 'boolean') errors.push(`${field} must be boolean`)
+  }
+  function requireNonNegativeInteger(value, field) {
+    if (!Number.isInteger(value) || value < 0) errors.push(`${field} must be a non-negative integer`)
+  }
+  function requireArray(value, field) {
+    if (!Array.isArray(value) || value.length === 0) errors.push(`${field} must be a non-empty array`)
+  }
+
+  if (receipt.schema !== TOOL_SURFACE_DIFF_SCHEMA) errors.push(`schema must be ${TOOL_SURFACE_DIFF_SCHEMA}`)
+  requireString(receipt.run_id, 'run_id')
+  requireString(receipt.generated_at, 'generated_at')
+  requireString(receipt.platform?.name, 'platform.name')
+  requireString(receipt.platform?.audit_sink, 'platform.audit_sink')
+  requireString(receipt.catalog?.server_id, 'catalog.server_id')
+  requireString(receipt.catalog?.previous_hash, 'catalog.previous_hash')
+  requireString(receipt.catalog?.current_hash, 'catalog.current_hash')
+  requireBoolean(receipt.runtime_discovery?.enabled, 'runtime_discovery.enabled')
+  requireString(receipt.runtime_discovery?.trigger, 'runtime_discovery.trigger')
+  requireArray(receipt.tools, 'tools')
+  requireString(receipt.privacy_boundary?.raw_schemas, 'privacy_boundary.raw_schemas')
+  requireString(receipt.privacy_boundary?.raw_prompts, 'privacy_boundary.raw_prompts')
+  requireString(receipt.privacy_boundary?.raw_results, 'privacy_boundary.raw_results')
+
+  if (receipt.privacy_boundary?.raw_schemas !== 'omitted_hash_only') errors.push('privacy_boundary.raw_schemas must be omitted_hash_only')
+  if (receipt.privacy_boundary?.raw_prompts !== 'omitted') errors.push('privacy_boundary.raw_prompts must be omitted')
+  if (receipt.privacy_boundary?.raw_results !== 'omitted') errors.push('privacy_boundary.raw_results must be omitted')
+
+  const statuses = new Set(['discovered', 'activated', 'withheld', 'blocked', 'removed'])
+  const outcomes = new Set(['accepted', 'blocked_by_rai', 'blocked_by_xpia', 'schema_invalid', 'entitlement_filtered', 'not_selected', 'removed'])
+  let discoveredCount = 0
+  let activatedCount = 0
+  let withheldCount = 0
+  let rawLeakCount = 0
+
+  for (const [index, tool] of (receipt.tools || []).entries()) {
+    const prefix = `tools[${index}]`
+    requireString(tool.tool_id, `${prefix}.tool_id`)
+    requireString(tool.name_hash, `${prefix}.name_hash`)
+    requireString(tool.schema_hash, `${prefix}.schema_hash`)
+    requireString(tool.status, `${prefix}.status`)
+    requireString(tool.validation_outcome, `${prefix}.validation_outcome`)
+    requireNonNegativeInteger(tool.diff_summary?.added_fields, `${prefix}.diff_summary.added_fields`)
+    requireNonNegativeInteger(tool.diff_summary?.removed_fields, `${prefix}.diff_summary.removed_fields`)
+    requireNonNegativeInteger(tool.diff_summary?.changed_fields, `${prefix}.diff_summary.changed_fields`)
+
+    if (!statuses.has(tool.status)) errors.push(`${prefix}.status must be one of ${[...statuses].join('|')}`)
+    if (!outcomes.has(tool.validation_outcome)) errors.push(`${prefix}.validation_outcome must be one of ${[...outcomes].join('|')}`)
+    if (!String(tool.name_hash || '').startsWith('sha256:')) errors.push(`${prefix}.name_hash must be a sha256: hash, not a raw tool name`)
+    if (!String(tool.schema_hash || '').startsWith('sha256:')) errors.push(`${prefix}.schema_hash must be a sha256: hash, not a raw schema`)
+    if (typeof tool.raw_schema === 'string' || typeof tool.description === 'string') rawLeakCount++
+
+    if (['discovered', 'activated', 'withheld', 'blocked'].includes(tool.status)) discoveredCount++
+    if (tool.status === 'activated') activatedCount++
+    if (['withheld', 'blocked'].includes(tool.status)) withheldCount++
+  }
+
+  if (rawLeakCount > 0) errors.push(`tools must not include raw_schema or description (${rawLeakCount} raw fields found)`)
+  if (activatedCount === 0) warnings.push('no activated tools recorded; receipt may only prove discovery/withholding')
+  if (withheldCount === 0) warnings.push('no withheld/blocked tools recorded; receipt does not prove negative space')
+
+  return {
+    errors,
+    warnings,
+    summary: { discoveredCount, activatedCount, withheldCount },
+  }
+}

package/src/utils/version.js

@@ -1 +1 @@
-export const VERSION = '0.3.38'
+export const VERSION = '0.3.40'