# Understanding SessionManager and AgentRun in Apache Maka's Execution Lifecycle

> Learn about SessionManager and AgentRun in Apache Maka. SessionManager manages session lifecycle, while AgentRun is the persistent agent instance for event capture and recovery.

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

---

**The SessionManager serves as Apache Maka's public Runtime API that orchestrates session lifecycle and dependencies, while AgentRun represents the persistent execution instance of an agent within that session, capturing events and state for recovery.**

Apache Maka's runtime architecture centers on two distinct but tightly coupled components that manage how agents execute and persist state. The SessionManager acts as the central coordinator that glues together storage, AI-SDK adapters, and sandbox boundaries, whereas AgentRun functions as the concrete, chronologically ordered record of a single execution attempt. Together, these components form the backbone of the **Apache Maka execution lifecycle**, ensuring that every agent interaction respects isolation contracts while maintaining recoverable state.

## What is SessionManager?

The SessionManager is the primary entry point for managing user-agent sessions in Apache Maka. Located in [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts), this class exposes the public Runtime API responsible for session creation, restoration, and termination.

### Core Responsibilities and Dependencies

The manager ties together three critical subsystems:

- **SessionStore**: Handles persistent storage of session metadata and ledger entries
- **AgentBackend**: Provides AI-SDK adapters for executing agent logic
- **ExecutionBoundary**: Enforces session isolation via sandbox mechanisms

According to the class comment on lines 21-27, the SessionManager "ties together SessionStore, AgentBackend, and ExecutionBoundary" to provide a unified interface for runtime operations. When instantiated via `new SessionManager(deps)`, the constructor registers a new session identifier and persists the initial header, establishing the context for all subsequent agent activities.

### Key Methods in the Public API

The SessionManager exposes several critical methods that drive the execution lifecycle:

- **`provisionAgentGraphOperator`**: Prepares graph operators as part of the execution plan before an agent runs
- **`runClaimedAgentGraphIntent`**: Spawns a new AgentRun after validating permissions and recording the intent in the session ledger
- **`stopSession`**: Terminates the active session and triggers cleanup of associated resources

These methods ensure that every action respects the storage, backend, and sandbox contracts, coordinating plan-level operations and recovery logic.

## What is AgentRun?

While SessionManager governs the session context, AgentRun represents the atomic unit of execution—a single, recoverable instance of an agent running inside a session.

### Execution Instance and Persistence Model

An AgentRun captures the chronological stream of **AgentRunEvent** objects and stores them alongside an **AgentRunHeader** in the **AgentRunStore**. This structure persists in [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts) as indicated by the runtime types imported on lines 19-24 (`AgentRunEvent`, `AgentRunHeader`, `AgentRunStore`).

The run serves as the concrete manifestation of the plan that the SessionManager orchestrates. It holds the execution state, handles terminal events, and maintains a complete audit trail of the agent's actions.

### Event Streaming and Recovery

