How SessionManager Delegates Execution in Apache Maka: Architecture and Flow

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 (lines 2788–2794), the constructor initializes the kernel:

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.

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.
• 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:

// 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: Central façade implementing provisionAgentGraphOperator and runClaimedAgentGraphIntent.
• packages/runtime/src/runtime-kernel.ts: Execution engine that schedules turns and mediates backend interactions.
• packages/runtime/src/backend-registry.ts: Factory registry mapping PersistedBackendKind to concrete backend implementations.
• 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) 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.

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