# What Information Does the RuntimeEvent Type Store in Apache Maka

> Discover what the RuntimeEvent type stores in Apache Maka. Learn about its immutable identifiers, timestamps, author metadata, and content payload for agent execution.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: deep-dive
- Published: 2026-09-05

---

**The `RuntimeEvent` interface stores immutable identifiers (UUIDs for invocation, run, session, and turn), timestamps, author metadata, and a polymorphic content payload that together describe every observable step of a Maka agent execution.**

The `RuntimeEvent` type is the canonical "fact" that records every observable step of a Maka agent execution. In the Apache Maka repository, this interface serves as the single source of truth for the **Runtime Event Log**, enabling deterministic replay and downstream projections. It captures both immutable identifiers and mutable payload data that describe who, what, when, and why an event occurred.

## Core Identity Fields

Every event carries a set of immutable identifiers that establish its unique position in the execution timeline.

- **`id`**: A unique UUID for the event itself, used for deduplication during reconnects and replays. Defined at line 600 in [`packages/core/src/runtime-event.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event.ts).
- **`invocationId`**: The durable "spine" identifier that groups all runs and turns belonging to a single provider invocation (line 603).
- **`runId`**: Identifies the concrete run, representing a single execution of the invocation (line 605).
- **`sessionId`**: The session that owns the event (line 607).
- **`turnId`**: Groups all events belonging to one agent turn, matching `StoredMessage.turnId` (line 609).
- **`ts`**: Unix-millisecond timestamp indicating when the event was created (line 611).
- **`branch`**: An optional logical branch or agent lane for future multi-agent trees (line 614).

## Execution Metadata

The interface captures contextual metadata about how the event was produced and its visibility characteristics.

- **`partial`**: A boolean indicating `true` for transient streaming chunks that will be superseded by a later non-partial event (line 616).
- **`role`**: The semantic role of the event, such as `assistant`, `user`, or `tool` (line 618).
- **`author`**: The concrete author that produced the event, such as `provider` or `code_mode` (line 619).
- **`origin`**: The execution surface that produced the fact (provider vs. code-mode), added after legacy ledgers (line 621).
- **`modelVisibility`**: The provider-history policy, either `visible` or `hidden`; omitted means visible for legacy compatibility (line 622).
- **`status`**: Lifecycle assertion such as `completed` or `failed`, present only on control-plane events (line 624).

## Content Payload and Side Effects

The variable data within an event is carried through three key fields:

- **`content`**: A discriminated union (`RuntimeEventContent`) whose shape varies by `kind` (line 627).
- **`actions`**: Structured side-effects including state deltas, artifact deltas, and permission requests (line 628).
- **`refs`**: References to related events, such as parent-child links (line 629).

## RuntimeEventContent Variants

The `content` property uses a discriminated union pattern where the `kind` field determines the payload interface. These definitions live in [`packages/core/src/runtime-event.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event.ts) alongside shape validators like `TEXT_CONTENT_SHAPE` and `FUNCTION_CALL_CONTENT_SHAPE`.

### Text and Thinking Content

- **`text`**: (`RuntimeEventTextContent`) Raw user or model text with optional steering flags, provider-specific metadata, and attachments.
- **`thinking`**: (`RuntimeEventThinkingContent`) Model's internal reasoning text with optional signed provenance.

### Function Call and Response Content

- **`function_call`**: (`RuntimeEventFunctionCallContent`) Tool-call identifier, name, arguments, and opaque provider options.
- **`function_response`**: (`RuntimeEventFunctionResponseContent`) Result of a tool call with optional error flags, including both provider-native and model-friendly projections.

### Control and Error Content

- **`error`**: (`RuntimeEventErrorContent`) Structured error information containing code, reason, message, and sanitized details.
- **`invocation_opened`**: (`RuntimeEventInvocationOpenedContent`) The first event of a run, containing route configuration, root authority, and source information.

## Architectural Role

The `RuntimeEvent` type serves as the cornerstone of Maka's durable execution model through three key architectural patterns.

**Single Source of Truth**: All observable facts—messages, tool calls, permission decisions, and state changes—flow through the **Runtime Event Log**. Downstream components including sessions, runs, UI layers, and model-replay projections consume this log rather than maintaining parallel state.

**Deterministic Replay**: Because every event carries a unique identifier and precise timestamp, the system can reconstruct any past execution by replaying the ordered events, excluding transient `partial` entries.

**Extensibility**: New event kinds or actions can be added by extending the `RuntimeEventContent` union and updating the corresponding shape validators. The envelope-key/value domain functions (`runtimeEventEnvelopeKeys`, `runtimeEventEnvelopeValueDomains`) guarantee schema conformance without breaking existing consumers.

## Practical Code Examples

### Creating a Text Event

The following example demonstrates creating a basic text event with provider metadata:

