Execution Lifecycle Difference Between AgentRun, RuntimeKernel, and SessionManager in Apache Maka

Apache Maka separates transient agent execution from persistent session coordination by delegating per-run sandboxing and resource management to the RuntimeKernel (which powers individual AgentRun instances) while the SessionManager maintains cross-run state, todo lists, and conversation context across the broader session lifecycle.

Apache Maka is an open-source agent execution framework that strictly delineates between code execution runtime and session orchestration. Understanding the execution lifecycle difference between AgentRun, RuntimeKernel, and SessionManager is essential for building reliable agent workflows that balance ephemeral compute with persistent state. These three components form a hierarchical architecture where the RuntimeKernel handles low-level execution, AgentRun represents a single execution instance, and SessionManager coordinates multiple runs into coherent user sessions.

Architectural Scope and Boundaries

The fundamental distinction lies in granularity: the RuntimeKernel and AgentRun operate on a per-run basis, while the SessionManager operates on a per-session basis spanning multiple runs.

RuntimeKernel and the AgentRun Lifecycle

The RuntimeKernel serves as the low-level execution engine that instantiates and manages an AgentRun. When an agent is launched, the kernel creates an isolated runtime environment with sandboxed memory and I/O constraints, schedules the agent's tasks, and monitors progress until completion.

According to the Apache Maka source architecture in docs/architecture/runtime-core-architecture-draft.md, the RuntimeKernel remains stateless between runs. It handles resource provisioning, API access restrictions, and low-level error containment within a single execution boundary. When an AgentRun completes—whether successfully, with errors, or via cancellation—the kernel tears down the environment and reclaims resources without retaining execution context.

SessionManager and Session State

In contrast, the SessionManager persists across multiple AgentRun executions, maintaining the high-level lifecycle of a user-driven conversation. As implemented in docs/session-todo-lifecycle.md, the SessionManager tracks todo items, stores intermediate context snapshots, and coordinates hand-offs between consecutive runs.

The SessionManager decides when to launch new AgentRun instances (triggered by user input, timers, or completion of previous tasks) and what data to pass to the RuntimeKernel. It maintains the session ledger, a persistent store that retains todo lists, user preferences, and conversation history until the session explicitly closes or expires.

Execution Lifecycle Differences

Per-Run vs. Per-Session Persistence

The RuntimeKernel and individual AgentRun instances are ephemeral by design. Any state required across runs must be explicitly passed in via the SessionManager; the kernel itself does not persist memory between executions. This statelessness ensures clean failure boundaries and prevents resource leaks.

Conversely, the SessionManager implements a durable persistence layer. It updates the session ledger after each AgentRun completes, recording results and queueing subsequent tasks. This allows later runs to resume where previous runs terminated, maintaining conversational continuity.

Failure Handling Responsibilities

The RuntimeKernel manages run-level exceptions, implementing retry logic and resource reclamation for the current AgentRun only. When a run fails, the kernel reports the failure to the SessionManager but does not attempt to recover the broader session state.

The SessionManager receives run-level failure reports and updates the session's error state accordingly. It may trigger fallback logic—such as requesting user clarification or alternative agent selection—while preserving the session context for subsequent recovery attempts.

Task Orchestration

The RuntimeKernel executes the specific instructions provided to an AgentRun without knowledge of previous or future executions. It emits runtime events (start, step, finish, error) that are consumed within the execution boundary.

The SessionManager orchestrates the sequence of AgentRun instances, feeding results from one execution into the input of the next. It maintains the todo list that determines which agent runs when, effectively stringing multiple ephemeral executions into a coherent, stateful session.

Component Interaction Flow

The interaction follows a hierarchical delegation pattern. The SessionManager invokes the RuntimeKernel each time a new AgentRun is required, passing session state and todo items as initialization parameters. Upon completion, the kernel returns a run result object that the SessionManager records in the session ledger before determining the next execution step.

As documented in docs/agent-swarm.md, this separation allows multiple AgentRun instances to execute within the same session context, with the SessionManager acting as the central coordinator while individual kernels remain isolated execution environments.

Code Implementation Examples

