# How SessionManager Delegates Execution in Apache Maka: Architecture and Flow

> Discover how Apache Maka's SessionManager delegates execution to RuntimeKernel, BackendRegistry, and AgentGraphExecutor. Learn about its architecture and flow.

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

---

**The SessionManager in Apache Maka delegates all runtime execution to three specialized components—RuntimeKernel, BackendRegistry, and AgentGraphExecutor—while remaining agnostic to concrete AI providers and execution environments.**

In the Apache Maka framework, the `SessionManager` serves as the primary public façade for coordinating agent workflows. Rather than executing tasks directly, it orchestrates activity by forwarding high-level requests to dedicated subsystems, enabling pluggable backends and isolated execution contexts.

## The Three Core Delegation Targets

The SessionManager achieves its flexibility by strictly separating concerns across three internal components. Each handles a distinct layer of the execution stack.

### RuntimeKernel: Turn-Based Execution Loop

The **RuntimeKernel** drives the turn-based execution loop, schedules runs, and manages backend lifecycles. When a session initiates work, the SessionManager relies on a `RuntimeKernelLike` instance (defaulting to `RuntimeKernel`) created in its constructor.

In [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts) (lines 2788–2794), the constructor initializes the kernel:

```typescript
this.runtimeKernel = deps.runtimeKernel ?? new RuntimeKernel({ 
  backendRegistry: this.backendRegistry,
  // ... other deps
});

```

The SessionManager delegates turn execution by calling `runtimeKernel.runTurn` or the private helper `runClaimedAgentGraphIntentOnce`, allowing the kernel to manage the actual scheduling and runtime state.

### BackendRegistry: Backend Factory Resolution

The **BackendRegistry** maintains factories for concrete backends (e.g., `@maka/backend-openai`, `@maka/backend-anthropic`). When the kernel requires a backend, it delegates resolution to this registry.

The SessionManager passes the registry reference to the kernel during construction. During execution, the kernel invokes `backendRegistry.prepare(kind, ctx)` to obtain a `PreparedBackendActivation`, which constructs the specific `AgentBackend` implementation. This interaction is defined around lines 3555–3564 in [`session-manager.ts`](https://github.com/apache/maka/blob/main/session-manager.ts).

This delegation pattern enables hot-swapping AI providers without modifying the SessionManager's public API.

### AgentGraphExecutor: Graph Intent Operations

For agent workflow operations, the SessionManager delegates to **AgentGraphExecutor** functionality exposed through two primary methods:

- **`provisionAgentGraphOperator`**: Registers a new operator for a graph. Implementation starts at line 2602 in [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts).
- **`runClaimedAgentGraphIntent`**: Executes a previously claimed intent. The entry point is at line 2602, with core logic in the private helper `runClaimedAgentGraphIntentOnce` (lines 2705–2718).

Both methods eventually trigger `runtimeKernel.runTurn`, which executes the turn within the selected backend while maintaining the abstraction boundary.

## Step-by-Step Delegation Flow

When a client initiates execution, the SessionManager coordinates the following delegation chain:

1. **Client call**: `SessionManager.runClaimedAgentGraphIntent(input)` receives the request.
2. **Claim creation**: The SessionManager creates a `runtimeExecution` claim and forwards the request via `this.runtimeKernel.runTurn(sessionId, turnId, exec)`.
3. **Backend preparation**: The RuntimeKernel queries the BackendRegistry to `prepare` a backend matching the session's `backend` kind.
4. **Backend instantiation**: The registry returns a prepared activation, building the concrete `AgentBackend` (e.g., an OpenAI SDK wrapper).
5. **Turn execution**: The kernel runs the turn, feeding input to the backend, handling tool calls, and streaming events back to the SessionManager, which persists messages to the `SessionStore`.

This pipeline ensures the SessionManager never directly interacts with provider-specific SDKs or execution sandboxes.

## Practical Implementation Example

The following TypeScript demonstrates the delegation API in practice:

```typescript
// 1️⃣ Create a session
const manager = new SessionManager(deps);
const summary = await manager.createSession({ name: 'Demo', backend: 'openai' });

// 2️⃣ Provision a graph operator (e.g., a custom tool)
await manager.provisionAgentGraphOperator({
  graphId: 'graph-1',
  workId: 'work-1',
  operatorId: 'op-42',
  source: 'user',
  edges: [],                     // define edges the operator will handle
  expectedScheduleRevision: 0,
});

// 3️⃣ Run a claimed intent on that graph
const result = await manager.runClaimedAgentGraphIntent({
  claimStore: claimStore,
  intent: runnableIntent,
  graphId: 'graph-1',
  intentId: 'intent-7',
  prompt: 'Generate a summary',
});

```

Each method call triggers the internal delegation chain described above, abstracting the complexity of kernel scheduling and backend instantiation.

## Key Source Files

Understanding the delegation architecture requires familiarity with these specific source locations:

- **[`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts)**: Central façade implementing `provisionAgentGraphOperator` and `runClaimedAgentGraphIntent`.
- **[`packages/runtime/src/runtime-kernel.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-kernel.ts)**: Execution engine that schedules turns and mediates backend interactions.
- **[`packages/runtime/src/backend-registry.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/backend-registry.ts)**: Factory registry mapping `PersistedBackendKind` to concrete backend implementations.
- **[`packages/runtime/src/stream-graph-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/stream-graph-coordinator.ts)**: Coordinates graph-level actions by invoking the SessionManager's delegated methods.

## Summary

- **SessionManager acts as a pure coordinator**, never executing AI operations directly but delegating to specialized subsystems.
- **RuntimeKernel** handles turn scheduling and lifecycle management, initialized in the SessionManager constructor (lines 2788–2794).
- **BackendRegistry** provides factory-based backend resolution, enabling provider-agnostic execution through the `prepare` method.
- **AgentGraphExecutor** functionality exposes graph provisioning and intent execution via `provisionAgentGraphOperator` and `runClaimedAgentGraphIntent`.
- **Execution boundaries** are respected throughout the chain, with the kernel delegating sandbox creation to the appropriate backend when needed.

## Frequently Asked Questions

### What is the role of SessionManager in Apache Maka?

The SessionManager serves as the public façade for all runtime activity in Maka. It coordinates session lifecycle, graph provisioning, and intent execution by delegating actual work to the RuntimeKernel, BackendRegistry, and internal executor helpers, keeping the public API stable while allowing backend flexibility.

### How does SessionManager handle different AI providers?

The SessionManager remains agnostic to specific AI providers by delegating backend resolution to the BackendRegistry. When execution begins, the RuntimeKernel requests a `PreparedBackendActivation` from the registry using the session's configured `backend` kind, allowing seamless swapping between OpenAI, Anthropic, or custom backends without changing the SessionManager code.

### What is the difference between provisionAgentGraphOperator and runClaimedAgentGraphIntent?

`provisionAgentGraphOperator` (defined at line 2602 in [`session-manager.ts`](https://github.com/apache/maka/blob/main/session-manager.ts)) registers a new operator for handling specific graph edges, while `runClaimedAgentGraphIntent` executes a previously claimed intent against the provisioned graph. The former sets up the operational structure; the latter triggers the actual execution turn via the RuntimeKernel.

### Where is the execution boundary managed in this architecture?

The **ExecutionBoundary** is stored in the session header and respected by the RuntimeKernel during turn execution. When sandboxing is required, the kernel delegates sandbox creation to the prepared backend, ensuring isolation constraints are enforced at the execution layer rather than the SessionManager layer.