# What Does the packages/runtime Directory Handle in Apache Maka

> Discover what the packages/runtime directory handles in Apache Maka. Learn how it orchestrates agent turns through tool runtime management, model adapter resolution, sandbox enforcement, and persistence.

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

---

**The `packages/runtime` directory serves as the core execution engine of Apache Maka, orchestrating agent turns through tool runtime management, model adapter resolution, sandbox boundary enforcement, and durable persistence mechanisms.**

The `packages/runtime` directory is the backbone of the Apache Maka repository, responsible for driving the entire lifecycle of an AI agent execution turn. This package implements the runtime host that mediates between large language model (LLM) providers, tool implementations, and security boundaries to ensure reliable and secure agent operations.

## Core Responsibilities of the packages/runtime Directory

### Agent Execution Flow via ToolRuntime

The `ToolRuntime` class in [`packages/runtime/src/tool-runtime.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool-runtime.ts) is the central orchestrator for agent execution. It manages the complete lifecycle of a tool call, including sandbox-boundary decisions, loop-gating logic, and child-agent management. According to the source code at lines 93-113, `ToolRuntime` records tool start and result events, enforces admission limits to prevent resource exhaustion, and guarantees durable commit semantics to ensure execution integrity.

### Model Adapters and Wiring

The runtime translates abstract model identifiers into concrete provider implementations through `resolveModelRuntime` in [`packages/runtime/src/model-runtime.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/model-runtime.ts). This function selects the appropriate API wire—such as OpenAI chat or Anthropic messages—based on the provider configuration. Lines 64-73 handle the adapter resolution, while lines 78-86 determine model capabilities including parallel tool call support and apply-patch contracts.

### Tool Catalog and Execution

Tools in Maka implement the `MakaTool` interface defined in the runtime. The [`packages/runtime/src/tool-runtime.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool-runtime.ts) module (lines 31-71) validates tool arguments against their JSON schemas, applies permission-projection rules to restrict capabilities, and executes implementations while respecting sandbox boundaries and recovery modes. This ensures that both built-in and custom tools operate within defined security and reliability constraints.

### Sandbox Boundary Enforcement

Security isolation is enforced through `SandboxBoundaryRequest` and `SandboxBoundarySettlement` mechanisms in [`packages/runtime/src/tool-runtime.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool-runtime.ts) (lines 24-30). The runtime mediates all interactions with the host operating system, requiring explicit approval for file-system or network access. This prevents unauthorized operations by ensuring potentially dangerous tools must clear permission gates before execution.

### Recovery and Persistence

Durability is built into the execution model through commit-boundary tracking. The `ToolRuntime` monitors durable attempts and writes synthetic error results when tools fail unexpectedly, as implemented at lines 84-92 of [`packages/runtime/src/tool-runtime.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool-runtime.ts). Coordinated commit-boundary errors maintain an immutable execution ledger, allowing the system to recover from partial failures without corrupting the session state.

### Context and Budgeting

The runtime monitors resource consumption through dedicated modules. [`packages/runtime/src/context-budget.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/context-budget.ts) implements token and byte budgeting to prevent context window overflow, while `latest-context-snapshot` and `run-trace` provide diagnostic visibility. These components expose current session snapshots to tools and enforce limits on model calls and tool output sizes.

## Key Source Files in packages/runtime

| File | Purpose |
|------|---------|
| [`packages/runtime/src/tool-runtime.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool-runtime.ts) | Central class managing tool invocation, sandbox gating, loop-gate logic, and durable commit handling. |
| [`packages/runtime/src/model-runtime.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/model-runtime.ts) | Resolves model identifiers to concrete provider adapters and selects API wires based on capabilities. |
| [`packages/runtime/src/agent-run.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-run.ts) | Entry point that creates a `ToolRuntime` instance per turn and drives the overall agent execution lifecycle. |
| [`packages/runtime/src/context-budget.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/context-budget.ts) | Implements token and byte budgeting with enforcement for model context windows. |
| [`packages/runtime/src/sandbox-boundary-tool.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox-boundary-tool.ts) | Helper utilities for handling sandbox-boundary requests and permission denials. |
| [`packages/runtime/src/recovery-resolver.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/recovery-resolver.ts) | Provides crash-recovery logic and resumption capabilities for partially completed tool calls. |

