How the Agent Graph Coordinator Manages Child Sessions in Apache Maka

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, 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 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, 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

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)

// 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

// 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

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

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