# How Apache Maka Handles the Agent Execution Lifecycle: Inside the AgentRun Class

> Discover how Apache Maka handles the agent execution lifecycle via the AgentRun class. Learn about its nine distinct stages from initialization to termination orchestrated by the Runtime Host.

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

---

**Apache Maka manages the agent execution lifecycle through the `AgentRun` class, which orchestrates a single turn from initialization through durable logging, tool execution, and graceful termination via nine distinct stages coordinated by the Runtime Host.**

Apache Maka is an open-source framework for building reliable AI agents. At the heart of its reliability guarantees lies the `AgentRun` class located in [`packages/runtime/src/agent-run.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-run.ts), which implements a durable, recoverable lifecycle for each agent turn. This article examines how Apache Maka handles the agent execution lifecycle through the `AgentRun` implementation, from initial registration to crash recovery.

## The AgentRun Class: Core of the Execution Lifecycle

The `AgentRun` class serves as the **execution authority** for a single agent turn. According to the Apache Maka source code, a "run" represents one complete turn—from the moment a user message is received, through tool invocations and possible continuations, to final termination. The class maintains the canonical state in the **AgentRunStore** and writes immutable events to the **Runtime Event Log**, ensuring that every action is durably recorded in SQLite stores under `packages/storage`.

The lifecycle operates through cooperation between the **Runtime Host**, which owns session identity and permissions, and the **Agent Graph**, which schedules sub-agents. The `AgentRun` instance bridges these components while guaranteeing that the ledger remains consistent even during crashes or graceful stops.

## The Nine Stages of the Agent Execution Lifecycle

The Apache Maka agent execution lifecycle breaks down into nine distinct stages, each implemented by dedicated components and hooks.

### 1. Run Creation and Registration

A client (CLI, TUI, desktop application, or bot) requests a new turn via the **Runtime Host**. The host constructs an `AgentRunInput` object and instantiates the `AgentRun` class. During construction (lines **69-84** in [`packages/runtime/src/agent-run.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-run.ts)), the `AgentRunHooks.reserveRun` method registers the run in an active-session map called `AgentRunActiveSession`, establishing the run's identity before any processing begins.

### 2. Input Validation and Orchestration

Before execution starts, the run resolves its orchestration mode and tool permissions. The `resolveEffectiveOrchestration` method (lines **99-101**) determines how the agent will coordinate with sub-agents, while tool-mode checks (lines **99-104**) validate whether the run operates in `DEFAULT_TOOL_MODE` or another configured mode. Invalid or missing data triggers early errors here, preventing corrupted runs from entering the event stream.

### 3. Runtime Event Stream Initialization

The run creates an **invocation opening** event (`RuntimeEventInvocationOpenedContent`) that marks the start of execution. The `isSessionInline()` method (lines **54-60**) determines whether the execution runs *session-inline* or *out-of-line*, affecting how the runtime buffers events. This opening event becomes the first entry in the **Runtime Event Log**, establishing the canonical source of truth for the turn.

### 4. Tool Execution and Logging

During the turn, the agent may invoke LLM-powered tools. Each tool call generates a **Tool Ledger** entry with the type `MODEL_CALL_ATTEMPT_EVENT_TYPE`. The run persists these events through the `AgentRunStore` API, using methods like `appendTurnState` and `appendMessage` to write to both the durable `AgentRunStore` and the `RuntimeEventStore`. This dual-write pattern ensures that tool interactions remain recoverable even if the host process terminates unexpectedly.

### 5. Continuation Handling

When a turn spawns a continuation—such as a sub-session or a resumed run—the run creates a **Continuation Start Admission Proof** via `createRuntimeContinuationStartAdmissionProof` (lines **66-70**). The `commitContinuationStart` method commits a *claimed opening* to the durable ledger before the backend begins execution. This guarantees that the continuation survives host crashes and can be resumed later without data loss.

### 6. Graceful Stop Requests

