Stream Graph Scheduling in Mako: How It Enables Parallel Execution Without a New Runtime

Stream Graph scheduling in Mako lets you run independent tasks in parallel by treating your execution graph as a durable schedule that coexists with the existing Session and Runtime Event Log, eliminating the need for a separate Agent runtime.

Mako's Stream Graph scheduling is a control-plane extension that adds parallelism to the existing execution engine without duplicating infrastructure. Instead of building a second runtime, Apache Maka (the open-source project formerly codenamed "Mako") projects immutable execution records into a queryable graph structure that can dispatch concurrent work across isolated child Sessions.

What Is Stream Graph Scheduling in Mako?

Stream Graph scheduling is a two-plane architecture that separates control from data. The Control Plane—backed by SQLite—stores topology, schedule revisions, intent claims, and supervisor wakes. The Data Plane remains the familiar Session plus RuntimeEvent log that owns all execution facts.

According to the design document, the graph never replaces the Runtime Event Log. Instead, stream-graph-projection.ts transforms immutable RuntimeEvent records into graph records that can be routed across operators. This projection layer lives in packages/runtime/src/stream-graph-projection.ts.

How the Two-Plane Model Enables Parallel Execution

The separation of concerns is what makes parallel execution possible without complexity.

Control Plane Responsibilities

The SQLite-based Control Plane handles:

• Topology definitions and schedule revisions
• Readiness intent computation
• Exactly-once admission claims
• Supervisor wake coordination

Data Plane Continuity

The existing Session/Runtime infrastructure continues to:

• Own execution facts and history
• Provide lifecycle management
• Enforce permissions
• Handle context compaction

Because the Data Plane is unchanged, every parallel task inherits battle-tested isolation guarantees.

Operator Containers: Child Sessions as Execution Units

Each child Session acts as an operator container. In packages/runtime/src/graph-mode.ts, the update_agent_graph tool provisions these containers once, then reuses them for many AgentRun activations.

This reuse is critical for performance: the Session's existing features—lifecycle, permission, history, compaction—apply automatically to every scheduled work item. You don't re-implement isolation; you get it for free.

Deterministic Readiness and Exactly-Once Admission

Parallel execution in Mako relies on two deterministic guarantees implemented in packages/runtime/src/stream-graph-readiness.ts and packages/runtime/src/stream-graph-admission.ts:

Readiness intent — A deterministic projection that discovers runnable work based on existing records and policy. Recomputing readiness never executes work; it only identifies candidates.

Admission claim — A single-flight SQLite decision that records an exactly-once claim binding a specific Session/Turn/Run identity. This prevents duplicate execution even if readiness is recomputed multiple times.

The scheduler in packages/runtime/src/stream-graph-schedule-reconcile.ts dispatches claimed work, while stream-graph-coordinator.ts orchestrates the coordinator lifecycle, handling projections and supervisor wakes without blocking graph advancement.

Parallelism Emerges from DAG Structure

No explicit "parallel thread" primitive is required. Here's how Stream Graph scheduling enables parallel execution:

1. Add independent work items via update_agent_graph
2. When readiness intent is satisfied (upstream records present), admission grants claims
3. The Runtime executes claimed work concurrently in separate child Sessions
4. SQLite's scheduler and the graph's DAG structure drive actual concurrency

The design document notes that supervisor-driven checkpointing can request wakes for new root turns without blocking record projection—so the graph advances even when the supervisor is offline.

Practical Example: Scheduling Parallel Tasks

This TypeScript example shows how to schedule independent work and collect results using the Stream Graph API:

// Schedule independent work items using the built-in tool
await runtime.callTool('update_agent_graph', {
  add_work: [
    { workId: 'w1', operatorId: 'opA', payload: { prompt: 'Inspect code A' } },
    { workId: 'w2', operatorId: 'opB', payload: { prompt: 'Inspect code B' } },
  ],
});

// Each work runs in its own child Session (operator) in parallel
// The scheduler automatically creates child Sessions and records admission claims

// After completion, read committed results via the graph API
const resultA = await runtime.callTool('agent_output', {
  child_session_id: '<session-id-for-opA>',
  run_id: '<run-id-for-opA>',
  view: 'result',
  max_bytes: 32768,
});

const resultB = await runtime.callTool('agent_output', {
  child_session_id: '<session-id-for-opB>',
  run_id: '<run-id-for-opB>',
  view: 'result',
  max_bytes: 32768,
});

// Finish the graph when all results are collected
await runtime.callTool('update_agent_graph', {
  finish: true,
  resultRecordIds: [resultA.resultRecordId, resultB.resultRecordId],
});

Key Source Files for Stream Graph Scheduling

File	Purpose
packages/runtime/src/graph-mode.ts	High-level API for update_agent_graph scheduling
packages/runtime/src/stream-graph-projection.ts	Projects RuntimeEvent records into graph records
packages/runtime/src/stream-graph-readiness.ts	Computes deterministic readiness intents
packages/runtime/src/stream-graph-admission.ts	Single-flight SQLite exactly-once claims
packages/runtime/src/stream-graph-schedule-reconcile.ts	Reconciles schedules and dispatches work
packages/runtime/src/stream-graph-coordinator.ts	Orchestrates coordinator lifecycle and supervisor wakes

Summary

• Stream Graph scheduling adds a durable, reusable schedule alongside Mako's existing Session/Runtime infrastructure
• Two-plane design (Control Plane SQLite + Data Plane Session/Event Log) avoids building a second runtime
• Child Sessions serve as operator containers with automatic isolation, lifecycle, and permission enforcement
• Deterministic readiness and admission provide exactly-once execution guarantees without blocking
• Parallelism emerges naturally from DAG structure and SQLite scheduling—no explicit thread management required

Frequently Asked Questions

How does Stream Graph scheduling differ from traditional Actor model parallelism?

Traditional Actor systems spawn separate runtime entities with their own mailbox and state. Mako's Stream Graph scheduling instead treats parallelism as a projection problem: work items become nodes in a durable graph, and the existing Session infrastructure executes them. You get concurrency without the complexity of message passing, supervision trees, or runtime restarts.

Can Stream Graph scheduling handle dependencies between parallel tasks?

Yes. Dependencies emerge naturally from the DAG structure. A work item's readiness intent specifies which upstream records must exist before admission. The scheduler in stream-graph-schedule-reconcile.ts only grants claims when all dependencies are satisfied, ensuring correct execution order without explicit synchronization code.

What happens if a child Session fails during parallel execution?

Failure recovery leverages the existing Session and RuntimeEvent Log infrastructure. Because execution facts remain in the Data Plane, the supervisor can observe failure records, update the graph schedule, and trigger retries or compensations. The exactly-once admission guarantees prevent duplicate execution even across recovery attempts.

Does Stream Graph scheduling require SQL expertise to use?

No. Developers interact through the update_agent_graph tool in graph-mode.ts. The SQLite Control Plane is an implementation detail—scheduling, readiness, and admission happen automatically. You add work items and collect results; the runtime handles the graph mechanics.

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