# Architecture of the Tool Runtime in Apache Maka: A Deep Dive into the Execution Stack

> Explore the Tool Runtime architecture in Apache Maka. Understand how it validates policies, enforces boundaries, streams output, and ensures deterministic recovery for tool invocations.

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

---

**Apache Maka routes every user-initiated tool invocation through a per-turn Tool Runtime that validates gating policies, enforces execution boundaries, streams output with size limits, and persists every interaction to the Runtime Event Log for deterministic recovery and replay.**

Apache Maka is an open-source AI orchestration framework that processes all model-driven operations through a strictly defined execution hierarchy. At the deepest layer of this stack sits the **Tool Runtime in Apache Maka**, a transient, per-turn component instantiated by the `RuntimeKernel` that serves as the sole authority for invoking tools, applying security constraints, and ensuring complete auditability through immutable event sourcing.

## The Execution Hierarchy: From Frontend to Tool Runtime

All work in Apache Maka flows downward through a single execution authority. According to the source code in [`packages/runtime-host/src/server/runtime-resource-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/runtime-resource-coordinator.ts), the system processes requests through this well-defined stack:

```

Desktop / TUI / CLI / Bot → Runtime Host → SessionManager → AgentRun + RuntimeKernel → Tool Runtime

```

The **Runtime Host** acts as the sole execution authority, receiving requests from various front-ends and exposing a public client protocol. The **SessionManager** tracks session and turn identity, manages the lifecycle of an agent run, and coordinates continuations. The **AgentRun** and **RuntimeKernel** (implemented in [`packages/runtime/src/runtime-kernel.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-kernel.ts)) drive model adapters, schedule tools, and write every event to the **Runtime Event Log**—the canonical source of truth for tool calls, results, and termination facts.

At the bottom of this chain, the Tool Runtime receives a single turn’s context at construction, invokes the actual tool implementations, and guarantees that every action is recorded for recovery.

## Core Responsibilities of the Tool Runtime

The `ToolRuntime` class in [`packages/runtime/src/tool-runtime.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool-runtime.ts) handles six critical responsibilities during each turn:

### Input Validation and Tool Gating

Before executing any tool, the runtime validates the request against `ToolGating` policies provided by the backend. The `setGating()` method accepts constraints such as `callCount` and `exclusiveToolName`, rejecting disallowed invocations before they reach the implementation layer.

### Execution Boundary Enforcement

The runtime respects `ToolExecutionFacts` to enforce isolation, network access restrictions, secret handling protocols, and write-back permissions. These boundaries ensure that tools execute within their authorized security contexts according to the `readExecutionBoundary` parameters passed via `ToolRuntimeInput`.

### Output Streaming and Size Management

Tool output flows through `ToolOutputStream`, which handles stdout and stderr streaming. The runtime enforces `TOOL_OUTPUT_DELTA_MAX_CHARS` limits, truncating oversized outputs to prevent memory exhaustion. Throughout execution, it emits `ToolStartEvent` and `ToolResultEvent` signals to the event log.

### Result Materialization

Upon completion, the runtime constructs a `ToolResultOutput` containing the tool's return value. If a tool fails to produce a result, the runtime generates a default placeholder, ensuring that every invocation yields a deterministic settlement object.

### Telemetry and Artifact Recording

The runtime records invocation statistics via `ToolInvocationRecord` and persists generated files through `ToolArtifactRecorder`. This telemetry attaches to the session history for debugging and optimization analysis.

### Crash Recovery and State Reconstruction

The Tool Runtime stores durable attempts in an in-memory map and writes all events to the Runtime Event Log (defined in [`packages/core/src/runtime-event.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event.ts)). If a run crashes, the `RuntimeResume` class (in [`packages/runtime/src/runtime-resume.js`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-resume.js)) replays these events to rebuild the exact state, enabling seamless continuation from the point of failure.

## Implementing Tool Execution

To invoke tools within this architecture, you instantiate a `ToolRuntime` with turn-specific context and call `settleToolCall()`:

```typescript
import { ToolRuntime, type ToolRuntimeInput } from '@maka/runtime';
import { type MakaTool } from '@maka/runtime/src/tool-runtime.js';

// 1️⃣ Build the runtime input (provided by the host for the current turn)
const runtimeInput: ToolRuntimeInput = {
  turnId: 'turn-123',
  sessionId: 'session-abc',
  toolCallId: 'call-456',
  readExecutionBoundary: { /* authority info */ },
  // optional: custom default result, telemetry recorder, etc.
};

// 2️⃣ Instantiate the runtime
const toolRuntime = new ToolRuntime(runtimeInput);

// 3️⃣ Define a simple tool (e.g., a web‑search wrapper)
const webSearchTool: MakaTool = {
  name: 'web-search',
  activityKind: 'search',
  impl: async (query, ctx) => {
    // pretend we call an external service here
    ctx.emitOutput('stdout', `Searching for "${query}"…`);
    return { kind: 'text', content: `Results for ${query}` };
  },
};

// 4️⃣ Resolve a tool call (normally produced by the LLM)
const resolvedCall = {
  tool: webSearchTool,
  toolCallId: 'call-456',
  args: 'cats',
  parentToolCallId: undefined,
};

// 5️⃣ Set any gating (optional)
toolRuntime.setGating({ callCount: 1, exclusiveToolName: 'web-search' });

// 6️⃣ Execute the tool and get the settlement
const settlement = await toolRuntime.settleToolCall(resolvedCall);

// 7️⃣ Append the result message back to the session
await appendMessage({
  role: 'tool',
  toolCallId: settlement.toolCallId,
  content: settlement.modelOutput,
});

```