```typescript
import { RuntimeEvent, RuntimeEventContent, RuntimeEventRole, RuntimeEventAuthor } from '@maka/core';

const textContent: RuntimeEventContent = {
  kind: 'text',
  text: 'Hello, world!',
  providerOptions: { citation: 'https://example.com' },
};

const event: RuntimeEvent = {
  id: crypto.randomUUID(),
  invocationId: 'inv-123',
  runId: 'run-456',
  sessionId: 'sess-789',
  turnId: 'turn-001',
  ts: Date.now(),
  partial: false,
  role: 'assistant' as RuntimeEventRole,
  author: 'provider' as RuntimeEventAuthor,
  content: textContent,
};

```

### Recording Tool Calls and Responses

Tool execution produces paired events for the call and response:

```typescript
// Tool call
const callEvent: RuntimeEvent = {
  id: crypto.randomUUID(),
  invocationId: 'inv-123',
  runId: 'run-456',
  sessionId: 'sess-789',
  turnId: 'turn-002',
  ts: Date.now(),
  partial: false,
  role: 'assistant',
  author: 'provider',
  content: {
    kind: 'function_call',
    id: 'call-001',
    name: 'search',
    args: { query: 'Maka runtime' },
    providerOptions: { timeoutMs: 5000 },
  },
};

// Tool response
const responseEvent: RuntimeEvent = {
  id: crypto.randomUUID(),
  invocationId: 'inv-123',
  runId: 'run-456',
  sessionId: 'sess-789',
  turnId: 'turn-002',
  ts: Date.now(),
  partial: false,
  role: 'assistant',
  author: 'provider',
  content: {
    kind: 'function_response',
    id: 'call-001',
    name: 'search',
    result: { links: ['https://github.com/apache/maka'] },
    modelProjection: { text: 'Found 1 result.' },
  },
};

```

### Emitting Invocation Opened Events

The first event of any run uses the `invocation_opened` kind to establish execution context:

```typescript
const openedEvent: RuntimeEvent = {
  id: crypto.randomUUID(),
  invocationId: 'inv-123',
  runId: 'run-456',
  sessionId: 'sess-789',
  turnId: 'turn-000',
  ts: Date.now(),
  partial: false,
  role: 'assistant',
  author: 'provider',
  content: {
    kind: 'invocation_opened',
    protocol: 'invocation_opened_v1',
    route: {
      provenance: 'runtime',
      backendKind: 'openai',
      llmConnectionId: 'conn-1',
      llmConnectionSlug: 'openai-gpt4',
      modelId: 'gpt-4',
    },
    configuration: {
      cwd: '/app',
      permissionMode: 'restricted',
      collaborationMode: 'single',
      orchestrationMode: 'none',
      orchestrationSource: 'manual',
      toolMode: 'auto',
    },
    root: { kind: 'user' },
    source: { kind: 'fresh' },
  },
};

```

## Summary

- The `RuntimeEvent` interface in [`packages/core/src/runtime-event.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event.ts) defines the canonical schema for all observable execution facts in Apache Maka.
- It stores immutable identifiers (`id`, `invocationId`, `runId`, `sessionId`, `turnId`) and timestamps (`ts`) to establish event uniqueness and ordering.
- Metadata fields (`partial`, `role`, `author`, `origin`, `modelVisibility`) describe the event's production context and visibility policies.
- The polymorphic `content` field uses a discriminated union (`RuntimeEventContent`) to carry type-safe payloads for text, thinking, function calls, responses, errors, and invocation initialization.
- Side effects are captured in the `actions` array, while `refs` maintains relationships between events.
- Schema validation through `runtimeEventEnvelopeKeys` and shape constants ensures type safety and prevents drift when extending the event model.

## Frequently Asked Questions

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

The **`invocationId`** serves as the durable "spine" identifier that groups all runs and turns belonging to a single provider invocation, persisting across re-invocations. The **`runId`** identifies a specific concrete execution of that invocation. A single invocation may generate multiple runs during retries or reconnections, but all will share the same `invocationId` while maintaining unique `runId` values.

### How does the partial field affect event processing?

When **`partial`** is set to `true`, the event represents a transient streaming chunk that will be superseded by a later non-partial event containing the complete data. Downstream consumers should treat partial events as temporary deltas rather than durable facts, and the system excludes these transient entries when reconstructing executions for deterministic replay.

### What are the valid values for the role and author fields?

The **`role`** field accepts semantic identifiers such as `assistant`, `user`, or `tool`, defining the event's position in the conversation flow. The **`author`** field specifies the concrete execution surface that produced the event, such as `provider` for LLM-generated content or `code_mode` for programmatically generated events. Additional values may be defined by extending the `RuntimeEventRole` and `RuntimeEventAuthor` types in the core package.

### Where is the RuntimeEvent interface defined in the Apache Maka codebase?

The **`RuntimeEvent`** interface and its associated content unions are defined in [`packages/core/src/runtime-event.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event.ts) at lines 600-629. Related mapping logic resides in [`packages/runtime/src/session-event-runtime-mapper.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-event-runtime-mapper.ts), while persistence implementations are found in [`packages/storage/src/runtime-event-persistence.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/runtime-event-persistence.ts). Read-model projections that consume these events are implemented in [`packages/runtime/src/runtime-event-read-model.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-event-read-model.ts).