@bighub/bighub-mcp 0.2.0 → 0.2.1

package/README.md

@@ -1,8 +1,8 @@
 # @bighub/bighub-mcp
 
-> MCP server for decision learning on agent actions.
+**BIGHUB's decision layer as an MCP server. Evaluate agent actions, receive structured recommendations, report outcomes, and improve future decisions — from any MCP-compatible client.**
 
-Use BIGHUB from any [Model Context Protocol](https://modelcontextprotocol.io) client to evaluate agent actions, report real outcomes, retrieve similar past cases, and improve future decisions over time.
+> MCP server for decision learning on agent actions.
 
 ```text
 MCP client
@@ -11,11 +11,32 @@ MCP client
    ↓
 BIGHUB API
    ↓
-evaluate -> execute -> report outcome -> learn
+evaluate → recommend → agent acts → report outcome → learn
 ```
 
 ---
 
+## Table of contents
+
+**Start here**
+
+- [Install](#install)
+- [Quickstart](#quickstart)
+- [When to use bighub-mcp](#when-to-use-bighub-mcp)
+- [Typical MCP Loop](#typical-mcp-loop)
+- [Structured recommendation](#structured-recommendation)
+- [Trajectory-aware evaluation](#trajectory-aware-evaluation)
+
+**Tool reference**
+
+- [Core loop](#core-loop) · [Actions](#actions) · [Outcomes](#outcomes) · [Decision cases](#decision-cases) · [Precedents](#precedents) · [Calibration](#calibration) · [Multi-signal retrieval](#multi-signal-retrieval) · [Insights](#insights) · [Simulations](#simulations) · [Learning](#learning) · [Features](#features) · [Runtime ingestion](#runtime-ingestion) · [Operating constraints](#operating-constraints) · [Approvals & kill switch](#approvals--kill-switch) · [Events](#events) · [Webhooks](#webhooks) · [API keys](#api-keys) · [Auth](#auth) · [Utility](#utility)
+
+**Reference**
+
+- [Environment Variables](#environment-variables) · [Free BETA](#free-beta) · [Local Development](#local-development) · [Links](#links)
+
+---
+
 ## Install
 
 ```bash
@@ -60,44 +81,330 @@ Works with MCP-compatible clients such as Claude Desktop and Cursor.
 
 ---
 
-## Core MCP Tools
+## When to use bighub-mcp
 
-Most teams start with the first three tools (the core loop):
+Use this server when your MCP-connected agent performs actions that:
 
-| Tool | Purpose |
-|---|---|
-| `bighub_actions_submit` | Submit an action for evaluation before execution |
-| `bighub_outcomes_report` | Report what actually happened |
-| `bighub_precedents_query` | Retrieve similar past cases |
-| `bighub_calibration_report` | Compare prediction vs reality |
-| `bighub_insights_advise` | Retrieve learned guidance for the next action |
+- **Have real consequences** — financial, operational, or reputational impact
+- **Are ambiguous or multi-step** — the right call depends on context and trajectory
+- **Produce observable outcomes** — you can report what actually happened
+- **Need to improve over time** — static instructions aren't enough
 
-`bighub_actions_submit_v2` is available as an advanced action submission endpoint.
+If your agent only answers questions or performs read-only lookups, you don't need this. It's designed for agents that make decisions with real-world consequences.
 
 ---
 
 ## Typical MCP Loop
 
-1. Evaluate the action
-2. Execute it in your runtime
-3. Report the real outcome
-4. Retrieve similar past cases
-5. Compare prediction vs reality
-6. Use learned guidance on the next action
-
-Typical tool flow:
+1. Submit a decision for evaluation
+2. Receive a recommendation and decision signals
+3. Let the agent or runtime act
+4. Report the real outcome
+5. Inspect similar past cases and calibration
+6. Use what was learned on the next decision
 
 ```text
-bighub_actions_submit
--> agent runtime executes action
--> bighub_outcomes_report
--> bighub_precedents_query
--> bighub_calibration_report
--> bighub_insights_advise
+bighub_actions_evaluate
+→ agent runtime acts based on recommendation
+→ bighub_outcomes_report
+→ bighub_precedents_query
+→ bighub_calibration_report
+→ bighub_insights_advise
 ```
 
 ---
 
+## Structured recommendation
+
+Every evaluation returns a structured recommendation — not just allow / block:
+
+| Field | Description |
+|---|---|
+| `recommendation` | `proceed`, `proceed_with_caution`, `review_recommended`, `do_not_proceed` |
+| `recommendation_confidence` | `high`, `medium`, `low` |
+| `risk_score` | Aggregated risk (0–1) |
+| `enforcement_mode` | `advisory`, `review`, `enforced` |
+| `decision_intelligence` | Rationale, evidence status, trajectory health, alternatives |
+
+Legacy fields (`allowed`, `result`, `reason`) may still appear for backward compatibility but are not the primary surface.
+
+---
+
+## Trajectory-aware evaluation
+
+BIGHUB evaluates actions not only in isolation, but also in the context of what happened before. As outcomes accumulate, similar sequences and prior decisions improve future recommendations.
+
+---
+
+# Complete Tool Reference
+
+125 tools organized by domain. The core loop tools are listed first.
+
+---
+
+## Core loop
+
+| Tool | Description |
+|---|---|
+| `bighub_actions_evaluate` | Submit an action for evaluation — returns recommendation, confidence, risk score |
+| `bighub_outcomes_report` | Report what actually happened after execution |
+| `bighub_precedents_query` | Query similar past cases |
+| `bighub_calibration_report` | Calibration report (prediction vs reality) |
+| `bighub_insights_advise` | Learned advisories for an action |
+
+---
+
+## Actions
+
+| Tool | Description |
+|---|---|
+| `bighub_actions_evaluate` | Evaluate an action (primary entry point) |
+| `bighub_actions_evaluate_payload` | Evaluate with a free-form payload |
+| `bighub_actions_evaluate_batch` | Evaluate multiple actions in one request |
+| `bighub_actions_dry_run` | Non-persistent evaluation (preview) |
+| `bighub_actions_live_connect` | Open a live connection slot |
+| `bighub_actions_live_heartbeat` | Heartbeat a live connection |
+| `bighub_actions_live_disconnect` | Close a live connection |
+| `bighub_actions_verify_validation` | Verify a validation hash |
+| `bighub_actions_observer_stats` | Observer statistics |
+| `bighub_actions_dashboard_summary` | Dashboard summary metrics |
+| `bighub_actions_status` | Service status |
+| `bighub_actions_memory_ingest` | Ingest decision memory events |
+| `bighub_actions_memory_context` | Retrieve memory context |
+| `bighub_actions_memory_refresh_aggregates` | Refresh memory aggregates |
+| `bighub_actions_memory_recommendations` | Pattern-based recommendations from memory |
+
+---
+
+## Outcomes
+
+| Tool | Description |
+|---|---|
+| `bighub_outcomes_report` | Report a real-world outcome |
+| `bighub_outcomes_report_batch` | Batch report outcomes |
+| `bighub_outcomes_get` | Get outcome by request_id |
+| `bighub_outcomes_get_by_validation` | Get outcome by validation_id |
+| `bighub_outcomes_get_by_case` | Get outcome by case_id |
+| `bighub_outcomes_timeline` | Full outcome timeline |
+| `bighub_outcomes_pending` | Decisions awaiting outcomes |
+| `bighub_outcomes_analytics` | Outcome analytics summary |
+| `bighub_outcomes_taxonomy` | Supported outcome statuses |
+| `bighub_outcomes_recommendation_quality` | Follow rate, quadrants, trend, by domain/actor |
+| `bighub_outcomes_partner_view` | Self-contained domain view with KPIs and examples |
+
+---
+
+## Decision cases
+
+| Tool | Description |
+|---|---|
+| `bighub_cases_create` | Create a decision case |
+| `bighub_cases_get` | Get a case by ID |
+| `bighub_cases_list` | List and filter cases |
+| `bighub_cases_report_outcome` | Report outcome for a case |
+| `bighub_cases_precedents` | Precedent intelligence for a proposed action |
+| `bighub_cases_calibration` | Calibration metrics for cases |
+
+---
+
+## Precedents
+
+| Tool | Description |
+|---|---|
+| `bighub_precedents_query` | Query similar past cases |
+| `bighub_precedents_signals` | Aggregated precedent signals |
+| `bighub_precedents_stats` | Precedent index statistics |
+
+---
+
+## Calibration
+
+| Tool | Description |
+|---|---|
+| `bighub_calibration_report` | Calibration report |
+| `bighub_calibration_reliability` | Reliability diagram data |
+| `bighub_calibration_drift` | Calibration drift over time |
+| `bighub_calibration_breakdown` | Breakdown by domain or tool |
+| `bighub_calibration_feedback` | Calibration feedback signals |
+| `bighub_calibration_observe` | Submit a calibration observation |
+| `bighub_calibration_quality_history` | Daily quality score over time |
+
+---
+
+## Multi-signal retrieval
+
+| Tool | Description |
+|---|---|
+| `bighub_retrieval_query` | Multi-signal precedent retrieval |
+| `bighub_retrieval_query_explained` | Retrieval with explanation trace |
+| `bighub_retrieval_strategies` | List available strategies |
+| `bighub_retrieval_strategy` | Get one strategy's details |
+| `bighub_retrieval_index_case` | Manually index a case |
+| `bighub_retrieval_compare` | Compare two strategies |
+| `bighub_retrieval_stats` | Retrieval index statistics |
+
+---
+
+## Insights
+
+| Tool | Description |
+|---|---|
+| `bighub_insights_advise` | Learned advisories for an action |
+| `bighub_insights_patterns` | Discovered risk patterns |
+| `bighub_insights_learn` | Learning refresh |
+| `bighub_insights_profile` | Action/tool profile |
+
+---
+
+## Simulations
+
+| Tool | Description |
+|---|---|
+| `bighub_simulations_list` | List simulation snapshots |
+| `bighub_simulations_get` | Get a snapshot |
+| `bighub_simulations_by_request` | Get snapshot by request |
+| `bighub_simulations_compare` | Compare predicted vs actual |
+| `bighub_simulations_accuracy` | Domain-level accuracy |
+| `bighub_simulations_stats` | Simulation statistics |
+
+---
+
+## Learning
+
+| Tool | Description |
+|---|---|
+| `bighub_learning_strategy` | Current learning strategy |
+| `bighub_learning_runs` | Recent learning runs |
+| `bighub_learning_recompute` | Trigger learning recomputation |
+| `bighub_learning_backfill` | Backfill learning artifacts |
+
+---
+
+## Features
+
+| Tool | Description |
+|---|---|
+| `bighub_features_compute` | Compute features for an action |
+| `bighub_features_compute_batch` | Batch feature computation |
+| `bighub_features_snapshot` | Create a feature snapshot |
+| `bighub_features_get_snapshot` | Get a snapshot |
+| `bighub_features_list_snapshots` | List snapshots |
+| `bighub_features_explain` | Explain features for a case |
+| `bighub_features_export` | Export features for a case |
+| `bighub_features_export_batch` | Batch export |
+| `bighub_features_compare` | Compare feature sets |
+| `bighub_features_schema` | Feature schema |
+| `bighub_features_stats` | Feature statistics |
+
+---
+
+## Runtime ingestion
+
+| Tool | Description |
+|---|---|
+| `bighub_ingest_event` | Ingest a single event |
+| `bighub_ingest_batch` | Ingest events in batch |
+| `bighub_ingest_reconcile` | Reconcile outcome with event |
+| `bighub_ingest_lifecycles` | List event lifecycles |
+| `bighub_ingest_lifecycle` | Get lifecycle for one event |
+| `bighub_ingest_pending` | Events pending reconciliation |
+| `bighub_ingest_stale` | Stale unreconciled events |
+| `bighub_ingest_stats` | Ingestion statistics |
+| `bighub_ingest_adapters` | List available adapters |
+
+---
+
+## Operating constraints
+
+| Tool | Description |
+|---|---|
+| `bighub_constraints_create` | Create a constraint |
+| `bighub_constraints_list` | List constraints |
+| `bighub_constraints_get` | Get a constraint |
+| `bighub_constraints_update` | Update a constraint |
+| `bighub_constraints_delete` | Delete a constraint |
+| `bighub_constraints_pause` | Pause a constraint |
+| `bighub_constraints_resume` | Resume a constraint |
+| `bighub_constraints_dry_run` | Preview without persisting |
+| `bighub_constraints_validate` | Validate an action against constraints |
+| `bighub_constraints_validate_dry_run` | Validate (dry run) |
+| `bighub_constraints_domains` | List domains with constraints |
+| `bighub_constraints_versions` | Constraint version history |
+| `bighub_constraints_apply_patch` | Apply a JSON Patch |
+| `bighub_constraints_purge_idempotency` | Admin: purge idempotency keys |
+
+---
+
+## Approvals & kill switch
+
+| Tool | Description |
+|---|---|
+| `bighub_approvals_list` | List approval requests |
+| `bighub_approvals_resolve` | Resolve an approval |
+| `bighub_kill_switch_status` | Kill switch status |
+| `bighub_kill_switch_activate` | Activate kill switch |
+| `bighub_kill_switch_deactivate` | Deactivate kill switch |
+
+---
+
+## Events
+
+| Tool | Description |
+|---|---|
+| `bighub_events_list` | Query event stream |
+| `bighub_events_stats` | Event statistics |
+
+---
+
+## Webhooks
+
+| Tool | Description |
+|---|---|
+| `bighub_webhooks_create` | Create a webhook |
+| `bighub_webhooks_list` | List webhooks |
+| `bighub_webhooks_get` | Get a webhook |
+| `bighub_webhooks_update` | Update a webhook |
+| `bighub_webhooks_delete` | Delete a webhook |
+| `bighub_webhooks_deliveries` | List deliveries |
+| `bighub_webhooks_test` | Send a test delivery |
+| `bighub_webhooks_list_events` | List subscribable event types |
+| `bighub_webhooks_verify_signature` | Verify webhook signature |
+| `bighub_webhooks_replay_failed_delivery` | Replay a failed delivery |
+
+---
+
+## API keys
+
+| Tool | Description |
+|---|---|
+| `bighub_api_keys_create` | Create an API key |
+| `bighub_api_keys_list` | List API keys |
+| `bighub_api_keys_delete` | Delete an API key |
+| `bighub_api_keys_rotate` | Rotate an API key |
+| `bighub_api_keys_validate` | Validate an API key |
+| `bighub_api_keys_scopes` | List available scopes |
+
+---
+
+## Auth
+
+| Tool | Description |
+|---|---|
+| `bighub_auth_signup` | Create an account |
+| `bighub_auth_login` | Log in |
+| `bighub_auth_refresh` | Refresh token |
+| `bighub_auth_logout` | Log out |
+
+---
+
+## Utility
+
+| Tool | Description |
+|---|---|
+| `bighub_http_request` | Generic HTTP passthrough |
+
+---
+
 ## Environment Variables
 
 | Variable | Required | Default | Description |
@@ -111,7 +418,7 @@ bighub_actions_submit
 
 \* One of `BIGHUB_API_KEY` or `BIGHUB_BEARER_TOKEN` is required.
 
-Some management tools (for example API key and webhook administration) require user JWT auth and should be used with `BIGHUB_BEARER_TOKEN`.
+Management tools (API keys, webhooks, auth) require user JWT auth via `BIGHUB_BEARER_TOKEN`.
 
 ---
 

package/dist/index.js

@@ -25,11 +25,11 @@ async function main() {
         bearerToken,
         timeoutMs: parseNumberEnv("BIGHUB_TIMEOUT_MS", 15000),
         maxRetries: parseNumberEnv("BIGHUB_MAX_RETRIES", 2),
-        userAgent: "bighub-mcp/0.2.0",
+        userAgent: "bighub-mcp/0.2.1",
     });
     const server = new McpServer({
         name: "bighub-mcp",
-        version: "0.2.0",
+        version: "0.2.1",
     });
     registerBighubTools(server, client);
     const transport = new StdioServerTransport();

package/dist/registerTools.js

@@ -36,8 +36,8 @@ export function registerBighubTools(server, client) {
         headers,
         idempotencyKey: idempotency_key,
     })));
-    server.registerTool("bighub_actions_submit", {
-        description: "Evaluate an action via /actions/submit.",
+    server.registerTool("bighub_actions_evaluate", {
+        description: "Evaluate an action via /actions/evaluate — returns decision intelligence (recommendation, risk, trajectory health, alternatives).",
         outputSchema: AnyOutputSchema,
         inputSchema: {
             action: z.string(),
@@ -49,14 +49,18 @@ export function registerBighubTools(server, client) {
             metadata: JsonObjectSchema.optional(),
             idempotency_key: z.string().optional(),
         },
-    }, async ({ action, actor, value, target, domain, context, metadata, idempotency_key }) => toResult(await client.request({
-        method: "POST",
-        path: "/actions/submit",
-        body: cleanObject({ action, actor, value, target, domain, context: context ?? metadata }),
-        idempotencyKey: idempotency_key,
-    })));
-    server.registerTool("bighub_actions_submit_v2", {
-        description: "Evaluate an action via /actions/submit/v2 (advanced mode).",
+    }, async ({ action, actor, value, target, domain, context, metadata, idempotency_key }) => {
+        const mergedContext = { ...(metadata || {}), ...(context || {}) };
+        const body = cleanObject({ action, actor, value, target, domain, context: Object.keys(mergedContext).length ? mergedContext : undefined });
+        return toResult(await client.request({
+            method: "POST",
+            path: "/actions/evaluate",
+            body,
+            idempotencyKey: idempotency_key,
+        }));
+    });
+    server.registerTool("bighub_actions_evaluate_payload", {
+        description: "Evaluate an action with full decision intelligence payload via /actions/evaluate.",
         outputSchema: AnyOutputSchema,
         inputSchema: {
             payload: JsonObjectSchema,
@@ -64,22 +68,58 @@ export function registerBighubTools(server, client) {
         },
     }, async ({ payload, idempotency_key }) => toResult(await client.request({
         method: "POST",
-        path: "/actions/submit/v2",
+        path: "/actions/evaluate",
         body: payload,
         idempotencyKey: idempotency_key,
     })));
     server.registerTool("bighub_actions_dry_run", {
-        description: "Dry-run action evaluation (non-persistent) via /actions/submit/dry-run.",
+        description: "Dry-run action evaluation (non-persistent) via /actions/evaluate with dry_run=true.",
         inputSchema: {
             payload: JsonObjectSchema,
             idempotency_key: z.string().optional(),
         },
     }, async ({ payload, idempotency_key }) => toResult(await client.request({
         method: "POST",
-        path: "/actions/submit/dry-run",
-        body: payload,
+        path: "/actions/evaluate",
+        body: { ...payload, dry_run: true },
         idempotencyKey: idempotency_key,
     })));
+    server.registerTool("bighub_actions_live_connect", {
+        description: "Open a concurrent live agent connection slot. Returns connection_id to reuse for heartbeats and submits.",
+        outputSchema: AnyOutputSchema,
+        inputSchema: {
+            actor: z.string().default("AI_AGENT"),
+            context: JsonObjectSchema.optional(),
+        },
+    }, async ({ actor, context }) => toResult(await client.request({
+        method: "POST",
+        path: "/actions/live/connect",
+        body: { actor, context: context || {} },
+    })));
+    server.registerTool("bighub_actions_live_heartbeat", {
+        description: "Heartbeat an existing live agent connection to keep it alive (recommended every 40s, TTL 120s).",
+        outputSchema: AnyOutputSchema,
+        inputSchema: {
+            connection_id: z.string(),
+            context: JsonObjectSchema.optional(),
+        },
+    }, async ({ connection_id, context }) => toResult(await client.request({
+        method: "POST",
+        path: "/actions/live/heartbeat",
+        body: { connection_id, context: context || {} },
+    })));
+    server.registerTool("bighub_actions_live_disconnect", {
+        description: "Disconnect a live agent connection, freeing the slot immediately.",
+        outputSchema: AnyOutputSchema,
+        inputSchema: {
+            connection_id: z.string(),
+            context: JsonObjectSchema.optional(),
+        },
+    }, async ({ connection_id, context }) => toResult(await client.request({
+        method: "POST",
+        path: "/actions/live/disconnect",
+        body: { connection_id, context: context || {} },
+    })));
     server.registerTool("bighub_actions_verify_validation", {
         description: "Verify a previous evaluation by validation_id.",
         inputSchema: { validation_id: z.string() },
@@ -176,7 +216,7 @@ export function registerBighubTools(server, client) {
         path: "/actions/memory/recommendations",
         body: cleanObject(args),
     })));
-    server.registerTool("bighub_rules_create", {
+    server.registerTool("bighub_constraints_create", {
         description: "Create a boundary rule.",
         outputSchema: AnyOutputSchema,
         inputSchema: {
@@ -189,7 +229,7 @@ export function registerBighubTools(server, client) {
         body: payload,
         idempotencyKey: idempotency_key,
     })));
-    server.registerTool("bighub_rules_list", {
+    server.registerTool("bighub_constraints_list", {
         description: "List boundary rules.",
         outputSchema: AnyOutputSchema,
         inputSchema: {
@@ -203,12 +243,12 @@ export function registerBighubTools(server, client) {
         path: "/rules",
         query: cleanObject({ status, domain, limit, offset }),
     })));
-    server.registerTool("bighub_rules_get", {
+    server.registerTool("bighub_constraints_get", {
         description: "Fetch a single rule by rule_id.",
         outputSchema: AnyOutputSchema,
         inputSchema: { rule_id: z.string() },
     }, async ({ rule_id }) => toResult(await client.request({ method: "GET", path: `/rules/${rule_id}` })));
-    server.registerTool("bighub_rules_update", {
+    server.registerTool("bighub_constraints_update", {
         description: "Update a rule by rule_id.",
         outputSchema: AnyOutputSchema,
         inputSchema: {
@@ -222,7 +262,7 @@ export function registerBighubTools(server, client) {
         body: payload,
         idempotencyKey: idempotency_key,
     })));
-    server.registerTool("bighub_rules_delete", {
+    server.registerTool("bighub_constraints_delete", {
         description: "Delete a rule.",
         inputSchema: {
             rule_id: z.string(),
@@ -233,7 +273,7 @@ export function registerBighubTools(server, client) {
         path: `/rules/${rule_id}`,
         idempotencyKey: idempotency_key,
     })));
-    server.registerTool("bighub_rules_pause", {
+    server.registerTool("bighub_constraints_pause", {
         description: "Pause a rule by rule_id.",
         inputSchema: {
             rule_id: z.string(),
@@ -244,7 +284,7 @@ export function registerBighubTools(server, client) {
         path: `/rules/${rule_id}/pause`,
         idempotencyKey: idempotency_key,
     })));
-    server.registerTool("bighub_rules_resume", {
+    server.registerTool("bighub_constraints_resume", {
         description: "Resume a paused rule.",
         inputSchema: {
             rule_id: z.string(),
@@ -255,7 +295,7 @@ export function registerBighubTools(server, client) {
         path: `/rules/${rule_id}/resume`,
         idempotencyKey: idempotency_key,
     })));
-    server.registerTool("bighub_rules_dry_run", {
+    server.registerTool("bighub_constraints_dry_run", {
         description: "Dry run a rule payload without persisting.",
         inputSchema: {
             payload: JsonObjectSchema,
@@ -265,7 +305,7 @@ export function registerBighubTools(server, client) {
         path: "/rules/dry-run",
         body: payload,
     })));
-    server.registerTool("bighub_rules_validate", {
+    server.registerTool("bighub_constraints_validate", {
         description: "Validate a rule payload.",
         inputSchema: {
             payload: JsonObjectSchema,
@@ -275,7 +315,7 @@ export function registerBighubTools(server, client) {
         path: "/rules/validate",
         body: payload,
     })));
-    server.registerTool("bighub_rules_validate_dry_run", {
+    server.registerTool("bighub_constraints_validate_dry_run", {
         description: "Dry-run validate a rule payload.",
         inputSchema: {
             payload: JsonObjectSchema,
@@ -285,11 +325,11 @@ export function registerBighubTools(server, client) {
         path: "/rules/validate/dry-run",
         body: payload,
     })));
-    server.registerTool("bighub_rules_domains", {
+    server.registerTool("bighub_constraints_domains", {
         description: "List available rule domains.",
         inputSchema: {},
     }, async () => toResult(await client.request({ method: "GET", path: "/rules/domains" })));
-    server.registerTool("bighub_rules_versions", {
+    server.registerTool("bighub_constraints_versions", {
         description: "List historical versions for a rule.",
         outputSchema: AnyOutputSchema,
         inputSchema: {
@@ -301,7 +341,7 @@ export function registerBighubTools(server, client) {
         path: `/rules/${rule_id}/versions`,
         query: cleanObject({ limit }),
     })));
-    server.registerTool("bighub_rules_purge_idempotency", {
+    server.registerTool("bighub_constraints_purge_idempotency", {
         description: "Purge rule idempotency records from the backend store.",
         outputSchema: AnyOutputSchema,
         inputSchema: {
@@ -314,7 +354,7 @@ export function registerBighubTools(server, client) {
         path: "/rules/admin/idempotency/purge",
         query: cleanObject({ only_expired, older_than_hours, limit }),
     })));
-    server.registerTool("bighub_rules_apply_patch", {
+    server.registerTool("bighub_constraints_apply_patch", {
         description: "Apply JSON Patch operations to a rule with preview/optimistic locking support.",
         outputSchema: AnyOutputSchema,
         inputSchema: {
@@ -370,21 +410,27 @@ export function registerBighubTools(server, client) {
         inputSchema: {},
     }, async () => toResult(await client.request({ method: "GET", path: "/kill-switch/status" })));
     server.registerTool("bighub_kill_switch_activate", {
-        description: "Activate global/domain kill switch.",
+        description: "Activate global/domain kill switch. Requires a reason.",
         inputSchema: {
-            payload: JsonObjectSchema.optional(),
+            reason: z.string().min(1).describe("Why the kill switch is being activated"),
+            scope: z.string().default("global").describe("Scope: global or domain"),
+            domain: z.string().optional().describe("Domain to target (when scope=domain)"),
+            rule_id: z.string().optional().describe("Specific rule to kill"),
         },
-    }, async ({ payload }) => toResult(await client.request({ method: "POST", path: "/kill-switch/activate", body: payload || {} })));
+    }, async ({ reason, scope, domain, rule_id }) => toResult(await client.request({ method: "POST", path: "/kill-switch/activate", body: cleanObject({ reason, scope, domain, rule_id }) })));
     server.registerTool("bighub_kill_switch_deactivate", {
-        description: "Deactivate kill switch by switch_id.",
+        description: "Deactivate kill switch by switch_id. Requires a reason.",
         inputSchema: {
             switch_id: z.string(),
-            payload: JsonObjectSchema.optional(),
+            reason: z.string().min(1).describe("Why the kill switch is being deactivated"),
+            scope: z.string().default("global").optional(),
+            domain: z.string().optional(),
+            rule_id: z.string().optional(),
         },
-    }, async ({ switch_id, payload }) => toResult(await client.request({
+    }, async ({ switch_id, reason, scope, domain, rule_id }) => toResult(await client.request({
         method: "POST",
         path: `/kill-switch/deactivate/${switch_id}`,
-        body: payload || {},
+        body: cleanObject({ reason, scope, domain, rule_id }),
     })));
     server.registerTool("bighub_events_list", {
         description: "List event stream entries.",
@@ -553,14 +599,14 @@ export function registerBighubTools(server, client) {
     // Cases — Decision case lifecycle
     // ---------------------------------------------------------------------------
     server.registerTool("bighub_cases_create", {
-        description: "Create a decision case.",
+        description: "Create a decision case. Requires action and verdict.",
         outputSchema: AnyOutputSchema,
         inputSchema: {
             domain: z.string(),
-            action: JsonObjectSchema,
+            action: JsonObjectSchema.describe("Action payload: {tool, action, arguments, value, target, domain}"),
+            verdict: JsonObjectSchema.describe("Required verdict: {verdict: ALLOWED|BLOCKED|APPROVAL_REQUIRED|LIMITED|DRY_RUN, mode, reasons, risk_score, confidence}"),
             context: JsonObjectSchema.optional(),
             simulation: JsonObjectSchema.optional(),
-            verdict: JsonObjectSchema.optional(),
             goal_summary: z.string().optional(),
             trigger_source: z.string().optional(),
             actor_type: z.string().default("AI_AGENT"),
@@ -618,20 +664,19 @@ export function registerBighubTools(server, client) {
         body: cleanObject({ status, description, details, actual_impact, correction_needed, rollback_performed, revenue_impact }),
     })));
     server.registerTool("bighub_cases_precedents", {
-        description: "Get precedent intelligence for a proposed action.",
+        description: "Get precedent intelligence for a proposed action. action must be a nested ActionInput object.",
         outputSchema: AnyOutputSchema,
         inputSchema: {
-            domain: z.string(),
-            action: z.string(),
-            tool: z.string().optional(),
-            actor_type: z.string().default("AI_AGENT"),
-            risk_score: z.number().optional(),
-            axes: JsonObjectSchema.optional(),
+            domain: z.string().optional().describe("Domain to scope precedent search"),
+            action: JsonObjectSchema.describe("ActionInput: {action, tool, action_type, arguments, value, target}"),
+            context: JsonObjectSchema.optional().describe("ContextInput: {axes, axes_risk_score, intent, irreversibility}"),
+            min_similarity: z.number().min(0).max(1).default(0.5).optional(),
+            limit: z.number().int().min(1).max(100).default(20).optional(),
         },
-    }, async ({ domain, action, tool, actor_type, risk_score, axes }) => toResult(await client.request({
+    }, async ({ domain, action, context, min_similarity, limit }) => toResult(await client.request({
         method: "POST",
         path: "/cases/precedents",
-        body: cleanObject({ domain, action, tool, actor_type, risk_score, axes }),
+        body: cleanObject({ domain, action, context, min_similarity, limit }),
     })));
     server.registerTool("bighub_cases_calibration", {
         description: "Get calibration metrics (prediction vs reality) for cases.",
@@ -659,16 +704,22 @@ export function registerBighubTools(server, client) {
             details: JsonObjectSchema.optional(),
             actual_impact: JsonObjectSchema.optional(),
             correction_needed: z.boolean().default(false),
+            correction_description: z.string().optional(),
+            correction_cost: z.number().optional(),
+            time_to_detect_s: z.number().optional(),
+            time_to_resolve_s: z.number().optional(),
             rollback_performed: z.boolean().default(false),
             revenue_impact: z.number().optional(),
+            customer_impact_count: z.number().int().default(0),
+            support_tickets_created: z.number().int().default(0),
             observed_at: z.string().optional(),
             reported_by: z.string().optional(),
             tags: z.array(z.string()).optional(),
         },
-    }, async ({ status, request_id, case_id, validation_id, description, details, actual_impact, correction_needed, rollback_performed, revenue_impact, observed_at, reported_by, tags }) => toResult(await client.request({
+    }, async ({ status, request_id, case_id, validation_id, description, details, actual_impact, correction_needed, correction_description, correction_cost, time_to_detect_s, time_to_resolve_s, rollback_performed, revenue_impact, customer_impact_count, support_tickets_created, observed_at, reported_by, tags }) => toResult(await client.request({
         method: "POST",
         path: "/outcomes/report",
-        body: cleanObject({ status, request_id, case_id, validation_id, description, details, actual_impact, correction_needed, rollback_performed, revenue_impact, observed_at, reported_by, tags }),
+        body: cleanObject({ status, request_id, case_id, validation_id, description, details, actual_impact, correction_needed, correction_description, correction_cost, time_to_detect_s, time_to_resolve_s, rollback_performed, revenue_impact, customer_impact_count, support_tickets_created, observed_at, reported_by, tags }),
     })));
     server.registerTool("bighub_outcomes_report_batch", {
         description: "Batch report outcomes (max 100).",
@@ -686,6 +737,16 @@ export function registerBighubTools(server, client) {
         outputSchema: AnyOutputSchema,
         inputSchema: { request_id: z.string() },
     }, async ({ request_id }) => toResult(await client.request({ method: "GET", path: `/outcomes/${request_id}` })));
+    server.registerTool("bighub_outcomes_get_by_validation", {
+        description: "Get outcome by validation_id.",
+        outputSchema: AnyOutputSchema,
+        inputSchema: { validation_id: z.string() },
+    }, async ({ validation_id }) => toResult(await client.request({ method: "GET", path: `/outcomes/by-validation/${validation_id}` })));
+    server.registerTool("bighub_outcomes_get_by_case", {
+        description: "Get outcome by case_id.",
+        outputSchema: AnyOutputSchema,
+        inputSchema: { case_id: z.string() },
+    }, async ({ case_id }) => toResult(await client.request({ method: "GET", path: `/outcomes/by-case/${case_id}` })));
     server.registerTool("bighub_outcomes_timeline", {
         description: "Get full outcome timeline for a request.",
         outputSchema: AnyOutputSchema,
@@ -720,6 +781,29 @@ export function registerBighubTools(server, client) {
         description: "Supported outcome status taxonomy.",
         inputSchema: {},
     }, async () => toResult(await client.request({ method: "GET", path: "/outcomes/taxonomy" })));
+    server.registerTool("bighub_outcomes_recommendation_quality", {
+        description: "Recommendation quality analytics: follow rate, quadrants (followed+positive, followed+negative, ignored+positive, ignored+negative), breakdowns by domain/actor, and notable examples of BIGHUB helped / missed.",
+        inputSchema: {
+            domain: z.string().optional().describe("Filter by domain"),
+            since: z.string().optional().describe("Start date (ISO 8601)"),
+            until: z.string().optional().describe("End date (ISO 8601)"),
+        },
+    }, async ({ domain, since, until }) => {
+        return toResult(await client.request({
+            method: "GET",
+            path: `/outcomes/analytics/recommendation-quality`,
+            query: cleanObject({ domain, since, until }),
+        }));
+    });
+    server.registerTool("bighub_outcomes_partner_view", {
+        description: "Self-contained partner/domain view: decisions evaluated, follow rate, positive after following, trend, by-action breakdown, sparse evidence pockets, and helped/missed examples.",
+        inputSchema: {
+            domain: z.string().describe("The domain to generate the partner view for"),
+        },
+    }, async ({ domain }) => toResult(await client.request({
+        method: "GET",
+        path: `/outcomes/analytics/partner-view/${encodeURIComponent(domain)}`,
+    })));
     // ---------------------------------------------------------------------------
     // Precedents — Case-based reasoning from past decisions
     // ---------------------------------------------------------------------------
@@ -843,6 +927,18 @@ export function registerBighubTools(server, client) {
         path: "/calibration/observe",
         body: cleanObject({ case_id, predicted_risk, outcome_status, domain, tool, action, actor_type, verdict }),
     })));
+    server.registerTool("bighub_calibration_quality_history", {
+        description: "Daily quality score over time — powers the Learning chart. Returns quality_score (1 − Brier), positive_rate per day.",
+        outputSchema: AnyOutputSchema,
+        inputSchema: {
+            days: z.number().int().min(1).max(180).default(30).describe("Number of days to include"),
+            domain: z.string().optional(),
+        },
+    }, async ({ days, domain }) => toResult(await client.request({
+        method: "GET",
+        path: "/calibration/quality-history",
+        query: cleanObject({ days, domain }),
+    })));
     // ---------------------------------------------------------------------------
     // Retrieval — Multi-signal decision retrieval engine
     // ---------------------------------------------------------------------------
@@ -932,6 +1028,25 @@ export function registerBighubTools(server, client) {
         description: "Get retrieval engine statistics.",
         inputSchema: {},
     }, async () => toResult(await client.request({ method: "GET", path: "/retrieval/stats" })));
+    server.registerTool("bighub_retrieval_compare", {
+        description: "Compare two retrieval strategies on the same query. Returns scored results, risk level, confidence, and stability for each strategy.",
+        outputSchema: AnyOutputSchema,
+        inputSchema: {
+            domain: z.string().default(""),
+            tool: z.string().default(""),
+            action: z.string().default(""),
+            actor_type: z.string().default(""),
+            axes: JsonObjectSchema.optional().describe("Risk axes as {axis_name: score}"),
+            risk_score: z.number().default(0.0),
+            intent: z.string().default(""),
+            strategy_a: z.string().default("balanced").describe("First strategy to compare"),
+            strategy_b: z.string().default("consequence-focused").describe("Second strategy to compare"),
+        },
+    }, async ({ domain, tool, action, actor_type, axes, risk_score, intent, strategy_a, strategy_b }) => toResult(await client.request({
+        method: "POST",
+        path: "/retrieval/compare",
+        body: cleanObject({ domain, tool, action, actor_type, axes, risk_score, intent, strategy_a, strategy_b }),
+    })));
     // ---------------------------------------------------------------------------
     // Features — Decision feature layer
     // ---------------------------------------------------------------------------
@@ -1003,6 +1118,52 @@ export function registerBighubTools(server, client) {
         description: "Get feature layer statistics.",
         inputSchema: {},
     }, async () => toResult(await client.request({ method: "GET", path: "/features/stats" })));
+    server.registerTool("bighub_features_compute_batch", {
+        description: "Compute feature vectors for multiple cases in a single request (max 500).",
+        outputSchema: AnyOutputSchema,
+        inputSchema: {
+            cases: z.array(z.object({
+                case_id: z.string(),
+                org_id: z.string().default(""),
+                case_data: JsonObjectSchema.optional(),
+                outcome_data: JsonObjectSchema.optional(),
+                precedent_data: JsonObjectSchema.optional(),
+                calibration_data: JsonObjectSchema.optional(),
+                advisory_data: JsonObjectSchema.optional(),
+                domain_stats: JsonObjectSchema.optional(),
+            })).min(1).max(500),
+        },
+    }, async ({ cases }) => toResult(await client.request({
+        method: "POST",
+        path: "/features/compute/batch",
+        body: { cases },
+    })));
+    server.registerTool("bighub_features_compare", {
+        description: "Compare two feature snapshots or cached vectors. Returns changed features with diffs.",
+        outputSchema: AnyOutputSchema,
+        inputSchema: {
+            snapshot_id_a: z.string().optional(),
+            snapshot_id_b: z.string().optional(),
+            case_id_a: z.string().optional(),
+            case_id_b: z.string().optional(),
+            changed_only: z.boolean().default(true).describe("Only return features that differ"),
+        },
+    }, async ({ snapshot_id_a, snapshot_id_b, case_id_a, case_id_b, changed_only }) => toResult(await client.request({
+        method: "POST",
+        path: "/features/compare",
+        body: cleanObject({ snapshot_id_a, snapshot_id_b, case_id_a, case_id_b, changed_only }),
+    })));
+    server.registerTool("bighub_features_export_batch", {
+        description: "Export flat feature dicts for multiple cases (max 500).",
+        outputSchema: AnyOutputSchema,
+        inputSchema: {
+            case_ids: z.array(z.string()).min(1).max(500),
+        },
+    }, async ({ case_ids }) => toResult(await client.request({
+        method: "POST",
+        path: "/features/export/batch",
+        body: { case_ids },
+    })));
     // ---------------------------------------------------------------------------
     // Insights — Patterns, advisories, and action profiles
     // ---------------------------------------------------------------------------
@@ -1148,4 +1309,161 @@ export function registerBighubTools(server, client) {
         path: "/ops/learning/backfill",
         body: { domain, action_family, force, limit, async_mode },
     })));
+    // ═══════════════════════════════════════════════════════════════════════════
+    // Batch action evaluation
+    // ═══════════════════════════════════════════════════════════════════════════
+    server.registerTool("bighub_actions_evaluate_batch", {
+        description: "Evaluate multiple actions in a single request via /actions/evaluate/batch. " +
+            "Each element follows the same schema as bighub_actions_evaluate. Max 100 actions. Rate limited: 10/min.",
+        outputSchema: AnyOutputSchema,
+        inputSchema: {
+            actions: z.array(z.object({
+                action: z.string(),
+                actor: z.string().default("AI_AGENT"),
+                value: z.number().optional(),
+                target: z.string().optional(),
+                domain: z.string().optional(),
+                context: JsonObjectSchema.optional(),
+                dry_run: z.boolean().default(false),
+                check_contracts: z.boolean().default(false),
+            })).max(100),
+            idempotency_key: z.string().optional(),
+        },
+    }, async ({ actions, idempotency_key }) => toResult(await client.request({
+        method: "POST",
+        path: "/actions/evaluate/batch",
+        body: { actions },
+        idempotencyKey: idempotency_key,
+    })));
+    // ═══════════════════════════════════════════════════════════════════════════
+    // Ingest — real-world event lifecycle
+    // ═══════════════════════════════════════════════════════════════════════════
+    server.registerTool("bighub_ingest_event", {
+        description: "Ingest a single real-world event into BIGHUB. Events flow through: " +
+            "normalize → enrich → correlate → sync. BIGHUB links the event to the " +
+            "correct decision lifecycle using any provided correlation key.",
+        outputSchema: AnyOutputSchema,
+        inputSchema: {
+            event_type: z.string().default("OUTCOME_OBSERVED").describe("Event type: ACTION_PROPOSED, ACTION_EXECUTED, ACTION_BLOCKED, " +
+                "HUMAN_OVERRIDE, HUMAN_APPROVAL, HUMAN_REJECTION, " +
+                "OUTCOME_OBSERVED, OUTCOME_UPDATED, ROLLBACK_PERFORMED, " +
+                "CORRECTION_APPLIED, ESCALATION_TRIGGERED, FRAUD_DETECTED, " +
+                "CHURN_SIGNAL, TICKET_REOPENED, REFUND_COMPLETED, PRICING_CORRECTION"),
+            timestamp: z.string().optional().describe("ISO 8601 timestamp (defaults to now)"),
+            request_id: z.string().default("").describe("Link to BIGHUB decision (from /actions/evaluate response)"),
+            case_id: z.string().default("").describe("Link to DecisionCase"),
+            validation_id: z.string().default("").describe("Link to rule validation"),
+            external_ref: z.string().default("").describe("Your system's reference (e.g. order_id)"),
+            tenant_ref: z.string().default("").describe("Tenant-level reference"),
+            entity_id: z.string().default("").describe("Entity being acted on"),
+            session_id: z.string().default("").describe("Session / conversation ID"),
+            action: JsonObjectSchema.optional().describe("Action payload: {tool, action, arguments, value, target, domain}"),
+            context: JsonObjectSchema.optional().describe("Context: {risk_score, axes, environment, ...}"),
+            execution: JsonObjectSchema.optional().describe("Execution result: {executed, status_code, error, ...}"),
+            outcome: JsonObjectSchema.optional().describe("Outcome: {status, description, revenue_impact, ...}"),
+            human_feedback: JsonObjectSchema.optional().describe("Human: {feedback_type, decision, reason, ...}"),
+            intent: JsonObjectSchema.optional().describe("Intent: {goal_summary, trigger_source, actor_type, ...}"),
+            adapter: z.string().default("generic_webhook"),
+            domain: z.string().default(""),
+            tags: z.array(z.string()).optional(),
+        },
+    }, async (args) => toResult(await client.request({
+        method: "POST",
+        path: "/ingest",
+        body: cleanObject(args),
+    })));
+    server.registerTool("bighub_ingest_batch", {
+        description: "Ingest multiple real-world events in a single request (max 500). " +
+            "Events are processed through the same normalize → enrich → correlate → sync pipeline.",
+        outputSchema: AnyOutputSchema,
+        inputSchema: {
+            events: z.array(JsonObjectSchema).max(500).describe("Raw event payloads"),
+            adapter: z.string().default("generic_webhook"),
+            domain: z.string().default(""),
+        },
+    }, async ({ events, adapter, domain }) => toResult(await client.request({
+        method: "POST",
+        path: "/ingest/batch",
+        body: { events, adapter, domain },
+    })));
+    server.registerTool("bighub_ingest_reconcile", {
+        description: "Reconcile a late-arriving outcome with a previous decision. " +
+            "Use when the outcome arrives after the initial event was already ingested.",
+        outputSchema: AnyOutputSchema,
+        inputSchema: {
+            key_name: z.string().describe("Correlation key: request_id, case_id, external_ref, tenant_ref, or entity_id"),
+            key_value: z.string().describe("Value of the correlation key"),
+            outcome: JsonObjectSchema.describe("Outcome event payload to attach"),
+        },
+    }, async ({ key_name, key_value, outcome }) => toResult(await client.request({
+        method: "POST",
+        path: "/ingest/reconcile",
+        body: { key_name, key_value, outcome },
+    })));
+    server.registerTool("bighub_ingest_lifecycles", {
+        description: "List decision lifecycles with optional status filter.",
+        outputSchema: AnyOutputSchema,
+        inputSchema: {
+            status_filter: z.string().optional().describe("Filter by lifecycle status"),
+            limit: z.number().int().default(50),
+        },
+    }, async ({ status_filter, limit }) => toResult(await client.request({
+        method: "GET",
+        path: "/ingest/lifecycles",
+        query: cleanObject({ status_filter, limit }),
+    })));
+    server.registerTool("bighub_ingest_lifecycle", {
+        description: "Get a specific decision lifecycle by correlation key.",
+        outputSchema: AnyOutputSchema,
+        inputSchema: {
+            request_id: z.string().optional(),
+            case_id: z.string().optional(),
+            external_ref: z.string().optional(),
+            tenant_ref: z.string().optional(),
+            entity_id: z.string().optional(),
+        },
+    }, async ({ request_id, case_id, external_ref, tenant_ref, entity_id }) => toResult(await client.request({
+        method: "GET",
+        path: "/ingest/lifecycle",
+        query: cleanObject({ request_id, case_id, external_ref, tenant_ref, entity_id }),
+    })));
+    server.registerTool("bighub_ingest_pending", {
+        description: "List lifecycles awaiting outcome reconciliation.",
+        outputSchema: AnyOutputSchema,
+        inputSchema: {
+            limit: z.number().int().default(50),
+        },
+    }, async ({ limit }) => toResult(await client.request({
+        method: "GET",
+        path: "/ingest/pending",
+        query: { limit },
+    })));
+    server.registerTool("bighub_ingest_stale", {
+        description: "List stale lifecycles that have not received an outcome within the expected timeframe.",
+        outputSchema: AnyOutputSchema,
+        inputSchema: {
+            stale_after_days: z.number().int().default(7),
+            limit: z.number().int().default(50),
+        },
+    }, async ({ stale_after_days, limit }) => toResult(await client.request({
+        method: "GET",
+        path: "/ingest/stale",
+        query: { stale_after_days, limit },
+    })));
+    server.registerTool("bighub_ingest_stats", {
+        description: "Get organization-wide ingestion statistics (event counts, adapter breakdown, lifecycle status distribution).",
+        outputSchema: AnyOutputSchema,
+        inputSchema: {},
+    }, async () => toResult(await client.request({
+        method: "GET",
+        path: "/ingest/stats",
+    })));
+    server.registerTool("bighub_ingest_adapters", {
+        description: "List available ingestion adapters and domain normalizers.",
+        outputSchema: AnyOutputSchema,
+        inputSchema: {},
+    }, async () => toResult(await client.request({
+        method: "GET",
+        path: "/ingest/adapters",
+    })));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bighub/bighub-mcp",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "mcpName": "io.bighub/mcp",
   "description": "MCP server for decision learning for AI agent actions with BIGHUB.",
   "type": "module",