thumbgate 1.34.3 → 1.37.1

package/scripts/tool-kpi-tracker.js

@@ -7,6 +7,12 @@ const path = require('node:path');
 const { resolveFeedbackDir } = require('./feedback-paths');
 const { readJsonl } = require('./fs-utils');
 
+const TOOL_CALL_OUTCOMES = Object.freeze({
+  SUCCESSFUL: 'successful',
+  FAILED: 'failed',
+  BLOCKED: 'blocked',
+});
+
 function getKpiLogPath(options = {}) {
   return path.join(
     options.feedbackDir ? path.resolve(options.feedbackDir) : resolveFeedbackDir(),
@@ -14,25 +20,69 @@ function getKpiLogPath(options = {}) {
   );
 }
 
+/**
+ * WriteGuard-aligned outcome taxonomy for every MCP attempt.
+ * Prefer explicit `outcome`; otherwise derive from blocked/denied/success.
+ */
+function normalizeToolCallOutcome({
+  outcome,
+  success,
+  blocked,
+  metadata,
+} = {}) {
+  if (
+    outcome === TOOL_CALL_OUTCOMES.SUCCESSFUL
+    || outcome === TOOL_CALL_OUTCOMES.FAILED
+    || outcome === TOOL_CALL_OUTCOMES.BLOCKED
+  ) {
+    return outcome;
+  }
+  if (
+    blocked === true
+    || metadata?.denied === true
+    || metadata?.outcome === TOOL_CALL_OUTCOMES.BLOCKED
+  ) {
+    return TOOL_CALL_OUTCOMES.BLOCKED;
+  }
+  if (success === false) return TOOL_CALL_OUTCOMES.FAILED;
+  return TOOL_CALL_OUTCOMES.SUCCESSFUL;
+}
+
 function recordToolCall({
   toolName,
   serverName,
   latencyMs,
   success,
+  blocked,
+  outcome,
   agentId,
+  clientId,
+  sessionId,
+  writeRiskTier,
   metadata,
   feedbackDir,
 } = {}) {
   const logPath = getKpiLogPath({ feedbackDir });
   fs.mkdirSync(path.dirname(logPath), { recursive: true });
+  const normalizedOutcome = normalizeToolCallOutcome({
+    outcome,
+    success,
+    blocked,
+    metadata,
+  });
   const entry = {
     id: `kpi_${Date.now()}_${crypto.randomBytes(4).toString('hex')}`,
     timestamp: new Date().toISOString(),
     toolName: toolName || 'unknown',
     serverName: serverName || 'default',
     latencyMs: typeof latencyMs === 'number' ? latencyMs : 0,
-    success: success !== false,
+    // Backward-compatible boolean: blocked and failed are both non-success.
+    success: normalizedOutcome === TOOL_CALL_OUTCOMES.SUCCESSFUL,
+    outcome: normalizedOutcome,
     agentId: agentId || 'unknown',
+    clientId: clientId || metadata?.clientId || null,
+    sessionId: sessionId || metadata?.sessionId || null,
+    writeRiskTier: writeRiskTier || metadata?.writeRiskTier || null,
     metadata: metadata || {},
   };
   fs.appendFileSync(logPath, `${JSON.stringify(entry)}\n`);
@@ -45,11 +95,32 @@ function percentile(sorted, quantile) {
   return sorted[Math.max(0, index)];
 }
 
+function emptyOutcomeCounts() {
+  return {
+    successful: 0,
+    failed: 0,
+    blocked: 0,
+  };
+}
+
+function pickDominantTier(tierCounts = {}) {
+  let best = null;
+  let bestCount = 0;
+  for (const [tier, count] of Object.entries(tierCounts)) {
+    if (count > bestCount) {
+      best = tier;
+      bestCount = count;
+    }
+  }
+  return best;
+}
+
 function computeToolKpis({ periodHours = 24, feedbackDir } = {}) {
   const entries = readJsonl(getKpiLogPath({ feedbackDir }));
   const cutoff = Date.now() - periodHours * 60 * 60 * 1000;
   const recent = entries.filter((entry) => new Date(entry.timestamp).getTime() > cutoff);
   const byTool = {};
+  const outcomes = emptyOutcomeCounts();
   for (const entry of recent) {
     const key = entry.toolName;
     if (!byTool[key]) {
@@ -58,11 +129,27 @@ function computeToolKpis({ periodHours = 24, feedbackDir } = {}) {
         calls: [],
         successes: 0,
         failures: 0,
+        blocked: 0,
+        outcomes: emptyOutcomeCounts(),
+        tierCounts: {},
       };
     }
     byTool[key].calls.push(entry.latencyMs);
-    if (entry.success) byTool[key].successes += 1;
-    else byTool[key].failures += 1;
+    const tier = entry.writeRiskTier || entry.metadata?.writeRiskTier || null;
+    if (tier) {
+      byTool[key].tierCounts[tier] = (byTool[key].tierCounts[tier] || 0) + 1;
+    }
+    const normalized = normalizeToolCallOutcome(entry);
+    byTool[key].outcomes[normalized] += 1;
+    outcomes[normalized] += 1;
+    if (normalized === TOOL_CALL_OUTCOMES.SUCCESSFUL) {
+      byTool[key].successes += 1;
+    } else if (normalized === TOOL_CALL_OUTCOMES.BLOCKED) {
+      byTool[key].blocked += 1;
+      byTool[key].failures += 1;
+    } else {
+      byTool[key].failures += 1;
+    }
   }
   const tools = Object.values(byTool)
     .map((tool) => {
@@ -77,6 +164,9 @@ function computeToolKpis({ periodHours = 24, feedbackDir } = {}) {
         p95: Math.round(percentile(sorted, 95)),
         successes: tool.successes,
         failures: tool.failures,
+        blocked: tool.blocked,
+        outcomes: tool.outcomes,
+        writeRiskTier: pickDominantTier(tool.tierCounts),
       };
     })
     .sort((left, right) => right.requestCount - left.requestCount);
@@ -84,9 +174,18 @@ function computeToolKpis({ periodHours = 24, feedbackDir } = {}) {
   const byServer = {};
   for (const entry of recent) {
     const key = entry.serverName;
-    if (!byServer[key]) byServer[key] = { serverName: key, total: 0, successes: 0 };
+    if (!byServer[key]) {
+      byServer[key] = {
+        serverName: key,
+        total: 0,
+        successes: 0,
+        outcomes: emptyOutcomeCounts(),
+      };
+    }
     byServer[key].total += 1;
-    if (entry.success) byServer[key].successes += 1;
+    const normalized = normalizeToolCallOutcome(entry);
+    byServer[key].outcomes[normalized] += 1;
+    if (normalized === TOOL_CALL_OUTCOMES.SUCCESSFUL) byServer[key].successes += 1;
   }
   const servers = Object.values(byServer).map((server) => ({
     serverName: server.serverName,
@@ -94,11 +193,13 @@ function computeToolKpis({ periodHours = 24, feedbackDir } = {}) {
     successRate: server.total > 0
       ? Math.round((server.successes / server.total) * 1000) / 10
       : 100,
+    outcomes: server.outcomes,
   }));
   return {
     periodHours,
     totalCalls: recent.length,
     evidenceStatus: recent.length > 0 ? 'measured' : 'insufficient_evidence',
+    outcomes,
     tools,
     servers,
   };
@@ -116,9 +217,11 @@ function getAtRiskTools({
 }
 
 module.exports = {
+  TOOL_CALL_OUTCOMES,
   computeToolKpis,
   getAtRiskTools,
   getKpiLogPath,
+  normalizeToolCallOutcome,
   percentile,
   recordToolCall,
 };

package/scripts/tool-registry.js

@@ -12,24 +12,68 @@ function humanizeTitle(name) {
     .join(' ');
 }
 
+// WriteGuard-style write risk tiers mapped onto existing MCP annotations.
+// Explicit annotations.writeRiskTier always wins; otherwise derive from hints + name.
+const WRITE_RISK_TIERS = Object.freeze({
+  READ_ONLY: 'read-only',
+  MINIMAL_IMPACT: 'minimal-impact',
+  CONTAINED_WRITE: 'contained-write',
+  CRITICAL: 'critical',
+});
+
+const CRITICAL_WRITE_NAME_RE = /(approve_protected|satisfy_gate|break[_-]?glass|create_purchase|reserve_purchase|reconcile_purchase|record_broker|verify_broker|reconcile_broker|parallel_workflow|bootstrap_internal_agent|run_managed_lesson_agent|run_harness|run_autoresearch)/i;
+const MINIMAL_WRITE_NAME_RE = /(append_feedback_context|open_feedback_session|request_human_escalation|report_product_issue|native_messaging_audit|detect_noop)/i;
+
+function inferWriteRiskTier(toolName, annotations = {}) {
+  if (annotations.writeRiskTier) return annotations.writeRiskTier;
+  if (annotations.readOnlyHint === true) return WRITE_RISK_TIERS.READ_ONLY;
+  const name = String(toolName || '');
+  if (CRITICAL_WRITE_NAME_RE.test(name)) return WRITE_RISK_TIERS.CRITICAL;
+  if (MINIMAL_WRITE_NAME_RE.test(name)) return WRITE_RISK_TIERS.MINIMAL_IMPACT;
+  // Destructive or unhinted tools default to contained write (conservative).
+  return WRITE_RISK_TIERS.CONTAINED_WRITE;
+}
+
 function readOnlyTool(tool) {
+  const title = tool.title || humanizeTitle(tool.name);
   return {
     ...tool,
-    title: tool.title || humanizeTitle(tool.name),
+    title,
     annotations: {
-      title: tool.title || humanizeTitle(tool.name),
+      title,
       readOnlyHint: true,
+      thumbgateScope: 'mcp:read',
+      writeRiskTier: WRITE_RISK_TIERS.READ_ONLY,
     },
   };
 }
 
+function inferThumbgateScope(toolName, annotations = {}) {
+  if (annotations.thumbgateScope) return annotations.thumbgateScope;
+  if (annotations.readOnlyHint === true) return 'mcp:read';
+  const name = String(toolName || '');
+  if (/(^|_)feedback($|_)|capture_memory_feedback|capture_feedback/.test(name)) {
+    return 'mcp:feedback';
+  }
+  if (/(^|_)gate($|_)|prevention_rules|enforcement_matrix|satisfy_gate/.test(name)) {
+    return 'mcp:gates';
+  }
+  return 'mcp:write';
+}
+
 function destructiveTool(tool) {
+  const title = tool.title || humanizeTitle(tool.name);
+  const baseAnnotations = {
+    title,
+    destructiveHint: true,
+    thumbgateScope: inferThumbgateScope(tool.name, { destructiveHint: true }),
+  };
   return {
     ...tool,
-    title: tool.title || humanizeTitle(tool.name),
+    title,
     annotations: {
-      title: tool.title || humanizeTitle(tool.name),
-      destructiveHint: true,
+      ...baseAnnotations,
+      writeRiskTier: inferWriteRiskTier(tool.name, baseAnnotations),
     },
   };
 }
@@ -60,6 +104,20 @@ const GOAL_CONTRACT_SCHEMA = {
   },
 };
 
+const CONTEXT_LIST_BLOCKS = ['businessData', 'examples', 'procedures', 'constraints', 'rubric'];
+const NON_EMPTY_STRING = { type: 'string', minLength: 1 };
+const CONTEXT_ENVELOPE_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['goal', ...CONTEXT_LIST_BLOCKS],
+  properties: {
+    goal: NON_EMPTY_STRING,
+    ...Object.fromEntries(CONTEXT_LIST_BLOCKS.map((key) => [
+      key, { type: 'array', minItems: 1, items: NON_EMPTY_STRING },
+    ])),
+  },
+};
+
 const TASK_OUTCOME_INPUT_SCHEMA = {
   type: 'object',
   additionalProperties: false,
@@ -207,6 +265,16 @@ const TOOLS = [
             budgetCompliant: { type: 'boolean' },
           },
         },
+        memorySource: {
+          type: 'object',
+          additionalProperties: false,
+          description: 'Provenance for content being considered for durable memory. External email, web, document, file, webhook, browser, or tool-output content should be marked untrusted.',
+          properties: {
+            type: { type: 'string' },
+            identifier: { type: 'string' },
+            trust: { type: 'string', enum: ['trusted', 'untrusted'] },
+          },
+        },
       },
     },
   }),
