Execution Paths

Every graph run in AgentCanvas — whether you click ▶ Play on the canvas or submit a batch-eval job — bottoms out in the same two-class engine: LoopRunner.run() driving GraphExecutor.run(). The two paths differ only in how that LoopRunner is created and wrapped — never in how nodes fire. This page is the class-by-class map of both paths and where they converge. For the firing engine itself see graph-executor; for the eval harness internals (workers, parallelism, persistence) see batch-eval; rationale in ADR-eval-001 + ADR-platform-002.

Two entries, one engine. Each lane is a real call chain (labelable file·function); both funnel into the shared LoopRunner → GraphExecutor band. Above the band the two paths differ; from the band down they are identical.

1. What it does

There are exactly two ways a graph gets executed:

• Canvas Play — an interactive single run you launch from the UI to watch an agent step live.
• Batch Eval — a headless run of the same graph across many episodes, aggregated into metrics.

Both reduce to one engine: a LoopRunner (the control-plane shell) calling GraphExecutor.run() (the firing engine). Everything that differs between the two paths lives above that call — in the wrapper classes that decide:

• who is allowed to run — ExecutionGuard (canvas, single-tenant) vs JobScheduler (eval, VRAM-admitted);
• where it runs — in the backend process (canvas) vs a spawned subprocess (eval, default);
• which LoopRunner — a process-global singleton (canvas) vs a fresh one per episode (eval);
• how calls are routed — none (canvas) vs per-worker env_panel_overrides / server_url_overrides (eval);
• logging + eval flags — self-created canvas logger vs injected per-episode logger + ExecutionPrinciples.

The name LoopRunner is slightly misleading: it has no loop of its own — the iteration lives entirely inside GraphExecutor.run() (the ready-queue). "Loop" names the agent loop it executes, not a loop in its body.

Smallest of each

The smallest canvas run is one POST carrying the whole graph; the smallest eval is a graph name + an episode count (everything else defaults):

# Canvas Play — fire-and-forget single run (run.py·run_loop)
POST /api/navigate/run
{ "loop_definition": { ...full GraphDefinition JSON... }, "execution_id": "uuid" }
# → { "ok": true, "execution_id": "uuid" }   (runs in a background asyncio task)

# Batch Eval — queued multi-episode run (eval.py·start_eval_v2)
POST /api/eval/v2/start
{ "graph_name": "navgpt_mp3d", "episode_count": 10 }
# → { "run_id": "20260616_...", "status": "queued" }   (JobScheduler admits → subprocess)

2. The shared engine (convergence point)

Both paths converge here. These two classes never change between canvas and eval — only their caller and wrapping do.

See graph-executor for the ready-queue, iteration, and the after-loop verdict; loop-control-system for the iterIn/iterOut pivots.

3. Canvas Play path (single run, in-process)

One endpoint, the singleton runner, a fire-and-forget task. No subprocess, no worker pool, no eval flags.

1. run.py · run_loop — the POST /api/navigate/run handler. Validates the graph (validate_graph_connectivity), auto-loads any missing nodesets (WorkspaceComponentRegistry.ensure_nodesets_for_graph), warns on wire-type mismatches, fetches global hooks.
2. ExecutionGuard.acquire(ExecutionMode.canvas) (state.py) — the single-tenant lock. Canvas and eval are mutually exclusive; if an eval (in-process) holds it, the request returns 409.
3. get_loop_runner() (loop_runner.py) — returns the process-global singleton LoopRunner. Constructed with defaults: principles=None, empty overrides, no injected logger.
4. asyncio.create_task(_run_and_release()) — wraps runner.run(graph, step_delay_ms, global_hooks=…) and releases the guard in a finally. The HTTP call returns {ok, execution_id} immediately; the run continues in the background. The task handle is stored on runner._task here (see §6).
5. Inside runner.run(): with no injected logger, LoopRunner self-creates an ExecutionLogger at outputs/runs/<execution_id>/ and writes graph.json for replay, then builds a fresh GraphExecutor and awaits it.
6. Controls — /run/pause, /run/stop, /run/status, /run/checkpoints, /run/restore/{step} all operate on the same singleton. Pause/stop just flip the runner's Events, which the in-flight executor polls between steps.

4. Batch Eval path (many episodes, subprocess)

A queued, admission-gated, subprocess-isolated run that fans out over workers and builds one LoopRunner per episode. The class roster (top to bottom):

This page stays at the class-roster level. For the eval internals — worker independence, the replicated vs shared parallelism contract, partial-result harvesting, and the on-disk layout — read batch-eval.

5. Where the paths converge & diverge

The convergence point is LoopRunner.run(). Everything above it differs; everything from it down (the engine, node firing, state, termination) is identical.

6. Where it deviates from the clean model