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

> Discover the four distinct identities driving Apache Maka's execution: Runtime Host, Session, Turn, and AgentRun. Understand process authority, conversation state, atomic operations, and agent lifecycle management.

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

---

**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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/index.ts) and documented in [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md) (lines 45-48) and implemented in [`packages/runtime/src/agent-run.ts`](https://github.com/apache/maka/blob/main/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:

```typescript
// 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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md).