gateway package

Reviewed against commit 8a2cb42ad on 2026-10-23.

Reference: package page (49 modules, 12,376 lines; 22 of them in handlers) · key modules: server, rpc, method_table, mcp_transport, config, audit. The request path from client to volk through the gateway is described in the overview.

The story

orchestrata_ultimate.gateway is the Orchestrata WebSocket Gateway (SPEC-014) — the real-time control plane of the system. Everything else in Orchestrata (the kernel, the volk agents, the pipeline, the knowledge graph) runs headless; this package is where a human-facing client — the VizInt web UI, a TUI, or any tooling speaking JSON-RPC 2.0 over WebSocket — plugs in. It exists so that one authenticated, subscription-aware socket can observe and steer the whole platform, instead of each client wiring itself to Redis, the operational graph (orchkg), the CXP router, and the kernel individually.

A connection's life begins at server.py's WebSocketGateway, the composition root that constructs and owns every subsystem. The socket is first handed to the authentication flow (auth_handler.py plus TokenAuthenticator in auth.py), driven by a GatewayConfig built entirely from environment variables — including explicit JWT-secret resolution that refuses insecure dev secrets via InsecureJWTSecretError. Once authenticated, the connection is tracked by the ConnectionManager (session.py) using the ConnectionInfo/ConnectionState models, and every inbound frame flows through the MessageProcessor (protocol.py), which parses and validates WSMessage traffic and decides whether a message is an RPC call, a subscription action, or a broadcast.

RPC calls land in rpc.py's RPCHandler, which is deliberately thin: _build_method_registry maps JSON-RPC method names such as cxp.send, session.open, or volk.list onto per-domain handler classes under handlers/ — one handler per subsystem (CXP routing, sessions, volks, governance, knowledge graph, memory engine, orchestrator intents, Redis state, projects, Fireflies transcripts, test metrics, and the UltimateTUI bridge to CheetahClaws agents). These handlers were split out of a formerly monolithic RPCHandler, so each one wraps exactly one neighboring package and nothing else. Results and events fan back out through the in-process PubSubManager (pubsub.py) to whichever connections have subscribed.

The gateway also remembers and reports. Every event is appended to a Redis-streams ring buffer (RedisRingBuffer in ring_buffer.py), which powers the gateway.replay RPC, and audited to the operational graph (orchkg; Neo4j until its retirement on 2026-07-27) by the AuditWriter (audit.py) behind a small circuit breaker so a graph outage never stalls the socket. The kernel link is the cxpt direct transport; kernel_reprobe.py keeps retrying in the background so a gateway that booted on its in-process fallback (PipelineKernelClient) upgrades to the real kernel once it is reachable (grpcio, the earlier transport, was retired on 2026-08-07). The JSON-RPC methods are also declared as data in method_table.py (ADR-0099), and mcp_transport.py turns that table into the stdio MCP server (orchestrata-mcp) that is a client of the running gateway, with mcp_approval_gate.py, mcp_ledger.py and mcp_tool_spec.py supporting it. Workflow control RPCs (workflow.start, pause, resume, cancel) and runtime configuration (config.get, config.watch) are served by the workflow and config handlers behind a scope guard and a governance policy gate. Background pumps inside WebSocketGateway (_pump_kernel_replies_once, _pump_pipeline_events_once) continuously pull kernel replies and pipeline events out of Redis and broadcast them onto subscribed sockets — this is how a running pipeline becomes visible in the UI in real time. An HTTP sidecar (http_surface.py) exposes /health, /ready, and /metrics for operations, and cli.py provides the serve entry point. VizIntWebUI, a subclass of WebSocketGateway, specializes the gateway for the VizInt web UI.

Key responsibilities

