# How Mako's SessionManager Manages the AI Agent Session Lifecycle: A Complete Guide

> Master Mako's SessionManager and its four phases for orchestrating AI agent session lifecycles. Learn creation, tracking, mutations, and termination.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: how-to-guide
- Published: 2026-09-06

---

**Mako's SessionManager orchestrates the complete lifecycle of an AI agent session through four distinct phases: creation and initialization, active turn tracking, runtime mutations and configuration changes, and final termination with cleanup.**

The **SessionManager** in Apache Mako serves as the public Runtime API that governs every stage of an AI agent session's existence. Located in [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts), this class coordinates between persistent storage, runtime execution kernels, and backend AI services to maintain consistent session state from creation through disposal.

## The Four Phases of Session Lifecycle Management

Mako's session lifecycle follows a structured pipeline that ensures data integrity and resource management across the entire execution span.

### Phase 1: Session Creation and Initialization

The lifecycle begins when `SessionManager.createSession` generates a new session entity and persists it to the **SessionStore**. This method delegates to `SessionStore.create` to write the initial session header to SQLite, generates a unique identifier via the injected `newId` function, and returns a `SessionSummary` object through the `headerToSummary` transformation. The implementation spans lines 19-25 in [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts), establishing the foundational persistent record before any AI execution begins.

During initialization, the manager also coordinates with the **BackendRegistry** to provision the concrete AI backend (such as OpenAI or Azure) and hands this activation to the **RuntimeKernel** for subsequent turn execution.

### Phase 2: Tracking Active Execution Turns