@@ -359,6 +427,44 @@ const TOOLS = [
           type: 'number',
           description: 'Optional total character budget for compacted feedback entries.',
         },
+        matryoshkaEmbedding: {
+          type: 'boolean',
+          description: 'When true, include Matryoshka embedding compaction footprint tiers. Default: true for MCP plan_context_footprint.',
+        },
+        matryoshkaOptions: {
+          type: 'object',
+          description: 'Optional Matryoshka compaction knobs. Invalid dimensions/counts are rejected.',
+          properties: {
+            fullDimension: {
+              type: 'integer',
+              minimum: 1,
+              description: 'Full embedding dimension before truncation. Default: 1536.',
+            },
+            targetDimensions: {
+              type: 'array',
+              description: 'Truncation tiers to plan (each <= fullDimension). Default: [768,512,256,128].',
+              items: { type: 'integer', minimum: 1 },
+            },
+            itemCount: {
+              type: 'integer',
+              minimum: 1,
+              description: 'Number of vectors for memory estimates. Default: 1000.',
+            },
+            qualityVerified: {
+              type: 'boolean',
+              description: 'Set true only when provider-specific golden RAG eval evidence is available.',
+            },
+            behaviorPreserved: {
+              type: 'boolean',
+              description: 'Must be true with qualityVerified to claim behavior preservation.',
+            },
+            accuracyLossEstimatePct: {
+              type: 'number',
+              description: 'Measured accuracy loss percent from golden eval (only used when qualityVerified).',
+            },
+          },
+          additionalProperties: false,
+        },
       },
     },
   }),
