# Flow Control Nodes

> Applies to: ChengOS v0.2.0+ ｜ Last verified: 2026-09-25 ｜ Source: `crates/cheng-nodes/src/nodes/builtin/utils`

These nodes decide where data goes and what shape it arrives in. `utils/condition_router` is the
deterministic branch — simple mode is one rule with a true/false pair of outputs, advanced mode is a
multi-rule switch with one output per branch. Reach for it before an LLM branch whenever the rule can
be written down. `utils/to_items` fans a single value out into items for downstream iteration,
`utils/type_cast` fixes type mismatches at a connection, `utils/smart_var` holds a named value you want
to reference from several places, and `utils/delay` paces calls against a rate-limited service.

## Condition Router — `utils/condition_router`

Route by field conditions: supports operator comparison, dot nested path, Schema hint generation, enhanced fallback metadata

### Inputs

| Field | Type | Required | Default | Description |
|---|---|:-:|---|---|
| `context` | object (port) | — | `null` | Input AgentContext (optional). Connection port, not a form field. Control: `code-editor` |
| `response` | string | — | `""` | LLM response text (JSON format). Control: `code-editor` |
| `custom_data` | string | — | `null` | Custom JSON data. Control: `code-editor` |
| `payload_source` | enum | — | `response` | Select data extraction source. Control: `select`. Options: `response` (从 response 字段解析 JSON), `context` (从完整 context 序列化为 JSON), `custom` (从 custom_data 字段取值) |
| `branch_fields` | array<object> | — | `[]` | Branch field list (click + to add; each entry auto-generates a corresponding output port) |
| `strict_mode` | boolean | — | `false` | Error on JSON parse failure (false routes error reason to fallback output) |
| `generate_schema` | boolean | — | `false` | Enable auto-generated JSON Schema hint output to schema_hint port (can connect to upstream LLM's system_prompt) |
| `mode` | enum | — | `advanced` | Simple (If: one rule, True/False) or Advanced (Switch: multi-rule, multi-output). Control: `select`. Options: `simple` (If 模式：单条件，True / False 输出), `advanced` (Switch 模式：多规则多输出（默认，兼容旧行为）) |
| `match_policy` | enum | — | `all` | First: stop at first match. All: output all matched branches (default). Control: `select`. Options: `first` (仅输出第一个命中的分支), `all` (所有命中的分支都输出（默认）) |
| `fallback_mode` | enum | — | `fallback_output` | FallbackOutput: route to fallback_out (default). None: skip. Output0: route to first branch port. Control: `select`. Options: `fallback_output` (输出到 fallback_out 端口（默认）), `none` (不输出，下游自动跳过), `output0` (输出到第一个分支端口) |

### Outputs

| Field | Type | Description |
|---|---|---|
| `branch_outputs` | array<any> (port) | Branch output list, corresponding 1:1 with branch_fields (AgentContext on match, null on miss). Connection port, not a form field. |
| `fallback_out` | object | Fallback output (acts as 'False' in Simple mode). Fires when no branch rule matches. Includes diagnostic metadata. |
| `context_out` | object | Legacy fallback output (use fallback_out instead). Mirrors fallback_out for backward compatibility. |
| `schema_hint` | object (port) | Auto-generated structured output hint (can connect to upstream LLM node's system_prompt port). Connection port, not a form field. |

## Smart Variable Node — `utils/smart_var`

Auto-detect text variables, dynamically generate ports, support full output and picked variable extraction

### Inputs

| Field | Type | Required | Default | Description |
|---|---|:-:|---|---|
| `template` | string | ✅ | — | Raw text (supports JSON/curl/YAML, etc.). Control: `textarea` |
| `extract_mode` | enum | — | `auto` | Extract mode: auto=auto-detect key names, manual={{var}} syntax only. Control: `select`. Options: `auto`, `manual` |
| `output_vars` | array<string> | — | `[]` | List of variables to include in output. Control: `multi-select`. Options loaded from `ports` |

### Outputs

| Field | Type | Description |
|---|---|---|
| `full_text` | string | Full text after variable substitution |
| `selected_vars` | object | Picked variable key-value pairs |
| `all_variables` | array<string> | All extracted variable names |
| `preview_content` | string | Formatted preview content |
| `statistics` | object | Variable extraction statistics |

## To Items — `utils/to_items`

Normalize any input into a loop-ready items array for LoopContainer

### Inputs

| Field | Type | Required | Default | Description |
|---|---|:-:|---|---|
| `input` | any | — | — | Data to convert into loop items |
| `mode` | enum | — | `auto` | How to convert the input. Control: `select`. Options: `auto` (Automatically detect input type.), `array` (Input is an array — pass through, normalizing each element.), `single` (Wrap any single value into a one-element array.), `split_text` (Split a string into text items.), `refs` (File / document / chunk reference passthrough — no content expansion.), `object_values` (Convert object key-value pairs into items.), `range` (Generate a numeric range as items.) |
| `chunkSize` | integer | — | `500` | Characters per chunk when Split By = Chunk. Control: `number` |
| `maxItems` | integer | — | `0` | Maximum number of items to emit (0 = unlimited). Control: `number` |
| `rangeEnd` | integer | — | `0` | Range end (exclusive, Range mode). Control: `number` |
| `rangeStart` | integer | — | `0` | Range start (inclusive, Range mode). Control: `number` |
| `rangeStep` | integer | — | `1` | Step between consecutive range values. Control: `number` |
| `splitBy` | enum | — | `paragraph` | Text split strategy (SplitText mode). Control: `select`. Options: `paragraph` (Split on blank lines (two consecutive newlines).), `line` (Split on every newline.), `sentence` (Heuristic sentence splitting (punctuation-based).), `chunk` (Fixed character chunk size.) |

### Outputs

| Field | Type | Description |
|---|---|---|
| `items` | any | Loop-ready items array |
| `count` | integer | Number of items in the array |
| `mode_used` | string | Conversion mode that was applied |

## Type Cast — `utils/type_cast`

Convert between common port types, with first-class AgentContext support

### Inputs

| Field | Type | Required | Default | Description |
|---|---|:-:|---|---|
| `agent_context` | object (port) | — | `null` | Connect AgentContext-like object here. Connection port, not a form field. |
| `text` | string (port) | — | `null` | Connect string/text output here. Connection port, not a form field. |
| `json` | object (port) | — | `null` | Connect object output here. Connection port, not a form field. |
| `array` | array<any> (port) | — | `null` | Connect array output here. Connection port, not a form field. |
| `integer` | integer (port) | — | `null` | Connect integer output here. Connection port, not a form field. |
| `number` | number (port) | — | `null` | Connect number output here. Connection port, not a form field. |
| `boolean` | boolean (port) | — | `null` | Connect boolean output here. Connection port, not a form field. |

### Outputs

| Field | Type | Description |
|---|---|---|
| `agent_context` | object (port) | Converted AgentContext. Connection port, not a form field. |
| `text` | string (port) | Converted string. Connection port, not a form field. |
| `json` | object (port) | Converted object. Connection port, not a form field. |
| `array` | array<any> (port) | Converted array. Connection port, not a form field. |
| `number` | number (port) | Converted number. Connection port, not a form field. |
| `integer` | integer (port) | Converted integer. Connection port, not a form field. |
| `boolean` | boolean (port) | Converted boolean. Connection port, not a form field. |
| `source_type` | string | Selected input source type |

## Delay Node — `utils/delay`

Add delay in workflow, for testing pause and stop functionality

### Inputs

| Field | Type | Required | Default | Description |
|---|---|:-:|---|---|
| `delay_type` | enum | — | `fixed` | fixed, random range, until timestamp, until time of day, fixed with jitter, or exponential backoff. Control: `select`. Options: `fixed` (固定时长延迟), `random_range` (随机区间延迟), `until_timestamp` (延迟到绝对时间戳), `until_time_of_day` (延迟到某个本地时间), `fixed_with_jitter` (固定延迟并附加抖动), `exponential_backoff` (指数退避) |
| `delay_value` | integer | — | `5` | Delay time value (used with unit). Control: `number` |
| `delay_unit` | enum | — | `seconds` | Delay time unit: milliseconds or seconds. Control: `select`. Options: `milliseconds` (毫秒), `seconds` (秒), `minutes` (分钟), `hours` (小时) |
| `max_delay_value` | integer | — | `null` | Upper bound for random range delay. Control: `number` |
| `target_timestamp` | string | — | `null` | RFC3339 timestamp or local datetime interpreted with timezone. Control: `datetime-local` |
| `time_of_day` | string | — | `null` | Local target time in HH:MM or HH:MM:SS |
| `timezone` | string | — | `UTC` | IANA timezone for local datetime interpretation; defaults to UTC |
| `jitter_percent` | integer | — | `null` | Maximum +/- jitter percentage for fixed_with_jitter mode. Control: `number` |
| `attempt` | integer | — | `null` | Zero-based attempt number for exponential_backoff mode. Control: `number` |
| `initial_delay_value` | integer | — | `null` | Initial delay value for exponential_backoff mode. Control: `number` |
| `max_backoff_value` | integer | — | `null` | Maximum delay value for exponential_backoff mode. Control: `number` |
| `multiplier` | number | — | `null` | Growth multiplier for exponential_backoff mode. Control: `number` |
| `log_message` | string | — | `null` | Log message: output before and after delay |
| `passthrough` | any | — | `null` | Passthrough data: forwarded as-is to output port |

### Outputs

| Field | Type | Description |
|---|---|---|
| `completed` | boolean | Whether delay completed normally |
| `actual_delay_ms` | integer | Actual delay duration (milliseconds) |
| `passthrough` | any | Passthrough data from input |
| `log_message` | string | Passthrough log message from input |
| `context` | object | AgentContext combining log_message and passthrough |
| `info` | object | Detailed delay execution info |

## Next steps

- [System & Safety Nodes](/docs/nodes-utils-system)
- [Variables & Data Mapping](/docs/editor-variables-and-mapping)
- [Execution Model: DAG, Scheduling, State](/docs/exec-model)