# How Are Agents Managed Within the Maka Workspace? Event-Driven Architecture Explained

> Discover how Maka manages agents as immutable event streams in SQLite. Learn about event replay and Runtime Host orchestration for robust agent management in Apache Maka.

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

---

**Agents are managed as immutable AgentRun event streams stored per-workspace in SQLite, orchestrated by the Runtime Host, and recovered through event replay.**

Apache Maka treats agent execution as durable, append-only logs rather than transient processes. Every interaction—from model calls to tool invocations—is captured in an **AgentRun**, the central abstraction for how agents are managed within the Maka workspace. This architecture enables crash recovery, auditability, and reproducibility by storing all events in a per-workspace SQLite database accessed through the storage layer.

## The AgentRun Event Stream Model

Maka models every agent execution as an **AgentRun**, an immutable, append-only stream of events that records model calls, tool invocations, permission decisions, and more. Unlike traditional agent frameworks that manage state in volatile memory, Maka persists everything to a **SQLite database** (`runtime.sqlite`) located in the workspace directory under the Electron `userData` folder (e.g., `…/workspaces/default/`).

The event schema is defined in [`packages/core/src/agent-run.ts`](https://github.com/apache/maka/blob/main/packages/core/src/agent-run.ts) and consumed by 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). This store implements the `DurableAgentRunStore` interface, providing methods such as `appendEvent`, `readEvents`, and `readEventsForRecovery` to interact with the event log.

## Workspace Storage Infrastructure

When you create a workspace via the Desktop, TUI, or CLI, Maka initializes a directory structure that includes the durable event store. According to the repository README (lines 886-894), the workspace layout places `runtime.sqlite` at the root of the workspace folder.

The **AgentRun store** defined in [`packages/storage/src/agent-run-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/agent-run-store.ts) abstracts all SQLite operations, ensuring that events are atomically appended and can be queried efficiently for both real-time updates and historical analysis. The store handles three primary operations:

- **Event appending**: Writing new `AgentRunEvent` objects to the log via `appendEvent`
- **Event reading**: Retrieving events by session ID and run ID via `readEvents`
- **Recovery queries**: Optimized reads for crash recovery via `readEventsForRecovery`

## Runtime Host Orchestration

The lifecycle of an AgentRun is orchestrated by the **Runtime Host** ([`packages/runtime-host/src/runtime-host.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/runtime-host.ts)), which boots as a single-owner host process. When a user initiates a task, the Runtime Host creates a **SessionManager** ([`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts)) for that user session.

The SessionManager instantiates a new `AgentRun` object from `@maka/core/agent-run` and manages the flow of events. All agent interactions—whether calling a model or requesting user permissions—emit `AgentRunEvent` objects that are immediately appended to the SQLite store. This separation of concerns ensures that the Runtime Host handles process management while the SessionManager tracks the specific state of each agent execution within the workspace.

## Crash Recovery and Observability

Because the AgentRun stream serves as the single source of truth, Maka implements **crash recovery** through event replay rather than state snapshots. If the Runtime Host restarts, it calls `readEventsForRecovery` from the storage layer to retrieve the complete event history for a given session and run ID.

The recovery logic reconstructs the UI state or resumes the agent turn (if the safe-resume flag is enabled) by replaying each event through the runtime interpreter. This approach guarantees that no agent progress is lost, even during unexpected shutdowns.

For observability, Maka provides a **Grep** tool (implemented in Rust) that searches the event log, and a **tool-result-archive** module in [`packages/storage/src/tool-result-archive-evidence.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/tool-result-archive-evidence.ts) that decodes AgentRun events for evidence generation and auditing.

## Working with the AgentRun Store

Creating and appending events to an AgentRun:

```typescript
import { createSqliteAgentRunStore } from '@maka/storage';
import { AgentRunEvent } from '@maka/core/agent-run';

// Initialize the store for a specific workspace
const store = createSqliteAgentRunStore(workspaceRoot);

// Construct a model call event
const event: AgentRunEvent = {
  type: 'modelCall',
  runId: 'run-123',
  sessionId: 'session-abc',
  timestamp: Date.now(),
  payload: { model: 'gpt-4', prompt: 'Hello' },
};

// Persist to SQLite
await store.appendEvent(event);

```

Reading events for a specific session:

```typescript
import { createSqliteAgentRunStore } from '@maka/storage';

const store = createSqliteAgentRunStore(workspaceRoot);
const events = await store.readEvents('session-abc', 'run-123');

events.forEach(e => console.log(`[${e.type}] ${JSON.stringify(e.payload)}`));

```

Recovering after a crash:

```typescript
import { createSqliteAgentRunStore } from '@maka/storage';

const store = createSqliteAgentRunStore(workspaceRoot);
const recoveryEvents = await store.readEventsForRecovery('session-abc', 'run-123');

// Replay events to restore state
for (const ev of recoveryEvents) {
  // Runtime Host interprets event types (modelCall, toolResult, etc.)
}

```

## Summary

- **AgentRun** is the core abstraction: an immutable event stream that captures every agent action within the Maka workspace
- **SQLite persistence**: All events are stored in `runtime.sqlite` via the `AgentRunStore` implementation in [`packages/storage/src/agent-run-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/agent-run-store.ts)
- **Runtime Host orchestration**: The host process manages SessionManagers, which create and manage individual AgentRun lifecycles
- **Event-driven recovery**: Crash recovery relies on `readEventsForRecovery` to replay the event log rather than restoring from snapshots
- **Observability built-in**: Tools like Grep and the evidence archive module allow querying and decoding of historical agent events

## Frequently Asked Questions

### Where are agent events physically stored in a Maka workspace?

Agent events are stored in a SQLite database named `runtime.sqlite` located in the workspace directory under the Electron `userData` folder (typically `…/workspaces/default/`). This file is managed by the `DurableAgentRunStore` implementation in [`packages/storage/src/agent-run-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/agent-run-store.ts).

### How does Maka recover agent state after a crash?

Maka recovers by replaying the event stream. The Runtime Host calls `readEventsForRecovery` from the storage layer to fetch all events for a given session and run, then reconstructs the agent state by processing each event sequentially. This ensures durability without requiring complex state serialization.

### What is the relationship between the Runtime Host and SessionManager?

The **Runtime Host** ([`packages/runtime-host/src/runtime-host.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/runtime-host.ts)) boots the single-owner process and manages the overall lifecycle, while the **SessionManager** ([`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts)) handles per-user sessions. When a task starts, the SessionManager creates the `AgentRun` instance and coordinates event emission to the storage layer.

### How can I query historical agent runs for debugging?

You can use the `readEvents` method from the `AgentRunStore` to fetch specific run histories, or use the built-in **Grep** tool (implemented in Rust) to search across the entire event log. The [`tool-result-archive-evidence.ts`](https://github.com/apache/maka/blob/main/tool-result-archive-evidence.ts) module in the storage package also provides utilities for decoding events into human-readable evidence formats.