What Is the Runtime Host in Apache Maka? Execution Authority and Architecture

The Runtime Host is the central execution authority in Apache Maka that exclusively owns all session-level state, orchestrates every turn of an agent's lifecycle, and maintains the durable event log as the system’s sole source of truth.

The Apache Maka project implements a strictly centralized architecture where the Runtime Host serves as the single authority for all runtime operations. According to the source code in apache/maka, every client—whether Desktop, TUI, CLI, or bot—delegates execution to this component rather than managing local runtimes. This design ensures consistent permission enforcement, tool sandboxing, and state recovery across all interaction modes.

Centralized Execution Authority

The Runtime Host is the only component permitted to create and manage Session and Turn identities. As documented in ARCHITECTURE.md, it controls the agent lifecycle, handles permission grants, schedules tool executions, and emits canonical RuntimeEvents. No client-facing frontend maintains a secondary runtime; instead, all work requests flow through the host’s admission and queuing layer.

This authority model guarantees that:

• Identity & Lifecycle – The host owns Session, Turn, Run, and Invocation IDs.
• Admission & Queuing – It controls message admission, queuing policies, and turn boundaries.
• Tool & Permission Management – It executes sandboxed tools and records every permission action.
• Event Logging – It persists every model text, thinking trace, tool call, and terminal result.

Control Flow Through the Host’s Pipeline

Internally, the Runtime Host implements a control-plane that connects the high-level SessionManager to the low-level tool execution stack. The execution flow follows a strict pipeline through six core components:

1. SessionManager – Receives public requests at packages/runtime/src/session-manager.ts and forwards them to the host kernel.
2. RuntimeKernel – Creates an AgentRun and registers the active run within the kernel’s state.
3. AgentRun – Provides a durable envelope for the execution and writes the initial RuntimeEvent to the log.
4. RuntimeRunner – Defines the uniform Invocation protocol and guarantees a single terminal RuntimeEvent per run.
5. AiSdkFlow – Maps legacy SessionEvents to canonical RuntimeEvents for backward compatibility.
6. ToolRuntime – Executes sandboxed tools, records their effects, and feeds results back to the model.

This pipeline ensures that every operation is recorded before state changes propagate to projections like the SessionStore or AgentRunStore.

The Runtime Event Log as Source of Truth

All state within Apache Maka is a projection over the ordered Runtime Event Log. The host’s event log is immutable and serves as the system’s source of truth; UI views, model history, and recovery snapshots are derived solely from this sequence. Before a Run header is closed, the host guarantees that a terminal RuntimeEvent exists, enabling reliable crash recovery and deterministic continuation.

Connecting to the Runtime Host

Clients communicate with the Runtime Host via WebSocket transport. The following TypeScript example demonstrates how to establish a connection, open a session, and send messages using the public client package:

import { RuntimeHostConnectionImpl } from '@maka/runtime-host/client/connection';
import { RuntimeHostSessionChannel } from '@maka/runtime-host/client/session-channel';

async function main() {
  // Connect to the host (WebSocket endpoint started by the desktop/CLI runner)
  const conn = new RuntimeHostConnectionImpl('ws://localhost:8080');
  await conn.connect();

  // Open a new session for this client
  const session = await conn.openSession({
    clientId: 'example-cli',
  });

  // Send a user message – routed through SessionManager → RuntimeKernel → AgentRun
  await session.sendMessage({
    role: 'user',
    content: 'Explain the role of the Runtime Host.',
  });

  // Listen for live runtime events (model replies, tool calls)
  const channel = new RuntimeHostSessionChannel(session);
  channel.onEvent(event => {
    console.log('Runtime event:', event);
  });
}

main().catch(console.error);

The example above demonstrates three critical integration points:

• RuntimeHostConnectionImpl establishes the WebSocket transport defined in packages/runtime-host/src/transport/websocket-transport.ts.
• openSession invokes the SessionManager entry point at packages/runtime/src/session-manager.ts.
• sendMessage triggers a RuntimeEvent that is persisted before any UI projection occurs.

Key Source Files

The Runtime Host architecture is implemented across several critical files in the apache/maka repository:

• ARCHITECTURE.md – High-level description of the Runtime Host’s responsibilities and execution spine.
• packages/runtime/src/session-manager.ts – Public façade that forwards requests to the host kernel.
• packages/runtime/src/runtime-kernel.ts – Core control-plane that creates AgentRun objects and assembles the execution pipeline.
• packages/runtime/src/agent-run.ts – Durable envelope for runs; handles initial and terminal RuntimeEvent writes.
• packages/runtime/src/runtime-runner.ts – Defines the Invocation protocol and terminal event guarantees.
• packages/runtime/src/ai-sdk-flow.ts – Adapts legacy SessionEvents to canonical RuntimeEvents.
• packages/runtime-host/src/transport/websocket-transport.ts – WebSocket transport implementation for client connections.
• packages/runtime-host/src/client/connection.ts – High-level client wrapper exposing openSession and sendMessage.

Summary

• The Runtime Host is the sole execution authority in Apache Maka, eliminating distributed state by centralizing all runtime operations.
• It exclusively manages Session and Turn identities, tool permissions, and the agent lifecycle through a six-stage control-plane pipeline.
• All system state is a projection of the immutable Runtime Event Log, enabling reliable recovery and deterministic replay.
• Clients connect via WebSocket transport using RuntimeHostConnectionImpl and delegate all work to the host rather than maintaining local runtimes.
• Key coordination occurs in runtime-kernel.ts, session-manager.ts, and agent-run.ts, with durable guarantees enforced by runtime-runner.ts.

Frequently Asked Questions

How does the Runtime Host differ from client frontends in Apache Maka?

Client frontends—such as the Desktop app, TUI, or CLI—are stateless consumers that send requests to the Runtime Host. According to the architecture documentation, none of these frontends own a secondary runtime; they merely render projections of the host’s event log. The host alone performs admission control, queues messages, and executes tools.

What guarantees the durability of agent runs in Apache Maka?

The RuntimeRunner component enforces a protocol that guarantees a single terminal RuntimeEvent before a Run header is closed, as implemented in packages/runtime/src/runtime-runner.ts. This ensures that the AgentRun durable envelope contains a completed event sequence, enabling crash recovery and preventing partial state commits.

Can tools execute outside the Runtime Host’s control?

No. The ToolRuntime executes all tools within a sandboxed environment managed by the host. It records tool effects and results back to the model only through the host’s event log, ensuring that permission boundaries and execution history remain centralized and auditable.

Where is the session state actually stored in Apache Maka?

While the SessionStore and AgentRunStore maintain working projections for performance, the Runtime Event Log in the host is the authoritative source of truth. All stores derive their state from this log, meaning the physical storage of truth is the ordered sequence of RuntimeEvents managed by the host.

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