# Maka AgentRunEvent Types: Complete Guide to Execution Lifecycle Events

> Explore Maka's eight core AgentRunEvent types including run-start, run-end, tool-invocation, and more. Understand the agent execution lifecycle comprehensively.

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

---

**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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-run.ts) expose helper functions for event generation:

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

```typescript
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:

```typescript
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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/core/src/events.ts).
- **Runtime helpers** in [`packages/runtime/src/agent-run.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/core/src/agent-run.ts)**, with supplementary type guards exported from **[`packages/core/src/events.ts`](https://github.com/apache/maka/blob/main/packages/core/src/events.ts)**. Runtime implementations reside in **[`packages/runtime/src/agent-run.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-run.ts)**, while the storage schema lives in **[`packages/storage/src/agent-run-store.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event.ts)**. However, the eight primary `AgentRunEventType` values are sealed enums used by the official runtime for lifecycle management.