Once a session is active, the manager monitors ongoing work through the `runningTurnIds` method (lines 40-42 in [`session-manager.ts`](https://github.com/apache/maka/blob/main/session-manager.ts)). This functionality delegates to **RuntimeKernel**, which maintains an in-memory map of active turn IDs per session. The private `#projectLiveRunState` method (lines 44-51) augments session listings with these live execution states, ensuring that calls to `listSessions` return real-time information about which sessions have active computational work in flight.

This tracking mechanism prevents premature termination of sessions with running operations and provides visibility into system workload.

### Phase 3: Runtime Mutations and Configuration Changes

Active sessions frequently require mid-lifecycle modifications, which the manager handles through several specialized methods.

**Configuration transitions** validate and apply changes to revision numbers, permission modes, collaboration settings, and deep-research labels via `transitionSessionConfiguration` (lines 25-30). This method updates the persistent header through `SessionStore.updateSessionConfiguration` only after validation passes.

**Workspace relocation** allows moving a session's working directory through `relocateSessionWorkspace` (lines 85-92). This complex operation ensures no active turns are executing, disposes the current backend, updates the session header with the new path, and re-opens any shell runs in the new location.

**Child-session handling** manages sub-agent spawning by provisioning work-tree bindings and recording workspace patches for crash recovery, tracked internally through the `childSessionSpawns` map.

### Phase 4: Termination and Resource Cleanup

Session conclusion involves multiple cleanup stages to prevent resource leaks. The `stopSession` method (following patterns established in lines 21-27) aborts active runs, updates the session header status, clears sandbox boundaries, and removes the session from the RuntimeKernel.

For backend resource management, `disposeSessionBackend` forces release of cached AI backend state, while `refreshIdleBackends` triggers lazy cache invalidation across all idle sessions. The manager also finalizes pending workspace patches to ensure work-tree changes survive unexpected crashes, guaranteeing idempotent handling through careful tracking maps that prevent duplicate work on retry.

## Key Implementation Files and Architecture

The session lifecycle relies on four core components working in concert:

- **[`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts)** – Contains the main `SessionManager` class implementing the public API for create, list, transition, stop, and dispose operations.

- **[`packages/runtime/src/runtime-kernel.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-kernel.ts)** – Executes individual turns, maintains the `runningTurnIds` map, and provides `invalidateCachedBackends` and `disposeBackend` utilities.

- **[`packages/runtime/src/backend-registry.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/backend-registry.ts)** – Factory registry that resolves backend implementations (OpenAI, Azure, etc.) for each session's AI provider.

- **[`packages/runtime/src/session-store.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-store.ts)** – Interface defining the SQLite persistence contract for session headers, messages, turns, and configuration states.

## Practical Code Examples for Session Lifecycle Operations

The following TypeScript examples demonstrate common session management patterns using an initialized `SessionManager` instance named `manager`:

```typescript
// Create a new AI agent session
const summary = await manager.createSession({
  name: 'Chat with Copilot',
  backend: 'openai',
  permissionMode: 'explore',
});

```

```typescript
// List all sessions with live running-turn IDs attached
const sessions = await manager.listSessions();
console.log(sessions.map(s => 
  `${s.name} – running turns: ${s.runningTurnIds?.join(', ')}`
));

```

```typescript
// Update session configuration (e.g., change permission mode)
await manager.transitionSessionConfiguration(summary.id, {
  expectedRevision: 1,
  configuration: {
    backend: 'openai',
    llmConnectionId: undefined,
    llmConnectionSlug: 'openai',
    connectionLocked: false,
    model: 'gpt-4',
    thinkingLevel: 'normal',
    permissionMode: 'reflect',
    collaborationMode: 'solo',
    orchestrationMode: 'auto',
    labels: [],
  },
  clearConnectionBlock: false,
});

```

```typescript
// Relocate session workspace to a new directory
await manager.relocateSessionWorkspace(summary.id, {
  expectedRevision: 2,
  cwd: '/new/workspace/path',
  projectId: null,
});

```

```typescript
// Gracefully stop a session and clean up resources
await manager.stopSession(summary.id, { 
  source: 'stop_button', 
  mode: 'graceful' 
});

```

## Summary

- **Mako's SessionManager** in [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts) provides the primary public API for AI agent session lifecycle management in the Apache Mako runtime.

- The lifecycle progresses through four distinct phases: **creation and initialization** (SQLite persistence via SessionStore), **active turn tracking** (RuntimeKernel coordination), **runtime mutations** (configuration transitions and workspace relocation), and **termination cleanup** (backend disposal and resource release).

- **RuntimeKernel** maintains in-memory execution state through `runningTurnIds`, while **BackendRegistry** handles AI provider activation and caching.

- Methods like `transitionSessionConfiguration` and `relocateSessionWorkspace` ensure atomic, validated updates to persistent session state, preventing data corruption during mid-lifecycle changes.

- **Idempotency guarantees** are maintained through internal maps (`childSessionSpawns`, `claimedAgentGraphIntentRuns`) that prevent duplicate work when operations retry after failures.

## Frequently Asked Questions

### How does SessionManager track which sessions have active AI work in progress?

The manager delegates to **RuntimeKernel**, which maintains an in-memory map of active turn IDs per session. The `runningTurnIds` method exposes this data, while `#projectLiveRunState` augments session listings with live execution states. This allows the UI and host services to see real-time execution status when calling `listSessions`.

### What happens when I change a session's backend configuration mid-conversation?

The `transitionSessionConfiguration` method validates the requested changes against the current revision number, then persists the update via `SessionStore.updateSessionConfiguration`. This ensures that permission modes, model selections, and collaboration settings transition atomically without interrupting active turns, provided no execution is currently running.

### Can I move a session to a different working directory without losing context?

Yes, through the `relocateSessionWorkspace` method. This operation verifies no active turns are executing, disposes the current backend to prevent file handle conflicts, updates the session header with the new path in SQLite, and re-opens any shell runs in the relocated directory. Child-session workspace patches are preserved and finalized during this process.

### How does Mako prevent resource leaks when sessions terminate?

The manager implements a multi-stage cleanup protocol through `stopSession`, which aborts active runs, updates the persistent header status, clears sandbox boundaries, and removes the session from RuntimeKernel. For backend resources, `disposeSessionBackend` explicitly releases cached AI connections, while `refreshIdleBackends` performs lazy cache invalidation to reclaim memory from inactive sessions.