How Apache Maka’s Runtime Host Manages the Session Lifecycle

Apache Maka’s Runtime Host orchestrates a deterministic, state-driven session lifecycle through five distinct phases—creation, activation, live streaming, draining, and termination—using dedicated server-side coordinators that enforce single-lease semantics and graceful shutdown guarantees.

The Apache Maka Runtime Host (RH) provides the server-side foundation for interactive AI sessions, ensuring that every session transitions through well-defined states while maintaining durability and consistency. Unlike simple connection managers, the RH implements a comprehensive lifecycle protocol that governs everything from UUID allocation to graceful host shutdown. This article examines the exact mechanics of how the Runtime Host manages session lifecycles according to the Apache Maka source code.

The Five Phases of Session Lifecycle Management

The Runtime Host manages every session through a strict progression of phases, each handled by a specialized coordinator component.

Creation and Catalog Registration

The lifecycle begins in packages/runtime-host/src/server/session-catalog-coordinator.ts, where the SessionCatalogCoordinator persists a new session record, allocates a durable UUID, and registers the session in the SessionCatalog projection. This phase establishes the persistent identity of the session before any client connections are accepted.

Activation and Admission Control

Before a client can attach, the session must pass through the SessionAdmissionGate (packages/runtime-host/src/server/session-admission-gate.ts). This component, utilized by the SessionContinuityCoordinator, grants a lease that permits client attachment. The gate validates that the host is not currently draining and that the session is not already attached elsewhere, enforcing the critical single active lease per session guarantee.

Live Streaming and Continuity

Once admitted, the SessionContinuityCoordinator (packages/runtime-host/src/server/session-continuity-coordinator.ts) manages WebSocket and IPC subscriptions. It buffers SessionDelta frames with strict resource limits: a maximum of 16 concurrent connections, 32 queued frames, and 256 KB of queued bytes per session. This coordinator also maintains a replayable transcript overlay using SessionTranscriptOverlay, enabling clients to resynchronize to any historical revision by replaying monotonically increasing deltas.

Effect Application and Durability

During the live phase, the SessionEffectCoordinator (packages/runtime-host/src/server/session-effect-coordinator.ts) applies side-effects such as tool result previews and transcript pagination to the in-memory projection. It tracks the terminalPublicationFence to gate the final commit of a turn, ensuring that transient effects remain durable without blocking the main execution flow.

Draining and Graceful Shutdown

When the Runtime Host initiates shutdown, the RuntimeHostControl sets a #draining flag on all coordinators. As implemented in session-continuity-coordinator.ts (lines 139-156), this phase rejects all new session admissions with a host_draining error code. Existing connections receive the error message "Runtime Host is draining", allowing clients to gracefully terminate or migrate to another host.

Termination and Catalog Cleanup

The final phase occurs when a session’s Turn graph closes and no live subscriptions remain. The SessionCatalogCoordinator marks the catalog entry as closed. According to runtime-policy-coordinator.ts (lines 463-467), if the host attempts to close a composition while any session remains active, it throws an AggregateError, ensuring that termination cannot occur while work is in progress.

Core Lifecycle Guarantees

The Runtime Host enforces four architectural guarantees that prevent race conditions and data loss:

• Single active lease per session: The SessionAdmissionGate prevents duplicate connections; attempts to attach an already-connected session raise Duplicate Runtime Host connection (see session-continuity-coordinator.ts line 295).
• Deterministic replay: The SessionContinuityCoordinator records every delta with a monotonic revision number, enabling disconnected clients to resume from any point via the transcript overlay.
• Graceful draining: When shutting down, the host aborts in-flight commands with explicit error messages and rejects new admissions with host_draining, preventing abrupt disconnections.
• Consistent termination: Sessions cannot close while turns remain live; the RuntimePolicyCoordinator validates this constraint before finalizing composition closure.

Working with the Session Lifecycle in Practice

Client applications interact with these lifecycle phases through the SessionManager API (packages/runtime/src/session-manager.ts), which delegates to the Runtime Host via the RuntimeMessageAuthority and RuntimeInteractionAuthority layers.

Creating a New Session

import { SessionManager } from '@maka/runtime';

// Creates a session record in the Runtime Host catalog
const session = await SessionManager.createSession({
  name: 'My Research Session',
  // optional: parent session, initial messages, etc.
});
console.log('Session created:', session.sessionId);

Subscribing to Live Events

import { SessionClient } from '@maka/runtime';

// Obtains admission lease from SessionAdmissionGate
const client = new SessionClient(session.sessionId);
await client.connect();

client.on('text_delta', (ev) => {
  console.log('Model output:', ev.text);
});

client.on('session_lifecycle_changed', () => {
  console.error('The session was closed or the host is draining');
});

Handling Host Draining Errors

try {
  await client.sendToolResult(/* ... */);
} catch (err) {
  if (err.message.includes('Runtime Host is draining')) {
    // Gracefully back-off or retry after host restart
    await client.reconnectToAlternateHost();
  }
}

Summary

• The Apache Maka Runtime Host implements a five-phase lifecycle (creation, activation, streaming, draining, termination) through specialized coordinators.
• SessionCatalogCoordinator handles persistence and UUID allocation, while SessionAdmissionGate enforces single-lease semantics.
• SessionContinuityCoordinator manages live streaming with hard limits on connections, frames, and memory usage.
• The draining phase explicitly signals clients via host_draining errors, enabling graceful migration during host shutdown.
• Termination is blocked if active turns exist, preventing data loss through AggregateError validation in runtime-policy-coordinator.ts.

Frequently Asked Questions

How does the Runtime Host prevent multiple clients from connecting to the same session simultaneously?

The SessionAdmissionGate component enforces a single active lease per session. When a client attempts to connect, the gate checks the session’s current attachment state; if already leased, it raises a Duplicate Runtime Host connection error (as found in session-continuity-coordinator.ts line 295). This ensures only one client holds the active connection at any time.

What happens to active sessions when the Runtime Host shuts down?

When the host initiates shutdown, it sets an internal #draining flag on all coordinators. New session admissions are immediately rejected with the host_draining error code, while existing connections receive the error "Runtime Host is draining" (lines 139-156 in session-continuity-coordinator.ts). This allows clients to detect the shutdown and gracefully save state or reconnect to a different host.

How does the SessionContinuityCoordinator enable clients to resume after disconnection?

The coordinator maintains a SessionTranscriptOverlay that records every SessionDelta with a monotonically increasing revision number. When a client reconnects, it can request replay from any historical revision, receiving all buffered frames in order. This mechanism supports deterministic recovery without requiring the session to restart or lose context.

What prevents a session from terminating while work is still in progress?

The RuntimePolicyCoordinator validates that no active turns exist before allowing composition closure. As implemented in lines 463-467 of runtime-policy-coordinator.ts, attempting to close a composition while sessions remain active throws an AggregateError, ensuring that termination only occurs after all pending operations complete and subscriptions disconnect.

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