What Is the Runtime Event Log in Maka? Architecture, Persistence, and Reproducibility Explained

The Runtime Event Log in Maka is the single source of truth for everything an agent does during execution, persisting ordered, immutable facts that enable replay, checkpointing, and exact reproducibility.

The Runtime Event Log sits at the heart of Maka's architecture, solving a fundamental problem in agent-based systems: how to maintain a reliable, queryable history of model interactions without scattering state across multiple components. This article explains what the Runtime Event Log is, why it's designed as an append-only log of facts, and how developers can leverage it for debugging, testing, and building derived views.

What the Runtime Event Log Stores

The Runtime Event Log captures four categories of facts generated during agent execution:

• Model messages — inputs and outputs exchanged with the language model
• Tool calls — requests made to external tools and services
• Tool results — responses returned from those tools
• Termination events — signals that the agent run completed or exited

These facts are written in JSON Lines format (.jsonl), with one JSON object per line representing a single event. This format balances human readability with efficient streaming and append operations.

According to the architecture documentation in docs/architecture/runtime-core-architecture-draft.md, the Runtime Event Log "is the canonical source for model messages, tool calls, tool results, and termination facts"【grep†/__modal/volumes/vo-cSqLfqnnIwYXEonuEJnnZa/repos/github.com/apache/maka/main/docs/architecture/runtime-core-architecture-draft.md†L35-L67】.

Why the Log Is Central to Maka's Architecture

Maka's design principle is simple: system state at any point in time is a projection over the ordered log. Rather than maintaining mutable state in memory, core components derive their view of reality by reading the Runtime Event Log.

This architectural decision provides three critical benefits:

1. Durability — Process restarts, session reconnections, and even cross-machine handoffs preserve complete execution history
2. Reproducibility — Any agent run can be replayed exactly by reprocessing the same ordered events
3. Flexibility — Multiple projections (UI views, checkpoints, analytics) can coexist without synchronization overhead

The SessionManager, RuntimeKernel, AgentRun, and UI components all consume projections of the Runtime Event Log rather than maintaining private state【grep†/__modal/volumes/vo-cSqLfqnnIwYXEonuEJnnZa/repos/github.com/apache/maka/main/docs/architecture/runtime-core-architecture-draft.md†L419-L428】.

How to Access and Parse the Runtime Event Log

The Maka CLI exposes the Runtime Event Log through the MAKA_MCP_STDIO_EVENT_LOG environment variable, which specifies the path where events are written.

Reading the Log in Node.js

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 demonstrates how the Runtime Event Log enables time-travel debugging — you can reconstruct exactly what the model saw and produced at any moment.

Log File Format and Structure

Events in the Runtime Event Log share a common envelope structure:

{
  "event": "modelMessage",
  "timestamp": "2024-01-15T09:23:47.123Z",
  "runId": "run-abc123",
  "role": "assistant",
  "content": "I'll help you analyze that data..."
}

The event field discriminates between fact types, while runId and timestamp provide ordering and grouping context.

Testing and Verification with the Runtime Event Log

Maka's test suite uses the Runtime Event Log for end-to-end assertions. The integration test in packages/cli/src/__tests__/tui-mcp-remote-integration.test.ts demonstrates this pattern【grep†/__modal/volumes/vo-cSqLfqnnIwYXEonuEJnnZa/repos/github.com/apache/maka/main/packages/cli/src/tests/tui-mcp-remote-integration.test.ts†L61-L70】:

// Test setup: configure log output path
const logPath = join(tmpDir, 'stdio-events.jsonl');
const env = {
  ...process.env,
  MAKA_MCP_STDIO_EVENT_LOG: logPath,
};

Later, the test verifies execution by asserting on specific events in the log【grep†/__modal/volumes/vo-cSqLfqnnIwYXEonuEJnnZa/repos/github.com/apache/maka/main/packages/cli/src/tests/tui-mcp-remote-integration.test.ts†L280-L285】:

// Verify the run produced an expected termination event
const events = await readLogFile(logPath);
const exitEvent = events.find(e => e.event === 'exit');
expect(exitEvent).toBeDefined();
expect(exitEvent.code).toBe(0);

This approach eliminates flaky tests that depend on timing or internal state — assertions run against the durable, observable Runtime Event Log.

Key Source Files for the Runtime Event Log

File	Purpose
docs/architecture/runtime-core-architecture-draft.md	Primary architectural documentation defining the Runtime Event Log's role as canonical source
docs/architecture/runtime-core-architecture-draft.zh-CN.md	Chinese translation of architecture docs
ARCHITECTURE.md	High-level system diagram including the Runtime Event Log
packages/cli/src/runtime-host-cli.ts	CLI entry point wiring MAKA_MCP_STDIO_EVENT_LOG to the runtime host
packages/cli/src/__tests__/tui-mcp-remote-integration.test.ts	Integration tests demonstrating log creation and verification

Summary

• The Runtime Event Log is Maka's single source of truth, persisting immutable, ordered facts about model messages, tool calls, tool results, and termination events.
• All components read projections of this log rather than maintaining private state, enabling exact reproducibility and flexible derived views.
• The log uses JSON Lines format written to a path specified by MAKA_MCP_STDIO_EVENT_LOG, making it accessible for debugging, testing, and custom tooling.
• Architecture documentation in docs/architecture/runtime-core-architecture-draft.md establishes that system state is always a projection over the ordered log, not independent mutable state.

Frequently Asked Questions

What format does the Maka Runtime Event Log use?

The Runtime Event Log uses JSON Lines (.jsonl) format, with one JSON object per line. Each line represents a single runtime event with fields for event type, timestamp, run identifier, and event-specific payload. This format supports efficient append operations and streaming reads.

How do I enable the Runtime Event Log in Maka?

Set the MAKA_MCP_STDIO_EVENT_LOG environment variable to a file path before running the Maka CLI. The runtime-host-cli.ts entry point wires this variable to the runtime host, causing all events to be written to that path. Integration tests in tui-mcp-remote-integration.test.ts demonstrate this pattern.

Can I replay an agent run from the Runtime Event Log?

Yes. Because the log contains the complete ordered history of facts, you can reconstruct the exact execution sequence by reprocessing events. The code example above shows parsing model messages; extending this to replay tool calls and responses yields bit-for-bit reproducible behavior.

Why does Maka use an append-only log instead of a database?

The append-only log design guarantees immutability and total ordering — critical properties for debugging non-deterministic agent behavior. Projections can be rebuilt from any point in the log without complex migration or synchronization logic. This approach trades query flexibility for simplicity, durability, and verifiability.

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