# Understanding SessionManager and AgentRun in Apache Maka: Runtime Execution Architecture

> Explore Apache Maka's SessionManager and AgentRun for robust runtime execution. Understand their roles in session management and durable per-turn execution with persistence and recovery.

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

---

**SessionManager and AgentRun in Maka form a two-layer execution architecture where SessionManager provides a stable public façade for session CRUD and message handling, while AgentRun encapsulates durable per-turn execution with guaranteed persistence and recovery semantics.**

Apache Maka is an open-source AI agent framework that separates external API stability from internal execution reliability through two core runtime components. Understanding **SessionManager and AgentRun in Maka** is essential for developers building interactive UI clients, headless bots, or automated testing suites. These components work in concert to ensure every user message results in a reliably persisted, recoverable turn execution.

## What Is SessionManager in Maka?

The **SessionManager** serves as the public entry point and stable façade for all runtime operations. Located in [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts), this class owns session lifecycle management and delegates turn execution to internal kernel components to maintain API consistency across UI, CLI, and bot integrations.

### Session CRUD and Metadata Management

SessionManager handles creation, listing, and updates of sessions through the `SessionStore` (SQLite persistence). It manages session-level concerns including permission mode updates, sub-agent spawning, and graph operator provisioning, ensuring that session state remains consistent regardless of underlying execution changes.

### The sendMessage API

External callers—whether desktop UI, CLI tools, bots, or tests—invoke the thin `sendMessage()` method. This method validates the session, updates metadata, and forwards the request to `RuntimeKernel.startTurn()` without exposing internal execution complexity to the caller.

## What Is AgentRun in Maka?

The **AgentRun** class, defined in [`packages/runtime/src/agent-run.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-run.ts), represents a durable execution unit for a single turn. It ensures that runtime facts are recorded reliably and provides mechanisms for graceful shutdown, abort semantics, and crash recovery.

### Turn Identification and Context

Each AgentRun instance carries a unique `runId`, `sessionId`, and `turnId`, establishing the execution context. This identification enables precise tracking and auditing of individual agent interactions across distributed systems and supports replay capabilities for debugging.

### Event Buffering and Terminal Commitment

AgentRun manages the complete turn lifecycle: starting backend streams, buffering runtime events, flushing partial logs, and committing terminal facts to the `AgentRunStore`. The `settleStopTerminal()` method exemplifies this durability by ensuring aborted statuses are persisted atomically even during stop operations.

```typescript
// In packages/runtime/src/agent-run.ts
public async settleStopTerminal(): Promise<void> {
  if (this.terminalClaim?.owner !== 'stop' || this.terminalRunHeaderCommitted) return;

  // Ensure durable writes exist
  if (!this.input.runtimeEventStore || !this.input.runStore) return;

  await this.flushRuntimePartialBuffer(true);
  const events = await this.loadTurnRuntimeEvents();

  // If any other terminal event already exists, we bail out
  if (events.some(e => isTerminalRuntimeEvent(e) && e.id !== this.terminalClaim.event?.id)) return;

  // Commit an aborted status as the final terminal fact
  const finalStatus = { status: 'aborted' as const };
  this.finalStatus ??= finalStatus;
  // ...additional commit logic...
}

```

## Architectural Integration: How SessionManager and AgentRun Collaborate

The relationship between these components follows a strict delegation pattern that keeps the public API thin while ensuring execution reliability. According to the Apache Maka source code, the flow operates as follows:

1. **External caller** invokes `SessionManager.sendMessage(sessionId, input)`—callers never interact with AgentRun directly.
2. **SessionManager** validates the session and delegates to `RuntimeKernel.startTurn()`.
3. **RuntimeKernel** instantiates an **AgentRun** to encapsulate the turn's execution context.
4. **AgentRun** drives the `AiSdkBackend`, processes model/tool calls, buffers events, and commits terminal facts to persistent storage.
5. **SessionManager** updates session state based on AgentRun's reported outcome (completed, aborted, etc.).

This separation provides two critical architectural benefits:

- **Thin façade**: SessionManager remains stable while internal execution details evolve, allowing UI and bot code to remain unchanged across framework updates.
- **Durable turn execution**: AgentRun guarantees that each turn's facts are persisted atomically, enabling reliable recovery, replay, and auditing even during system interruptions.

## Implementation Examples

The following patterns demonstrate real-world usage of **SessionManager and AgentRun in Maka** within a desktop host environment:

```typescript
import { SessionManager } from '@maka/runtime';
import { SQLiteSessionStore } from '@maka/storage';
import { AiSdkBackend } from '@maka/ai-sdk';

// Assemble dependencies
const store = new SQLiteSessionStore({ /* …config… */ });
const backend = new AiSdkBackend({ /* …config… */ });

const manager = new SessionManager({
  store,
  backends: { default: backend },
  newId: () => crypto.randomUUID(),
  now: () => Date.now(),
});

// Send a user message – this call goes through SessionManager only
await manager.sendMessage('session-123', {
  role: 'user',
  content: { type: 'text', text: 'Explain the architecture of Maka.' },
});

```

## Summary

- **SessionManager** provides the stable public API façade for session management and message entry in [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts).
- **AgentRun** encapsulates durable per-turn execution with unique identifiers (`runId`, `sessionId`, `turnId`) and atomic persistence to `AgentRunStore`.
- The delegation pattern through `RuntimeKernel` ensures external code remains unchanged during internal execution engine evolution.
- AgentRun handles backend streams, event buffering, and terminal commitment including `stop()`, `settleStopTerminal()`, and recovery semantics.
- External callers interact exclusively with SessionManager, never directly with AgentRun, maintaining clean architectural boundaries.

## Frequently Asked Questions

### What is the difference between SessionManager and AgentRun in Maka?

**SessionManager** is the public façade handling session CRUD and message routing through `sendMessage()`, while **AgentRun** is the internal durable execution engine for individual turns. SessionManager manages the "what" (session state and metadata), and AgentRun manages the "how" (turn execution with event buffering and persistence). This separation ensures API stability while allowing execution internals to evolve.

### How does Maka ensure reliable turn execution during system interruptions?

AgentRun commits terminal facts atomically to the `AgentRunStore` even during stop or abort operations. The `settleStopTerminal()` method in [`packages/runtime/src/agent-run.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-run.ts) ensures that partial runtime events are flushed and final statuses are persisted before shutdown, enabling reliable recovery and replay without data loss.

### Can developers interact with AgentRun directly when building Maka applications?

No, direct interaction with AgentRun is intentionally encapsulated by the architecture. External callers must use SessionManager's `sendMessage()` API, which delegates to `RuntimeKernel` to instantiate and manage AgentRun instances. This abstraction prevents coupling between client code and execution internals, maintaining long-term API compatibility.

### Where are SessionManager and AgentRun defined in the Maka source code?

SessionManager is implemented in [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts) and AgentRun in [`packages/runtime/src/agent-run.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-run.ts). Both reside within the `@maka/runtime` package and depend on storage interfaces like `SQLiteSessionStore` and `AgentRunStore` for persistence, as documented in the runtime package README and architecture drafts.