@@ -821,6 +927,8 @@ const TOOLS = [
         maxItems: { type: 'number' },
         maxChars: { type: 'number' },
         namespaces: { type: 'array', items: { type: 'string' } },
+        strategy: { type: 'string', enum: ['summarize-then-expand'] },
+        contextEnvelope: CONTEXT_ENVELOPE_SCHEMA,
       },
     },
   }),
@@ -1070,6 +1178,11 @@ const TOOLS = [
         actionId: { type: 'string', description: 'Identifier of the tracked action this receipt pairs with' },
         toolName: { type: 'string', description: 'Name of the tool that was invoked' },
         toolInput: { type: 'object', description: 'Structured input the tool was called with' },
+        target: { type: 'string', description: 'Optional target path, host, or resource the action touched' },
+        principal: { type: 'string', description: 'Optional agent/principal identity recorded on the receipt' },
+        decision: { type: 'string', description: 'Optional gate decision (allow/warn/deny)' },
+        idempotencyKey: { type: 'string', description: 'Optional idempotency key for dedupe of the signed receipt' },
+        providerEventId: { type: 'string', description: 'Optional upstream provider event id' },
         diff: { type: 'string', description: 'Optional unified diff or change summary produced by the action' },
         exitCode: { type: 'number', description: 'Optional command exit code outcome' },
         testOutcome: { type: 'string', description: 'Optional test outcome (e.g. passed, failed, 12/12)' },
@@ -1089,6 +1202,69 @@ const TOOLS = [
       },
     },
   }),
