🛰 agent-control-plane

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.

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	test_stdio_writes_only_mcp_messages_to_stdout
Framing must never contain an embedded newline	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:

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.

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 — a prompt instruction is not a security control: redaction before embedding, scope filtering before ranking, 39 security tests.
• 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 — 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 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.