Babelfish

​

What it adds

• A flow engine. Deterministic flows registered as ordinary tools through the public contract — run a flow, step it, read its state, and abort it. Because they are tools, everything the platform already does to a tool applies: access control, backends, schedules, and tracing. Aborting a flow parked on an async ask while an answer to it is being driven does not cut that drive short: the abort is requested of it (flow_abort reports found: true with mode: "requested") and the drive honours it. Only such a requested abort waits for the live drive; an abort reported found: false lapses within 60 seconds and never aborts a later resume.
• A flow editor in the Studio. A front-end bundle the runtime serves to the Studio through its integrity-pinned import map, contributing a top-level Babelfish Flows page and its sidebar entry; the states a flow binds live on the platform States screen. On the canvas, nodes can be gathered into named, collapsible groups — a collapsed group renders as one card that hides its members and reroutes their boundary edges, and expanding it reveals them again. Groups persist with the flow and carry across the editable, run, read-only history, and reading views, showing an aggregated member status in Run mode; the collapse/expand toggle itself is a transient view preference and is not saved.

​

The explanation layer

​

Presets

​

Looping over a list

​

How a run runs: tool calls, loops and abort

{"config": {"entry_points": ["fetch"], "checkpoint_retention": {"waiting_minutes": 10, "finished_minutes": 5}}}

​

Inputs and results

​

Calling another flow: cancel, resume, start

• start_expr — shapes the held call’s start input. Absent starts the held target on the resolved node input; a jq giving null starts nothing; any other result merges over the resolved node input (a non-dict result wrapped as {input: …}), the expression’s keys winning on collision.
• cancel_expr — null, one parked-ask id, or a list of ids to cancel; a cancel tears the whole held chain down.
• resume_expr — a list of rows, one per ask of a step. Each row’s id_expr names the parked ask to resume and an optional payload_expr carries the answer; an absent payload takes the ask’s own default answer, a payload giving null resumes with null.
• warmstart_expr — the warm-start rows a Flow Call pre-fills its held flow’s nodes with.
• on_ask and send_up — where a caller ask goes (see the ask exit).

​

The ask exit and sending an ask up

• An ask exit (on_ask). Name a node in the flow as the ask exit and the holder routes to it when the held call settles with asks; its other outcomes take the ordinary edges. The card grows an extra ask exit handle, and wiring it is required — an unwired exit is a save error on a holder that can ask. The exit settles the held call’s caller asks itself and does not re-park on them: taking it releases the held run, which stays parked on its own ask, standalone. A holder — later in this run or in a later one — resumes it with its own resume_expr row and settles on the held run’s result; a released run’s result never re-enters the run that released it. The release is kept for twice the platform’s interactions idle TTL (INTERACTIONS_IDLE_TTL_SECONDS, 48 hours by default), counted from the exit and never extended, and a released agent must finish inside it. An ask exit whose held step’s reported deadline (the earliest of its open asks) does not end at least the park margin (one hour) before the window closes is refused before anything is written; an answer that still arrives after the window — a later ask of the same step, or a new ask the agent raises after a resume — is refused at delivery as a failure, never as the agent’s result (no park-index entry for interaction_id '<chain key>'; cannot resume): the resuming holder fails, so its On Error runs, or the flow fails when none is set. Keep every ask of a released agent inside the window, and the held step’s earliest deadline inside it by at least an hour. A held flow is not chained: its ask exit has no release and no window.
• Send up (send_up). Turn the send-up switch on and the holder parks the ask as a nested park and hands it up to this flow’s own caller unchanged, for a run further up to answer. With send-up on, there is no ask exit to wire.

​

Asking your caller

​

Expiry in a flow

• A held ask — an ask_node flow called through a holder — derives its behaviour from its outcome. Wire the holder’s expired outcome downstream and the ask resumes on expiry, so that branch runs; leave the expired outcome unwired and expiry kills the held chain instead (the default). The wiring owns it — see wiring an outcome by hand for the exact shape the derivation reads.
• A raw ask runnable sets its behaviour on the ask itself: its On expiry control is end the run (the default) or resume with the expired marker.

​

Warm start

• A row whose jq gives null runs that node normally instead of pre-filling it.
• A filled node writes the given output and skips its own state writes — it was never called, so it records no call and applies no update.
• A node inside a loop is filled per round: its value is a list, one entry per round, and a null entry or an index past the list’s end runs that round normally.

​

Portable flow files

​

Structured agent output

​

Node waits

• All inputs (the default). The node waits for every declared or edge-derived input to arrive, then runs.
• Quorum. A minimum input count releases the node once any that many inputs have arrived; it is purely count-based and never looks at which inputs arrived.
• Named release. A named-producer list releases the node once every named producer is present in the fan-in — a barrier keyed on specific producers rather than a count. Every other input is still consumed if it happened to arrive by release time, but is never waited on.