Terminate WebSocket connections and authenticate them with JWTs (TokenAuthenticator, auth_handler.py), refusing the insecure dev secret outside a dev/test context.
Track connection lifecycle — register, heartbeat, and unregister sockets and their states (ConnectionManager, ConnectionInfo).
Parse and route protocol frames into RPC calls, subscription actions, and broadcasts (MessageProcessor, WSMessage).
Dispatch JSON-RPC methods to one-per-subsystem domain handlers under handlers/ (RPCHandler, dispatch).
Fan events out to subscribers via in-process topic pub/sub with pattern matching and filters (PubSubManager, Subscription).
Persist an event history in a Redis-streams ring buffer for replay (RedisRingBuffer) and audit events to the operational graph with circuit-breaker protection (AuditWriter).
Bridge live backends into the socket — kernel replies and pipeline events pumped out of Redis and broadcast to the UI in real time (WebSocketGateway).
Expose operational endpoints — /health, /ready, /metrics (http_surface.py) — and a serve CLI entry point (cli.py).

Class diagram

Runtime core

The gateway's beating heart. WebSocketGateway is the composition root that owns one instance of every collaborator; MessageProcessor is where inbound frames are decoded and then routed — down to RPCHandler for method calls, across to ConnectionManager for the socket registry, and out through PubSubManager to subscribers (render-verified).

Persistence, auth, and config

The support tier. A single frozen GatewayConfig, resolved from environment variables, feeds every collaborator: TokenAuthenticator signs and validates JWTs, RedisRingBuffer streams events to Redis for replay, and AuditWriter mirrors events into the operational graph behind a failure-counting circuit breaker (render-verified).

Protocol data models

The dataclasses that travel over the wire and the registry. WSMessage is the envelope for every frame (tagged by the MessageType enum); ConnectionInfo is the per-socket record the ConnectionManager keeps (carrying a ConnectionState enum); Subscription is one pub/sub interest a connection registers (render-verified).

MessageType values: RPC_REQUEST, RPC_RESPONSE, EVENT, ERROR, HEARTBEAT, AUTH. ConnectionState values: CONNECTING, AUTHENTICATING, ACTIVE, CLOSING, CLOSED.

Inheritance diagram

Inheritance across the package: a flat GatewayError exception hierarchy, two enums, and the VizIntWebUI specialization of the gateway (render-verified).

Module dependency diagram

Internal module imports within orchestrata_ultimate.gateway, generated from the AST (render-verified):

Module inventory

Module	Purpose
`__init__.py`	Package facade — re-exports `GatewayConfig`, models, and core classes. SPEC-014 summary docstring.
`audit.py`	Graph audit writer for gateway events (operational graph; formerly Neo4j) (`AuditWriter`) with a failure-counting circuit breaker.
`auth.py`	Token-based authentication for WebSocket connections (`TokenAuthenticator`).
`auth_handler.py`	Connection authentication flow: `authenticate`, `handle_jsonrpc_auth`, `send_error`, plus Redis/graph lazy-connect helpers.
`error_taxonomy.py`	SPEC-098 FR-006/007 error schema for JSON-RPC errors: `ErrorCategory` (AUTH, AUTHZ, VAL, RES, RATE, SYS) and code categories.
`kernel_reprobe.py`	Bounded background re-probe that upgrades the in-process fallback kernel client to the real kernel (SPEC-014 US-014-011).
`mcp_approval_gate.py`	`McpApprovalGate` — single-use, tool-bound approval tokens for MCP tool calls.
`mcp_ledger.py`	`McpLedger` — append-only ndjson ledger of MCP tool calls.
`mcp_tool_spec.py`	`McpToolSpec` — one generated MCP tool, adapted from a `MethodSpec`.
`mcp_transport.py`	`McpTransport` — the stdio MCP transport (`orchestrata-mcp`, ADR-0099); a client of the gateway's WebSocket API.
`method_spec.py`	`MethodSpec` — one row of the declarative method table.
`method_table.py`	The declarative table of JSON-RPC methods (ADR-0099 rules 2 and 3); rows are mutating unless explicitly read-only.
`metrics.py`	Prometheus instruments for the gateway (SPEC-014 US-009).
`runtime_config.py`	Redis-backed runtime configuration service behind `config.get` / `config.watch` (SPEC-014 US-014-005).
`workflow_types.py`	Workflow control types (`WorkflowControlPort`) for the SPEC-014 resurrection (US-014-005).
`cli.py`	Thin CLI wrapper — `build_parser`, `run_serve`, `main`, dotenv loading.
`config.py`	`GatewayConfig` built from environment variables; JWT-secret resolution and dev-secret gating.
`exceptions.py`	Exception hierarchy: `GatewayError`, `AuthenticationError`, `ConnectionLifecycleError`, `RPCError`, `RingBufferError`, `PubSubError`, `InsecureJWTSecretError`.
`http_surface.py`	Gateway HTTP surface — `/health`, `/ready`, `/metrics` (`build_gateway_http_app`, `serve_http`).
`models.py`	Protocol data models: `MessageType`, `WSMessage`, `ConnectionState`, `ConnectionInfo`, `Subscription`.
`protocol.py`	`MessageProcessor` — WebSocket message processing and broadcast logic.
`pubsub.py`	`PubSubManager` — in-process pub/sub for gateway topics.
`ring_buffer.py`	`RedisRingBuffer` — Redis-streams event history with `serialize_for_redis`.
`rpc.py`	`RPCHandler` — thin RPC dispatcher; `_build_method_registry` maps method names to domain handlers.
`server.py`	`WebSocketGateway` — ties all subsystems together; `VizIntWebUI` subclass; kernel-reply and pipeline-event pumps.
`session.py`	`ConnectionManager` — WebSocket connection lifecycle management.
`test_runner.py`	`TestRunner` — async pytest runner with real-time progress broadcasting.
`handlers/__init__.py`	RPC handler modules — split from the monolithic RPCHandler.

