# What Is RuntimeKernel in Maka? The Internal Execution Engine Explained

> Discover Maka's RuntimeKernel, the internal execution engine. It orchestrates turns, ensures durability, and offers crash recovery while maintaining API compatibility.

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

---

**The RuntimeKernel is the internal execution engine that orchestrates individual turns within a Maka session, providing clear architectural boundaries, durable run recording, and robust crash recovery while maintaining full backward compatibility with existing APIs.**

The Apache Maka project introduced the **RuntimeKernel** to decompose the monolithic runtime logic previously embedded in `AiSdkBackend` and `SessionManager.sendMessage()`. This internal refactor extracts the execution engine into a modular system that handles tool lifecycles, model stream normalization, and persistent state management.

## Why Maka Extracted the RuntimeKernel

Prior to the RuntimeKernel extraction, turn execution logic was tightly coupled inside `AiSdkBackend` and `SessionManager.sendMessage()`. This monolithic structure made it difficult to test components in isolation or recover from crashes reliably.

By introducing the RuntimeKernel, the codebase now enforces clear internal boundaries between distinct execution concerns. The refactor does not alter any public APIs—including window `maka.*` interfaces, Electron IPC channels, session JSONL formats, or builtin tool names—ensuring complete backward compatibility while improving internal maintainability.

## Core Components of the RuntimeKernel

The RuntimeKernel groups related concerns into four dedicated components, each responsible for a specific aspect of turn execution.

### ToolRuntime: Managing Tool Lifecycles

The `ToolRuntime` component, implemented in [`packages/runtime/src/tool-runtime.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool-runtime.ts), owns the complete lifecycle of model-requested tools. It handles validation, permission policy evaluation, abort signal propagation, and telemetry emission.

By isolating tool execution within `ToolRuntime`, the kernel can gracefully handle permission denials and cancellation requests without destabilizing the broader session.

### ModelAdapter: Normalizing AI Provider Streams

Located in [`packages/runtime/src/model-adapter.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/model-adapter.ts), the `ModelAdapter` isolates provider-specific stream handling and error normalization. It abstracts the differences between various AI SDK backends, presenting a unified interface to the rest of the kernel.

This normalization ensures that streaming responses and error conditions from different providers are handled consistently within `AgentRun.execute()`.

### RunTrace: Runtime Observability

The `RunTrace` component in [`packages/runtime/src/run-trace.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/run-trace.ts) records a best-effort trace of runtime events during turn execution. These traces provide visibility into the execution flow without impacting performance.

Importantly, `RunTrace` failures are intentionally non-fatal, ensuring that telemetry issues never interrupt a user-facing session.

### AgentRun and AgentRunStore: Durable State Contracts

The `AgentRun` class, defined in [`packages/core/src/agent-run.ts`](https://github.com/apache/maka/blob/main/packages/core/src/agent-run.ts) and invoked from [`packages/runtime/src/agent-run.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-run.ts), orchestrates the core turn execution. It creates a durable, file-backed run contract that survives application crashes.

The `AgentRunStore` in [`packages/storage/src/agent-run-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/agent-run-store.ts) manages the persistent ledger, storing run headers in [`run.json`](https://github.com/apache/maka/blob/main/run.json) and append-only event logs in `events.jsonl` within `sessions/<sessionId>/runs/<runId>/` directories.

## Session Recovery and the Run Ledger

The RuntimeKernel enables robust startup recovery through `recoverInterruptedSessions()` in [`packages/runtime/src/agent-run-recovery.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-run-recovery.ts). On application startup, this function scans the run ledger to classify stale runs—such as a `run_started` event without a corresponding terminal state.

By examining the file-backed ledger rather than replaying model streams or re-executing tools, the system can deterministically write terminal states for interrupted runs. This prevents sessions from becoming stuck in *running* or *waiting* states after an application restart.

## Practical Usage Examples

The following examples demonstrate how to interact with the RuntimeKernel components programmatically.

### Executing a Turn with AgentRun

To initiate a new turn within a session, invoke `AgentRun.execute()`:

```ts
import { AgentRun } from '@maka/runtime';

// inside SessionManager.sendMessage()
const run = await AgentRun.execute({
  sessionId,
  userMessage,
  backend: activeBackend,
});

```

### Running Tools Through the Kernel

Invoke tools through the `ToolRuntime` boundary to ensure proper permission handling and signal propagation:

```ts
import { ToolRuntime } from '@maka/runtime';

await ToolRuntime.run({
  toolName: 'search',
  input: { query: 'Maka architecture' },
  permissionPolicy,   // evaluated inside the kernel
  abortSignal,       // propagated automatically
});

```

### Reading the Persistent Run Ledger

Access the durable run history using `AgentRunStore` to inspect past execution events:

```ts
import { AgentRunStore } from '@maka/storage';

const store = new AgentRunStore();
const runHeader = await store.readRunHeader(sessionId, runId);
const events    = await store.readRunEvents(sessionId, runId);

```

## Summary

- The **RuntimeKernel** is an internal execution engine in Apache Maka that orchestrates turn-based session processing with clear architectural boundaries.
- It comprises four core components: **ToolRuntime** for tool lifecycle management, **ModelAdapter** for provider normalization, **RunTrace** for observability, and **AgentRun/AgentRunStore** for durable state persistence.
- Each turn persists to a file-backed ledger ([`run.json`](https://github.com/apache/maka/blob/main/run.json) and `events.jsonl`) enabling crash recovery via `recoverInterruptedSessions()` without replaying streams or tools.
- The refactor maintains 100% backward compatibility with existing public APIs while significantly improving testability, modularity, and recovery capabilities.

## Frequently Asked Questions

### Does RuntimeKernel change how I interact with Maka's public APIs?

No. The RuntimeKernel is strictly an internal refactor. According to the Apache Maka source code, window `maka.*` interfaces, Electron IPC channels, session JSONL formats, and builtin tool names remain unchanged. Your existing integrations continue to function identically.

### How does RuntimeKernel recover from application crashes?

The kernel writes a durable ledger to `sessions/<sessionId>/runs/<runId>/` containing [`run.json`](https://github.com/apache/maka/blob/main/run.json) headers and `events.jsonl` logs. On startup, `recoverInterruptedSessions()` scans these files to classify stale runs and writes deterministic terminal states, preventing sessions from hanging in *running* or *waiting* states.

### What happens if RunTrace fails during execution?

`RunTrace` failures are intentionally non-fatal. The kernel captures telemetry on a best-effort basis, ensuring that trace recording issues never interrupt the actual tool execution or model streaming. This design prioritizes user-facing stability over observability completeness.

### Can I use RuntimeKernel components outside of the standard session flow?

Yes. While `AgentRun.execute()` serves as the primary entry point called by `SessionManager`, you can import individual components like `ToolRuntime` or `AgentRunStore` directly from `@maka/runtime` and `@maka/storage` respectively. This modular design supports custom workflows and unit testing without requiring full session initialization.