agent-control-plane
by sujithnsn953
README.md
# 🛰 agent-control-plane
[](https://github.com/sujithnsn953/agent-control-plane/actions/workflows/ci.yml)
**The systems layer around an agent — not another agent.**
> Anyone can wire up a model and some tools. What decides whether it survives production
> is the layer around it: a **portable tool surface**, **scope grants the model cannot
> argue with**, **failure modes you can name and detect**, and **a bill you can predict
> before it arrives.**
```bash
git clone https://github.com/sujithnsn953/agent-control-plane
cd agent-control-plane
python examples/demo.py # all four, ~0.1s, no API key
pytest # 55 tests
```
Zero runtime dependencies — the MCP server, both transports and the HTTP conformance
tests are standard library only. There is no framework between the code and the spec.
---
## Three things, each enforced in code
### 1. A spec-correct MCP server — protocol `2025-11-25`
Not a wrapper around someone else's SDK. JSON-RPC 2.0 framing, lifecycle, and **both**
standard transports, written against the spec's MUSTs with a conformance test for each
rule that is easy to get wrong:
| Rule | Where | Test |
|---|---|---|
| stdout carries **only** MCP messages; logs go to stderr | [`transports.py`](agent_control_plane/mcp/transports.py) | `test_stdio_writes_only_mcp_messages_to_stdout` |
| Framing must never contain an embedded newline | [`jsonrpc.py`](agent_control_plane/mcp/jsonrpc.py) | `test_encoded_message_never_contains_a_newline` |
| `Origin` validated → **403** (DNS rebinding defence) | `origin_allowed` | `test_http_rejects_bad_origin_with_403` |
| `Accept` must offer **both** json and event-stream | `accept_ok` | `test_http_rejects_missing_accept_types_with_400` |
| Missing `MCP-Protocol-Version` → assume `2025-03-26` | `protocol_version_ok` | `test_protocol_version_header_rules` |
| Unsupported version → **400** | `protocol_version_ok` | `test_http_rejects_unsupported_protocol_version_with_400` |
| `MCP-Session-Id` issued at init, visible ASCII only | `SessionStore` | `test_http_initialize_issues_a_session_id` |
| Unknown/terminated session → **404**, so the client restarts | `do_POST` | `test_http_unknown_session_is_404_so_client_restarts` |
| Notification input → **202**, no body, never answered | `do_POST` | `test_http_notification_returns_202_with_no_body` |
| No server-initiated stream → GET returns **405** | `do_GET` | `test_http_get_declines_sse_stream_with_405` |
Two decisions worth defending:
**Version negotiation doesn't echo.** If a client requests a version we don't speak, the
server replies with its own latest rather than parroting the request back. Echoing claims
support you don't have, and the client finds out the hard way.
**Tool failure is a result, not a protocol error.** A tool that raises returns
`isError: true` so the model can see it and adapt. JSON-RPC errors are reserved for
protocol faults — which keeps "the agent misbehaved" separable from "the transport did".
### 2. Orchestration with failure modes that are *detected*, not described
A supervisor plans and delegates. Workers hold **scoped tool grants**. A critic reviews.
The supervisor **holds no tools at all** — so a confused supervisor wastes tokens rather
than causing side effects, and every side effect traces to exactly one scoped worker.
Seven named pathologies, each detectable as a pure function of the run record, each
driven deliberately in [`test_failure_modes.py`](tests/test_failure_modes.py):
| Mode | What it looks like |
|---|---|
| `supervisor_thrash` | the same assignment reissued forever because the result won't parse |
| `empty_worker_result` | success reported with no content; emptiness propagates into the answer |
| `critic_deadlock` | the reviewer never signs off |
| `context_explosion` | every agent appends, none compacts; the run dies of context length |
| `scope_violation` | a worker reaches outside its grant — **OWASP LLM06 Excessive Agency** |
| `partial_completion` | success claimed while subtasks failed — the most dangerous, because nothing *looks* broken |
| `orphaned_subtask` | planned, then never assigned or never returned |
`critic_deadlock` is the one I'd read first. Bounding the loop stops the budget bleeding,
but a run that exits early because the synthesis stopped changing is *still* a run whose
reviewer never accepted the answer. Flagging only on the round limit would hide exactly
the case the bound was added to handle — so the detector covers both.
### 3. Cost governance — the question that separates shipped from demoed
Hiring guides put it bluntly: someone who has never reasoned about inference cost has
never shipped under a budget.
```
routing 8/10 calls down: $0.0738 vs $0.225 always-frontier (67.2% saved)
prefix reused 1x : caching LOSES money (breakeven at 1.278 calls)
prefix reused 2x : worth caching
per-run P&L : $0.044500 of $0.5 ceiling
supervisor:synthesis $0.042500
reader:t1 $0.002000
```
**Prompt-cache breakeven is independent of prefix size.** Writing to cache costs *more*
than a normal input token; reading costs far less. Set the two totals equal and the
prefix length cancels:
```
N* = (cache_write − cache_read) / (input − cache_read)
```
So "is my prompt big enough to cache?" is the wrong question. "Will I reuse it enough
times?" is the right one — and for a prefix you touch once, caching is a straight loss.
There's [a test for that](tests/test_cost.py).
**Routing escalates on evidence, never on a guess** — a declared complexity or an actual
failure — and every decision records *why*. A routing layer you can't audit is one nobody
will trust with production traffic.
**The ceiling is enforced, not advisory.** `charge()` raises when the budget is gone, and
a rejected charge is never recorded — a ledger that logs charges it refuses can't be
reconciled against the provider's bill.
---
## How this fits the other two repos
This is the platform; those are its components.
- **[secure-rag-assistant](https://github.com/sujithnsn953/secure-rag-assistant)** — *a
prompt instruction is not a security control*: redaction before embedding, scope
filtering before ranking, 39 security tests.
- **[pharma-ops-agent](https://github.com/sujithnsn953/pharma-ops-agent)** — *a correct
final answer is not a working agent*: trajectory evaluation, budgets, loop detection,
and a CI release gate.
- **[pharma-supply-intelligence](https://github.com/sujithnsn953/pharma-supply-intelligence)**
— the data platform underneath: Event Hubs → Databricks medallion → XGBoost → FastAPI,
Terraform-provisioned and run live on Azure.
Three focused libraries and one platform composing them, which is how real teams build —
and a better signal than one repo trying to do everything.
## Roadmap
Phase 1 is what's here. Next: OpenTelemetry GenAI tracing, working/episodic memory with
write policies, hybrid retrieval (BM25 + vector) with recall@k, and a human-in-the-loop
approval queue with a kill switch for irreversible actions.
## A note on the numbers
Model prices move constantly. The table in [`pricing.py`](agent_control_plane/cost/pricing.py)
is **illustrative and configurable** — `verify_prices_before_use` exists so nobody ships a
cost model built on a stale constant. The arithmetic is the durable part; the rates are
data you supply.
## License
MIT — see [LICENSE](LICENSE).
This server cannot be deployed
Maintenance
ActivitySlowing
ResponsivenessNo issues