# How the Agent Graph Coordinator Manages Child Sessions in Apache Maka

> Discover how the Apache Maka Agent Graph Coordinator manages child sessions through a root-to-child hierarchy, immutable graph IDs, and internal assertions for robust session orchestration.

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

---

**The Agent Graph Coordinator enforces a strict root-to-child hierarchy by binding every child Session to its parent root Session through immutable graph IDs, validating all operations via internal assertions, and orchestrating lifecycle events through dedicated GraphDriver instances.**

In the Apache Maka repository, the `AgentGraphCoordinator` serves as the runtime-host component that orchestrates both root Sessions and their child Sessions (graph operators). This coordinator ensures that every child Session exists as a durable entity within an Agent Graph linked to exactly one root Session, preventing cross-root leaks and maintaining deterministic lifecycle management. Understanding how this component manages child Sessions requires examining its validation mechanisms, driver architecture, and provisioning APIs.

## Core Architecture of Child Session Management

The coordinator treats child Sessions as first-class graph operators that live inside durable Agent Graphs. Each graph is identified by a unique `graphId` and bound to a single root Session through immutable identity relationships.

### Root Session Validation and Ownership

When instantiated, the `AgentGraphCoordinator` validates that any supplied `rootSessionId` represents a canonical, trimmed identity. In [`packages/runtime/src/stream-graph-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/stream-graph-coordinator.ts), the constructor performs this validation to establish the root boundary before any child Sessions are provisioned.

All public methods that interact with graph operators first invoke `#assertGraphBelongsToRoot`, a private helper that throws if the graph (or its child operator) does not belong to the supplied root Session. This assertion appears early in the method flow to ensure that no child Session operation occurs outside its parent context.

### GraphDriver as the Child Session Container

The coordinator tracks child Sessions through `GraphDriver` objects, where each driver represents a single Agent Graph. These drivers maintain:
- A set of `yieldWaiters` for async coordination
- A `clientProjectionTask` for materialized views
- A `closed` flag indicating lifecycle state

The coordinator stores these drivers in an internal `#drivers` Map keyed by `graphId`, enabling O(1) lookups when routing operations to specific child Session collections.

## Provisioning and Identity Assignment

Child Sessions enter the system through a formal provisioning API that links them permanently to their root Session's identity.

### The provisionAgentGraphOperator Flow

When a schedule update authorizes a new operator, the coordinator forwards a `provisionAgentGraphOperator` call to the runtime's session manager. This occurs in [`packages/runtime/src/stream-graph-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/stream-graph-coordinator.ts) through the coordinator's runtime interface, which delegates to `sessionMgr.provisionAgentGraphOperator`.

The provisioned operator receives a `childSessionId` that serves as its durable identifier throughout the Session lifecycle. This ID becomes the canonical reference for all subsequent operations involving that child Session.

### childSessionId as the Durable Identifier

Unlike transient process identifiers, the `childSessionId` persists across coordinator restarts and graph reconciliations. The runtime uses this ID to correlate historical results, checkpoint state, and tool invocations with the correct child operator instance.

## Runtime Validation and Security Boundaries

The coordinator implements multiple validation layers to ensure child Sessions remain scoped to their root Session.

### Ownership Assertions (#assertGraphBelongsToRoot)

Before executing any graph operation, the coordinator calls `#assertGraphBelongsToRoot` to verify that the target `graphId` exists within the supplied root Session's namespace. This method performs an identity check against the internal `#drivers` Map, throwing an authorization error if the graph belongs to a different root or no longer exists.

### Preventing Cross-Root Data Access (#assertScheduleOwnedByRoot)

For schedule updates, claims, and result inputs, the coordinator employs `#assertScheduleOwnedByRoot` to validate that:
1. The `request.graphId` matches an existing driver in the coordinator's Map
2. The source session equals the root Session

This prevents child Sessions from one root Session from consuming or modifying resources belonging to another root.

## Historical Result Resolution for Child Operators

Child Sessions frequently need to consume results from previous graph epochs. The coordinator manages this through controlled access to the epoch store.

### The #resolveSelectedResultInputs Method

When a child Session requests historical data, `#resolveSelectedResultInputs` performs three critical validations:
1. Reads the epoch store to locate the prior epoch's projection
2. Verifies that the requested `sourceGraphId` belongs to the same root Session
3. Pulls committed records only from authorized prior epochs

This method, implemented in [`packages/runtime/src/stream-graph-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/stream-graph-coordinator.ts), guarantees immutability and root-scoping by checking the source graph ownership before returning any `AgentRun` records to the requesting child operator.

## Lifecycle Management and Shutdown

The coordinator provides deterministic lifecycle control over all child Sessions within a graph.

### Graceful Shutdown Procedures

The `stop` and `stopExecution` methods propagate termination signals through `#stopGraph` and `#stopDriver`. These methods:
- Set the driver's `stopping`, `paused`, and `closed` flags
- Await in-flight operator tasks to ensure clean resource release
- Terminate all child Sessions (operators) within the graph atomically

This prevents orphaned child processes and ensures that partial shutdowns cannot leave child Sessions running independently of their root Session.

## Supervisor Tool Isolation

Child Sessions operate with restricted capabilities compared to their root Session supervisors. The `toolsForSession` method first asserts that the caller possesses root supervisor privileges, effectively blocking child Sessions from accessing control surfaces reserved for the parent. This architectural constraint prevents child operators from interfering with coordinator-level configuration or other graphs.

## Practical Implementation Examples

### Initializing the Coordinator with Root Session Binding

```typescript
import { AgentGraphCoordinator } from '@apache/maka/runtime';

const coordinator = new AgentGraphCoordinator({
  sessionStore,
  runtimeEventStore,
  controlStore,
  runtime: {
    provisionAgentGraphOperator: sessionMgr.provisionAgentGraphOperator,
    runClaimedAgentGraphIntent: sessionMgr.runClaimedAgentGraphIntent,
    stopSession: sessionMgr.stopSession,
  },
  newId: () => crypto.randomUUID(),
  rootSessionId: rootSession.id, // Canonical root identity
});

```

### Provisioning a Child Session (Graph Operator)

```typescript
// Only the root supervisor can initiate provisioning
await coordinator.toolsForSession(rootSession.id);

// Create the child operator with durable identity
const operator = await coordinator.runtime.provisionAgentGraphOperator({
  rootSessionId: rootSession.id,
  operatorId: crypto.randomUUID(),
  // Returns childSessionId for persistent identification
});

```

### Accessing Historical Results from Previous Epochs

```typescript
// Child operator requests prior results
const historicalRecords = await coordinator.resolveSelectedResultInputs(
  rootSession.id,
  currentGraphId,
  [{ sourceGraphId: previousGraphId, resultId: 'epoch-result-1' }]
);

// Records are verified to belong to the same root Session before return

```

### Terminating All Child Sessions

```typescript
// Gracefully stops the graph and all child operators
await coordinator.stop(rootSession.id);

```

## Summary

The Agent Graph Coordinator in Apache Maka manages child Sessions through a strict hierarchical model that enforces security and determinism:

- **Immutable root binding**: Every child Session is permanently linked to a single root Session via `graphId` and validated through `#assertGraphBelongsToRoot`
- **Driver-based tracking**: `GraphDriver` instances maintain child Session state in a private `#drivers` Map keyed by graph identity
- **Durable identifiers**: The `childSessionId` provisioned through `provisionAgentGraphOperator` persists across runtime restarts
- **Root-scoped data access**: Methods like `#resolveSelectedResultInputs` and `#assertScheduleOwnedByRoot` prevent cross-root data leaks
- **Privilege separation**: Child Sessions cannot access supervisor tools, while root Sessions control lifecycle events through coordinated stop procedures

## Frequently Asked Questions

### How does the Agent Graph Coordinator prevent child Sessions from accessing other root Sessions' data?

The coordinator implements multiple ownership assertions, including `#assertGraphBelongsToRoot` and `#assertScheduleOwnedByRoot`, which verify that any requested `graphId` or `sourceGraphId` exists within the requesting root Session's namespace. These checks occur before any data access or modification operations, throwing authorization errors if a child Session attempts to reference resources outside its parent boundary.

### What is the relationship between a GraphDriver and child Sessions in Apache Maka?

Each `GraphDriver` instance represents a single Agent Graph and serves as the container for all child Sessions (operators) within that graph. The driver maintains coordination primitives like `yieldWaiters` and lifecycle flags (`closed`, `stopping`), while the coordinator manages these drivers in an internal Map keyed by `graphId` to route operations to the correct set of child Sessions.

### Can child Sessions persist state across coordinator restarts?

Yes, child Sessions receive a `childSessionId` during the `provisionAgentGraphOperator` call that acts as a durable identifier. The coordinator uses this ID to correlate historical results from the epoch store and maintain continuity across restarts, provided the root Session remains valid and the graph configuration persists in the storage layer.

### Why can't child Sessions access the toolsForSession API?

The `toolsForSession` method explicitly asserts that the caller is the root supervisor before returning control surfaces. This restriction prevents child operators (which run arbitrary code as graph nodes) from modifying coordinator configuration, accessing other graphs, or interfering with the runtime-host's control plane, maintaining a strict security boundary between execution contexts.