pluribus-context 0.3.40 → 0.3.42

package/examples/task-scoped-mcp-config/select-mcp-config.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const args = new Map();
+for (let i = 2; i < process.argv.length; i += 1) {
+  const key = process.argv[i];
+  const value = process.argv[i + 1];
+  if (!key.startsWith('--') || value === undefined || value.startsWith('--')) {
+    throw new Error(`Expected --key value, got ${key}`);
+  }
+  args.set(key.slice(2), value);
+  i += 1;
+}
+
+const taskPath = args.has('task') ? resolve(process.cwd(), args.get('task')) : resolve(here, 'tasks/browser-debug.json');
+const catalogPath = args.has('catalog') ? resolve(process.cwd(), args.get('catalog')) : resolve(here, 'mcp-catalog.json');
+const outPath = args.has('out') ? resolve(process.cwd(), args.get('out')) : null;
+const receiptPath = args.has('receipt') ? resolve(process.cwd(), args.get('receipt')) : null;
+
+const catalog = JSON.parse(readFileSync(catalogPath, 'utf8'));
+const task = JSON.parse(readFileSync(taskPath, 'utf8'));
+const servers = new Map(catalog.servers.map((server) => [server.id, server]));
+const missing = task.includeServerIds.filter((id) => !servers.has(id));
+if (missing.length) {
+  throw new Error(`Task references unknown server ids: ${missing.join(', ')}`);
+}
+
+const selected = task.includeServerIds.map((id) => servers.get(id));
+const withheld = catalog.servers.filter((server) => !task.includeServerIds.includes(server.id));
+const mcpServers = Object.fromEntries(
+  selected.map((server) => [
+    server.id,
+    {
+      command: server.command,
+      args: server.args,
+    },
+  ]),
+);
+
+const config = { mcpServers };
+const receipt = {
+  schema: 'pluribus.task_scoped_mcp_config_receipt.v1',
+  task_id: task.taskId,
+  catalog_id: catalog.catalogId,
+  selected_server_ids: selected.map((server) => server.id),
+  withheld_server_ids: withheld.map((server) => server.id),
+  selected_estimated_schema_tokens: selected.reduce((sum, server) => sum + server.estimatedSchemaTokens, 0),
+  withheld_estimated_schema_tokens: withheld.reduce((sum, server) => sum + server.estimatedSchemaTokens, 0),
+  selection_reason: task.description,
+  withheld_reason: task.excludeReason,
+  raw_tool_schemas_logged: false,
+  raw_prompts_logged: false,
+  raw_tool_outputs_logged: false,
+  adoption_claim_allowed: false,
+  note: 'This proves only the task-scoped MCP config surface. It does not prove that the agent later called or adopted the selected tools.',
+};
+
+if (outPath) writeFileSync(outPath, `${JSON.stringify(config, null, 2)}\n`);
+if (receiptPath) writeFileSync(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`);
+
+console.log(JSON.stringify({ ok: true, config, receipt }, null, 2));

package/examples/task-scoped-mcp-config/tasks/browser-debug.json

@@ -0,0 +1,7 @@
+{
+  "schema": "pluribus.mcp_task_profile.v1",
+  "taskId": "browser-debug",
+  "description": "Debug a failing browser flow and look up one library API while keeping unrelated memory/observability/repo tools out of the initial context.",
+  "includeServerIds": ["playwright", "context7"],
+  "excludeReason": "Not needed for this task's first pass; load a different --mcp-config if the task changes."
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pluribus-context",
-  "version": "0.3.40",
+  "version": "0.3.42",
   "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",
@@ -89,7 +89,10 @@
     "agent-context-audit",
     "agent-memory",
     "bob",
-    "bob-rules"
+    "bob-rules",
+    "agent-skill",
+    "skillpm",
+    "agent-skills-registry"
   ],
   "author": "Caio Ribeiro",
   "license": "MIT",

package/skills/context-receipts/README.md

@@ -1,6 +1,6 @@
 # Context receipts Agent Skill recipe
 
-This is a small, copyable Agent Skill recipe for context-engineering users who are adopting Tool Search, lazy MCP loading, skills, memory, compaction, or subagents and need to verify what actually crossed the context boundary.
+This is a small, copyable Agent Skill recipe for context-engineering users who are adopting Tool Search, lazy MCP loading, dynamic tool discovery, skills, memory, compaction, GraphRAG/code search, transcript review, or subagents and need to verify what actually crossed the context boundary.
 
 It is intentionally markdown-only so it can be copied into a local skills directory such as:
 
@@ -8,6 +8,11 @@ It is intentionally markdown-only so it can be copied into a local skills direct
 - `.opencode/skills/context-receipts/SKILL.md`
 - `.agents/skills/context-receipts/SKILL.md`
 
+The two newest smoke paths are:
+
+- **Runtime tool-surface diff:** prove which MCP tools were discovered, activated, withheld, or blocked without copying raw schemas/prompts/results.
+- **Context attention:** prove that retrieved/baseline context was delivered, acknowledged before planning, and cited before edits/tool calls.
+
 ## Quick smoke
 
 Ask an agent or harness using the skill to emit a receipt for one workflow and verify these constraints:
@@ -19,9 +24,15 @@ grep -E 'raw_(schema|query|args|result|output|transcript|text)_copied":false|raw
 
 Then manually check that the receipt contains counts, hashes, ids, buckets, and `audit_gap`, but does **not** contain private prompts, raw schemas, tool args/results, skill bodies, memory bodies, customer names, secrets, or transcript text.
 
-For executable fixture examples, see [`../../examples/context-input-evidence/`](../../examples/context-input-evidence/), including the ToolSearch propagation, pruning, and compaction transaction smokes:
+For executable fixture examples, see:
+
+- [`../../examples/tool-surface-diff-receipts/`](../../examples/tool-surface-diff-receipts/) for runtime MCP tool-surface diff receipts.
+- [`../../examples/context-attention-receipts/`](../../examples/context-attention-receipts/) for retrieved-context attention receipts.
+- [`../../examples/context-input-evidence/`](../../examples/context-input-evidence/) for ToolSearch propagation, pruning, and compaction transaction smokes.
 
 ```bash
+node ../../examples/context-attention-receipts/check-attention-receipt.mjs \
+  ../../examples/context-attention-receipts/attention-receipt-pass.json
 node ../../examples/context-input-evidence/convert-subagent-toolsearch-propagation-log.mjs
 node ../../examples/context-input-evidence/convert-pruning-log.mjs
 node ../../examples/context-input-evidence/convert-compaction-transaction-log.mjs

package/skills/context-receipts/SKILL.md

@@ -45,6 +45,71 @@ Minimal JSONL event names:
 {"event":"mcp.tool_call.completed","tool_id":"github.search_code","args_hash":"sha256:...","result_token_bucket":"2k_4k","raw_args_copied":false,"raw_result_copied":false,"status":"ok"}
 ```
 
+## Runtime tool-surface diff smoke
+
+For MCP dynamic discovery, gateways, admin/Purview-style audit trails, or runtime tool catalogs, separate discovery from activation:
+
+- which platform/gateway/audit sink observed the runtime catalog change;
+- which catalog/version/hash was active before and after discovery;
+- which tools were discovered, activated, withheld, or blocked;
+- which validation outcome applied, such as `accepted`, `blocked_by_rai`, `blocked_by_xpia`, `schema_invalid`, or `entitlement_filtered`;
+- whether only low-cardinality ids, hashes, counts, and outcome codes entered the receipt;
+- the audit gap, such as not proving the tool was semantically right for the user task.
+
+Minimal JSON shape:
+
+```json
+{
+  "receipt_type": "pluribus.mcp_tool_surface_diff_receipt.v1",
+  "runtime_discovery": {
+    "trigger": "turn_start|admin_refresh|tool_search|manual_refresh",
+    "before_catalog_hash": "sha256:...",
+    "after_catalog_hash": "sha256:..."
+  },
+  "summary": {
+    "discovered_count": 3,
+    "activated_count": 1,
+    "withheld_count": 1,
+    "blocked_count": 1
+  },
+  "privacy": {
+    "raw_schemas_copied": false,
+    "raw_prompts_copied": false,
+    "raw_results_copied": false
+  },
+  "audit_gap": "proves tool-surface boundary, not semantic usefulness"
+}
+```
+
+## Context attention smoke
+
+For GraphRAG, memory, code search, transcript review, or baseline-first workflows, separate retrieval from attention:
+
+- which required context ids were selected or retrieved;
+- where they were delivered, such as prompt, tool result, memory result, subagent packet, or file read;
+- which ids were acknowledged before planning;
+- which ids were cited before edits/tool calls;
+- what the agent must stop on if a required id is missing;
+- whether raw docs, prompts, results, paths, customer text, and full transcript snippets stayed out of the receipt.
+
+Minimal JSON shape:
+
+```json
+{
+  "receipt_type": "pluribus.context_attention_receipt.v1",
+  "required_context_ids": ["ctx:auth-boundary", "ctx:migration-plan"],
+  "delivered_context_ids": ["ctx:auth-boundary", "ctx:migration-plan"],
+  "acknowledged_before_plan_ids": ["ctx:auth-boundary", "ctx:migration-plan"],
+  "cited_before_edit_ids": ["ctx:auth-boundary"],
+  "missing_context_stop": "stop_before_edit",
+  "privacy": {
+    "raw_context_copied": false,
+    "raw_transcript_copied": false
+  },
+  "audit_gap": "proves required context was acknowledged/cited, not that the edit is correct"
+}
+```
+
 ## Skill / prompt context smoke
 
 For skills, rules, AGENTS.md overlays, or instruction files, answer:

package/src/commands/demo.js

@@ -12,7 +12,8 @@ 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 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 CONTEXT_SUFFICIENCY_TRACE_DEMO = 'context-sufficiency-trace'
+const AVAILABLE_DEMOS = [SKILL_USE_RATE_DEMO, MCP_AUDIT_RECEIPT_DEMO, MCP_TELEMETRY_IMPORT_DEMO, TOOL_SURFACE_DIFF_DEMO, CONTEXT_SUFFICIENCY_TRACE_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'
@@ -33,6 +34,8 @@ export async function runDemo(args, positional = []) {
       return runMcpTelemetryImportDemo(args)
     case TOOL_SURFACE_DIFF_DEMO:
       return runToolSurfaceDiffDemo(args)
+    case CONTEXT_SUFFICIENCY_TRACE_DEMO:
+      return runContextSufficiencyTraceDemo(args)
     default:
       console.error(`❌ Unknown demo: ${demoName}`)
       console.error(`   Available demos: ${AVAILABLE_DEMOS.join(', ')}`)
@@ -196,6 +199,18 @@ function bundledToolSurfaceDiffReceiptPath() {
   return fileURLToPath(new URL('../../examples/tool-surface-diff-receipts/tool-surface-diff-receipt.json', import.meta.url))
 }
 
+function bundledContextSufficiencyGroundTruthPath() {
+  return fileURLToPath(new URL('../../examples/context-sufficiency-trace/ground-truth.json', import.meta.url))
+}
+
+function bundledContextSufficiencyTracePath() {
+  return fileURLToPath(new URL('../../examples/context-sufficiency-trace/context-trace.json', import.meta.url))
+}
+
+function bundledContextSufficiencyPassTracePath() {
+  return fileURLToPath(new URL('../../examples/context-sufficiency-trace/context-trace-pass.json', import.meta.url))
+}
+
 function runToolSurfaceDiffDemo(args) {
   const receiptPath = selectedReceiptPath(args, bundledToolSurfaceDiffReceiptPath())
   const receipt = readReceipt(receiptPath, 'tool-surface diff')
@@ -230,6 +245,71 @@ function runToolSurfaceDiffDemo(args) {
   if (result.errors.length > 0) process.exit(1)
 }
 
+function runContextSufficiencyTraceDemo(args) {
+  const truthPath = typeof args.receipt === 'string' && args.receipt.trim()
+    ? path.resolve(process.cwd(), args.receipt)
+    : bundledContextSufficiencyGroundTruthPath()
+  const tracePath = typeof args.input === 'string' && args.input.trim()
+    ? path.resolve(process.cwd(), args.input)
+    : (Boolean(args.pass) ? bundledContextSufficiencyPassTracePath() : bundledContextSufficiencyTracePath())
+
+  const truth = readReceipt(truthPath, 'context sufficiency ground-truth')
+  const trace = readReceipt(tracePath, 'context trace')
+  const result = validateContextSufficiencyTrace(truth, trace)
+
+  if (Boolean(args.json)) {
+    console.log(JSON.stringify({
+      ok: result.verdict === 'pass',
+      demo: CONTEXT_SUFFICIENCY_TRACE_DEMO,
+      groundTruth: path.relative(process.cwd(), truthPath) || truthPath,
+      trace: path.relative(process.cwd(), tracePath) || tracePath,
+      summary: result,
+    }, null, 2))
+  } else {
+    console.log('🧪 Pluribus demo: context sufficiency trace')
+    console.log(`   Ground truth: ${path.relative(process.cwd(), truthPath) || truthPath}`)
+    console.log(`   Trace: ${path.relative(process.cwd(), tracePath) || tracePath}`)
+    console.log('')
+
+    const mark = result.verdict === 'pass' ? '✅' : '❌'
+    console.log(`${mark} context sufficiency ${result.verdict}: gold_context_recall=${result.gold_context_recall}, missed_required_file_rate=${result.missed_required_file_rate}, late_context_rate=${result.late_context_rate}`)
+    if (result.missed_required_files.length > 0) console.log(`   • missed_required_files: ${result.missed_required_files.join(', ')}`)
+    if (result.frontier_cut_misses.length > 0) console.log(`   • frontier_cut_misses: ${result.frontier_cut_misses.join(', ')}`)
+    console.log('')
+    console.log('Why this matters: context compression is only safe if the reduced bundle still contains the files/symbols the task ground truth requires before editing starts.')
+    console.log('Try your own trace: pluribus demo context-sufficiency-trace --receipt ground-truth.json --input context-trace.json --json')
+  }
+
+  if (result.verdict !== 'pass') process.exit(1)
+}
+
+export function validateContextSufficiencyTrace(truth, trace) {
+  const required = new Set(Array.isArray(truth.required_files) ? truth.required_files : [])
+  const returned = new Set((Array.isArray(trace.returned_files) ? trace.returned_files : []).map((file) => file.path).filter(Boolean))
+  const frontierCut = new Set((Array.isArray(trace.frontier_cut) ? trace.frontier_cut : []).map((file) => file.path).filter(Boolean))
+  const late = new Set((Array.isArray(trace.late_files) ? trace.late_files : []).map((file) => file.path).filter(Boolean))
+
+  const requiredList = [...required]
+  const returnedRequired = requiredList.filter((filePath) => returned.has(filePath))
+  const missedRequired = requiredList.filter((filePath) => !returned.has(filePath))
+  const frontierCutMisses = missedRequired.filter((filePath) => frontierCut.has(filePath))
+  const lateMisses = missedRequired.filter((filePath) => late.has(filePath))
+
+  const ratio = (count, total) => (total === 0 ? 0 : Number((count / total).toFixed(4)))
+  return {
+    task_id: truth.task_id || 'unknown-task',
+    trace_id: trace.trace_id || 'unknown-trace',
+    required_files: requiredList.length,
+    returned_files: returned.size,
+    gold_context_recall: ratio(returnedRequired.length, requiredList.length),
+    missed_required_file_rate: ratio(missedRequired.length, requiredList.length),
+    late_context_rate: ratio(lateMisses.length, requiredList.length),
+    missed_required_files: missedRequired,
+    frontier_cut_misses: frontierCutMisses,
+    verdict: missedRequired.length === 0 ? 'pass' : 'fail',
+  }
+}
+
 export function validateSkillUseRateReceipt(receipt) {
   const errors = []
   const warnings = []

package/src/utils/version.js

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