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

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, 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) 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 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). If a run crashes, the RuntimeResume class (in 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():

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 into SQLite), crashed sessions are fully reconstructable:

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 – Core implementation of the per-turn Tool Runtime, handling gating, execution, output management, and recovery support.
• 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 – 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 – Public protocol entry point that forwards client requests through the SessionManager to the Tool Runtime layer.
• packages/storage/src/runtime-event-persistence.ts – Persists events emitted by the Tool Runtime into SQLite for replay and recovery scenarios.
• 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 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. 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. 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), 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. 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).

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