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

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, 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 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 – Manages the discovery and invocation of agent skills.
• 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. 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. 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) – 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) – 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), 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 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

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

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 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) 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.

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}