What Information Does the RuntimeEvent Type Store in Apache Maka

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.
• 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 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:

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:

// 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:

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 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 at lines 600-629. Related mapping logic resides in packages/runtime/src/session-event-runtime-mapper.ts, while persistence implementations are found in 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.

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