What Is the Runtime Event Log in Maka? Architecture and Usage Guide

The Runtime Event Log in Maka is an immutable, ordered record of all agent execution facts that serves as the single source of truth for system state, enabling replay, checkpointing, and reproducible projections across components.

The Runtime Event Log forms the backbone of Apache Maka’s execution model, ensuring that every interaction between the language model, tools, and runtime environment is captured durably. According to the architecture documentation in docs/architecture/runtime-core-architecture-draft.md, this log maintains the canonical record of model messages, tool calls, tool results, and termination events, allowing any component to reconstruct system state by reading projections rather than maintaining private mutable state.

Core Architecture and Design Principles

The Runtime Event Log implements an event-sourced architecture where the log itself is the primary source of truth, not a secondary audit trail.

Immutable Facts and Projections

Every action an agent takes generates a fact—a discrete, immutable event such as a model message, tool invocation, or completion signal. These facts are persisted in strict chronological order to the Runtime Event Log. Rather than storing current state directly, higher-level components like SessionManager, RuntimeKernel, and AgentRun maintain projections—derived views computed by reading the ordered stream of events.

This design guarantees that system state at any point in time is simply a projection over the ordered log. As documented in the architecture specification, this approach ensures exact reproducibility of the agent’s interaction history without requiring complex synchronization mechanisms between components.

Durable Execution History

Because the log is written to durable storage (typically as a JSON Lines file specified via the MAKA_MCP_STDIO_EVENT_LOG environment variable), processes can restart, new sessions can open, and different consumers can build independent views from the same execution trace. The log’s immutability ensures that once an event is recorded, it becomes a permanent part of the audit trail, enabling debugging, compliance, and forensic analysis of agent behavior.

Reading and Replaying the Runtime Event Log

Developers interact with the Runtime Event Log primarily through file I/O operations on the JSON Lines format file specified at runtime. The CLI entry point in packages/cli/src/runtime-host-cli.ts wires the MAKA_MCP_STDIO_EVENT_LOG environment variable to the runtime host, causing all events to be appended to the designated file path.

Parsing Event Log Files

Each line in the log file represents a single JSON object describing a discrete event. Below is a practical example demonstrating how to read and replay model messages from a Runtime Event Log file:

import { readFile } from 'node:fs/promises';

// The CLI sets MAKA_MCP_STDIO_EVENT_LOG to the path of the JSON-Lines file
const logPath = process.env.MAKA_MCP_STDIO_EVENT_LOG;
if (!logPath) {
  throw new Error('Runtime Event Log path not provided');
}

// Each line is a JSON object describing a single runtime event
const raw = await readFile(logPath, 'utf-8');
const events = raw
  .trim()
  .split('\n')
  .map(line => JSON.parse(line));

// Simple replay: print every model message in order
for (const ev of events) {
  if (ev.event === 'modelMessage') {
    console.log(`[${ev.timestamp}] ${ev.role}: ${ev.content}`);
  }
}

This pattern allows external tools to reconstruct the entire execution timeline without accessing internal runtime state, supporting use cases ranging from simple debugging to complex analytics pipelines.

Testing and Validation Strategies

The Maka test suite demonstrates robust validation patterns for the Runtime Event Log. In packages/cli/src/__tests__/tui-mcp-remote-integration.test.ts, the test harness configures the runtime to write events to a temporary file, then asserts on the log contents to verify correct system behavior.

For example, tests check for the presence of specific event types such as the exit event, ensuring that the recorded execution trace matches expected terminal states. This approach validates not only that the system behaves correctly in real time, but that the durable record accurately reflects the execution semantics for future replay or debugging sessions.

Summary

• The Runtime Event Log serves as the single source of truth for all agent execution facts in Apache Maka, including model messages, tool calls, and termination events.
• Projections allow components like SessionManager and RuntimeKernel to derive current state without maintaining separate mutable stores, ensuring consistency across the system.
• Events are stored in immutable, ordered fashion, enabling exact replay and reconstruction of agent interaction history.
• The log is accessed via the MAKA_MCP_STDIO_EVENT_LOG environment variable as a JSON Lines file, facilitating interoperability with external tools and audit systems.
• Architecture documentation in docs/architecture/runtime-core-architecture-draft.md and high-level references in ARCHITECTURE.md define the log’s central role in Maka’s reliability guarantees.

Frequently Asked Questions

What file format does the Runtime Event Log use?

The Runtime Event Log uses JSON Lines format (.jsonl), where each line contains a single JSON object representing one discrete event. This format allows for efficient appending during execution and streaming reads during replay or analysis, without requiring the entire file to be parsed as a single JSON array.

How do I specify the location of the Runtime Event Log?

Set the MAKA_MCP_STDIO_EVENT_LOG environment variable to the desired file path before launching the Maka CLI. The runtime host, implemented in packages/cli/src/runtime-host-cli.ts, reads this variable and directs all execution events to the specified location.

Can the Runtime Event Log be used to resume an interrupted agent session?

Yes. Because the log contains the complete ordered history of facts—including all model messages and tool results—a new session can reconstruct the previous state by reading the log and projecting it into memory. This capability supports checkpointing and fault recovery scenarios where processes must restart without losing execution context.

What types of events are recorded in the Runtime Event Log?

The log records facts representing the agent’s complete execution trace, including modelMessage events (LLM inputs and outputs), tool call requests and results, and termination events such as exit. These categories cover the full lifecycle of an agent run, ensuring no interaction is lost from the audit trail.

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