What Does the packages/runtime Directory Handle in Apache Maka

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 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. 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 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 (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. 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 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	Central class managing tool invocation, sandbox gating, loop-gate logic, and durable commit handling.
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	Entry point that creates a ToolRuntime instance per turn and drives the overall agent execution lifecycle.
packages/runtime/src/context-budget.ts	Implements token and byte budgeting with enforcement for model context windows.
packages/runtime/src/sandbox-boundary-tool.ts	Helper utilities for handling sandbox-boundary requests and permission denials.
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:

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:

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:

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

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