What Is RuntimeKernel in Maka? The Internal Execution Engine Explained

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, 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, 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 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 and invoked from 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 manages the persistent ledger, storing run headers in 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. 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():

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:

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:

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

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