During execution, the AgentRun progresses through the ExecutionBoundary sandbox and produces a sequence of events. If a crash occurs, the SessionManager uses the stored AgentRun data to resume or repair the session. The utility `inspectAgentRunReadModel` in [`packages/runtime/src/agent-run-inspect.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-run-inspect.ts) enables debugging by pulling persisted run data—including events, status, and artifacts—from the store.

## How They Work Together in the Execution Lifecycle

The interaction between SessionManager and AgentRun follows a strict orchestration pattern that ensures reliable execution and recovery.

### Session Initialization

When a user begins an interaction, a new session is created via `new SessionManager(deps)`. All subsequent agent activities route through this manager, which validates permissions and maintains the session ledger.

### Spawning an AgentRun

Once the SessionManager approves a graph-intent claim, it spawns an AgentRun via internal calls like `runtimeReadModel.startAgentRun`. This instantiation creates the persistent execution record that will track the agent's progress.

### Execution and Persistence

The run progresses through the ExecutionBoundary, generating AgentRunEvent entries that are committed to the AgentRunStore. Upon completion, the outcome is finalized, and the SessionManager can use this persistent record for state inspection or crash recovery.

## Code Example: Creating a Session and Starting an AgentRun

The following TypeScript example demonstrates the complete lifecycle from SessionManager instantiation to AgentRun inspection:

```typescript
import { SessionManager } from '@maka/runtime';
import { createInMemoryStore, createMockBackend } from '@maka/test-utils';

// 1️⃣ Prepare the dependencies required by SessionManager
const store   = createInMemoryStore();          // implements SessionStore
const backend = createMockBackend();            // implements AgentBackend
const boundary = {/* ExecutionBoundary implementation */};

// 2️⃣ Instantiate the manager – this creates a new session context
const manager = new SessionManager({
  store,
  backend,
  executionBoundary: boundary,
  now: () => Date.now(),
});

// 3️⃣ Provision an operator (part of the plan) and start an AgentRun
await manager.provisionAgentGraphOperator(/* …operator request… */);
const runId = await manager.runClaimedAgentGraphIntent(/* …intent claim… */);

// 4️⃣ The run progresses; you can inspect it via the read model
import { inspectAgentRunReadModel } from '@maka/runtime';
const inspection = await inspectAgentRunReadModel(runId);
console.log('Current run status:', inspection.runStatus);

```

This example illustrates dependency wiring, session creation, operator provisioning, and AgentRun inspection as implemented in the Apache Maka source code.

## Key Source Files to Understand the Implementation

| File | Significance |
|------|--------------|
| [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts) | Core class implementing the public Runtime API, containing the SessionManager definition (lines 21-27) and runtime type imports (lines 19-24) |
| [`README.md`](https://github.com/apache/maka/blob/main/README.md) (Agent Runtime section) | High-level architectural overview explaining the execution model and component relationships |
| [`packages/runtime/src/agent-run-inspect.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-run-inspect.ts) | Helper utilities for reading AgentRun state, demonstrating the persistence model |
| [`packages/runtime/src/__tests__/session-manager.test.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/__tests__/session-manager.test.ts) | Unit-test suite exhibiting real-world usage patterns and API behaviors |

## Summary

- **SessionManager** acts as the public Runtime API that orchestrates the Apache Maka execution lifecycle by coordinating SessionStore, AgentBackend, and ExecutionBoundary dependencies.
- **AgentRun** represents a single, persistent execution instance within a session, capturing AgentRunEvent streams and storing them via AgentRunStore for recovery and inspection.
- The SessionManager spawns AgentRuns through methods like `runClaimedAgentGraphIntent`, while maintaining session state via `provisionAgentGraphOperator` and termination via `stopSession`.
- Source code in [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts) defines these interactions, with supporting utilities in [`agent-run-inspect.ts`](https://github.com/apache/maka/blob/main/agent-run-inspect.ts) providing read access to execution history.
- These components ensure that every agent execution is isolated, auditable, and recoverable according to the architecture described in the repository's Agent Runtime documentation.

## Frequently Asked Questions

### How does SessionManager handle session recovery after a crash?

The SessionManager uses the persistent AgentRun data stored in AgentRunStore to resume or repair sessions. Because each AgentRun maintains a chronological stream of AgentRunEvent objects and an AgentRunHeader, the manager can reconstruct the execution state and determine whether to restart from a checkpoint or roll back to a consistent state.

### What is the relationship between AgentRun and ExecutionBoundary?

The ExecutionBoundary provides the sandbox environment where an AgentRun executes. While the SessionManager coordinates the creation of both components, the AgentRun represents the logical execution instance and event stream, whereas the ExecutionBoundary enforces the physical isolation and security constraints during that execution.

### Can multiple AgentRuns exist within a single SessionManager session?

Yes, a single session managed by SessionManager can spawn multiple AgentRuns over its lifetime. Each call to `runClaimedAgentGraphIntent` generates a distinct AgentRun with its own runId and event stream, allowing a session to handle sequential or parallel agent executions while maintaining separate persistence records for each run.

### Where does the SessionManager store session metadata?

The SessionManager delegates persistence to the SessionStore interface provided during instantiation. The implementation used in production typically persists to a database or distributed store, while test suites in [`packages/runtime/src/__tests__/session-manager.test.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/__tests__/session-manager.test.ts) often use in-memory implementations like `createInMemoryStore()` for isolation and speed.