What Types of Facts Are Recorded in the Apache Maka Runtime Event Log?

The Apache Maka Runtime Event Log records exactly six semantic fact types: Model messages, Tool calls, Tool results, Permission facts, Usage facts, and Terminal facts, which together form the immutable audit trail of every agent interaction.

The apache/maka project relies on a single, ordered Runtime Event Log as the canonical source of truth for everything an agent does. Every interaction the system produces is turned into a semantic fact and appended to this persistent log, enabling the runtime to reconstruct session state after crashes, power UI projections, and maintain complete audit trails. Understanding what types of facts are recorded in the runtime event log is essential for developers building debugging tools, compliance dashboards, or custom runtime hosts.

The Six Core Fact Types in the Runtime Event Log

According to the architecture documentation in docs/architecture/ARCHITECTURE.md and docs/architecture/runtime-core-architecture-draft.md, the log appends six distinct categories of facts that capture all observable agent state.

Model Messages

Model messages record the raw text or structured payload sent by the LLM model to the agent. These entries represent the canonical source for all model outputs and are typically the first facts generated at the beginning of an agent turn. In the source code, these are committed to the log during the message processing phase of an agent run.

Tool Calls

Tool calls capture requests generated by the agent to invoke external capabilities. As implemented in packages/runtime/src/ToolRuntime.ts, these facts document when the agent decides to execute tools like Read, Write, Bash, Glob, or Grep, including the specific parameters passed to each tool.

Tool Results

Tool results store the output returned from a tool execution, whether successful or erroneous. These facts are appended immediately after the corresponding tool call completes, creating a paired record of both the request and response in the ordered log.

Permission Facts

Permission facts record permission checks that guarded a tool call or other privileged operation. These entries serve as the audit trail for security-sensitive actions, documenting when the system verified user or policy authorization before allowing a privileged operation to proceed.

Usage Facts

Usage facts capture operational metrics such as token usage, compute time, and cost data emitted after a model or tool step. These facts enable consumption tracking and performance analysis without requiring external telemetry systems.

Terminal Facts

Terminal facts mark the final termination event of a turn, indicating whether the session ended in success, failure, abort, or user-requested stop. These entries signal to downstream consumers that no further facts will be appended for the current turn.

How the Runtime Event Log Enables System Capabilities

The six fact categories enable three critical system behaviors defined in the architecture documents:

• Replay & recovery – Because the log is ordered and immutable, the system can replay events after a crash or restart to reconstruct the exact session state from packages/runtime/src/AgentRun.ts.
• Projections – UI components, session managers, and graph operators consume the ordered log from packages/runtime-host/src/RuntimeHost.ts to project the current view of the workspace without storing duplicate state.
• Auditing & privacy – Every decision, from model output to permission grants, exists as an immutable fact, creating a complete compliance trail for security reviews.

Querying the Runtime Event Log via the TypeScript API

Developers can access these facts programmatically through the @maka/runtime-host package. The API surface is used by the Desktop, CLI, and evaluation runners to build their projections.

import { RuntimeHost } from '@maka/runtime-host';

// Obtain the singleton host (already created by the CLI/Desktop entry point)
const host = RuntimeHost.getInstance();

// Retrieve the full event log for the current session
const events = await host.getEventLog();   // → Event[]

// Filter specific fact types
const modelMessages = events.filter(e => e.type === 'modelMessage');
const toolCalls    = events.filter(e => e.type === 'toolCall');
const toolResults  = events.filter(e => e.type === 'toolResult');
const permissions  = events.filter(e => e.type === 'permission');
const usageFacts   = events.filter(e => e.type === 'usage');
const terminal     = events.find(e => e.type === 'terminal');

// Example: pretty-print the sequence of model messages
for (const m of modelMessages) {
  console.log(`[model] ${m.payload.text}`);
}

The getEventLog() method defined in packages/runtime-host/src/RuntimeHost.ts returns the complete ordered array of events, allowing you to filter by the string literals 'modelMessage', 'toolCall', 'toolResult', 'permission', 'usage', and 'terminal' to isolate specific fact types.

Summary

• The Runtime Event Log in apache/maka stores six immutable fact types: Model messages, Tool calls, Tool results, Permission facts, Usage facts, and Terminal facts.
• These facts are appended by AgentRun.ts and ToolRuntime.ts to create a complete audit trail of every agent decision and action.
• The log enables replay & recovery, real-time projections, and compliance auditing by serving as the single source of truth.
• Developers query facts using RuntimeHost.getInstance().getEventLog() and filter by type strings defined in the runtime core architecture.

Frequently Asked Questions

What is the primary purpose of the Runtime Event Log in Apache Maka?

The Runtime Event Log serves as the canonical source of truth for the entire agent runtime. It stores every interaction as an immutable, ordered fact, allowing the system to reconstruct session state after crashes, power UI components with live data projections, and maintain complete audit trails for security and debugging purposes.

How does the Runtime Event Log handle tool execution tracking?

Tool execution generates paired facts: first a Tool call fact (generated by ToolRuntime.ts) documenting the request and parameters, followed immediately by a Tool result fact capturing the output or error. This pairing creates a complete execution record without gaps, enabling precise replay and debugging of agent tool usage.

Can I query historical events from a previous session?

Yes, the RuntimeHost API exposes getEventLog(), which returns all events for the current session. For persistent historical queries, the log facts are durably stored by the runtime host implementation, allowing external tools to load and filter previous sessions by fact type, timestamp, or content for analysis or compliance reporting.

Where is the Runtime Event Log implementation located in the source code?

The core logic resides in packages/runtime/src/AgentRun.ts (which commits facts during agent turns) and packages/runtime/src/ToolRuntime.ts (which handles tool-specific facts). The host API that exposes getEventLog() is implemented in packages/runtime-host/src/RuntimeHost.ts, while the fact type definitions and architectural specifications are documented in docs/architecture/ARCHITECTURE.md and docs/architecture/runtime-core-architecture-draft.md.

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