What Information Does a RuntimeEvent Preserve in Apache Maka

A RuntimeEvent in Apache Maka preserves immutable identity metadata, classification flags, payload content, and extended provenance links to create a complete semantic record of every agent execution step.

The RuntimeEvent serves as the single, canonical representation of everything that happens during agent execution in the apache/maka repository. This immutable data structure captures the complete semantic fact about any turn, model message, tool call, permission decision, or lifecycle milestone. Understanding what information a RuntimeEvent preserves is essential for building replayable, auditable agent systems.

Four Categories of Preserved Information

Identity and Timing Metadata

Every RuntimeEvent captures immutable identifiers that tie the fact to a specific request, run, session, and turn. According to packages/core/src/runtime-event.ts, these include id (UUID for deduplication on reconnect/replay), invocationId (groups every run/turn of one request), runId (durable operational identity), sessionId, turnId, and ts (Unix-ms timestamp). The partial boolean flag indicates whether the event represents a transient streaming chunk or a completed fact.

Classification and Role Metadata

The event records how the fact should be interpreted by the model and runtime through classification fields. The role field (lines 72-78) accepts values like 'user', 'model', 'tool', or 'system', while author (lines 92-98) identifies who produced the event ('user', 'host', 'agent', 'tool', or 'system'). Additional classification includes origin ('provider' vs 'code_mode'), modelVisibility ('visible' vs 'hidden'), and status ('streaming', 'completed', 'failed', 'aborted', or 'cancelled').

Payload Content

The actual semantic content resides in the content field, which can represent text, thinking tokens, function calls/responses, or errors. The actions field captures ancillary operations like permission decisions, token usage, or tool dispatch protocols. References to related events or parent operations are stored in refs, enabling provenance tracking and compensation workflows.

Extended Metadata and Provenance

Optional fields provide deep operational context for complex multi-agent scenarios. These include branch (for future multi-agent lanes), stepId, operationId, parentToolCallId, parentOperationId, and source attribution fields (sourceMessageDigest, sourceInvocationId, sourceRunId, sourceTurnId). The providerRequestTraceId and artifactId fields link events to external telemetry and storage systems.

The RuntimeEvent Interface Structure

The canonical interface in packages/core/src/runtime-event.ts defines the exact shape of preserved data:

export interface RuntimeEvent {
  id: string;               // UUID – deduplication on reconnect/replay
  invocationId: string;     // Groups every run/turn of one request
  runId: string;            // Durable operational run identity
  sessionId: string;
  turnId: string;
  ts: number;               // Unix‑ms timestamp
  branch?: string;          // Future multi‑agent lane
  partial: boolean;         // Transient streaming chunk?
  role: RuntimeEventRole;   // 'user' | 'model' | 'tool' | 'system'
  author: RuntimeEventAuthor; // 'user' | 'host' | 'agent' | 'tool' | 'system'
  origin?: RuntimeEventOrigin;        // 'provider' | 'code_mode'
  modelVisibility?: RuntimeEventModelVisibility; // 'visible' | 'hidden'
  status?: RuntimeEventStatus;        // 'streaming' | 'completed' | 'failed' | 'aborted' | 'cancelled'
  content?: RuntimeEventContent;      // Text, thinking, function call/response, error …
  actions?: RuntimeEventActions;      // Permission, token usage, tool dispatch, etc.
  refs?: RuntimeEventRefs;            // Links to related events (e.g., parentOperationId)
}

Why Immutability Matters for RuntimeEvents

Replayability and Auditing

By storing every fact with durable IDs and timestamps, the runtime can reconstruct the exact sequence of actions for debugging, auditing, or re-execution. As noted in the architecture documentation, the Runtime Event Log serves as the authoritative source of truth for every agent interaction.

Projection-Friendly Architecture

Higher-level views—including session UI components, AgentRun ledgers, and LLM context windows—are projections of the event log. They consume RuntimeEvents without modifying the original facts, ensuring consistent state reconstruction across different consumers.

Extensibility Without Breaking Changes

New action types can be added through the centrally defined envelope keys (runtimeEventEnvelopeKeys at lines 46-50) without breaking existing consumers. This design allows the system to evolve while maintaining backward compatibility.

