What Is a RuntimeEvent in Apache Maka? Complete Guide to the Atomic Event Log

A RuntimeEvent is the atomic, append-only record that captures every interaction during an agent's execution in Apache Maka, serving as the immutable source of truth from which all UI, storage, and replay systems derive their projections.

Apache Maka is an open-source agent runtime that treats execution history as a first-class concern. The RuntimeEvent interface defines the canonical contract for this history, ensuring that every model turn, tool call, permission prompt, and termination is recorded in a single, append-only log. This article explores the RuntimeEvent structure, validation logic, and architectural role based on the current Apache Maka source code.

Core Definition and Architecture

A RuntimeEvent represents the fundamental unit of execution history in the Maka runtime. Unlike derived UI events or telemetry records, a RuntimeEvent is the primary, immutable fact recorded for every interaction that occurs while an agent (model) is executing.

According to the implementation in packages/core/src/runtime-event.ts, these events form an append-only log that captures the complete lifecycle of a single invocation—from the moment the invocation opens, through every model turn and tool dispatch, to the terminal event that closes the run. Because the log is never altered, crash recovery, UI reconstruction, and model replay can be derived reliably from this single source of truth.

The Maka website copy succinctly describes this architecture: "Every message, tool call, permission decision and termination is an append-only RuntimeEvent. The UI, the next prompt and crash recovery are projections of that log, never the only copy." (see website/src/copy/zh-CN.ts).

The RuntimeEvent Data Structure

The RuntimeEvent interface in packages/core/src/runtime-event.ts defines a strict envelope containing identifying metadata, lifecycle status, content payload, and diagnostic references.

Core Identification Fields

• id: A unique UUID for deduplication during reconnect or replay scenarios.
• invocationId: Groups all events belonging to the same logical user request.
• runId: Identifies the concrete execution instance of that request, allowing multiple attempts of the same invocation to be distinguished.
• sessionId / turnId: Bridge the runtime to the UI/session layer, where a turn corresponds to a single user-model exchange.

Execution Context

• ts: Unix-millisecond timestamp recording when the event occurred.
• role: Indicates who produced the event—values include user, model, tool, or system.
• author: Identifies which subsystem authored the event, such as agent, tool, or host.
• status: Tracks lifecycle state with values like streaming, completed, failed, aborted, or cancelled. Terminal statuses mark the final event of a run.

Content and Actions

• content: The event payload, which varies by type (text messages, thinking annotations, function calls/responses, errors, or invocation metadata).
• actions: Side-effect intents including token-usage accounting, permission decisions, tool-dispatch facts, and workspace mutations.
• refs: Diagnostic links to other projections, such as trace rows, stored messages, or specific tool call IDs.

Validation and Type Safety

Maka enforces strict shape compliance through the decodeRuntimeEvent function exported from packages/core/src/runtime-event.ts. This validator ensures that every event conforms to the canonical contract before processing.

import {
  type RuntimeEvent,
  decodeRuntimeEvent,
} from '@maka/core/runtime-event';

// Validate an untrusted payload
const json = JSON.stringify(potentialEvent);
const parsed = JSON.parse(json);
const verified: RuntimeEvent = decodeRuntimeEvent(parsed); // throws if schema mismatch
console.log('Verified event role:', verified.role);

This validation layer guarantees that downstream consumers—whether the SQLite storage layer, replay engine, or telemetry systems—can safely assume structural correctness.

RuntimeEvent vs. Projections

It is critical to understand what a RuntimeEvent is not. The following components are projections derived from the RuntimeEvent log, not the source of truth itself:

• UI Events: Transient state for interface rendering.
• Trace Rows: Aggregated diagnostic views for debugging.
• Telemetry Records: Filtered, sampled, or transformed data for analytics.

Because these are projections, they can be reconstructed, regenerated, or modified without losing the canonical execution history. The append-only nature of the RuntimeEvent log ensures that the true record remains immutable and audit-safe.

Practical Implementation Examples

Basic Text Message Event

The following example constructs a simple text message event with complete metadata:

import {
  type RuntimeEvent,
  type RuntimeEventRole,
  type RuntimeEventAuthor,
} from '@maka/core/runtime-event';