The host or user can request termination via `run.stop(source)` (lines **25-33**). This method records a *terminal claim* in the run's state and prevents further events from being appended. The `hasPendingStop()` and `completeStop()` methods (lines **62-68**) manage the stop lifecycle, ensuring that in-flight operations complete gracefully while new operations are rejected.

### 7. Finalization and Terminal Claims

When the backend signals completion, the `finalize()` method (called from `runCompositionWrite` and `flushRuntimePartialBuffer`) writes the **terminal run fact** to the durable store. The `settleStopTerminal()` method (lines **81-99**) ensures that any pending stop claim is "cashed," marking the run as definitively terminated in the ledger. The `terminalRunFactCommitted` flag (lines **54-56**) prevents duplicate finalization.

### 8. Recovery and Inspection

After a crash or during continuation resume, the `AgentRunRecovery` machinery in [`packages/runtime/src/agent-run-recovery.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-run-recovery.ts) re-hydrates the run from the **AgentRun event stream** and **Runtime Event Log**. The recovery process validates ledger consistency and can replay missing events. Developers can inspect run diagnostics through `AgentRunInspectDiagnostic` in [`packages/runtime/src/agent-run-inspect.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-run-inspect.ts), which provides visibility into the lifecycle state.

### 9. Agent Graph Coordination

