How the Agent Graph Schedules Dependent Work Using Child Sessions in Apache Maka

Apache Maka schedules dependent work by treating child Sessions as durable operator containers, using deterministic intent claims bound to specific Turn/Run IDs to guarantee exactly-once execution across arbitrarily-deep dependency trees.

The Apache Maka runtime implements a sophisticated scheduling mechanism through its Agent Graph feature, which layers a control-plane atop the existing Runtime data-plane without spawning a second execution engine. By provisioning child Sessions as stable operator identities and projecting committed RuntimeEvents into immutable graph records, the system declaratively coordinates dependent work while re-using the core Session and Runtime infrastructure.

Architecture: Control-Plane Over Data-Plane

The Agent Graph operates as a control-plane built on top of the existing Runtime data-plane. Unlike traditional workflow engines, it does not create a second execution engine or re-implement Runtime semantics. Instead, the graph manipulates metadata—specifically operator-session bindings, intent claims, schedule revisions, and supervisor wakes—stored in SQLite.

This two-plane architecture ensures that child Sessions serve as the actual execution environment. A Session-inline AgentRun inside a child Session represents an activation of the operator, while each committed RuntimeEvent becomes a read-only record that the graph routes to downstream operators.

Step 1: Provisioning Operators as Child Sessions

The scheduling lifecycle begins by atomically creating a durable child Session that serves as an operator container. In packages/storage/src/sqlite-session-metadata-store.ts, the createAgentGraphOperator function (lines 1039–1075) provisions both the child Session and its associated operator metadata:

// 1️⃣ Provision a new child Session + operator
await sessionStore.createAgentGraphOperator({
  graphId,
  workId,
  operatorId,
  childSessionId,
  // …other provision fields
});

This establishes a stable identity for the operator that persists across system restarts, enabling the graph to reference specific Turn/Run IDs within that Session for deterministic execution.

Step 2: Declaring and Claiming Execution Intents

Once provisioned, operators declare their readiness to execute through intent claims. The system computes a deterministic projection of existing records (edges) and policy to generate a readiness intent, implemented in decodeAgentGraphIntentClaim and related helpers around lines 3081–3114 of the SQLite store.

To guarantee exactly-once execution, the graph binds this intent to a pre-allocated Turn/Run inside the child Session using claimAgentGraphIntent or claimAgentGraphIntentAtScheduleRevision:

// 2️⃣ Declare a new intent (e.g. “run specialist A after data X is ready”)
await sessionStore.claimAgentGraphIntent({
  graphId,
  intentId,
  workId,
  operatorId,
  // the intent includes a deterministic predicate over graph records
});

This binding ensures that the claimed Turn/Run executes exactly once, even across supervisor restarts or failovers.

Step 3: Executing Session-Inline Activations

When an intent becomes runnable, the Runtime executes the child Session’s AgentRun normally without requiring modifications to the core execution path. The function isSessionInlineRun in packages/runtime/src/session-manager.ts (line 106) identifies these Session-inline runs, which serve as the activation of the operator.

The output of this execution becomes immutable RuntimeEvents committed to the Session's history. These events are not directly consumed by downstream operators; instead, they are projected into the graph's read-model as records.

Step 4: Projecting Records and Resolving Dependencies

After execution completes, the RuntimeReadModel in packages/runtime/src/runtime-read-model.ts folds committed RuntimeEvents back into graph records and routes (edges). The readiness projection checks that required records from predecessor child Sessions are visible before marking dependent intents as runnable.

This dependency resolution mechanism, documented in the architecture draft's section “Two planes over one existing Runtime” (lines 55–63), ensures that downstream operators only activate after their required inputs exist as durable records in the graph.

Step 5: Updating the Schedule and Supervisor Wakes

The main Agent (supervisor) coordinates overall graph progression by writing schedule-update records via commitAgentGraphScheduleUpdate (lines 3234–3242 in the SQLite store). These updates may add new work, cancel existing work, or close the graph entirely:

// 5️⃣ Supervisor updates the schedule – e.g. adds a dependent work item
await sessionStore.commitAgentGraphScheduleUpdate({
  updateId,
  graphId,
  source: 'user',
  ops: [{ type: 'add', workId: newWorkId, operatorId: downstreamOperator }],
});