+  readOnlyTool({
+    name: 'verify_broker_execution_receipt',
+    title: 'Verify Broker Execution Receipt',
+    description: 'Verify a broker-signed execution receipt (Ed25519). Rejects agent-minted or rewritten "proof". ThumbGate verifies; the broker holds provider credentials and signs.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        receipt: { type: 'object', description: 'Broker execution receipt object (schema broker-execution-receipt-v1)' },
+      },
+    },
+  }),
+  // Registered for discovery/docs only. Default MCP allowlist excludes this tool,
+  // and the server refuses agent-surface issuance even if a host key is present.
+  destructiveTool({
+    name: 'issue_broker_execution_receipt',
+    title: 'Issue Broker Execution Receipt (broker host only)',
+    description: 'Not available on the agent MCP surface. Brokers issue receipts out-of-band via scripts/broker-execution-receipts.js with THUMBGATE_BROKER_SIGNING_KEY.',
+    inputSchema: {
+      type: 'object',
+      required: ['principal', 'target', 'idempotencyKey'],
+      properties: {
+        principal: { type: 'object', description: '{ id, kind } of the acting agent/user' },
+        target: { type: 'object', description: '{ provider, action, resource? }' },
+        decision: { type: 'string', description: 'allow | execute | deny' },
+        idempotencyKey: { type: 'string' },
+        providerEventId: { type: 'string' },
+        brokerId: { type: 'string' },
+        previousReceiptHash: { type: 'string' },
+        metadata: { type: 'object' },
+      },
+    },
+  }),
+  destructiveTool({
+    name: 'record_broker_execution_receipt',
+    title: 'Record Broker Execution Receipt',
+    description: 'Append a verified broker-signed execution receipt to the local hash-chained ledger.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        receipt: { type: 'object', description: 'Verified broker execution receipt' },
+      },
+    },
+  }),
+  readOnlyTool({
+    name: 'get_broker_execution_receipts',
+    title: 'Get Broker Execution Receipts',
+    description: 'Read recent broker-signed execution receipts from the local ledger.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        limit: { type: 'number', description: 'Max receipts to return (default 20)' },
+      },
+    },
+  }),
+  readOnlyTool({
+    name: 'reconcile_broker_receipt_chain',
+    title: 'Reconcile Broker Receipt Chain',
+    description: 'Verify signatures and hash-chain continuity for all broker execution receipts on the ledger.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  }),
   destructiveTool({
     name: 'record_task_outcome',
     title: 'Record Verified Task Outcome',
@@ -1164,11 +1340,14 @@ const TOOLS = [
             id: { type: 'string', minLength: 1 },
             kind: { type: 'string', enum: ['agent', 'service', 'human'] },
             displayName: { type: 'string' },
+            role: { type: 'string', enum: ['admin', 'reviewer'] },
           },
         },
         evidence: { type: 'array', minItems: 1, items: { type: 'string', minLength: 1 } },
         ttlMs: { type: 'number', minimum: 1 },
         idempotencyKey: { type: 'string' },
+        approvalContextDigest: { type: 'string', pattern: '^[a-fA-F0-9]{64}$' },
+        requiredReviewerRole: { type: 'string', enum: ['admin'] },
       },
     },
   }),
