The Four Distinct Identities That Drive Apache Maka's Execution Model

Apache Maka's runtime is governed by four distinct identities—Runtime Host, Session, Turn, and AgentRun—that collectively define process authority, conversation state, atomic operations, and agent lifecycle management.

These architectural primitives establish clear boundaries for who performs work, what constitutes a unit of work, and how the system coordinates execution across front-end clients. According to the Apache Maka source code, specifically ARCHITECTURE.md, these identities drive the entire execution flow from client request to tool execution.

The Four Core Execution Identities

Runtime Host (The Single Execution Authority)

The Runtime Host serves as the sole execution authority that owns the process, admission controls, client capabilities, and the public protocol. All front-end interfaces—including Desktop, TUI, CLI, and bots—submit work to this central authority; there is no secondary runtime. This identity is implemented in packages/runtime-host/src/index.ts and documented in ARCHITECTURE.md (lines 24-32).

Session (The Conversation Identity)

A Session represents an interactive conversation, such as a user session or bot session, providing a stable identity for the duration of a high-level interaction. The Runtime Host owns the Session identity, which in turn owns the SessionManager responsible for coordinating state. According to ARCHITECTURE.md (lines 41-42), Sessions maintain context across multiple discrete operations.

Turn (The Atomic Interaction Unit)

A Turn constitutes the atomic step inside a Session—a single request/response pair processed by the Runtime Host. As the smallest unit of observable interaction in the event log, Turns capture discrete operations within a conversation. The Turn identity is defined alongside Session in ARCHITECTURE.md and implemented within packages/core.

AgentRun (The Execution Lifecycle)

AgentRun manages the lifecycle of a running agent, including the execution of tools, model adapters, and continuations. Created by the SessionManager, an AgentRun holds the Agent Graph and drives state mutation during tool execution. This identity is detailed in ARCHITECTURE.md (lines 45-48) and implemented in packages/runtime/src/agent-run.ts.

Mapping Identities to Package Boundaries

The Apache Maka codebase enforces these identities through strict package separation:

• packages/runtime-host: Implements the Runtime Host authority and the public client protocol.
• packages/runtime: Contains SessionManager, AgentRun, model adapters, tools, context, and recovery logic.
• packages/core: Defines the contracts for Session and Turn identities, event logs, and permissions.
• packages/eval: Is not an execution identity; it owns only benchmark-level semantics (experiments, cells, attempts).

This structure ensures that the Runtime Host remains the single execution authority while Session and Turn identities handle conversation semantics, and AgentRun manages the actual tool execution lifecycle.

Implementing the Four Identities in Code

The following TypeScript examples demonstrate how to interact with each identity in the Apache Maka runtime:

// Runtime Host provides the SessionManager (Session identity)
import { SessionManager } from '@maka/runtime';
const session = await SessionManager.create({ userId: 'alice' });

// Creating a Turn within a Session (Turn identity)
const turn = await session.beginTurn({ request: 'run ls' });
const result = await turn.executeTool('shell', { cmd: 'ls' });
await turn.end();

// Launching an AgentRun (AgentRun identity)
import { AgentRun } from '@maka/runtime';
const agent = new AgentRun(session);
await agent.start();               // AgentRun acquires its own identity
await agent.runTool('search', { query: 'example' });
await agent.shutdown();

In this workflow, the Runtime Host is implicit as the process authority providing SessionManager, while developers explicitly create Session, Turn, and AgentRun objects that each carry their own distinct identity and lifecycle.

Summary

• Runtime Host: The single execution authority owning process, admission, and public protocol responsibilities.
• Session: The conversation-level identity providing stable context across multiple interactions.
• Turn: The atomic request/response unit representing the smallest observable work unit in the event log.
• AgentRun: The agent lifecycle manager created by SessionManager that executes tools and maintains execution state.

Frequently Asked Questions

How does the Runtime Host differ from the SessionManager?

The Runtime Host is the single execution authority that owns the process and public protocol, while the SessionManager is a component owned by the Session identity that creates and manages AgentRun instances. The Runtime Host resides in packages/runtime-host, whereas SessionManager is implemented in packages/runtime/src/session-manager.ts.

What is the relationship between a Turn and an AgentRun?

A Turn represents the atomic request/response pair within a Session, while an AgentRun represents the lifecycle of the agent executing the work requested by that turn. The SessionManager creates an AgentRun to handle the processing initiated by a Turn, meaning AgentRuns execute within the context of Turns but maintain independent state for tool execution.

Can multiple AgentRuns exist within a single Session?

Yes, the SessionManager can create multiple AgentRun instances as needed to handle different aspects of a conversation. While the Runtime Host remains the single execution authority, the source code in packages/runtime/src/agent-run.ts allows for sequential or concurrent AgentRun management depending on the SessionManager's coordination logic and the Session's requirements.

Where are the identity contracts defined in the Apache Maka codebase?

The contracts for Session and Turn identities reside in packages/core, establishing the event log formats and permission structures. AgentRun and SessionManager implementations are located in packages/runtime, while the Runtime Host authority is implemented in packages/runtime-host, with high-level architecture documented in ARCHITECTURE.md.

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