## Practical Usage Examples

### Creating a ToolRuntime Instance

To initialize the execution environment for an agent turn, instantiate `ToolRuntime` with the required configuration:

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

const runtime = new ToolRuntime({
  sessionId: 'sess-123',
  header: { turnId: 'turn-1', ts: Date.now() },
  connection: { providerType: 'openai', baseUrl: undefined },
  modelId: 'gpt-4o',
  appendMessage: async (msg) => console.log('Message:', msg),
  readExecutionBoundary,
  newId: () => crypto.randomUUID(),
  now: () => Date.now(),
  getPermissionPauseTarget: () => null,
  turnId: 'turn-1',
});

```

### Resolving a Model Runtime for a Provider

The runtime selects the appropriate adapter based on provider configuration:

```typescript
import { resolveModelRuntime } from '@maka/runtime';

const conn = { 
  providerType: 'openai', 
  models: [{ id: 'gpt-4o', apiProtocol: 'openai-chat' }] 
};
const model = resolveModelRuntime(conn, 'gpt-4o');

console.log('Adapter kind:', model.adapter.kind); // "openai"
console.log('Wire used:', model.wire); // "openai-chat"

```

### Executing a Custom Tool Through the Runtime

Define and execute tools using the `MakaTool` interface:

```typescript
const myTool: MakaTool = {
  name: 'echo',
  description: 'Returns the supplied text.',
  parameters: { 
    type: 'object', 
    properties: { text: { type: 'string' } }, 
    required: ['text'] 
  },
  impl: async ({ text }: { text: string }, ctx) => text,
};

await runtime.settleToolCall({
  tool: myTool,
  turnId: 'turn-1',
  toolCallId: 'call-42',
  input: { text: 'Hello, Maka!' },
  abortSignal: new AbortController().signal,
  eventSink: { 
    push: () => {}, 
    pushAndWaitUntilConsumed: async () => {} 
  },
});

```

## Summary

- The `packages/runtime` directory implements the **execution host** that drives Apache Maka agent turns, coordinating between LLM providers and tool implementations.
- **`ToolRuntime`** in [`tool-runtime.ts`](https://github.com/apache/maka/blob/main/tool-runtime.ts) manages the complete execution flow including sandbox gating, admission control, and durable commit semantics.
- **`resolveModelRuntime`** handles provider abstraction, selecting appropriate API wires and capability flags for different LLM backends.
- **Sandbox boundaries** enforce security by requiring explicit approval for OS-level operations, preventing unauthorized file-system or network access.
- **Recovery mechanisms** ensure execution durability through commit-boundary tracking and synthetic error reporting for failed operations.
- **Context budgeting** prevents resource exhaustion by monitoring token usage and enforcing limits on model interactions.

## Frequently Asked Questions

### What is the primary entry point for agent execution in packages/runtime?

The [`packages/runtime/src/agent-run.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-run.ts) module serves as the main entry point, creating a fresh `ToolRuntime` instance for each turn and orchestrating the overall agent lifecycle. It initializes the execution context, binds the model connection, and manages the transition between planning and tool execution phases.

### How does packages/runtime handle different LLM providers?

The runtime abstracts provider differences through the `resolveModelRuntime` function in [`model-runtime.ts`](https://github.com/apache/maka/blob/main/model-runtime.ts). This resolver maps model identifiers to concrete adapters—such as OpenAI or Anthropic implementations—selects the correct API wire protocol (e.g., `openai-chat` or `anthropic-messages`), and extracts capability flags like parallel tool call support.

### What security mechanisms does packages/runtime implement to prevent unauthorized system access?

Security is enforced through sandbox boundary mediation in [`tool-runtime.ts`](https://github.com/apache/maka/blob/main/tool-runtime.ts). The runtime requires all potentially dangerous operations—such as file-system modifications or network requests—to pass through `SandboxBoundaryRequest` validation. Explicit user approval through `SandboxBoundarySettlement` is required before the runtime permits these operations to execute.

### How does the runtime recover from crashes or failures during tool execution?

The [`packages/runtime/src/recovery-resolver.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/recovery-resolver.ts) module implements crash-recovery logic that tracks durable commit boundaries. If a tool fails mid-execution, `ToolRuntime` writes synthetic error results to maintain ledger immutability, while the recovery resolver enables resumption of partially completed operations without losing execution state.