​

Handling a node’s error

• A wired Recovery. Name another runnable in the flow as the Recovery node; it is dispatched only through the On Error, never by ordinary routing.
• An inline tool. Attach a tool directly to the On Error, with optional baseline keyword arguments that the On Error’s expression overrides map onto. Any registered tool qualifies — including a flow-call preset, which makes the On Error an arbitrary nested flow.

​

Who handles a failure

​

When a loop’s failure reaches the flow’s On Error

• The loop could not build or run its plan — its list input was not a list, its count was not a number, its while condition was not a boolean, or a bounded driver’s plan (a resolved list or count) was larger than the max-iterations ceiling. additional carries .failed_iterate_node alone.
• The body failed while running — one or more iterations failed inside the body, or a while loop reached the max-iterations cap without its condition turning false. Alongside .failed_iterate_node, additional carries the two keys below, so recovery can name which items failed and read every completed iteration’s outcome.

​

Run condition

• True runs the node normally.
• False skips it: the node does not execute, its output is null, and its status reads skipped. The output key is still written, so every downstream input barrier still releases and the flow continues past the node — the gate stops the one node, not the path. To stop a whole path, use a conditional or a router instead.

​

Run after the reply

• an after_reply node with no tool, with return_result or return_expr, with its own on_error, or with a session_thread;
• an edge out of it, a node naming it in inputs, or the node inside an iterate body;
• a state binding with updates on it.

​

Routing on a verdict

• Kind — fires when the verdict finds that kind. An optional jq guard is combined with it, so “this kind, but only when…” stays one edge.
• Condition — the branch condition is an authored jq expression with full access to the run, $states included. It is a condition route, not a disguised kind, and the canvas says so.
• Otherwise — the default branch, taken when no other branch matched.

​

Decided by

• LLM agent (the default). The card lowers to an agent that reads the input, extracts the items of each kind into a generated structured-output schema, and renders the kinds into a system prompt through the router_kinds variable. A kind route fires when that kind’s item array is non-empty; the agent can loop over the extracted items, a kind may carry extra per-kind fields merged into each item beside its text, and the card may declare turn-level output fields.
• Classifier model. The card lowers to a classify call that asks one yes/no question per kind — the kind’s name is the question’s key and its description the instruction — and returns a probability per kind. A kind route fires when that probability reaches the card’s threshold (0 to 1, default 0.5), AND-combined with the route’s optional guard exactly as the non-empty check is under the agent. The classifier extracts no items, so it declares at least one kind and offers no loop, no per-kind or turn-level fields, and no system prompt; its provider and model are set on the card (an empty provider uses the host’s default classifier provider).

​

Route keys

​

Every match or first match

• Every match (the default). Every route whose condition holds fires, in parallel — the multi-fire fan-out. This is the default discipline and carries no wire marker: Every match emits no routing-discipline key on the wire.
• First match. The routes are evaluated in row order and only the first one that matches fires; the rest are never evaluated. This is the classic single-path routing table — at most one route ever fires.

• At most one catch-all, and an unconditional one comes last. An always-true route makes every route below it unreachable, and a second catch-all can never fire — so declaring either is refused with the dead rows named. A plain otherwise route is order-free (it fires only when nothing matched, wherever it sits) and may be declared anywhere.
• Route keys are never plain numbers. A numeric branch key is an array index that a JSON-object client silently re-orders ahead of every other key; the router never mints one, and the engine refuses it whether or not an order carrier rides, so the two spellings of a first-match table cannot disagree.

​

The routes table

​

Turn-level output fields

​

Dispatch: once or loop

• Once (the default). Every chip is a plain routing line: the flow continues from each matched chip, and the target reads the whole verdict as .upstream_outputs.<router>. This is the router exactly as above — no result chip, and a card on Once emits no dispatch key on the wire.
• Loop. Every chip’s line starts a body — any nodes and conditions you draw off the chip, in the same flow — and that body runs once per classified item of the chip’s kind. The runs go sequentially or in parallel (a parallel run takes an optional max concurrency cap), or the body repeats while an authored jq condition holds. A looping card grows one result chip, the loop-done exit the collected output leaves through.

​

Per-route On Error

• an inline tool on the row, with its own expression and condition; or
• a wire from the route chip’s error dot to an On Error node on the canvas — that node then holds the handling, its own inline tool or its wired Recovery, as any On Error node does.

​

Judging with a classifier

