Design Docs
Deep-dive references for AgentCanvas developers and contributors — system internals and subsystem specs, grouped by contract owner. Read on demand when you're building or debugging the relevant piece.
Pages are grouped by which layer owns the contract — each group's index states a one-line membership test. A page that passes no test stays flat at this level (flat is the legal default, not a failure). The pre-2026-06-11 flat layout and global card numbering are gone; per-domain support-status registries moved to nodesets/status/.
§ 1 Graph & Execution
How a graph is represented and executed — topology, typed values on wires, state, firing order, and how that execution is driven across many episodes (batch eval). ADR fields: dataflow + executor + eval.
Graph System
GraphDefinition, dual storage (graphs/ + graph_nodes/), explorer, API
Wire Type System
Type catalog, serialisation, canvas colours, LIST[T] modifier
State Containers
Dual-wire state system — visible shared state, containers, checkpointing
Graph Executor
Node firing, iteration, state — the runtime engine
Loop Control System
Initialize / iterIn / iterOut pivots; multi-scope iteration; signal contract
Backend Overview
The "you are here" map — per-process singletons (ProcessServices, WorkspaceComponentRegistry, NODE_HANDLERS) + per-run objects, and who owns whom
Why a Component Registry
The argument from code — binds node-type strings to handlers + owns the env servers; why batch eval can't skip it
Execution Paths
Canvas Play & Batch Eval — the class stack behind every run, converging on LoopRunner → GraphExecutor
Canvas Play
The interactive single-run path — in-process, single-tenant, fire-and-forget, live WS streaming + pause / checkpoint / restore
Batch Eval System
Two processes, JobScheduler admission, replicated-spawn vs shared-borrow — executing a graph across many episodes
§ 2 Components
The contracts you implement when authoring a component — a node, a nodeset, an env panel — and their runtime obligations. ADR fields: canvas + components.
Canvas System
System view — composite nesting, navigation, node specs, registry
Base Canvas Node
Developer view — the one base class for tools / skills / policies / agents
NodeSets
Packaging unit — atomic lifecycle, local / auto-hosted / manual server modes
Nodeset Env Panels
Env-side runtime knobs — suite/episode, parallelism contract, scope boundary
Env & Episode Lifecycle
Five nested scopes, three signals — lifecycle ownership across panel / nodes / engine
§ 3 Operations
How the system is run and observed — serving, configuration, logs. ADR fields: server + observability.
Server Mode
BaseServer, ServerApp, manifest, lifecycle, parallelism gate
LLM/VLM Configuration System
Multi-provider profiles, env vars, CLI, per-node selection + usage hook
Execution Logs
Two-layer logging — executor exterior + node interior, JSONL, per-node usage hook
§ 4 API Surfaces
HTTP and programmatic API surfaces consumed by external programs — coding agents, search operators — rather than by humans in the UI. ADR field: platform.
Coding-Agent Backend Surface
Programmatic API surface — HTTP + filesystem + process model
Search Operator API (RFC)
Planned BaseSearchOperator + SearchLoop + Graph Mutation API; today's variant family is the working complement
§ Sibling sections
- capabilities/ — the nine things AgentCanvas does, with implementation walkthroughs (v2 ✓)
- core/ — blueprint, architecture, codebase-map, glossary, roadmap, decisions (v2 ✓)
- nodesets/status/ — per-domain support-status registries (VLN / VLA / EQA), moved out of design-docs 2026-06-11