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

> Learn how Apache Maka schedules dependent work using child sessions and deterministic intent claims for guaranteed exactly-once execution across deep dependency trees.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: deep-dive
- Published: 2026-08-30

---

**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`](https://github.com/apache/maka/blob/main/packages/storage/src/sqlite-session-metadata-store.ts), the `createAgentGraphOperator` function (lines 1039–1075) provisions both the child Session and its associated operator metadata:

```ts
// 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`:

```ts
// 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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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:

```ts
// 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:

```ts
// 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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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.