Self-improving AI Employees for everyone
Node Parameter Panel — Logic Flow Documentation
Reference for the three-section node configuration UI (Input / Parameters / Output). Companion test suite in client/src/hooks/tests/ and client/src/components/parameterPanel/tests/.
The Parameter Panel is the modal that opens when a node is selected on the canvas. It has three columns that can be hidden independently depending on the node type:
+---------------------------------------------------------------+
| header: icon + name + Run / Save / Cancel |
+----------------+--------------------------+-------------------+
| Input section | Middle section | Output section |
| (left) | (parameters / config) | (right) |
| flex 0.7 | flex 1.6 | flex 0.7 |
+----------------+--------------------------+-------------------+
Files:
- client/src/ParameterPanel.tsx — modal shell
- client/src/components/parameterPanel/ParameterPanelLayout.tsx — flex layout
- client/src/components/parameterPanel/InputSection.tsx
- client/src/components/parameterPanel/MiddleSection.tsx
- client/src/components/parameterPanel/OutputSection.tsx
- client/src/components/output/OutputPanel.tsx — execution-results renderer (no edge walking; see §6)
- client/src/utils/parameterVisibility.ts —
shouldShowParameter(shared by MiddleSection + ParameterRenderer) - client/src/components/ParameterRenderer.tsx — universal widget
- client/src/hooks/useParameterPanel.ts
- client/src/hooks/useDragVariable.ts
1. Lifecycle
- User clicks a node on the canvas →
selectedNodeset in Zustand store. ParameterPanelmounts →useParameterPanel()fires.- Hook reads defaults from
nodeDefinition.properties[].default, then asks backend for any saved parameters via WebSocketget_node_parameters. Saved values overlay defaults. The buffer is seeded only once the saved row has arrived: until then (socket not ready yet, read failed)isLoadingstays true and Save is refused, because a save replaces the node's whole row. - Modal renders three sections;
MiddleSectionfilters parameters viadisplayOptions.show(see §4 invariants), then renders each visible parameter throughParameterRenderer. - User edits →
handleParameterChange(name, value)updates local state.hasUnsavedChangesflips true (computed viaJSON.stringifyequality with original). - Save → WebSocket
save_node_parameters→ DB; on successoriginalParametersupdated. - Run → if
hasUnsavedChangessave first, thenexecuteNodeViaWebSocket. - Cancel → revert pending edits, clear selection, close modal.
2. Section Visibility Rules
| Node type bucket | Input | Middle | Output |
|---|---|---|---|
| Start | hidden | shown | hidden |
| Skill (e.g. masterSkill, single skill nodes) | hidden | shown | hidden |
Monitor (teamMonitor) |
hidden | shown | hidden |
| Everything else | shown | shown | shown |
The buckets are not frontend type lists: ParameterPanel.tsx (around lines 141–150) reads
hideInputSection / hideOutputSection / hideRunButton straight off the node's backend
NodeSpec uiHints and passes the derived flags to ParameterPanelLayout. A plugin that wants the
Start / Skill / Monitor shape declares those hints itself (Wave 10.G.5); nothing in the client
matches on node.type.
3. Template Variable Naming (drag-and-drop contract)
When the user drags a value from OutputPanel into a parameter input, the dragged payload is a
template string {{name.path}} plus a JSON sidecar with metadata.
name is resolved by useDragVariable.getTemplateVariableName(sourceNodeId) with this strict
priority:
node.data.label— user-renamed labelnodeDefinition.displayName— built-in display namenodeType— registered type namenodeId— final fallback
In every case the result is lowercased and whitespace-stripped ('My Cron Scheduler' →
'mycronscheduler').
The drag payload is set on both MIME types:
text/plain→ the template string{{name.path}}(used by simple text inputs)application/json→{type: 'nodeVariable', nodeId, nodeName, key, variableTemplate, dataType}
effectAllowed is 'copy'.
Drop discriminators
ParameterRenderer.handleDrop branches on application/json's type. The three
have different write semantics, which is the whole reason they are separate —
reusing one for another's payload silently destroys user input.
type |
Produced by | Payload | Write semantics |
|---|---|---|---|
nodeVariable |
useDragVariable (InputSection) |
{nodeId, nodeName, key, variableTemplate, dataType} |
Appends variableTemplate with smart spacing |
nodeOutput |
nothing currently — the branch exists but has no producer | {value} |
Replaces unconditionally |
workspaceFile |
useDragWorkspaceFile (GalleryPanel) |
{path, ref} — ref is a finished serialized FileRef from the server |
Conditional: a file param takes ref whole; every other param appends path with smart spacing |
Two details that look incidental and are not:
workspaceFileis deliberately notnodeOutput. That branch replaces the target value with no type check, so dropping a file into a half-written prompt would erase the prompt.- Its
text/plainfallback is the bare workspace-relative path, so a drop onto a plain<textarea>(or an editor outside the app) still lands something useful. Directories are non-draggable — the server sends themref: null, and appending a bare folder path into a prompt was never the intent.
4. Parameter Visibility (displayOptions.show)
Each INodeProperties entry can include a displayOptions.show map. Values can be arrays
(allowed-values list) or scalars (single allowed value). All conditions must hold:
displayOptions: {
show: {
operation: ['create', 'update'], // operation must be one of these
useProxy: [true], // AND useProxy must be true
}
}
When ALL conditions match the parameter renders; otherwise it's hidden.
A parameter without displayOptions.show always renders.
shouldShowParameter in client/src/utils/parameterVisibility.ts
implements this. It was extracted out of MiddleSection.tsx so that ParameterRenderer (nested
collection options, line 760) can share it and so tests can import it directly —
client/src/components/parameterPanel/tests/MiddleSection.test.tsx
exercises the pure function (array membership, scalar equality, AND across keys, type-coercion
edges). line 187).MiddleSection applies it in its parameter filter (
5. Connection Discovery (Input + Output)
InputSection walks the workflow's edges to figure out which other nodes feed the current one
(OutputPanel no longer does any edge walking — it only renders results). Its isConfigHandle
helper (~line 258) classifies handles into two buckets:
| Handle bucket | Examples | Effect |
|---|---|---|
| Data flow | input-main, input-chat, input-task, input-teammates |
shown as connected nodes |
| Config / auxiliary | every other input-* — input-context, input-tools, input-skill, input-model |
hidden on agents that declare uiHints.hasSkills — they belong to the dedicated UI in MiddleSection |
input-memory is retired (RFC-0002): normalize_workflow_graph rewrites legacy simpleMemory -> input-memory edges into a Context node plus an ordinary input-tools edge, so the handle never
reaches this code on a normalised graph.
Plus a special case for config nodes themselves: a node is a config node when its NodeSpec
carries uiHints.isConfigNode === true (auto-derived on the backend by _derive_auto_ui_hints for
any plugin whose group contains memory or tool; canvas opts out explicitly). When the user is
viewing one, the panel inherits the parent agent's main inputs and labels them via <Agent Name> so
the user can still drag those upstream variables into the config node's parameters. The client never
inspects group strings for this.
6. Output Display (OutputSection)
OutputSection combines two sources of execution data:
executionResults— local results from in-modal Run button.nodeStatuses[selectedNode.id]— push updates from workflow runs via WebSocket.
The WebSocket result is folded in at the front (newest-first) only when its outputs field
isn't already present in executionResults (deduplicated via JSON.stringify). Statuses other
than success/error (e.g. running) are ignored.
Rendering lives in client/src/components/output/OutputPanel.tsx
(the active and only renderer; the former ui/OutputDisplayPanel.tsx was deleted). The Response
section picks, in order: response / output / text / content (prose keys), then an
object-typed result (the canonical payload key CLI nodes fill with server-side-parsed JSON —
arrays survive unwrap un-peeled and surface here), then stdout. Objects/arrays render in the
themed @uiw/react-json-view tree. Strings render through ReactMarkdown unless the node's
NodeSpec declares uiHints.outputMode = "terminal" (CLI-wrapper plugins: githubAction,
vercelAction, shell) — then they render preformatted in a <pre> on the per-theme
--code-* surface, with wholly-JSON strings detected via the shared tryParseJson
(utils/formatters.ts) and routed to the tree instead. The panel resolves the spec via
useNodeSpec(selectedNode?.type) — backend owns display logic, no node-name checks.
7. Refactor Invariants
Locked in by the test suite at:
- client/src/hooks/tests/useParameterPanel.test.tsx
- client/src/hooks/tests/useDragVariable.test.ts
- client/src/components/parameterPanel/tests/MiddleSection.test.tsx
- client/src/components/parameterPanel/tests/InputSection.test.tsx
- client/src/components/parameterPanel/tests/OutputSection.test.tsx
- Defaults loaded from
nodeDefinition.properties[].default; missing default ⇒null. - Saved params win over defaults when merged (DB is source of truth).
No row, no seed:
get_node_parametersanswers{parameters: {}}for a node without a saved row, so anullreply is a failed read.fetchSavedNodeParams(useNodeParamsQuery.ts) throws on it for every query on thenodeParamskey, so the cache never holds a failed read as an empty row; the panel shows the failure as a toast and Save stays refused. hasUnsavedChangesis a deep-equal check against the original snapshot loaded from DB.- Save routes to
save_node_parametersand updates the original snapshot on success. - Cancel restores the pending edits and clears
selectedNode. - Drag template variable uses the priority
label > displayName > nodeType > nodeId, normalised to lowercase + no whitespace. - Drag payload sets both
text/plainandapplication/json;effectAllowed = 'copy'. displayOptions.showhides a parameter unless ALL keyed conditions match. Array values are membership checks; scalar values are equality checks.- Config handles (
input-memory|tools|skill|model) are SKIPPED by bothInputSectionandOutputPanelfor agent nodes — those dependencies surface in MiddleSection. input-main|chat|task|teammatesare NEVER skipped — they are data flow.- Memory / tool config nodes inherit their parent agent's main inputs and label them
via <Agent Name>so upstream variables remain draggable. - OutputSection deduplication compares result
outputsviaJSON.stringifybefore folding in WebSocket status into local results. Onlysuccess/errorstatuses fold in.
8. Run / Save / Cancel Buttons
- Run disabled while
isExecuting. Prefixed by an autosave whenhasUnsavedChanges. - Save disabled when
!hasUnsavedChanges. - Cancel/Stop acts as Stop (cancels event-wait via WebSocket) when the node is in
waitingstate; otherwise plain Cancel that reverts edits and closes the modal.
9. Test Run
bun install
bun --cwd=client run test -- src/hooks/__tests__/useDragVariable.test.ts \
src/components/parameterPanel/__tests__
Or use the dedicated script (added in client/package.json):
bun --cwd=client run test:nodepanels