pluribus-context 0.3.39 → 0.3.40

package/CHANGELOG.md

@@ -4,6 +4,11 @@
 
 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.

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

@@ -94,6 +94,8 @@ EXAMPLES
   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

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/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.39",
+  "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

@@ -11,9 +11,11 @@ const DEFAULT_DEMO = 'skill-use-rate'
 const SKILL_USE_RATE_DEMO = 'skill-use-rate'
 const MCP_AUDIT_RECEIPT_DEMO = 'mcp-audit-receipt'
 const MCP_TELEMETRY_IMPORT_DEMO = 'mcp-telemetry-import'
-const AVAILABLE_DEMOS = [SKILL_USE_RATE_DEMO, MCP_AUDIT_RECEIPT_DEMO, MCP_TELEMETRY_IMPORT_DEMO]
+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
@@ -29,6 +31,8 @@ export async function runDemo(args, positional = []) {
       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(', ')}`)
@@ -188,6 +192,44 @@ 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 = []
@@ -537,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.39'
+export const VERSION = '0.3.40'