((.upstream_outputs.judge.answers.urgent.noul) // 0) >= 0.5

​

The visual jq editor

• Input (primary) — the data the expression receives, ..
• Value (muted) — a literal or a path into the input.
• Operator (muted) — combines two values (+, ==, //, …).
• Condition (warning) — chooses a result with if / else.
• Try/Catch (danger) — runs logic and recovers on error.
• Call Function (primary) — applies a built-in or defined function.
• Define Function (primary) — declares a reusable function.
• Comment (muted) — a note; never runs.

​

Visual jq on every surface

​

Flow states

• Bind a node to a state. Each node carries a binding document — one or more states, each with the templates it uses, a jq subject_expr that picks the subject, an optional scope_expr, input injections evaluated after the node’s input is assembled and before it runs, and updates applied after the node completes. Its shape and the injection and update forms are in Binding a node to a state. In a run, every bound state’s record is available to jq as $states.<name>, seeded once at run start.
• Subjects. A subject_expr is required on every binding and resolves to a subject reference — a full subject object {target_kind, target_name, kind, key}, a {kind, key} object, or a bare key string — which the platform resolves at run start by the same rule as every door; see A binding’s subject and scope. A subject_expr resolving to null is a loud mint-door error naming the state and the expression; a reference the platform refuses fails the run with the platform’s refusal.
• Write through updates. An update’s op batch may carry keyed list ops and per-op compare-and-set guards — the coordination primitives for many writers on one record; the platform applies every op atomically under the record’s row lock.
• Refresh. A node can opt into a fresher view of its bound records — see refresh.

​

Reading a state a flow does not bind

• A warning while you author. Flow validation reports a $states.<name> read of a state that is not declared (state_ref), or is declared but not bound to this flow (state_unbound), or a refresh_states naming an unbound state (state_refresh_unbound), as a warning — never a save gate. The fact is extra-graph and per-environment: the read is fixed by binding the state at a separate door, so a flow authored or imported before its states are bound in this environment is not blocked. The message names the read and the fix, for example: “Node ‘n’: return_expr reads $states.x, but ‘x’ is a declared state that is NOT bound to this flow, so the read resolves to null at runtime. Bind ‘x’ to this flow, or read a state it binds. States bound to this flow are […].”
• A loud error when it runs. A refresh_states naming a state the node does not bind is a loud drift error at node execution: “node ‘n’ refresh_states names state(s) [‘x’] that are not bound on this node; bound states are […].” A binding whose subject_expr cannot resolve is likewise a loud mint-door error naming the state and the resolved value.

​

Cross-flow state writers

​

Keyed state list ops

• set_by_key — update or append the list item whose key field equals a given value. The op’s value is the item itself: a JSON object that must carry its own key field, so the match key can never drift from the payload. The first item whose key field equals that key is replaced in list order; if none matches, the item is appended (upsert). An absent list is created. The value may also be a list of complete items, applied in payload order — one op, many upserts.
• merge_by_key — patch fields on items that already exist. The op’s value is a list of partial items, each carrying the key field; each partial is shallow-merged into the first stored item with that key ({**existing, **partial}, top level only — a nested object replaces wholesale rather than deep-merging). Null-valued fields are dropped before merging, so null never deletes a field. A partial matching nothing is skipped: unlike set_by_key this never inserts.
• unset_by_key — the deleting dual of merge_by_key: remove named fields from items that already exist. The op’s value is a list of entries, each exactly {<key_field>: <key>, "fields": [<name>, …]} — the item’s identity plus the top-level field names to delete. An already-absent field is an idempotent no-op and an entry matching nothing is skipped; the key field itself may never be listed, since an item keeps its identity. Stray keys on an entry, a duplicate field name, and a duplicate entry key are all refused loudly.
• set_by_key_each — the keyed fan-out of the upsert, for a classifier envelope. The op’s value is an object mapping fan-out keys to lists of complete items; each (key, items) pair applies the set_by_key list semantics into the list one level deeper, at the path plus that key. One op and one atomic apply replace one op per fan-out key. A fan-out key must be a non-empty string and never "-"; a key mapping to an empty list contributes nothing.
• remove_by_key — remove the list item(s) whose key field equals a given value. The op’s value is the key to remove by — a single scalar, or a list of scalars (the MongoDB $pull + $in idiom) that drops every item matching any listed key across all of them, in one op. Every matching item is dropped; zero matches, or an absent list, is a quiet no-op. A remove list is capped at 200 keys; a nested container or a duplicate key is refused loudly, while an empty list is accepted as a no-op — a jq selection that legitimately matched nothing lands as a traced no-op rather than raising.

• Distinct keys compose. Two flows that upsert items under different keys both land — exactly like list appends, which always compose.
• Appends compose with a keyed update. One flow appending a fresh item while another updates an existing one by key keeps both, whatever the commit order.
• The same key from two flows needs a guard. Two flows racing to write the same key each replace the whole item, last-writer-wins; where that is a genuine race, pair the op with a compare-and-set guard (the writer-token pattern).

​

Refresh: opt-in state re-read

• What it heals — and what it does not. Refresh heals causality: a document an already-finished upstream node (or another completed flow) committed after this run’s mint-time seed, or a write whose channel update was rolled back at an interrupt boundary. A subflow a parent node invokes is this case — its updates commit immediately but stay invisible to a later parent node until that node refreshes. It is not a race primitive — the re-read is a single point-in-time snapshot with no lock span, so a writer racing concurrently is still a keyed-op or compare-and-set guard concern, never this one. A record that reads absent/erased skips the landing entirely: a refresh cannot observe a deletion.
• Once at loop entry. On an iterate (and its map face) the re-read fires once, at loop entry — re-entries through the body back-edge skip the barrier — so every iteration’s body, and any while predicate, inherits the same entry-time refreshed view.
• Interrupt-resume caveat. A tool node that pauses and resumes re-runs on resume, so its refresh re-reads at resume time and its injections and updates — and the input recorded for the node — are recomputed over the resume-time view, which can diverge from the arguments the tool actually received on the first drive.
• Stateless bypass. On an unbound run — a raw-graph surface, or a flow imported to an environment where it is unbound — the re-read is a silent no-op, the same shape as the binding’s writes. But naming, in the subset, a state this node does not bind is a loud binding error naming the node’s bound states, whenever bindings do load.

​

Enable the state store

TAI_DB_BINDING_FLOWS_STATES=default
# plus the TAI_DATABASE_<NAME>_PG_* settings for that database

tai db migrate

​

State templates

​

Binding a node to a state

• input injections — each evaluates a purpose: "input" template jq (or a custom jq reading the bound record as . with the run input as $input) and merges the value into the node input under a named field before the node runs;
• updates — each applies a write after the node completes: a purpose: "update" template jq (its returned op batch rebased under the attachment path), shaped by an adapter that reads the node’s output as . with the run input as $input to build the program’s declared input, or a custom jq reading the node’s output as . with the bound record as $record and the run input as $input, returning the op batch itself. An optional op_id — a jq reading the node’s output as . with $input — makes the write idempotent.

​

The template-jq prelude

def tjq_<name>($params): <the program body, with $params, $declarations and $parameters bound>;

​

Trace, declarations, and the effective schema

​

Binding scope

​

Shipped defaults

​

Upload — one door, two kinds

• flow → a preset over the flow base tool, through the same in-process authoring path the preset HTTP doors use (create for a new name, a new active version for an existing one — earlier versions kept).
• node → the same, plus a palette entry: the preset carries a palette-node tag so it lists in the canvas palette, with an optional folder placing its card.

​

Shipped defaults are files

​

Run state

• Every value, in order of .outputs.<node> / .inputs.<node> when an expression of the flow reads that node by name — a node’s expression, run condition or result shaping, a holder’s expressions, a conditional’s and its branches’, a loop’s drivers, any On Error.
• The newest value when only the engine reads it: a node’s inputs, a flagged result, a loop’s output, branch routing.
• Nothing otherwise. A monitoring plugin still records every step’s input and output.

​

Monitoring a flow

​

Checkpoint retention and durability

​

Agent session continuity

​

How it plugs in

​

Organizing flows

• Folders and breadcrumbs. The page is a current-directory explorer: a breadcrumb, the folder’s subfolders, then the flows filed there, with unfiled flows at the root.
• Display names and tags. Each flow shows its display name (its real tool name stays visible) and is filtered by its merged tags — a flow’s plugin-native babelfish tag unioned with your editable user tags. A tag filter and a search box narrow the list. A tool’s display name from that same overlay also surfaces inside the flow editor: a tool node’s canvas label shows it, the node-editing tool pickers show it with the raw name kept visible, and the run popup and history inspector show it with the raw name in parentheses.
• List or card view. A toggle switches between a compact list and a card grid; the choice persists per browser.
• Per-flow editing. A flow row edits its display name, tags, and folder in place. Hiding a tool is centralized on the Studio Tools screen, not here — the Flows page manages everything except visibility.

​

See also

• Babelfish on tai42.ai — the product, its pricing, and its terms.
• Visual jq in flows — the flow field’s Inline/Template tabs and what each jq field seeds the editor with.
• The jq editor — jq-studio, the platform’s open-source, built-in visual jq editor.
• Studio plugins — how a plugin contributes a Studio page.
• Presets — the versioned wrap a saved flow becomes.
• Tool organization — the folders, display names, tags, and visibility a flow rides.