Maka AgentRunEvent Types: Complete Guide to Execution Lifecycle Events

Maka defines eight core AgentRunEvent types—run-start, run-end, tool-invocation, tool-result, model-output, message, error, and runtime-event—that capture every meaningful state change during an agent's execution.

The Apache Maka framework tracks agent execution through a comprehensive event system centered on the AgentRunEventType enum. These events serve as the backbone for persistence, replay, and inspection across the runtime-host and storage layers. Understanding these types is essential for debugging agent behavior and building custom tooling integrations.

Core AgentRunEvent Types

The AgentRunEventType enum, defined in packages/core/src/agent-run.ts, categorizes all execution events into four functional groups. Each event carries a discriminant type field enabling type-safe handling throughout the codebase.

Lifecycle Events

run-start marks the creation of a new RuntimeInvocationRecord at the beginning of execution. Emitted via emitRunStart(), this event carries the runId, sessionId, and startTimestamp.

run-end signals completion, whether successful or aborted. Emitted through emitRunEnd(), its payload includes endTimestamp, final status, and optional error details.

Interaction Events

message handles generic chat events between user and agent. The emitMessage() function in packages/runtime/src/agent-run.ts dispatches these with role, content, and timestamp fields.

model-output captures every LLM response destined for the user. Emitted via emitModelOutput(), this includes content, role, model identifier, and tokenUsage statistics.

Tooling Events

tool-invocation fires when the agent calls any tool (browser actions, file operations, or custom integrations). The emitToolInvocation() method records toolName, args, and a unique invocationId.

tool-result arrives when the invoked tool returns data. emitToolResult() pairs with the invocation via invocationId, carrying the result, success boolean, and any error information.

Diagnostic Events

error captures uncaught exceptions or explicit aborts. emitError() generates payloads containing errorMessage, stack traces, and the associated runId.

runtime-event provides low-level internal telemetry for state transitions and context snapshots. Defined in packages/core/src/runtime-event.ts, these events power diagnostics and projection systems with flexible { type, data } structures.

Event Payload Structure

Each event adheres to a consistent schema defined in packages/core/src/events.ts. The type system guarantees that every AgentRunEvent carries:

• A type: AgentRunEventType discriminant
• A data object specific to the event category
• Timestamp and correlation identifiers

The core package provides type guards isEmittedAgentRunEventType() and isProjectedAgentRunEvent() for runtime validation of event structures.

Emitting Events in Practice

Runtime implementations in packages/runtime/src/agent-run.ts expose helper functions for event generation:

// Initialize a new agent run
import { emitRunStart } from '@maka/core/agent-run';

await emitRunStart({
  runId: 'r-123',
  sessionId: 's-456',
  timestamp: Date.now(),
});

Tool interactions follow a request-response pattern:

import { emitToolInvocation, emitToolResult } from '@maka/core/agent-run';

// Record tool call
await emitToolInvocation({
  runId: 'r-123',
  sessionId: 's-456',
  toolName: 'web-search',
  args: { query: 'Maka architecture' },
  invocationId: 'inv-789',
});

// Record completion
await emitToolResult({
  invocationId: 'inv-789',
  result: { urls: ['https://maka.apache.org'] },
  success: true,
});

Error handling requires explicit event emission:

import { emitError } from '@maka/core/agent-run';

await emitError({
  runId: 'r-123',
  errorMessage: 'Tool timeout exceeded',
  stack: error.stack,
});

Storage and Persistence

The storage layer in packages/storage/src/agent-run-store.ts persists these events to SQLite. The AgentRunStore class provides insertAgentRunEvent() for writes and readEventsForRecovery() for replay scenarios. All events maintain strict ordering through monotonic timestamps, enabling deterministic reconstruction of execution history.

Summary

• Eight core types cover the complete agent lifecycle: run-start, run-end, tool-invocation, tool-result, model-output, message, error, and runtime-event.
• Type-safe architecture uses the AgentRunEventType enum with discriminated unions and runtime guards in packages/core/src/events.ts.
• Runtime helpers in packages/runtime/src/agent-run.ts provide emitRunStart(), emitToolInvocation(), and companion methods for consistent event generation.
• Persistence layer stores events via AgentRunStore in packages/storage/src/agent-run-store.ts for debugging and replay functionality.

Frequently Asked Questions

What is the difference between message and model-output events?

message events represent chat layer communication between user and agent, while model-output specifically captures raw LLM generation metadata including token usage and model identifiers. The runtime emits model-output for every inference call, whereas message events may aggregate or filter content for the conversation interface.

How does Maka handle tool execution failures?

Failed tool calls generate tool-result events with success: false and an error field containing failure details. Additionally, uncaught exceptions trigger error events via emitError(), which include stack traces and abort the current run context.

Where are AgentRunEvent types defined in the source code?

The AgentRunEventType enum and AgentRunEvent interface are defined in packages/core/src/agent-run.ts, with supplementary type guards exported from packages/core/src/events.ts. Runtime implementations reside in packages/runtime/src/agent-run.ts, while the storage schema lives in packages/storage/src/agent-run-store.ts.

Can third-party tools extend the event type system?

The core architecture supports extension through the runtime-event type, which accepts arbitrary payloads via its { type, data } structure defined in packages/core/src/runtime-event.ts. However, the eight primary AgentRunEventType values are sealed enums used by the official runtime for lifecycle management.

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