# How RuntimeKernel Manages AgentRun Instances in Apache Maka

> Discover how Apache Maka's RuntimeKernel orchestrates AgentRun instances, managing their lifecycle from creation to persistence and resumption for durable execution.

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

---

**The RuntimeKernel class serves as the central orchestration component that transforms user-level session requests into durable AgentRun execution units, managing their complete lifecycle from creation through persistence and resumption.**

The `RuntimeKernel` is the core execution engine within the Apache Maka framework responsible for bridging high-level session APIs with low-level AI SDK operations. It isolates runtime concerns—including execution ordering, resource limits, and state persistence—from the thin `SessionManager` façade. This article examines the internal mechanisms by which `RuntimeKernel` instantiates, tracks, and governs `AgentRun` instances based on the source implementation in [`packages/runtime/src/runtime-kernel.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-kernel.ts).

## The AgentRun Lifecycle: From Turn Initiation to Completion

The `RuntimeKernel` owns the complete lifecycle of every `AgentRun`, acting as the authoritative manager for execution state transitions.

### Turn Orchestration and Chain Creation

When `SessionManager.sendMessage()` receives a user request, it delegates to `RuntimeKernel.startTurn()` to initiate execution. The kernel constructs a durable execution chain that flows from the high-level session down to the backend AI provider:

`AgentRun → RuntimeRunner → AiSdkFlow → AiSdkBackend`

This chain implementation, documented in the runtime-mainline-teaching-manual, ensures that each turn becomes a traceable, instrumentable execution unit. The kernel instantiates a new `AgentRun` during `startTurn()`, binding it to the specific session and configuring its metadata through the constructor dependencies passed to `new RuntimeKernel(deps)`.

### Active Run Tracking and State Management

Within [`runtime-kernel.ts`](https://github.com/apache/maka/blob/main/runtime-kernel.ts), the kernel maintains an `activeRun` property that references the currently executing `AgentRun` instance. This property allows the kernel to monitor tool invocations, enforce usage caps, and process stop signals throughout the execution duration. The kernel records durable metadata at creation time and transitions the run through discrete states: running, paused, and finished.

```ts
// Inside runtime-kernel.ts
const currentRun = this.activeRun;  // Access the live AgentRun instance
console.log('Run ID:', currentRun.runId);

```

## Concurrency Control and Session Exclusivity

The `RuntimeKernel` enforces strict concurrency constraints to prevent resource contention and state corruption.

### Enforcing Single Active Run Policy

Apache Maka guarantees that only **one** active `AgentRun` exists per session at any given time. If code attempts to invoke `startTurn()` while another run is active, the kernel raises a `SessionQuiescentMutationBusyError` as defined in [`packages/runtime/src/quiescent-session-snapshot.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/quiescent-session-snapshot.ts). This exclusivity prevents overlapping mutations that could corrupt session state or cause race conditions during backend communication.

### Quiescent Mutations for Snapshot Consistency

Before capturing session snapshots, the kernel enters a quiescent state using `runSessionQuiescentMutation()`. This method ensures all asynchronous operations complete and provides a consistent view of the session state for persistence.

```ts
import { SessionQuiescentMutationBusyError } from './runtime-kernel.js';

try {
  await runtimeKernel.runSessionQuiescentMutation(async (kernel) => {
    // Safe to read/write session state here
    await kernel.store.saveSnapshot(...);
  });
} catch (e) {
  if (e instanceof SessionQuiescentMutationBusyError) {
    // Another mutation is in progress – implement retry logic
    console.error('Snapshot blocked by active mutation');
  }
}

```

## Persistence and Continuation of AgentRun Instances

The kernel implements sophisticated persistence mechanisms that enable long-running conversations to survive process restarts and continue across multiple turns.

### Rehydrating Runs with resumeRun

When a turn concludes with a "continue" plan, the kernel does not discard the `AgentRun`. Instead, it persists the execution state and provides the `resumeRun()` method to rehydrate the run on subsequent turns. This functionality, detailed in [`docs/architecture/runtime-resume-architecture.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-resume-architecture.md), allows the kernel to restore the exact execution context including conversation history and tool states.

```ts
// Resuming a persisted AgentRun after a continue plan
await runtimeKernel.resumeRun({
  runId: persistedRunId,
  sessionId: 'sess-123',
});

```

### Backend Binding Across Turns

The `RuntimeKernel` maintains a critical optimization by binding a single `AiSdkBackend` instance to a session for the entire lifetime of an `AgentRun`. This backend, implemented in [`ai-sdk-backend.ts`](https://github.com/apache/maka/blob/main/ai-sdk-backend.ts), is reused across all turns of the session rather than recreated for each interaction. The kernel manages this binding in [`runtime-kernel.ts`](https://github.com/apache/maka/blob/main/runtime-kernel.ts), ensuring connection pooling and credential caching remain consistent throughout the run duration.

## Error Handling and Resource Cleanup

Beyond execution orchestration, the kernel tracks interaction boundaries and manages resource cleanup. When an `AgentRun` terminates—whether through completion, error, or external cancellation—the kernel triggers cleanup routines that release backend connections and flush telemetry. Unrecoverable errors propagate upward from the kernel to `SessionManager`, maintaining clear separation between runtime failures and session-level API concerns.

## Summary

- **Single Authority**: The `RuntimeKernel` in [`packages/runtime/src/runtime-kernel.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-kernel.ts) serves as the sole manager of `AgentRun` instantiation and lifecycle, ensuring one active run per session.
- **Execution Chain**: It constructs the flow `AgentRun → RuntimeRunner → AiSdkFlow → AiSdkBackend` to isolate runtime concerns from session APIs.
- **Concurrency Safety**: The kernel enforces exclusivity through `SessionQuiescentMutationBusyError` and provides `runSessionQuiescentMutation()` for consistent snapshots.
- **Persistence Support**: Through `resumeRun()`, the kernel enables continuation of `AgentRun` instances across server restarts and conversation turns.
- **Resource Optimization**: It maintains persistent backend bindings throughout the `AgentRun` lifetime, avoiding connection overhead.

## Frequently Asked Questions

### What happens if I try to start a new turn while another AgentRun is active?

The `RuntimeKernel` prevents concurrent execution attempts by throwing a `SessionQuiescentMutationBusyError` defined in [`quiescent-session-snapshot.ts`](https://github.com/apache/maka/blob/main/quiescent-session-snapshot.ts). This ensures only one `AgentRun` executes per session, preventing race conditions and maintaining state integrity. Client code should catch this error and implement retry logic or queue the request until the current run completes.

### How does RuntimeKernel ensure data consistency during snapshots?

The kernel utilizes `runSessionQuiescentMutation()` to enter a quiescent state where all active mutations complete before snapshot capture. This method accepts a callback that executes only when the session reaches a consistent state, ensuring that `AgentRun` metadata and conversation history remain synchronized during persistence operations.

### Can AgentRun instances be resumed after a server restart?

Yes. When a turn ends with a continuation plan, the kernel persists the `AgentRun` state and provides the `resumeRun()` method to rehydrate the execution context. According to the runtime-resume-architecture documentation, this capability allows long-running tasks to survive process termination and resume exactly where they left off, including tool states and backend connections.

### What is the relationship between RuntimeKernel and SessionManager?

`SessionManager` acts as a thin façade that forwards high-level API calls to the `RuntimeKernel`, which contains the actual orchestration logic. While `SessionManager` handles user-facing concerns like authentication and request validation, the kernel manages the `AgentRun` lifecycle, backend binding, and execution ordering. This separation keeps the session API lightweight while centralizing complex runtime management within the kernel.