consequence-gate 0.1.0__py3-none-any.whl

consequence_gate/integrations/mcp_proxy.py

@@ -0,0 +1,316 @@
+"""
+MCP Proxy: consequence-gate middleware for Model Context Protocol.
+
+Intercepts tools/call requests, runs consequence simulation, and either:
+- ALLOW: forwards request to downstream MCP server
+- DENY: returns JSON-RPC error (code=-32603, "BLOCKED: <reason>")
+- ASK: returns tool result with isError=true and "ESCALATION_REQUIRED" message
+- STEER: returns tool result with isError=true and structured guidance
+
+Transport: stdio (newline-delimited JSON-RPC)
+- Reads from stdin (client -> proxy)
+- Writes to stdout (proxy -> client)
+- Forwards to downstream MCP server via subprocess stdio
+
+MCP spec reference:
+- tools/call: https://modelcontextprotocol.io/specification/2025-11-25/server/tools/
+- Transport: https://modelcontextprotocol.io/specification/2025-11-25/basic/transports/
+- Error handling: https://apxml.com/courses/getting-started-model-context-protocol/chapter-3-implementing-tools-and-logic/error-handling-reporting
+"""
+
+import json
+import subprocess
+import sys
+from typing import Any, Callable, Dict, Optional
+
+from ..core.models import GateDecision, EvaluationResult
+from ..core.circuit_breaker import SteerCircuitBreaker
+from ..simulators.financial import FinancialDeltaPredictor
+from ..simulators.database import DataDeletionSimulator
+from ..simulators.communications import OutboundCommunicationSimulator
+
+
+class MCPConsequenceProxy:
+    """
+    MCP proxy that sits between an MCP client (Claude Desktop, Cursor, etc.)
+    and a downstream MCP server, intercepting tools/call requests to run
+    consequence simulation before forwarding.
+
+    Usage:
+        proxy = MCPConsequenceProxy(
+            downstream_command=["npx", "-y", "mcp-server-mytool"],
+            simulator_fn=financial_simulator,
+            evaluator_fn=evaluator,
+            circuit_breaker=SteerCircuitBreaker(),
+        )
+        proxy.run()  # Blocks, reading from stdin, writing to stdout
+    """
+
+    def __init__(
+        self,
+        downstream_command: list,
+        simulator_fn: Callable[[str, Dict[str, Any], Dict[str, Any]], Any],
+        evaluator_fn: Callable[[Any, SteerCircuitBreaker], EvaluationResult],
+        circuit_breaker: Optional[SteerCircuitBreaker] = None,
+        context_provider: Optional[Callable[[Dict[str, Any]], Dict[str, Any]]] = None,
+    ):
+        """
+        Args:
+            downstream_command: Command to launch downstream MCP server
+            simulator_fn: function(tool_name, args, context) -> delta
+            evaluator_fn: function(delta, circuit_breaker) -> EvaluationResult
+            circuit_breaker: SteerCircuitBreaker (default: max_retries=2)
+            context_provider: function(request_params) -> context dict
+        """
+        self.downstream_command = downstream_command
+        self.simulator_fn = simulator_fn
+        self.evaluator_fn = evaluator_fn
+        self.circuit_breaker = circuit_breaker or SteerCircuitBreaker(max_retries=2)
+        self.context_provider = context_provider or (lambda params: {})
+
+        self.downstream_process: Optional[subprocess.Popen] = None
+
+    def _extract_natural_key(self, tool_name: str, arguments: Dict[str, Any]) -> str:
+        """Extract stable natural key for idempotency."""
+        return arguments.get("claim_id") or arguments.get("transaction_ref") or f"{tool_name}:{json.dumps(arguments, sort_keys=True)}"
+
+    def _intercept_tools_call(self, request: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        """
+        Intercept a tools/call request. Returns a response dict if the gate
+        decides DENY/ASK/STEER, or None if the request should be forwarded.
+        """
+        params = request.get("params", {})
+        tool_name = params.get("name", "unknown")
+        arguments = params.get("arguments", {})
+        context = self.context_provider(params)
+
+        natural_key = self._extract_natural_key(tool_name, arguments)
+        delta = self.simulator_fn(tool_name, arguments, context)
+        result = self.evaluator_fn(delta, self.circuit_breaker)
+
+        request_id = request.get("id")
+
+        if result.decision == GateDecision.ALLOW:
+            return None  # Forward to downstream
+
+        if result.decision == GateDecision.DENY:
+            # Protocol error - model cannot retry
+            return {
+                "jsonrpc": "2.0",
+                "id": request_id,
+                "error": {
+                    "code": -32603,
+                    "message": f"BLOCKED: {result.reason}",
+                },
+            }
+
+        if result.decision in (GateDecision.ASK, GateDecision.STEER):
+            # Tool execution error - model can retry with adjusted parameters
+            if result.decision == GateDecision.ASK:
+                error_text = f"ESCALATION_REQUIRED: {result.reason}"
+            else:  # STEER
+                steer_payload = result.steer_payload or {}
+                guidance = steer_payload.get("guidance", result.reason)
+                suggested_tool = steer_payload.get("suggested_tool")
+                suggested_args = steer_payload.get("suggested_args", {})
+                idempotency_key = suggested_args.get("idempotency_key")
+                if idempotency_key:
+                    guidance += f" [idempotency_key={idempotency_key}]"
+                error_text = (
+                    f"STEER_GUIDANCE: {guidance}\n"
+                    f"Suggested alternative: {suggested_tool} with args {suggested_args}"
+                )
+
+            return {
+                "jsonrpc": "2.0",
+                "id": request_id,
+                "result": {
+                    "content": [{"type": "text", "text": error_text}],
+                    "isError": True,
+                },
+            }
+
+        return None  # Should not reach here
+
+    def _forward_to_downstream(self, request: Dict[str, Any]) -> Dict[str, Any]:
+        """Forward request to downstream MCP server and return response."""
+        if self.downstream_process is None:
+            self.downstream_process = subprocess.Popen(
+                self.downstream_command,
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                bufsize=1,
+            )
+
+        # Write request to downstream stdin
+        request_line = json.dumps(request) + "\n"
+        self.downstream_process.stdin.write(request_line)
+        self.downstream_process.stdin.flush()
+
+        # Read response from downstream stdout
+        response_line = self.downstream_process.stdout.readline()
+        return json.loads(response_line)
+
+    def _process_line(self, line: str) -> Optional[str]:
+        """Process a single JSON-RPC line from client."""
+        try:
+            request = json.loads(line)
+        except json.JSONDecodeError:
+            # Malformed JSON - forward as-is, let downstream handle
+            return None
+
+        method = request.get("method")
+        if method != "tools/call":
+            # Not a tool call - forward as-is
+            return None
+
+        # Intercept tools/call
+        intercepted_response = self._intercept_tools_call(request)
+        if intercepted_response is not None:
+            # Gate decided - return response directly to client
+            return json.dumps(intercepted_response)
+
+        # Gate allowed - forward to downstream
+        response = self._forward_to_downstream(request)
+        return json.dumps(response)
+
+    def run(self):
+        """Main proxy loop: read from stdin, process, write to stdout."""
+        try:
+            for line in sys.stdin:
+                line = line.strip()
+                if not line:
+                    continue
+
+                response_line = self._process_line(line)
+                if response_line is not None:
+                    sys.stdout.write(response_line + "\n")
+                    sys.stdout.flush()
+        except KeyboardInterrupt:
+            pass
+        finally:
+            if self.downstream_process is not None:
+                self.downstream_process.terminate()
+
+
+# Convenience factory functions
+
+def create_financial_mcp_proxy(
+    downstream_command: list,
+    daily_tier_limit_inr: float = 25000.0,
+    instant_wire_threshold: float = 10000.0,
+    max_retries: int = 2,
+    context_provider: Optional[Callable[[Dict[str, Any]], Dict[str, Any]]] = None,
+) -> MCPConsequenceProxy:
+    """
+    Factory for financial-disbursement MCP proxy.
+
+    Usage:
+        proxy = create_financial_mcp_proxy(
+            downstream_command=["npx", "-y", "mcp-server-payments"],
+            daily_tier_limit_inr=25000.0,
+            context_provider=lambda params: {
+                "account_rolling_24h_spend": get_spend(params),
+                "kyc_verified": is_kyc_verified(params),
+            },
+        )
+        proxy.run()
+    """
+    predictor = FinancialDeltaPredictor(
+        daily_tier_limit_inr=daily_tier_limit_inr,
+        instant_wire_threshold=instant_wire_threshold,
+    )
+    breaker = SteerCircuitBreaker(max_retries=max_retries)
+
+    def evaluator(delta, circuit_breaker):
+        return predictor.evaluate(delta, circuit_breaker)
+
+    return MCPConsequenceProxy(
+        downstream_command=downstream_command,
+        simulator_fn=predictor.simulate,
+        evaluator_fn=evaluator,
+        circuit_breaker=breaker,
+        context_provider=context_provider,
+    )
+
+
+def create_database_mcp_proxy(
+    downstream_command: list,
+    max_autonomous_delete_rows: int = 100,
+    db_conn=None,
+    max_retries: int = 2,
+    context_provider: Optional[Callable[[Dict[str, Any]], Dict[str, Any]]] = None,
+) -> MCPConsequenceProxy:
+    """
+    Factory for database-deletion MCP proxy.
+
+    Usage:
+        proxy = create_database_mcp_proxy(
+            downstream_command=["npx", "-y", "mcp-server-postgres"],
+            max_autonomous_delete_rows=100,
+            db_conn=get_db_connection(),
+        )
+        proxy.run()
+    """
+    simulator = DataDeletionSimulator(
+        max_autonomous_delete_rows=max_autonomous_delete_rows,
+        db_conn=db_conn,
+    )
+    breaker = SteerCircuitBreaker(max_retries=max_retries)
+
+    def evaluator(delta, circuit_breaker):
+        return simulator.evaluate(delta, circuit_breaker)
+
+    return MCPConsequenceProxy(
+        downstream_command=downstream_command,
+        simulator_fn=simulator.simulate,
+        evaluator_fn=evaluator,
+        circuit_breaker=breaker,
+        context_provider=context_provider,
+    )
+
+
+def create_communications_mcp_proxy(
+    downstream_command: list,
+    max_autonomous_recipients: int = 10000,
+    canary_min_size: int = 100,
+    canary_max_bounce_rate: float = 0.05,
+    canary_max_complaint_rate: float = 0.01,
+    max_retries: int = 2,
+    context_provider: Optional[Callable[[Dict[str, Any]], Dict[str, Any]]] = None,
+) -> MCPConsequenceProxy:
+    """
+    Factory for communications-blast MCP proxy.
+
+    Usage:
+        proxy = create_communications_mcp_proxy(
+            downstream_command=["npx", "-y", "mcp-server-sendgrid"],
+            max_autonomous_recipients=10000,
+            context_provider=lambda params: {
+                "segment_counts": get_segments(params),
+                "recent_unsubscribes": get_unsubscribes(params),
+                "historical_bounce_rate": 0.02,
+            },
+        )
+        proxy.run()
+    """
+    simulator = OutboundCommunicationSimulator(
+        max_autonomous_recipients=max_autonomous_recipients,
+        canary_min_size=canary_min_size,
+        canary_max_bounce_rate=canary_max_bounce_rate,
+        canary_max_complaint_rate=canary_max_complaint_rate,
+    )
+    breaker = SteerCircuitBreaker(max_retries=max_retries)
+
+    def evaluator(delta, circuit_breaker):
+        return simulator.evaluate(delta, circuit_breaker)
+
+    return MCPConsequenceProxy(
+        downstream_command=downstream_command,
+        simulator_fn=simulator.simulate,
+        evaluator_fn=evaluator,
+        circuit_breaker=breaker,
+        context_provider=context_provider,
+    )

consequence_gate/integrations/strands_hook.py

@@ -0,0 +1,224 @@
+"""
+Strands Agents integration: BeforeToolCallEvent hook adapter.
+
+Strands API reference:
+- BeforeToolCallEvent: https://strandsagents.com/docs/api/python/strands.hooks.events/
+- Event attributes: selected_tool, cancel_tool (string or True)
+- No event.set_result() exists — steering must be done via cancellation
+  message that the agent sees on its next turn and can re-reason from.
+
+Design contract (from project history):
+- No silent argument mutation — we cancel with guidance, not rewrite args.
+- Idempotency keys derived from natural_key, not regenerated per retry.
+- Hard retry cap (default: 2) before forced escalation to ASK.
+- Confidence-gated escalation — low confidence routes to ASK, never
+  confident ALLOW/DENY on unfounded projections.
+"""
+
+from typing import Any, Callable, Dict, Optional
+import json
+
+try:
+    from strands.hooks import BeforeToolCallEvent
+    from strands.hooks.events import HookProvider, HookRegistry
+except ImportError:
+    class HookProvider:  # type: ignore[no-redef]
+        """Fallback base class when strands-agents is not installed."""
+        pass
+
+    BeforeToolCallEvent = Any  # type: ignore[misc,assignment]
+    HookRegistry = Any  # type: ignore[misc,assignment]
+
+from ..core.models import GateDecision, EvaluationResult
+from ..core.circuit_breaker import SteerCircuitBreaker
+from ..simulators.financial import FinancialDeltaPredictor
+from ..simulators.database import DataDeletionSimulator
+
+
+class ConsequenceGateHook(HookProvider):
+    """
+    Strands hook provider that intercepts BeforeToolCallEvent, runs the
+    consequence simulation gate, and either:
+    - ALLOW: returns cleanly, tool executes normally
+    - DENY: sets event.cancel_tool with a hard-block message
+    - ASK: sets event.cancel_tool with an escalation message
+    - STEER: sets event.cancel_tool with structured guidance that the
+             agent can parse and retry toward on its next turn
+
+    Usage:
+        from consequence_gate.integrations.strands_hook import ConsequenceGateHook
+
+        hook = ConsequenceGateHook(
+            simulator_fn=financial_simulator,  # or database_simulator, etc.
+            circuit_breaker=SteerCircuitBreaker(max_retries=2),
+        )
+        agent = Agent(hooks=[hook])
+    """
+
+    def __init__(
+        self,
+        simulator_fn: Callable[[str, Dict[str, Any], Dict[str, Any]], Any],
+        evaluator_fn: Optional[Callable[[Any, SteerCircuitBreaker], EvaluationResult]] = None,
+        circuit_breaker: Optional[SteerCircuitBreaker] = None,
+        context_provider: Optional[Callable[[BeforeToolCallEvent], Dict[str, Any]]] = None,
+    ):
+        """
+        Args:
+            simulator_fn: function(tool_name, args, context) -> delta object
+            evaluator_fn: function(delta, circuit_breaker) -> EvaluationResult
+                          If None, uses a default generic evaluator.
+            circuit_breaker: SteerCircuitBreaker instance (default: max_retries=2)
+            context_provider: function(event) -> context dict for simulation
+                              If None, uses a minimal default context.
+        """
+        self.simulator_fn = simulator_fn
+        self.evaluator_fn = evaluator_fn
+        self.circuit_breaker = circuit_breaker or SteerCircuitBreaker(max_retries=2)
+        self.context_provider = context_provider or self._default_context
+
+    def register_hooks(self, registry: HookRegistry, **kwargs: Any) -> None:
+        registry.add_callback(BeforeToolCallEvent, self.intercept)
+
+    def _default_context(self, event: BeforeToolCallEvent) -> Dict[str, Any]:
+        """
+        Minimal default context extractor. Override this to pull in
+        session state, user identity, account telemetry, etc.
+        """
+        return {
+            "tool_use_id": event.tool_use.get("toolUseId"),
+            "conversation_id": getattr(event, "invocation_state", {}).get("conversation_id"),
+        }
+
+    def intercept(self, event: BeforeToolCallEvent) -> None:
+        tool_name = event.tool_use.get("name", "unknown")
+        args = event.tool_use.get("input", {})
+        context = self.context_provider(event)
+
+        # Extract natural key from args (domain-specific; financial uses claim_id,
+        # database uses table+filter hash, etc.)
+        natural_key = args.get("claim_id") or args.get("transaction_ref") or f"{tool_name}:{json.dumps(args, sort_keys=True)}"
+
+        # Run simulation + evaluation
+        delta = self.simulator_fn(tool_name, args, context)
+
+        if self.evaluator_fn is not None:
+            result = self.evaluator_fn(delta, self.circuit_breaker)
+        else:
+            # Fallback: generic evaluator (not domain-aware, but safe)
+            from ..core.evaluator import BlastRadiusEvaluator
+            evaluator = BlastRadiusEvaluator()
+            gate_decision = evaluator.evaluate(delta)
+            # Wrap generic decision into EvaluationResult for uniform handling
+            result = EvaluationResult(
+                decision=gate_decision,
+                confidence=delta.confidence,
+                reason="Generic evaluator fallback.",
+            )
+
+        # Apply decision
+        if result.decision == GateDecision.ALLOW:
+            # Pass through — do nothing, tool executes normally
+            return
+
+        if result.decision == GateDecision.DENY:
+            event.cancel_tool = f"BLOCKED: {result.reason}"
+            return
+
+        if result.decision == GateDecision.ASK:
+            event.cancel_tool = f"ESCALATION_REQUIRED: {result.reason}"
+            return
+
+        if result.decision == GateDecision.STEER:
+            # Cancel with structured guidance — agent sees this message
+            # on its next turn and can re-reason toward the safer path.
+            steer_payload = result.steer_payload or {}
+            guidance_text = steer_payload.get("guidance", result.reason)
+            suggested_tool = steer_payload.get("suggested_tool")
+            suggested_args = steer_payload.get("suggested_args", {})
+
+            # Include idempotency key in the guidance so the agent can
+            # include it when retrying (if the suggested tool expects it).
+            idempotency_key = suggested_args.get("idempotency_key")
+            if idempotency_key:
+                guidance_text += f" [idempotency_key={idempotency_key}]"
+
+            cancel_message = (
+                f"STEER_GUIDANCE: {guidance_text}\n"
+                f"Suggested alternative: {suggested_tool} with args {suggested_args}"
+            )
+            event.cancel_tool = cancel_message
+            return
+
+
+# Convenience factory functions for common domain simulators
+
+def create_financial_gate_hook(
+    daily_tier_limit_inr: float = 25000.0,
+    instant_wire_threshold: float = 10000.0,
+    max_retries: int = 2,
+    context_provider: Optional[Callable[[BeforeToolCallEvent], Dict[str, Any]]] = None,
+) -> ConsequenceGateHook:
+    """
+    Factory for a financial-disbursement gate hook.
+
+    Usage:
+        hook = create_financial_gate_hook(
+            daily_tier_limit_inr=25000.0,
+            context_provider=lambda event: {
+                "account_rolling_24h_spend": get_current_spend(event),
+                "kyc_verified": is_kyc_verified(event),
+            },
+        )
+        agent = Agent(hooks=[hook])
+    """
+    predictor = FinancialDeltaPredictor(
+        daily_tier_limit_inr=daily_tier_limit_inr,
+        instant_wire_threshold=instant_wire_threshold,
+    )
+    breaker = SteerCircuitBreaker(max_retries=max_retries)
+
+    def evaluator(delta, circuit_breaker):
+        return predictor.evaluate(delta, circuit_breaker)
+
+    return ConsequenceGateHook(
+        simulator_fn=predictor.simulate,
+        evaluator_fn=evaluator,
+        circuit_breaker=breaker,
+        context_provider=context_provider,
+    )
+
+
+def create_database_gate_hook(
+    max_autonomous_delete_rows: int = 100,
+    db_conn=None,
+    max_retries: int = 2,
+    context_provider: Optional[Callable[[BeforeToolCallEvent], Dict[str, Any]]] = None,
+) -> ConsequenceGateHook:
+    """
+    Factory for a database-deletion gate hook.
+
+    Usage:
+        hook = create_database_gate_hook(
+            max_autonomous_delete_rows=100,
+            db_conn=get_db_connection(),
+            context_provider=lambda event: {
+                "table_metadata": get_table_metadata(event),
+            },
+        )
+        agent = Agent(hooks=[hook])
+    """
+    simulator = DataDeletionSimulator(
+        max_autonomous_delete_rows=max_autonomous_delete_rows,
+        db_conn=db_conn,
+    )
+    breaker = SteerCircuitBreaker(max_retries=max_retries)
+
+    def evaluator(delta, circuit_breaker):
+        return simulator.evaluate(delta, circuit_breaker)
+
+    return ConsequenceGateHook(
+        simulator_fn=simulator.simulate,
+        evaluator_fn=evaluator,
+        circuit_breaker=breaker,
+        context_provider=context_provider,
+    )