What Does the `packages/runtime` Package Handle in Apache Maka?

The packages/runtime package provides the pure-Node agent runtime for Apache Maka, handling model execution, session sandboxing, event projection, context budgeting, and workspace tool execution to transform raw model outputs into safe, stateful AI agents.

The packages/runtime directory in the Apache Maka repository contains the core execution engine that powers all AI agent interactions. This package isolates the agent's execution environment from the host system while managing backend communication, resource limits, and crash recovery. Understanding what the packages/runtime package handles is essential for developers extending Maka's capabilities or integrating its agent runtime into custom product shells.

Core Responsibilities of the Runtime Package

Model and Backend Execution

At its foundation, the runtime package manages all communication with language models and backend-specific logic. According to the README, the package ships with production-ready backends like AiSdkBackend alongside test utilities such as FakeBackend.

In packages/runtime/src/plugin-runtime.ts, the runtime wires these backends to the execution loop, handling model initialization, request routing, and response streaming. This abstraction allows agent developers to swap backend implementations without changing the core execution logic.

Session Sandboxing and Security Boundaries

The runtime enforces strict isolation between the host system and the agent process. Each session operates within a sandboxed workspace that controls:

• Child process execution – spawning and monitoring tool subprocesses
• File-system boundaries – restricting reads and writes to designated sandbox roots
• Network transport – proxying or blocking outbound connections based on security policy

This boundary control ensures that code execution tools or file operations cannot escape the agent's designated workspace, protecting the host environment from unintended side effects.

Event Projection and Recovery

Apache Maka agents must survive crashes and interruptions. The runtime implements an event projection system that records execution traces to a durable ledger. When a session terminates unexpectedly, the recovery helpers in the kernel and projection modules allow the agent to resume from its last known state.

As referenced in the conceptual implementation of runtime-recovery.ts and the kernel modules, the RuntimeKernel.recoverSession() method reconstructs session state from persisted events, enabling long-running agents to maintain continuity across process restarts.

Context Budgeting and Resource Management

To prevent runaway token consumption or memory exhaustion, the runtime provides the ContextBudget class in packages/runtime/src/context-budget.ts #L1-L25. This subsystem tracks:

• Token usage against configurable limits
• Memory allocation for conversation history and tool outputs
• Execution time budgets for long-running operations

When a session exceeds its allocated resources, the runtime triggers graceful degradation or termination, ensuring fair resource sharing in multi-tenant deployments.

Key Implementation Files

The runtime's functionality is split across several focused modules:

• src/plugin-runtime.ts – Core runtime implementation that orchestrates backend connections, tool execution, and event emission. This file contains the main execution loop that product shells interact with indirectly.

• src/plugin-kernel.ts – Public API surface for creating and managing agent sessions. This is the primary entry point documented at #L1-L20, exposing RuntimeKernel and session lifecycle methods.

• src/computer-use-tools.ts – Built-in tool suite enabling file system operations, shell command execution, and image processing within the sandbox. These tools are instantiated per-session to prevent cross-contamination.

• src/context-budget.ts – Resource accounting module that enforces token and memory limits per conversation, as implemented at #L1-L25.

• src/runtime-recovery.ts – Contains persistence and state reconstruction logic for crash recovery, referenced conceptually at #L1-L15, though production recovery logic spans the kernel and projection modules.

Practical Code Examples

Initializing the Runtime Kernel

Create a new runtime instance with a specific backend factory:

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

// Configure kernel with AiSdkBackend for production use
const kernel = new RuntimeKernel({
  backendFactory: () => new AiSdkBackend({ 
    apiKey: process.env.OPENAI_API_KEY 
  })
});

// Initialize a new sandboxed session
await kernel.startSession({ sessionId: 'session-123' });

Source: [packages/runtime/src/plugin-kernel.ts](https://github.com/apache/maka/blob/main/packages/runtime/src/plugin-kernel.ts#L1-L20)

Executing Computer-Use Tools

Run sandboxed file and shell operations through the built-in tool suite:

import { ComputerUseTools } from '@maka/runtime';

const tools = new ComputerUseTools({
  sandboxRoot: '/tmp/agent-sandbox'
});

// List files within the sandbox boundary
const result = await tools.runCommand('ls -la');
console.log(result.stdout);

Source: [packages/runtime/src/computer-use-tools.ts](https://github.com/apache/maka/blob/main/packages/runtime/src/computer-use-tools.ts#L1-L30)

Enforcing Context Budgets

Prevent token overflow by tracking consumption:

import { ContextBudget } from '@maka/runtime';

const budget = new ContextBudget({
  maxTokens: 4096,
  maxMemoryBytes: 10_000_000
});

// Simulate model interaction
budget.consumeTokens(120);
budget.consumeMemory(1024);

console.log(budget.remainingTokens); // 3976
if (budget.isExceeded()) {
  await kernel.compactSession(); // Trigger context compression
}

Source: [packages/runtime/src/context-budget.ts](https://github.com/apache/maka/blob/main/packages/runtime/src/context-budget.ts#L1-L25)

Recovering from Crashes

Restore a session after process interruption:

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

// Attempt to recover session state from the event ledger
const recovered = await RuntimeKernel.recoverSession('session-123');
if (recovered) {
  console.log('Session resumed from last checkpoint');
  await recovered.continueExecution();
}

Source: Conceptual implementation in [packages/runtime/src/runtime-recovery.ts](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-recovery.ts#L1-L15)

Summary

• packages/runtime is the pure-Node execution engine that Apache Maka product shells compose to run AI agents.
• It abstracts backend communication, supporting both production backends (AiSdkBackend) and test mocks (FakeBackend).
• It enforces security boundaries through workspace sandboxing, isolating file system and process execution.
• It manages resource limits via ContextBudget, tracking tokens and memory to prevent exhaustion.
• It supports fault tolerance through event projection and the recoverSession mechanism, allowing agents to resume after crashes.

Frequently Asked Questions

What is the difference between plugin-runtime.ts and plugin-kernel.ts?

plugin-kernel.ts exposes the public RuntimeKernel class and session management APIs that product shells call to start and stop agents. plugin-runtime.ts contains the internal orchestration logic that wires the backend, tool execution, and event systems together. Think of the kernel as the steering wheel and the runtime as the engine.

How does the runtime package handle agent crash recovery?

The runtime emits execution events to a durable ledger during agent operation. If the process crashes, the RuntimeKernel.recoverSession() static method reconstructs the session state from these events, restoring the conversation history, tool contexts, and memory to the last consistent checkpoint without requiring manual intervention.

Can packages/runtime be used independently of the Maka desktop application?

Yes. The runtime is designed as a library that any Node.js application can import. The desktop and web product shells are separate packages that depend on packages/runtime as an npm dependency, meaning you can embed the agent runtime in custom servers, CLI tools, or third-party integrations while maintaining the same sandboxing and execution guarantees.

Which backend implementations are available in the runtime package?

According to the README, the package ships with AiSdkBackend for production OpenAI-compatible API integration and FakeBackend for deterministic testing. Developers can implement the backend interface in plugin-runtime.ts to add support for additional model providers without modifying the core runtime logic.

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