Understanding SessionManager and AgentRun in Apache Maka's Execution Lifecycle

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, 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 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 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:

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	Core class implementing the public Runtime API, containing the SessionManager definition (lines 21-27) and runtime type imports (lines 19-24)
README.md (Agent Runtime section)	High-level architectural overview explaining the execution model and component relationships
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	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 defines these interactions, with supporting utilities in 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 often use in-memory implementations like createInMemoryStore() for isolation and speed.

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