Flows and work nodes

Work nodes

A work node is a reusable, independently maintained and versioned definition of an agent execution. It describes what one node execution needs, and nothing about where it sits in any particular graph.

A work node fixes:

• one exact model and reasoning tier;
• a platform-independent runtime configuration with semantic runtime hooks;
• prompts, skills referenced by name and version, extension connection details, and sub-agents;
• the timeout, maximum turns, maximum tokens and maximum cost of a single attempt;
• human-in-the-loop defaults, describing questions and ordinary approvals separately;
• user-declared unit gate commands;
• the working directory, the repository clone location, non-sensitive environment variables and logical cache configuration references.

Model fallback is entirely an internal capability of the model gateway and never appears in a flow, a node or the execution manifest. High availability and degradation inside the gateway stay transparent to flows.

Flows

A flow composes several work node invocations into a directed acyclic graph by dependency. Each invocation has its own node identifier, input sources, outputs, artefact paths and dependencies.

The flow's YAML definition is authoritative; the visual dependency graph is a projection of that same content onto a canvas, not a second definition.

Drafts are editable. Publishing produces an immutable version with a normalised content digest. Every published version fixes an exact node template version or tag alias policy, along with the invocation's input and output bindings and the dependency graph.

A tag alias is not a basis for reproducibility

This is an easy place to go wrong, and it is worth stating on its own.

A tag alias — latest, for instance — is only a movable alias pointing at some published version. It is not guaranteed to be the numerically highest version. A flow draft may use aliases to make authoring more pleasant, but the deterministic compiler must resolve each one to an exact version immediately. Flow publication and task creation validate the concrete version and digest once more, and write the resolved result into the frozen lock.

So: a later tag move does not affect a published flow or a running task. But if your flow draft still carries an alias, the next time you edit it, it may point somewhere else.

Completion conditions

Whether a node succeeded is deterministic:

• every required business artefact declared by the flow has been produced;
• the artefact manifest exists, is non-empty, and can enumerate the actual artefacts;
• the result summary exists and contains valid content;
• every unit gate passes.

The artefact manifest reports what actually happened; the flow's outputs are the required contract. Extra artefacts must be registered, and can only be handed to a legitimate downstream that already exists in the graph.

The result summary is the single user-visible authoritative summary for each successful node, and carries result, files, links, verification, risks and follow-ups in a fixed structure. The files section must list, one by one, the runner-validated relative paths of the artefacts, so the agent's self-reported result cannot drift away from the frozen artefacts. The links section records only external addresses that this node actually created or discovered.

The summary format is part of the platform's default execution policy, not of the user message body. The runner writes it into the task's private agent home according to the actual runtime, and the native instruction-discovery mechanism loads it when the session starts. These files are not written into the repository worktree, the artefacts or the task snapshot.

Be clear about one thing: this instruction layer exists to guide runtime behaviour, and is not treated as a security boundary. The runner still enforces summary format validation after artefact validation and before the read-only freeze; a malformed format or incomplete file coverage fails the node. A project's own instructions, or model drift, cannot bypass the completion contract.

Human in the loop

A flow can explicitly enable questions or approvals, but human collaboration is a policy capability rather than a mandatory step on every task. The default policy aims for end-to-end autonomy.

An agent question only marks the current attempt as waiting for input; dependent downstream nodes wait, while independent parallel branches keep running. A reply is bound to the node, the attempt and the question identifier, and stale questions from an invalidated attempt are closed automatically.

When a user sends a message unprompted, it enters a pending queue if the agent is busy. An explicit forced insertion prefers the runtime's native insertion capability and otherwise interrupts the current turn and resumes. A runtime that cannot resume reliably must explicitly refuse forced insertion rather than silently queueing.

Parallelism

A single supervisor runs nodes whose dependencies are satisfied, and applies backpressure according to sandbox CPU, memory and model quota. Flow authors do not configure concurrency — dependencies determine what can run in parallel, while sub-agents and the runtime determine parallelism within a node.

Commits from parallel coding nodes are merged by an explicit integration node in its own worktree. The integration node deals with code semantics and conflicts; the supervisor only provides the mechanism. Conflicts it cannot resolve go back to the relevant coding nodes as targeted rework.

The nodes downstream of a failed node do not run; independent branches with no dependency on it keep running.