Protoos

CI License Python 3.12+ Tests Requirements MCP SDK CLI API x402

Reference implementation of a policy-governed control plane that composes existing agent protocols — MCP, A2A, AP2 mandates, x402, MPP, UCP/ACP-style commerce, AG-UI, ANP/DID-style identity — into one environment where agents are built, discovered, coordinated, authorized, paid, and audited.

Pure Python 3.12 standard library (+ optional cryptography for Ed25519, with OS-verified HMAC fallback). Zero network required.

Related: OpenMesha · rui · server-os

Surfaces

Surface	Entry
CLI	protoos status · protoos verify · protoos graph · protoos vault
SDK	from protoos.sdk import ProtoOSClient
MCP Server	protoos-mcp / protoos/mcp.py (JSON-RPC, paid tools, mux, OpenAPI→MCP)
HTTP/JSON-RPC + SSE	protoos/httpapi.py (/mcp, /a2a, /agui/<run>, /.well-known/agents)
Multi-agent workflows	discovery + budgeted delegate + TaskGraph + AG-UI
Skills	skills/*/SKILL.md (policy, x402, multi-agent, constellation, mcp)
Constellation + Vault	python -m protoos.graph · python -m protoos.vault
CI	.github/workflows/ci.yml
AGENTS.md	Coding-agent contract at repo root
Requirement audit	traceability.json · VERIFICATION.md · python -m protoos.verify

New in 0.2.0 — Constellation & Obsidian vault

The world is now a first-class graph, at parity with the web console's Constellation tab.

• protoos.graph.build_graph(os) derives the live object graph — principals, budgets, MCP servers/tools, AP2 mandate chains, receipts, tasks, pending approvals — with the same node-type/edge-kind vocabulary as the browser build (parity-checked: MATCH).
• protoos.graph.layout(graph, seed=…) is a deterministic force layout. Exports: to_json, to_dot, to_svg.
• protoos.vault.write_vault[_zip](os, dest) writes an Obsidian vault of wikilinked notes; unresolved_links() proves integrity.
• Hardening: AuditLog.append deep-copies payloads; TraditionalRail retains receipts.

python3 -m protoos.graph out/        # constellation.{json,dot,svg}
python3 -m protoos.vault vault.zip   # Obsidian vault
python3 demo.py                      # also writes both artifacts
python3 -m protoos.cli status

Quickstart

python3 -m unittest discover -s tests   # 95 tests
python3 demo.py                          # end-to-end scenario
python3 -m protoos.verify                # traceability audit + live smoke
pip install -e ".[crypto]"               # optional Ed25519
protoos status

from protoos import ProtoOS, Catalog
from protoos.sdk import ProtoOSClient

os_ = ProtoOS()
os_.engine.add_rule("user", "allow", ["payment.settle"], "amount <= 200")
os_.engine.add_rule("org", "require_approval", ["payment.settle"], "amount > 50")

casey  = os_.create_user("casey")
shop   = os_.create_merchant("shop")
budget = os_.wallet.create_budget(casey.did, 500.0, window=(300.0, 86400))

catalog = Catalog(shop.did, "shop")
catalog.add("bk1", "Distributed Systems 101", 10.00, "USD", "digital")

receipt = os_.purchase(casey.did, catalog, [{"sku": "bk1", "qty": 2}],
                       intent_text="buy two intro ebooks", max_amount=100,
                       budget_id=budget.id, categories=["digital"])
# Intent Mandate -> checkout -> Cart Mandate -> Payment Mandate
# -> policy + budget -> x402 settle -> hash-chained audit

Spec → module map

Spec box	Module
Policy Engine + Mandate Store	protoos/policy.py
Orchestrator / Task Graph	protoos/runtime.py, protoos/core.py
Identity & Credential Service	protoos/identity.py
Discovery & Registry	protoos/registry.py
Observability & Audit	protoos/audit.py
Wallet / Spending Controller	protoos/wallet.py
MCP adapter (+OpenAPI→MCP, federation, cache)	protoos/mcp.py
A2A adapter + AG-UI event bus	protoos/a2a.py
UCP/ACP-style commerce	protoos/commerce.py
HTTP/JSON-RPC + SSE transport	protoos/httpapi.py
Control-plane facade (ProtoOS)	protoos/core.py
CLI	protoos/cli.py
SDK	protoos/sdk/
Constellation graph	protoos/graph.py
Obsidian vault export	protoos/vault.py
Kubernetes CRDs + Deployment	deploy/k8s/
Skills	skills/
Requirement audit	traceability.json, VERIFICATION.md, protoos/verify.py

What "reference implementation" means here

Every protocol surface named by the spec is working and tested in-process: JSON-RPC MCP with paid tools, the A2A task lifecycle, the full AP2 Intent→Cart→Payment mandate chain, x402 challenge/settle with an in-process facilitator, MPP prepaid sessions, AG-UI event streams over SSE, DID documents and well-known publication. This sandbox has no network egress, no Kubernetes cluster, and no external SDKs, so anything that requires the open internet is implemented against local/loopback equivalents and explicitly marked partial or deferred in traceability.json — nothing is silently omitted.

Production hardening path

1. Rust control plane (X1): module boundaries here mirror the intended services; the Python build is the executable specification.
2. Storage (X3): in-memory + JSONL → etcd/Postgres / object storage / vector DB.
3. Rails (M1/X6): official x402/MPP/AP2 SDKs slot into the existing rail seams.
4. Transports (X4/X5): add gRPC/QUIC beside httpapi.py.
5. Sandboxing (G4): replace SandboxedExecutor with container/microVM isolation.

Design principles

1. Compose, don't replace
2. Policy-first autonomy (every sensitive action gated)
3. Cryptographic mandates + hash-chained audit
4. Human-in-the-loop as a first-class primitive
5. Multi-rail everything (tools, messaging, payments, identity)
6. Offline-first reference with honest partial/deferred markers

License

Apache-2.0. Governance charter draft: GOVERNANCE.md.