## Recovering from Runtime Failures

Because the Tool Runtime persists every significant state change to the Runtime Event Log (stored via [`packages/storage/src/runtime-event-persistence.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/runtime-event-persistence.ts) into SQLite), crashed sessions are fully reconstructable:

```typescript
import { RuntimeResume } from '@maka/runtime';
import { type ResumeInput } from '@maka/runtime/src/runtime-resume.js';

const resumeInput: ResumeInput = {
  sessionId: 'session-abc',
  turnId: 'turn-123',
  // ...event‑log cursor, recovery mode, etc.
};

const resume = new RuntimeResume(resumeInput);
await resume.replay();   // rebuilds in‑memory state from the event log

```

The `replay()` method processes the immutable event stream, reconstructing the exact in-memory state of the Tool Runtime and all parent components up to the Runtime Host.

## Key Source Files

- **[`packages/runtime/src/tool-runtime.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool-runtime.ts)** – Core implementation of the per-turn Tool Runtime, handling gating, execution, output management, and recovery support.
- **[`packages/runtime/src/runtime-kernel.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-kernel.ts)** – Manages the overall run lifecycle, coordinates AgentRun and model adapters, and instantiates the Tool Runtime for each turn.
- **[`packages/core/src/runtime-event.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event.ts)** – Defines the canonical event types (`ToolStartEvent`, `ToolResultEvent`, etc.) written by the Tool Runtime to the Runtime Event Log.
- **[`packages/runtime-host/src/server/runtime-resource-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/runtime-resource-coordinator.ts)** – Public protocol entry point that forwards client requests through the SessionManager to the Tool Runtime layer.
- **[`packages/storage/src/runtime-event-persistence.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/runtime-event-persistence.ts)** – Persists events emitted by the Tool Runtime into SQLite for replay and recovery scenarios.
- **[`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md)** – High-level diagram and description of the backend architecture, including the Tool Runtime's position within the execution stack.

## Summary

- The **Tool Runtime in Apache Maka** operates as a per-turn execution boundary instantiated by the RuntimeKernel for each tool invocation.
- It enforces **tool-availability gating** via `ToolGating` policies and **execution boundaries** through `ToolExecutionFacts` (isolation, network, secrets).
- All output streams through `ToolOutputStream` with enforced size limits (`TOOL_OUTPUT_DELTA_MAX_CHARS`) and truncation safeguards.
- Every tool call and result is materialized as a `ToolResultOutput` and recorded as immutable events in the **Runtime Event Log**, the system's single source of truth.
- Crash recovery is achieved through `RuntimeResume`, which replays the event log from [`packages/storage/src/runtime-event-persistence.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/runtime-event-persistence.ts) to reconstruct exact runtime state.
- The architecture guarantees deterministic, auditable, and recoverable tool execution across all front-end interfaces (Desktop, TUI, CLI, Bots).

## Frequently Asked Questions

### How does the Tool Runtime enforce security policies during tool execution?

The Tool Runtime enforces security through two mechanisms defined in [`packages/runtime/src/tool-runtime.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool-runtime.ts). First, it validates invocations against **tool-availability gating** via the `setGating()` method, which rejects calls exceeding `callCount` limits or not matching `exclusiveToolName` constraints. Second, it applies **execution facts** from the `readExecutionBoundary` input, controlling network access, process isolation, secret injection, and file system write-back permissions before the tool implementation executes.

### What happens when a tool produces output exceeding size limits?

When a tool streams output through `ToolOutputStream`, the Tool Runtime enforces the `TOOL_OUTPUT_DELTA_MAX_CHARS` constant, automatically truncating oversized stdout or stderr content. This prevents memory exhaustion during long-running operations while still capturing the beginning of the output for debugging. The runtime emits `ToolResultEvent` signals containing the truncated content, marking the output as incomplete in the Runtime Event Log.

### How does Apache Maka recover from crashes during tool execution?

Apache Maka achieves crash recovery through the `RuntimeResume` class in [`packages/runtime/src/runtime-resume.js`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-resume.js). Since the Tool Runtime writes every significant action—tool calls, results, errors—to the **Runtime Event Log** (persisted in SQLite via [`packages/storage/src/runtime-event-persistence.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/runtime-event-persistence.ts)), the system can reconstruct the exact pre-crash state. The `replay()` method reads these immutable events and rebuilds the in-memory state of the Tool Runtime, SessionManager, and Runtime Host, allowing the turn to continue from the exact point of interruption.

### Where is the canonical record of tool invocations stored?

The canonical record resides in the **Runtime Event Log**, defined in [`packages/core/src/runtime-event.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event.ts). This log captures `ToolStartEvent` and `ToolResultEvent` entries for every invocation, serving as the single source of truth for tool activity. The log is written by the Tool Runtime during execution and persisted to storage, enabling recovery, audit trails, and deterministic replay regardless of front-end interface (Desktop, TUI, CLI, or Bot).