`handlers/` — one domain handler per subsystem

Handler	Wraps
`handlers/auth.py`	Auth RPC surface for the socket.
`handlers/config.py`	Runtime configuration RPCs (get / watch / set).
`handlers/gateway.py`	Gateway RPCs: ping, info, clients, replay.
`handlers/workflow.py`	Workflow control RPCs (start / pause / resume / cancel) over a `WorkflowControlPort`.
`handlers/_policy_gate.py`	`PolicyGate` — asks the governance engine whether a workflow RPC verb is allowed (REQ-014-080).
`handlers/_scope_guard.py`	`ScopeGuard` — per-connection `read_only` / `read_write` scope check for workflow and config RPCs.
`handlers/_session_events.py`	`SessionEventOps` — session event broadcasts (SPEC-016).
`handlers/_session_kg.py`	Graph query building for the session handler, split out of it.
`handlers/cxp.py`	CXP packet routing (`cxp.send` and friends).
`handlers/session.py`	Session open/close/query.
`handlers/volk.py`	Volk listing plus admin-gated register/deregister.
`handlers/governance.py`	Governance policy evaluation via the constitutional engine.
`handlers/knowledge.py`	Operational knowledge-graph queries (`orchkg`).
`handlers/memory.py`	The gateway's shared `MemoryEngine`.
`handlers/orchestrator.py`	Orchestrator intents and NL ingress.
`handlers/state.py`	Redis ring-buffer state / replay.
`handlers/projects.py`	Project listing and metadata.
`handlers/fireflies.py`	Fireflies transcript access.
`handlers/test_metrics.py`	Test-metrics reporting.
`handlers/ultimatetui.py`	Bridge to CheetahClaws agents for the UltimateTUI.
`handlers/utils.py`	Shared helpers for the handler modules.

Class map (generated)

Generated from the live source AST by scripts/gen-module-class-diagrams.py — do not hand-edit. Abstract classes have a green border; members listed are those defined on the class itself (inherited members excluded). Solid empty-triangle arrows = in-package inheritance; dashed arrows into dashed boxes = external/stdlib/cross-package bases; filled diamond = composition (constructed in __init__); open diamond = aggregation (annotated/injected reference); diamond edge labels name the owning attribute.