Practical Implementation Examples

Creating a Simple Text Message Event

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

const textEvent: RuntimeEvent = {
  id: crypto.randomUUID(),
  invocationId: 'inv‑123',
  runId: 'run‑456',
  sessionId: 'sess‑789',
  turnId: 'turn‑001',
  ts: Date.now(),
  partial: false,
  role: 'user' as RuntimeEventRole,
  author: 'user' as RuntimeEventAuthor,
  content: {
    kind: 'text',
    text: 'Hello, world!',
  },
};

Recording a Tool-Call Event with Parent Operation

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

const toolCall: RuntimeEvent = {
  id: crypto.randomUUID(),
  invocationId: 'inv‑123',
  runId: 'run‑456',
  sessionId: 'sess‑789',
  turnId: 'turn‑001',
  ts: Date.now(),
  partial: false,
  role: 'tool',
  author: 'tool',
  origin: 'provider',
  content: {
    kind: 'function_call',
    id: 'call‑001',
    name: 'search',
    args: { query: 'Maka runtime' },
    providerExecuted: true,
  },
  actions: {
    toolDispatch: {
      protocol: 'json',
      operationId: 'op‑001',
      providerToolCallId: 'ptc‑777',
      toolName: 'search',
      canonicalArgsHash: 'sha256:…',
      recoveryMode: 'replay_safe',
    } as RuntimeEventToolDispatch,
  },
};

Validating Event Envelope Structure

import {
  runtimeEventEnvelopeKeys,
  runtimeEventEnvelopeValueDomains,
} from '@maka/core/runtime-event';

function isValidRuntimeEvent(ev: unknown): boolean {
  const keys = runtimeEventEnvelopeKeys();
  if (typeof ev !== 'object' || ev === null) return false;
  for (const key of keys) {
    if (!(key in ev)) return false;
  }
  return true;
}

Key Source Files in apache/maka

• packages/core/src/runtime-event.ts – Defines the canonical RuntimeEvent contract, including roles, authors, statuses, and envelope validation helpers.
• packages/runtime/src/session-event-runtime-mapper.ts – Translates backend SessionEvent objects into canonical RuntimeEvent instances.
• packages/runtime/src/runtime-event-read-model.ts – Implements read-model projections that consume RuntimeEvent objects for UI, replay, and analytics.
• docs/architecture/runtime-core-architecture-draft.md – High-level description of the Runtime Event Log and its role as the source of truth.

Summary

• RuntimeEvent preserves four distinct categories: identity/timing, classification, payload content, and extended provenance metadata.
• The structure is deliberately immutable; once persisted, events become part of the authoritative Runtime Event Log.
• Classification fields (role, author, origin, status) determine how the runtime and model interpret the fact.
• Extended metadata fields enable complex multi-agent scenarios, tool-call chaining, and cross-session attribution.
• All UI events, stored messages, and telemetry are derived projections of the canonical RuntimeEvent stream.

Frequently Asked Questions

What is the difference between role and author in a RuntimeEvent?

The role field (lines 72-78) indicates the semantic function of the content (user, model, tool, or system), while author (lines 92-98) identifies the specific producer of the event (user, host, agent, tool, or system). This distinction allows the system to distinguish between a tool result authored by a host versus content presented with a tool role.

How does the partial flag affect RuntimeEvent processing?

The partial boolean indicates whether the event represents a transient streaming chunk or a completed, durable fact. Partial events are used for real-time UI updates during streaming responses, while partial: false marks the final canonical state suitable for persistence and replay.

Can RuntimeEvents be modified after they are created?

No. RuntimeEvents are deliberately immutable by design. Once created and persisted to the Runtime Event Log, they become part of the permanent source of truth. Any corrections or updates must be recorded as new events rather than mutations of existing ones.

What is the relationship between RuntimeEvent and the Runtime Event Log?

The Runtime Event Log is the durable, append-only storage of RuntimeEvent instances. It serves as the authoritative source of truth for every agent interaction, while RuntimeEvent is the data structure that defines what information is preserved in each entry of that log. All higher-level views (UI, analytics, LLM context) are projections derived from this log.

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