@@ -1841,10 +2020,19 @@ const NORMALIZED_TOOLS = TOOLS.map((tool) => {
     ...existing,
     ...(hasHint ? {} : { destructiveHint: true }),
   };
+  if (!annotations.thumbgateScope) {
+    annotations.thumbgateScope = inferThumbgateScope(tool.name, annotations);
+  }
+  if (!annotations.writeRiskTier) {
+    annotations.writeRiskTier = inferWriteRiskTier(tool.name, annotations);
+  }
   return { ...tool, title, annotations };
 });
 
 module.exports = {
   TOOLS: NORMALIZED_TOOLS,
+  WRITE_RISK_TIERS,
   humanizeTitle,
+  inferThumbgateScope,
+  inferWriteRiskTier,
 };

package/scripts/universal-claim-evaluator.js

@@ -456,13 +456,25 @@ function assertSelectOnly(query) {
 }
 
 function readSqliteCount(repoRoot, verifier) {
-  const Database = require('better-sqlite3');
   const dbPath = resolveSafePath(repoRoot, verifier.dbPath || verifier.path);
   if (!fs.existsSync(dbPath)) {
     throw new Error(`sqlite database not found: ${verifier.dbPath || verifier.path}`);
   }
   const query = assertSelectOnly(verifier.query);
-  const db = new Database(dbPath, { readonly: true, fileMustExist: true });
+  let db = null;
+  let isBuiltin = false;
+  try {
+    const BetterDatabase = require('better-sqlite3');
+    db = new BetterDatabase(dbPath, { readonly: true, fileMustExist: true });
+  } catch {
+    try {
+      const sqlite = require('node:sqlite');
+      db = new sqlite.DatabaseSync(dbPath, { readOnly: true, open: true });
+      isBuiltin = true;
+    } catch {
+      throw new Error('SQLite driver not available (install better-sqlite3 or use Node 22.5+ node:sqlite)');
+    }
+  }
   try {
     const row = db.prepare(query).get();
     if (!row || typeof row !== 'object') {