A durable AgentGraphSupervisorWake entry then signals the root Session to begin a new turn once the checkpoint is ready, triggering beginAgentGraphIntentExecutionAtScheduleRevision logic to continue the scheduling cycle.

Complete Implementation Workflow

The following pattern demonstrates the full lifecycle of scheduling dependent work, from provisioning through execution:

// 1️⃣ Provision a new child Session + operator
await sessionStore.createAgentGraphOperator({
  graphId,
  workId,
  operatorId,
  childSessionId,
  // …other provision fields
});

// 2️⃣ Declare a new intent (e.g. “run specialist A after data X is ready”)
await sessionStore.claimAgentGraphIntent({
  graphId,
  intentId,
  workId,
  operatorId,
  // the intent includes a deterministic predicate over graph records
});

// 3️⃣ When the intent becomes runnable, begin execution
const transition = await sessionStore.beginAgentGraphIntentExecutionAtScheduleRevision({
  graphId,
  intentId,
  // optionally specify the current schedule revision to avoid races
});

// 4️⃣ After the child Session’s AgentRun finishes, commit its RuntimeEvents
// (handled automatically by the runtime; no extra code needed)

// 5️⃣ Supervisor updates the schedule – e.g. adds a dependent work item
await sessionStore.commitAgentGraphScheduleUpdate({
  updateId,
  graphId,
  source: 'user',
  ops: [{ type: 'add', workId: newWorkId, operatorId: downstreamOperator }],
});

Key Source Files

File	Role
packages/runtime/src/session-manager.ts	Public API that orchestrates child-Session provisioning, intent claims, and schedule updates via isSessionInlineRun detection.
packages/storage/src/sqlite-session-metadata-store.ts	SQLite-backed control-plane containing createAgentGraphOperator, claimAgentGraphIntent, beginAgentGraphIntentExecutionAtScheduleRevision, and commitAgentGraphScheduleUpdate.
packages/runtime/src/runtime-read-model.ts	Projects committed RuntimeEvents into graph records and routes used by readiness projections.
docs/architecture/agent-graph-stream-scheduling-draft.md	Narrative architecture description of the two-plane model and dependency scheduling semantics.

Summary

• Child Sessions as Operators: Apache Maka treats each child Session as a durable operator container, provisioning them atomically via createAgentGraphOperator in the SQLite metadata store.
• Intent-Based Scheduling: Dependent work is scheduled through deterministic intent claims (claimAgentGraphIntent) that bind to specific Turn/Run IDs, guaranteeing exactly-once execution without duplicates or omissions.
• Immutable Records: RuntimeEvents from Session-inline AgentRuns become read-only graph records that the RuntimeReadModel projects into routes for downstream dependency resolution.
• Control-Plane Coordination: The Agent Graph uses SQLite-backed schedule revisions and supervisor wakes to coordinate arbitrarily-deep dependency trees while re-using the existing Runtime execution engine.

Frequently Asked Questions

What distinguishes the Agent Graph control-plane from the Runtime data-plane?

The Agent Graph control-plane manages metadata—specifically operator-session bindings, intent claims, and schedule revisions—stored in SQLite, while the Runtime data-plane handles the actual execution of AgentRuns and commits RuntimeEvents. This separation allows the graph to coordinate dependent work without creating a second execution engine or modifying core Runtime semantics.

How does Apache Maka ensure exactly-once execution for dependent operators?

The system guarantees exactly-once execution by binding intents to pre-allocated Turn/Run IDs inside child Sessions using claimAgentGraphIntentAtScheduleRevision. Once claimed, the intent is durably recorded in the SQLite store, ensuring that even across supervisor restarts or failovers, the same Turn/Run executes exactly once and produces immutable RuntimeEvents.

What role do child Sessions play in the Agent Graph architecture?

Child Sessions serve as operator containers that provide stable identity and state isolation for each unit of work in the graph. When activated via Session-inline AgentRuns, they produce immutable RuntimeEvents that the graph projects into records, enabling downstream operators to declaratively depend on specific outputs without direct coupling to the producing Session.

How does the graph resolve dependencies between operators?

The graph resolves dependencies through a readiness projection that examines committed records from upstream child Sessions. The RuntimeReadModel folds RuntimeEvents into graph records, and the intent claim logic (decodeAgentGraphIntentClaim) evaluates whether required predecessor records are visible before allowing a dependent operator's intent to become runnable and claimable.

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