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

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 and consumed by the storage layer in 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 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), 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) 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 that decodes AgentRun events for evidence generation and auditing.

Working with the AgentRun Store

Creating and appending events to an AgentRun:

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:

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:

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

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) boots the single-owner process and manages the overall lifecycle, while the SessionManager (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 module in the storage package also provides utilities for decoding events into human-readable evidence formats.

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