Apache Maka's Architecture: The Single-Execution-Authority Model

Apache Maka's architecture is built around a single-execution-authority model where the Runtime Host serves as the sole component authorized to execute work, while all front-ends act as thin clients that delegate operations to this central authority.

Apache Maka is an open-source framework that implements a distinctive approach to AI agent orchestration through strict architectural separation. Understanding Apache Maka's architecture requires examining its foundational principle: the Runtime Host maintains exclusive rights to execute all sessions, tool calls, and lifecycle operations, providing a consistent and secure foundation for diverse client interfaces.

The Single-Execution-Authority Principle

The cornerstone of Apache Maka's architecture, as documented in ARCHITECTURE.md#L24-L33, is the single-execution-authority model. The Runtime Host is the only component that can actually execute work, while all other interfaces—including Desktop, TUI, CLI, bots, and evaluation clients—function as passive requesters that lack execution capabilities.

This design centralizes five critical concerns within the Runtime Host:

• Session Identity: Unique session and turn IDs are generated and managed exclusively by the Runtime Host, guaranteeing reliable continuation across network failures or crashes
• Tool Runtime: All tool invocations flow through the Runtime Host, which maintains the Runtime Event Log for complete observability
• Permissions: Capability checks occur exclusively at the Runtime Host before any work is scheduled or admitted
• Recovery: Crash recovery and context pruning operate from a canonical source of truth, ensuring state consistency
• Evaluation Boundary: Even evaluation frameworks delegate execution to the Runtime Host rather than running experiments independently

Centralized Control Mechanisms

Session and Turn Management

Within packages/runtime, the Runtime Host implements exclusive control over session lifecycles through components like SessionManager and AgentRun. When a client initiates a conversation, the Runtime Host generates the canonical session identity and maintains the state necessary for turn-by-turn continuity. This prevents state drift between different client interfaces and ensures that recovery operations reference a single source of truth.

Unified Tool Runtime and Logging

The Runtime Host funnels all tool calls through a centralized pipeline. When a client requests a tool invocation, the Runtime Host logs the operation in the Runtime Event Log before execution, captures the result, and returns the output to the requesting client. This centralized logging enables complete audit trails across all entry points, from CLI commands to programmatic API calls.

Admission Control and Recovery

Before scheduling any work, the Runtime Host enforces capability checks based on the session's permissions. If a crash occurs, the recovery mechanisms in packages/runtime handle context pruning and state restoration, preserving the integrity of active sessions without requiring client-side intervention.

Client Interaction Patterns

All front-end implementations follow a consistent pattern: package user intent, transmit to the Runtime Host, and render responses. This thin-client architecture ensures that business logic and security policies remain server-side.

CLI Execution Flow

The command-line interface in packages/cli/src/cli.ts demonstrates this delegation pattern. When a user executes:

# Initialise a new session and run a prompt

maka run "Summarize the latest Apache releases"

The CLI packages the request, transmits it to the Runtime Host, and streams the resulting output back to the terminal. The CLI itself never executes prompts or accesses tool runtimes directly.

Programmatic Tool Invocation

For TypeScript applications, the RuntimeHostClient class in packages/runtime-host/src/client.ts provides the bridge to the Runtime Host:

import { RuntimeHostClient } from '@maka/runtime-host';

const client = new RuntimeHostClient();
await client.invokeTool({
  tool: 'web-search',
  args: { query: 'Apache HTTP Server release notes' },
});

This client forwards the tool request to the Runtime Host, which validates permissions, logs the invocation, executes the tool, and returns results.

Evaluation Delegation

Even evaluation experiments follow the single-authority principle. The EvalExperiment class in packages/eval/src/experiment.ts defines benchmark semantics but delegates execution:

import { EvalExperiment } from '@maka/eval';

const exp = new EvalExperiment({
  name: 'HTTP Server Benchmarks',
  subjects: ['httpd-2.6', 'httpd-2.8'],
  tasks: ['fetch-homepage'],
  repetitions: 5,
});
await exp.run();   // Internally contacts the Runtime Host

The evaluation framework only describes the experiment structure; the Runtime Host handles all actual execution, ensuring consistent measurement environments.

Key Source Files and Components

The single-execution-authority principle is implemented across these critical paths:

• packages/runtime-host/: Implements the sole execution authority, handling session admissions, the public protocol, and the RuntimeHostClient
• packages/runtime/: Contains SessionManager, AgentRun, tool adapters, context handling, and crash recovery mechanisms
• packages/cli/: Front-end client including the maka run command and TUI implementation
• packages/eval/: Defines experiment semantics (cells, attempts, result selection) while routing execution through the Runtime Host
• ARCHITECTURE.md: High-level design documentation specifying the single-authority principle at lines 24-33

Summary

• Apache Maka's architecture centers on a single-execution-authority model where only the Runtime Host can execute work
• All front-ends (CLI, TUI, Desktop, bots, evaluators) function as thin clients that delegate to the Runtime Host
• The Runtime Host exclusively manages session identity, permissions, event logging, and crash recovery
• Tool invocations flow through the Runtime Host, enabling unified observability via the Runtime Event Log
• Even evaluation frameworks in packages/eval defer execution to the Runtime Host, maintaining architectural consistency

Frequently Asked Questions

What is the core principle of Apache Maka's architecture?

The core principle is the single-execution-authority model, where the Runtime Host acts as the exclusive execution engine. According to ARCHITECTURE.md, this design ensures that only one component manages session state, permissions, and tool execution, while all other interfaces remain thin clients that request services from this central authority.

How do front-end clients interact with the Runtime Host?

Front-ends use client libraries like RuntimeHostClient (defined in packages/runtime-host/src/client.ts) to send requests via the public protocol. The CLI in packages/cli/src/cli.ts demonstrates this pattern by packaging user commands and transmitting them to the Runtime Host, then streaming results back without local execution.

What happens if the Runtime Host crashes during execution?

The Runtime Host maintains the canonical state for all sessions in packages/runtime, enabling crash recovery and context pruning from a single source of truth. When the Runtime Host restarts, it can recover active sessions and resume operations without data loss, as all state remains centralized rather than distributed across client interfaces.

Can evaluation experiments run independently of the Runtime Host?

No. Despite defining benchmark semantics in packages/eval/src/experiment.ts, the EvalExperiment class internally contacts the Runtime Host to execute tasks. This ensures that evaluation runs occur within the same controlled environment as production sessions, maintaining consistent permissions, logging, and recovery capabilities across all execution contexts.

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