Skip to content
threadle

Iterator

The ∀ Iterator turns one text wire into a list. Downstream, an agent runs once per item instead of once for the whole blob.

It requires an input. An unwired iterator is a loose end.

Split modes

Section titled “Split modes”
ModeNode labelBehavior
lineslinesSplit on newlines. Each line trimmed, blanks dropped
blocksblank-line blocksSplit on blank lines. Each block trimmed, blanks dropped
jsonJSON arrayJSON.parse the text. Array elements become items (non-string elements are re-serialized)

Several inbound wires are joined with a blank line before splitting.

max caps the list. Leave it empty (∞) for no limit. The cap is applied after splitting, so it takes the first N items.

JSON that fails to parse is a difference between the two runners: the canvas run raises iterator: input is not a JSON array, while a detached run falls back to treating the whole text as a single item.

The run log records the result: ∀ iterator: 3 item(s) (lines) (append , parallel when map mode is parallel).

Map mode (serial vs parallel)

Section titled “Map mode (serial vs parallel)”
ModeBehavior
serial (default)One conversation: each item continues the previous session id. threadle-shaped for “triage these failures in one brain.”
parallelFresh session per item. Concurrency capped by graph ǁ parallelism (settings.ply). Do not reuse a linked session. Join answers with an explicit Merge downstream. The iterator does not auto-join.

Graph lint hints when a parallel iterator has no Merge reachable downstream.

✎ Prompt ──▶ ∀ parallel ──▶ ⟨/⟩ Agent ──▶ ⋈ Merge ──▶ ⇤ Output
 3 lines        ply=2         3 fresh          concat

What downstream sees

Section titled “What downstream sees”

The iterator emits both the original joined text and the item list. Only an agent consumes the list:

  • ⟨/⟩ Agent. Runs once per item (serial: one session. Parallel: fresh sessions under ply). Result texts are collected in item order.
  • Anything else. Sees the unsplit text and behaves normally.

Collected replies leave the agent joined with \n\n---\n\n, and the item list is carried forward so a further agent could iterate again. The session the agent emits is from the last finished item (parallel: whichever call finished last).

✎ Prompt ──▶ ∀ Iterator ──▶ ⟨/⟩ Agent ──▶ ⇤ Output
 3 lines        lines          3 runs       joined

Notes

Section titled “Notes”
  • A per-item run costs a provider call each. Pair an iterator with max and a circuit breaker when the upstream list length is not under your control.
  • Bypass on the iterator forwards the inbound text untouched, so the agent runs once. A quick way to test the tail of a graph.
  • Partial runs that start below an iterator forward text unsplit. Only an executed iterator fans out.

Examples

Section titled “Examples”
ExampleLevelShape
iterator-linesintermediateprompt → ∀ lines → output. Split alone
iterator-agentadvanced∀ serial → Cursor ask once per question
iterator-paralleladvanced∀ parallel → asks under ply → ⋈ Merge
Terminal window
threadle run iterator-lines --approve-all
threadle run iterator-parallel

iterator-agent / iterator-parallel call a real provider CLI unless you are in the test suite.

Section titled “Related”