Architecture

The three planes

The control plane runs as replica pods. It owns the public API, the Kubernetes reconciler, the approval RPC, and the read-only forensics UI. It coordinates turns and commits their results to the state plane. It holds no journal of its own.

The state plane runs as polychrome-state and stores durable records on its own volume. It alone writes the conversation journal. It also owns credential, session, ceremony, and persona records. The control plane connects to it over mutual TLS before binding any listener. If that connection fails, the control plane does not report ready or accept turns.

The execution plane is one harness pod per conversation. The harness runs the run_turn loop, executes pure tools and MCP calls, pauses for approvals, and hands off to other agents. Every turn-loop LLM call and external MCP call goes through the harness; the control plane reaches the provider only for transcript summarization and classification.

One turn, end to end

Use the controls below to follow a message through the system. The sequence shows the edge, control plane, reconciler, state plane's log, harness, and response.

The run_turn loop

The harness executes the agent loop in run_turn. The model emits text or requests a tool call. The loop executes tools and returns their results to the model. It repeats up to MAX_STEPS. A __handoff_to call or a tool requiring approval suspends the turn for the control plane to resolve.

Replay and exclusive journal access

A new replica resumes a conversation by replaying its partition through the state plane. The state plane alone opens and writes the Commonware journal on its volume. Control-plane replicas read that journal through the state plane, so they all read from the same authority.

Verify the event log

The event log uses signed roots to detect changes to committed events. The commands below verify those roots.

Each event produces one leaf digest from its position, kind, and payload. Changing any of these produces a different digest. The leaves form a Merkle Mountain Range. Each batch signs the resulting root with ed25519. It appends the signature and covered events to the same partition in one atomic commit. The signature covers the leaf count and root under a dedicated namespace.

Verification replays the partition and recomputes every root. A mismatch identifies the root that failed verification. The tree also supports proving one leaf against a trusted root without replaying the partition. The planes use these proofs to verify individual events. The commands below recompute the whole partition.

The first command asks the state plane to verify a named partition and requires no admin role. The second verifies a conversation through the control plane and requires an admin persona. Both commands are read-only and exit non-zero on failure. You can use either in incident-response checks.

# Ask the state plane to recompute one partition's signed roots.
polychrome state verify conv-abc --format json

# Or check a whole conversation through the control plane, as an admin.
polychrome conversation verify abc --actor '<provider>:<scope>:<external-id>'

Payments

When a tool receives 402 Payment Required, the harness forwards the charge to the control plane. The control plane settles it and returns the response body with a signed receipt. Signing occurs on the control plane. The harness holds no signing key. Payments use the foundation capability polyc-payments through the trusted-tool proxy. The orchestration core does not require payment-provider-specific logic.

Every payment requires human approval before settlement. The turn uses the same approval_request / approval_response pause as other sensitive tools. After settlement, a signed outbound_payment_receipt records the onchain reference and approved call in the event log. You can replay the log to audit each payment. A SecretStore stores keys in per-wallet Kubernetes Secrets in a cluster, or a local directory during development. Keys never enter the event log. Payments describes wallet linking and self-service tools.

Persisted event kinds

Observability

A turn spans three planes, several pods, and an external provider. Server components using the shared runtime expose health, metrics, tracing, and logging interfaces so you can inspect a request across components.

The W3C traceparent header connects control-plane and harness spans in one trace. That trace includes the public API, persistence, reconciliation, harness execution, and LLM provider calls. Set OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_SERVICE_NAME to enable the shared exporter.