The following TypeScript examples demonstrate the distinct programmatic interfaces for direct kernel usage versus session-managed execution.

Direct RuntimeKernel Usage (Low-Level)

When interacting directly with the RuntimeKernel for a single AgentRun, you must manually handle all inputs and results:

import { RuntimeKernel } from '@apache/maka/runtime';

// Create a kernel for a single run
const kernel = new RuntimeKernel({
  agentId: 'weather-assistant',
  resources: { cpu: 1, memory: '256Mi' },
});

kernel.run({
  input: 'What is the forecast for tomorrow in Paris?',
}).then((result) => {
  console.log('Run completed:', result);
});

This approach provides direct control over the execution environment but requires manual state management between runs.

SessionManager Orchestration (High-Level)

Using the SessionManager abstracts the kernel instantiation and handles persistence automatically:

import { SessionManager } from '@apache/maka/session';

// Obtain a session (creates a new one if none exists)
const session = await SessionManager.getOrCreate('user-12345');

// Add a todo item that will trigger an agent run
session.todo.add({
  agentId: 'weather-assistant',
  prompt: 'What is the forecast for tomorrow in Paris?',
});

// Run the session – the manager will invoke the Runtime Kernel
// for each pending todo and update the session ledger automatically.
await session.runPending();
const latestResult = session.todo.latestResult;
console.log('Session result:', latestResult);

In this pattern, the SessionManager creates the RuntimeKernel instances under the hood, manages the todo queue, and persists execution state without requiring manual intervention.

Source Code References

The architectural boundaries between these components are documented in the following Apache Maka source files:

• docs/archive/runtime-kernel.md – Design specification for the low-level execution kernel, detailing sandboxing and resource management.
• docs/session-todo-lifecycle.md – Documentation of the SessionManager's todo tracking and session state persistence mechanisms.
• docs/agent-swarm.md – Coordination patterns describing how multiple AgentRun instances are managed within a single session.
• docs/architecture/runtime-core-architecture-draft.md – Comprehensive architectural overview covering both the RuntimeKernel and SessionManager interaction models.

Summary

• RuntimeKernel provides the isolated, stateless execution environment for individual AgentRun instances, handling low-level resource management and run-level error containment.
• AgentRun represents a single, transient execution boundary that starts when an agent launches and ends when the run completes, with no persistence between executions.
• SessionManager maintains durable state across multiple AgentRun executions, persisting todo lists, context, and conversation history in the session ledger.
• The RuntimeKernel is invoked by the SessionManager for each execution, returning results that the SessionManager records to coordinate subsequent runs.
• Direct kernel usage requires manual state management, while SessionManager usage provides automatic persistence and orchestration capabilities.

Frequently Asked Questions

How does the SessionManager handle failures from the RuntimeKernel?

When the RuntimeKernel encounters an error during an AgentRun execution, it reports the failure to the SessionManager without terminating the session. The SessionManager updates the session ledger with the error state and can trigger predefined recovery logic, such as retrying with modified parameters, switching to fallback agents, or requesting user intervention, all while preserving the existing session context.

Can multiple AgentRun instances execute simultaneously within the same SessionManager session?

Yes, the SessionManager can coordinate concurrent AgentRun instances by invoking multiple RuntimeKernel processes. According to docs/agent-swarm.md, the SessionManager maintains the session ledger to track parallel todo items, though each individual AgentRun executes within its own isolated RuntimeKernel environment without shared memory.

What happens to session state if the RuntimeKernel crashes during execution?

The RuntimeKernel's crash affects only the current AgentRun, not the SessionManager's persistent state. Because the kernel is stateless and the SessionManager maintains the session ledger independently, a kernel crash results in a failed run status being recorded in the session ledger. The SessionManager can then initiate a new AgentRun with the same or modified parameters without losing the broader session context.

When should developers use direct RuntimeKernel access instead of the SessionManager?

Direct RuntimeKernel access is appropriate for isolated, single-execution tasks where persistence and multi-run coordination are unnecessary, such as batch processing or testing individual agent behaviors. The SessionManager is required for conversational workflows, multi-step agent swarms, or any scenario requiring state persistence across multiple AgentRun executions and user interactions.

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