const textEvent: RuntimeEvent = {
  id: 'e9c1f33a-1234-5678-abcd-9876fedcba00',
  invocationId: 'inv-01',
  runId: 'run-01',
  sessionId: 'sess-42',
  turnId: 'turn-7',
  ts: Date.now(),
  partial: false,
  role: 'model' as RuntimeEventRole,
  author: 'agent' as RuntimeEventAuthor,
  content: {
    kind: 'text',
    text: 'Hello, world!',
  },
};

Tool Dispatch Event with Actions

Tool calls include action metadata for coordination between the host and runtime:

import { type RuntimeEventToolDispatch } from '@maka/core/runtime-event';

const toolDispatch: RuntimeEvent = {
  id: 'dispatch-01',
  invocationId: 'inv-01',
  runId: 'run-01',
  sessionId: 'sess-42',
  turnId: 'turn-7',
  ts: Date.now(),
  partial: false,
  role: 'tool',
  author: 'tool',
  content: {
    kind: 'function_call',
    id: 'call-123',
    name: 'search',
    args: { query: 'Maka runtime' },
  },
  actions: {
    toolDispatch: {
      protocol: 't1_after_preflight_v1',
      operationId: 'op-01',
      providerToolCallId: 'prov-abc',
      toolName: 'search',
      canonicalArgsHash: 'sha256:xxx',
      recoveryMode: 'replay_safe',
    } as RuntimeEventToolDispatch,
  },
};

Key Source Files in Apache Maka

Understanding the RuntimeEvent requires familiarity with these specific source locations:

• packages/core/src/runtime-event.ts: Defines the TypeScript interface, role/author enums, content unions, actions, refs, and the decodeRuntimeEvent validation logic.
• packages/core/src/canonical-runtime-event.ts: Provides encodeCanonicalRuntimeEvent and canonicalizeRuntimeEventForStorage for normalizing events before persistence.
• packages/storage/src/sqlite-runtime-store.ts: Implements durable SQLite storage, including import/export and event scanning capabilities.
• packages/runtime/src/runtime-event-read-model.ts: Projects Runtime Events into model-history for replay and reasoning workflows.
• packages/runtime-host/src/server/workhub-coordination.ts: Demonstrates how actions extracted from Runtime Events drive coordination between the host, model, and tool subsystems.

Summary

• RuntimeEvent is the atomic, append-only record in Apache Maka that captures every interaction during agent execution.
• Each event contains identification fields (id, invocationId, runId), context (role, author, status), and payload (content, actions).
• The decodeRuntimeEvent function in packages/core/src/runtime-event.ts enforces strict schema validation.
• UI events, trace rows, and telemetry records are projections—derived views of the immutable RuntimeEvent log.
• This architecture enables reliable crash recovery, complete audit trails, and deterministic replay across the Maka platform.

Frequently Asked Questions

What is the difference between invocationId and runId in a RuntimeEvent?

The invocationId groups all events belonging to the same logical user request, while the runId identifies a specific execution instance of that request. This distinction allows Maka to handle retries or replays of the same invocation, with each attempt receiving a unique runId while maintaining the stable invocationId for logical grouping.

How does Apache Maka ensure RuntimeEvent integrity?

Maka enforces integrity through the decodeRuntimeEvent validator in packages/core/src/runtime-event.ts, which throws on schema mismatch. Additionally, the storage layer in packages/storage/src/sqlite-runtime-store.ts treats the event log as append-only, preventing mutation of historical records and ensuring that projections can always be reconstructed from the canonical source.

Can RuntimeEvents represent streaming or partial content?

Yes. The partial boolean field indicates whether an event represents an incremental chunk of content (such as streaming model output) or a final, complete record. The status field further distinguishes between streaming and terminal states like completed or failed, allowing consumers to handle progressive updates correctly.

Where are RuntimeEvents actually stored in a Maka deployment?

The canonical storage implementation is in packages/storage/src/sqlite-runtime-store.ts, which provides durable persistence with import/export capabilities. However, the RuntimeEvent itself is an interface, not a storage format—the same events can be serialized for network transmission, logged to telemetry systems, or held transiently in memory during execution, always maintaining the same schema contract defined in the core package.

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