For parallel sub-agents or complex workflows, the **Agent Graph** ([`packages/runtime/src/agent-graph.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-graph.ts)) schedules child sessions through the **Agent Graph Control Plane**. The run propagates lineage metadata (parent run/turn IDs, retry information) to child sessions and collects results back through the Runtime Host, maintaining a unified event log across distributed execution.

## Implementing the Lifecycle: Code Examples

### Starting an Agent Run

The following TypeScript example demonstrates initializing a run with the required stores and hooks:

```typescript
import { createSqliteAgentRunStore } from '@maka/storage';
import { SessionManager } from '@maka/runtime';
import { AgentBackend } from '@maka/core';

// 1. Prepare the stores
const runStore = createSqliteAgentRunStore('/path/to/workspace');
const runtimeEventStore = /* …create RuntimeEventStore… */;

// 2. Build the input payload
const input = {
  sessionId: 'sess-123',
  header: {/* SessionHeader */},
  userInput: {/* UserMessageInput */},
  store: { /* Session store */ },
  runStore,
  runtimeEventStore,
  newId: () => crypto.randomUUID(),
  now: () => Date.now(),
  hooks: {
    reserveRun: async (sid, hdr, run) => ({
      sessionId: sid,
      backend: {/* … */} as AgentBackend,
      cachedHeader: hdr,
      activeRuns: new Map([[run.runId, run]]),
      turnToRunId: new Map(),
    }),
    updateHeader: async () => ({/* … */}),
    updateStatus: async () => {},
    appendTurnState: async () => {},
  },
};

// 3. Create the run – this runs the constructor logic (initialisation, lineage, etc.)
const run = new AgentRun(input);

// 4. Start the backend (e.g., a LLM model) – the `run.begin()` method returns the initial runtime events
const beginResult = await run.begin();

```

### Stopping a Run Gracefully

To initiate a graceful shutdown from the UI or a scheduler:

```typescript
const stopped = run.stop({ source: 'user', workHubActionId: 'task-456' });
if (stopped) {
  console.log('Run stop scheduled – terminal claim recorded');
}

```

### Handling Continuations

When suspending a turn for later resumption:

```typescript
// The backend decides to continue the turn in a later session.
await run.commitContinuationStart(Date.now()); // writes the start admission proof
// Later, when the continuation resumes, the runtime will call `run.beginContinuation()`

```

### Recovering from Crashes

To recover a run after a host restart:

```typescript
import { recoverAgentRun } from '@maka/runtime/agent-run-recovery';

const recoveredRun = await recoverAgentRun({
  sessionId: 'sess-123',
  runId: 'run-abc',
  runStore,
  runtimeEventStore,
});

```

## Key Source Files for the Execution Lifecycle

- **[`packages/runtime/src/agent-run.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-run.ts)** – Implements the full `AgentRun` class including construction, stop handling, terminal claim settlement (`settleStopTerminal`), and interaction with durable stores.
- **[`packages/runtime/src/agent-run-recovery.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-run-recovery.ts)** – Contains `AgentRunRecovery` logic for re-hydrating runs after crashes and validating ledger consistency.
- **[`packages/runtime/src/agent-run-inspect.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-run-inspect.ts)** – Provides `AgentRunInspectDiagnostic` utilities for debugging lifecycle states.
- **[`packages/storage/src/sqlite-agent-run-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/sqlite-agent-run-store.ts)** – Persists the immutable AgentRun event stream to SQLite, serving as the authoritative source for "what happened."
- **[`packages/runtime/src/agent-graph.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-graph.ts)** – Implements the Agent Graph Control Plane for scheduling sub-agents and propagating lineage.
- **[`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md)** (root) – Describes the high-level relationship between the Runtime Host, Session Manager, AgentRun, and Agent Graph components.

## Summary

- The `AgentRun` class in [`packages/runtime/src/agent-run.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-run.ts) manages a single agent turn as a durable, recoverable unit of work.
- The lifecycle spans nine stages: creation, validation, event stream initialization, tool execution, continuations, stop requests, finalization, recovery, and graph coordination.
- **Durable stores** (`AgentRunStore` and `RuntimeEventStore`) ensure that every event is persisted to SQLite before acknowledgment, enabling crash recovery.
- **Graceful stops** use terminal claims (`terminalClaim`) and `settleStopTerminal` to ensure clean termination without data loss.
- **Continuations** use admission proofs to survive host crashes and resume execution later.
- **Recovery machinery** in [`agent-run-recovery.ts`](https://github.com/apache/maka/blob/main/agent-run-recovery.ts) re-hydrates runs from the event stream, validating consistency before resuming.

## Frequently Asked Questions

### What is the difference between AgentRun and SessionManager in Apache Maka?

The `AgentRun` class governs a **single turn** within a session—the execution of one user request through completion—while the `SessionManager` (located in [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts)) coordinates multiple turns and tracks active sessions over time. The SessionManager creates `AgentRun` instances and manages the **Runtime Host** identity, whereas `AgentRun` handles the specific lifecycle of one turn's event stream and durable ledger.

### How does Apache Maka ensure durability during agent execution?

Apache Maka ensures durability through **immediate persistence** to SQLite-backed stores. Every significant event—invocation openings, tool calls, and terminal claims—is written to the `AgentRunStore` and `RuntimeEventStore` before the runtime acknowledges progress. The `commitContinuationStart` method writes admission proofs before spawning sub-sessions, and the `finalize` method commits terminal facts before releasing resources, ensuring the ledger remains consistent even if the host crashes.

### Can Apache Maka recover an agent turn after a host crash?

Yes. The `AgentRunRecovery` mechanism in [`packages/runtime/src/agent-run-recovery.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-run-recovery.ts) can re-hydrate a run from the **AgentRun event stream** and **Runtime Event Log** after a crash. The recovery process validates that the ledger is consistent and can replay missing events. Because continutations write **Continuation Start Admission Proofs** before beginning work, even interrupted sub-sessions can be resumed without data loss.

### How does the Agent Graph interact with the agent execution lifecycle?

The **Agent Graph** ([`packages/runtime/src/agent-graph.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-graph.ts)) extends the lifecycle to parallel and hierarchical execution. When a run spawns sub-agents, the Agent Graph Control Plane schedules child sessions, propagates lineage metadata (parent run IDs and retry contexts) through the Runtime Host, and collects results back into the parent run's event stream. This integration allows `AgentRun` to manage complex multi-agent workflows while maintaining a unified, durable audit log.