Automation Builder Architecture
The Wardian automation builder is the current node-based authoring surface for automation blueprints. It edits the markdown-backed Blueprint model consumed by wardian_core::automation and executed by the durable automation engine.
The old automation system visual builder produced JSON AutomationDefinition records. Treat AutomationDefinition and old trigger-node behavior as old automation system concepts, not the current authoring contract.
🎨 The Canvas
Built on top of React Flow, the canvas provides a drag-and-drop environment for positioning nodes and defining execution paths (edges).
Type-Safe Port System
Nodes communicate via defined input and output ports. The visual builder enforces "type-safety" at the connection level:
- Ports are visually and logically distinguished (e.g.,
default,body,done,on_true,on_false). - This maps directly to the current automation engine's graph execution model.
🧠 Integrated Variable Assistant (IVA)
A standout feature of the automation builder is the Integrated Variable Assistant (IVA). Instead of requiring users to memorize the exact dot-notation paths of upstream node outputs, the IVA provides a contextual, interactive cheat sheet.
How it Works
The IVA is implemented as a React component (VariableAssistant.tsx) that sits alongside the selected node fields. When a node is selected, the IVA calculates the specific execution path leading up to that node and displays available variables.
1. Upstream Context Calculation
The IVA uses a custom hook (useUpstreamContext.ts) to traverse the graph backwards from the currently selected node. It identifies all upstream nodes whose outputs are guaranteed to be available in the Registry when the selected node executes.
2. Deep Key Extraction
The IVA inspects the JSON schemas or known output structures of the upstream nodes and generates a visual tree of available variables.
3. Cycle Awareness
For complex automations involving loop nodes, the IVA distinguishes between:
- Upstream Outputs: Values generated in the current execution cycle.
- Cycle Contexts (PREV ITER): Values generated by nodes in a previous iteration of a loop, ensuring users don't accidentally reference stale data without intent.
4. One-Click Interpolation
Users can click any variable in the IVA tree (e.g., gatekeeper.decision). The IVA automatically wraps it in the correct Handlebars syntax (\{\{nodes.gatekeeper.output.decision\}\}) and copies it to the clipboard, ready to be pasted into prompt fields, file paths, or shell commands within the selected node's configuration.
Run Storage
The IVA also constantly displays the storage.* namespace, allowing easy access to the persistent key-value store scoped to the current automation run. Cross-run or cross-agent shared storage is not implemented by the automation engine.