# Apache Maka runtime-host Package: Architecture and Communication Protocol Explained

> Explore the Apache Maka runtime-host package, the execution engine orchestrating agent lifecycles and host-client communication via a JSON protocol.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: architecture
- Published: 2026-08-26

---

**The `packages/runtime-host` package serves as the core execution engine for Apache Maka, orchestrating agent lifecycles and managing all communication between the host process and external clients through a versioned, JSON-based protocol.**

The `runtime-host` package sits at the heart of the Apache Maka repository, providing the sandboxed environment where autonomous agents—referred to as *candidates*—execute their logic. This TypeScript-based component defines how the host process boots these agents, tracks conversational state, and exposes domain-specific services over pluggable transport layers.

## Core Responsibilities of the runtime-host Package

The `runtime-host` package consolidates six critical responsibilities into a unified architecture. Each responsibility maps to specific source modules that enforce strict boundaries between execution, coordination, and transport concerns.

### Execution Engine and Candidate Lifecycle

At [`src/execution-candidate-main.ts`](https://github.com/apache/maka/blob/main/src/execution-candidate-main.ts), the package implements the **execution engine** that boots candidate processes and manages their lifecycles. This module creates a sandboxed context where agent code runs in isolation from the host process, ensuring that errors or resource exhaustion within a candidate do not compromise the stability of the broader Maka system. The engine handles process initialization, resource allocation, and graceful termination.

### Session and Project Management

The host maintains conversational state through **sessions** (turn-based interactions) and **projects** (logical groupings of sessions). The [`src/server/session-catalog-coordinator.ts`](https://github.com/apache/maka/blob/main/src/server/session-catalog-coordinator.ts) module creates and tracks these entities, persisting metadata about active conversations and enforcing access controls. When a client initiates a new turn, this coordinator validates the request against existing project boundaries before allowing the execution engine to proceed.

### Domain-Specific Service Coordinators

Beyond basic execution, the host exposes specialized business logic through coordinator modules located in `src/server/`. Key implementations include:

- **[`skill-catalog-coordinator.ts`](https://github.com/apache/maka/blob/main/skill-catalog-coordinator.ts)** – Manages the discovery and invocation of agent skills.
- **[`usage-pricing-coordinator.ts`](https://github.com/apache/maka/blob/main/usage-pricing-coordinator.ts)** – Tracks resource consumption and enforces billing policies.
- **Task ledger and runtime policy coordinators** – Maintain audit trails and enforce governance rules.

These coordinators act as the bridge between the raw execution environment and high-level Maka services, processing protocol requests and returning structured responses.

## Communication Protocol Architecture

The **runtime-host communication protocol** defines a versioned, JSON-encoded message schema that operates over multiple transport implementations. The protocol specifies request formats, error codes, and event streaming patterns that enable full-duplex communication between the host and remote clients.

### Message Format and Validation

All protocol messages conform to a codec defined in [`src/protocol/codec.ts`](https://github.com/apache/maka/blob/main/src/protocol/codec.ts). The host encodes every outbound message as a UTF-8 JSON object and validates inbound frames against size limits defined by `RUNTIME_HOST_MAX_MESSAGE_BYTES`. Malformed frames trigger `RuntimeHostProtocolError`, which the transport layer serializes back to the client with diagnostic details preserved in the `cause` property.

Message types use a discriminated union pattern via the **`type`** field (e.g., `session-turns`, `skill-catalog`, `usage-pricing`), allowing the host router to dispatch requests to the appropriate coordinator without parsing opaque payload data.

### Transport Implementations

The package abstracts transport mechanics behind the `RuntimeHostMessageTransport` interface defined in [`src/transport/message-transport.ts`](https://github.com/apache/maka/blob/main/src/transport/message-transport.ts). This interface mandates four core operations:

1. **`read(timeoutMs)`** – Awaits inbound messages with configurable timeouts.
2. **`write(message)`** – Queues outbound data with back-pressure handling.
3. **`closeAfterFlush()`** – Gracefully terminates after pending writes complete.
4. **`abort(error)`** – Forcefully closes the connection with an error.

Concrete implementations include:

- **`WebSocketTransport`** ([`src/transport/websocket-transport.ts`](https://github.com/apache/maka/blob/main/src/transport/websocket-transport.ts)) – Provides reliable TCP-based communication for browser clients and external UIs. This implementation enforces message queuing and back-pressure limits to prevent memory exhaustion during high-throughput scenarios.
- **Native Peer IPC** ([`src/transport/peer-native.ts`](https://github.com/apache/maka/blob/main/src/transport/peer-native.ts)) – Enables low-latency, intra-process communication using a custom binary framing protocol optimized for desktop integrations.
- **Local IPC Framing** – Offers a pipe-like interface for unit test harnesses and development tools.

### Request/Response Cycle and Event Streaming

Clients initiate interactions by sending **request** messages containing an `action` field and domain-specific payload. The host routes these to the relevant coordinator (e.g., [`session-revision-coordinator.ts`](https://github.com/apache/maka/blob/main/session-revision-coordinator.ts)), which processes the logic and returns a **response** message containing the result or a protocol-level error.

For asynchronous updates, the protocol supports **event streaming**. Coordinators push events—such as session state changes or task ledger entries—to all subscribed clients over the same full-duplex channel. Events carry an **`isEvent`** flag set to `true` and contain the same `type` discriminator used for requests, allowing clients to multiplex handling logic on a single connection.

## Error Handling Across the Transport Layer

The [`src/protocol/errors.ts`](https://github.com/apache/maka/blob/main/src/protocol/errors.ts) module defines a hierarchy of error types that propagate cleanly across wire boundaries:

- **`RuntimeHostProtocolError`** – Indicates schema violations, unsupported message types, or business logic failures detected by coordinators.
- **`RuntimeHostTransportError`** – Signals network failures, connection resets, or framing errors at the transport layer.

Both error classes preserve the original cause through standard JavaScript error chaining, ensuring that clients receive actionable diagnostic information without exposing internal stack traces that could leak implementation details.

## Working with the Runtime Host Protocol

The following examples demonstrate how to interact with the runtime host using the WebSocket transport and the high-level client API.

### Establishing a WebSocket Connection

```typescript
import WebSocket from 'ws';
import { WebSocketTransport } from '@maka/runtime-host/transport/websocket-transport';
import { RuntimeHostProtocolError } from '@maka/runtime-host/protocol/errors';

const ws = new WebSocket('ws://localhost:8080/runtime');
const transport = new WebSocketTransport(ws);

// Send a request to create a new session turn
await transport.write(JSON.stringify({
  type: 'session-turns',
  action: 'create',
  payload: { projectId: 'proj-123' },
}));

// Await the response with a 5-second timeout
try {
  const response = await transport.read(5000);
  console.log('Turn created:', response);
} catch (e) {
  if (e instanceof RuntimeHostProtocolError) {
    console.error('Protocol error:', e.message);
  } else {
    console.error('Transport error:', e);
  }
}

```

### Using the High-Level Client API

```typescript
import { RuntimeHostClient } from '@maka/runtime-host/client';
import { WebSocketTransport } from '@maka/runtime-host/transport/websocket-transport';

const client = new RuntimeHostClient(
  new WebSocketTransport(new WebSocket('ws://localhost:8080/runtime'))
);

// Call the skill-catalog service
const skill = await client.call('skill-catalog', 'lookup', { name: 'search' });
console.log('Skill definition:', skill);

```

## Summary

- The **`packages/runtime-host`** package functions as the centralized execution engine and communication hub for Apache Maka, managing candidate lifecycles and service orchestration.
- **Domain coordinators** in `src/server/` handle specific business logic areas such as sessions, skills, and billing, processing requests routed by the protocol layer.
- The **communication protocol** uses JSON-encoded, versioned messages validated at the transport boundary, with strict size limits defined by `RUNTIME_HOST_MAX_MESSAGE_BYTES`.
- **Transport implementations** in `src/transport/` provide WebSocket, native IPC, and local pipe interfaces, all adhering to the `RuntimeHostMessageTransport` contract.
- **Error handling** distinguishes between protocol violations (`RuntimeHostProtocolError`) and transport failures (`RuntimeHostTransportError`), preserving causal chains for debugging.

## Frequently Asked Questions

### What is the primary function of the runtime-host package in Apache Maka?

The runtime-host package provides the execution environment for Maka agents (candidates) and implements the communication protocol that connects these sandboxed processes with external clients. It manages process lifecycles, tracks conversational sessions, and exposes domain-specific services through a unified message-based interface.

### How does the runtime-host protocol handle message validation?

All messages must conform to the codec defined in [`src/protocol/codec.ts`](https://github.com/apache/maka/blob/main/src/protocol/codec.ts) and pass size validation against `RUNTIME_HOST_MAX_MESSAGE_BYTES`. The transport layer rejects malformed frames by throwing `RuntimeHostProtocolError`, which serializes back to the client with details about the violation.

### What transport options are available in the runtime-host package?

The package supports three primary transports: **WebSocketTransport** for browser and network clients, **Native Peer IPC** ([`peer-native.ts`](https://github.com/apache/maka/blob/main/peer-native.ts)) for high-performance intra-process communication, and **Local IPC Framing** for testing and development tools. All implement the `RuntimeHostMessageTransport` interface defined in [`src/transport/message-transport.ts`](https://github.com/apache/maka/blob/main/src/transport/message-transport.ts).

### How are errors propagated between the host and clients?

Errors caught at any layer are wrapped in either `RuntimeHostProtocolError` for schema or business logic issues, or `RuntimeHostTransportError` for network failures. These error objects serialize across the wire with their `cause` property intact, allowing clients to distinguish between recoverable protocol violations and critical transport disconnections.