Builders & Supervisor

New in Psyclone AIOS v2.2 — shipped 22 August 2026.

Builders & Supervisor is how a running Psyclone system builds — and rebuilds — itself. Every node carries a Builder: a deterministic executor that takes a recipe (a PsySpec submitted at runtime, plus optional shell or code steps) and bakes it into live components, streaming progress back as it goes. A Supervisor is the component that decides what to bake and when: it mints recipes, dispatches them to the right node’s Builder, watches the two reverse streams, and can pause, retry or cancel a bake mid-flight. Since 2.2, ordinary system startup itself runs through a built-in Startup Supervisor, so Psyclone.Ready only fires once every component actually exists. If you run long-lived systems that must add capability, heal, or reconfigure without a restart, this page is for you.

Why it matters

Most middleware treats startup as a one-shot event: the configuration is read once, everything in it is created, and any later change means a redeploy or a restart. Psyclone 2.2 turns that same machinery into a runtime service. The failure mode this removes is the ambiguous bring-up: systems that report “ready” while half their components are still materialising, and operators who cannot tell a slow deployment from a wedged one. The Startup Supervisor publishes Psyclone.Ready exactly once, only after the local bring-up recipe reaches Bake.Success — so “ready” genuinely means “all components exist”.

The engineering consequence is a single, governed pathway for structural change. Because a recipe is written in the same XML as a PsySpec and parsed by the same code path, there is no second configuration language to learn and no drift between “what startup does” and “what runtime changes do”. Because every bake message is correlated by one RecipeID and rides the ordinary sub-100µs message bus, any component can observe a bake — a read-only dashboard is just a subscriber.

The business consequence: in production systems such as a real-time voice AI system, adding a camera pipeline, warming a model, or retrying a failed step becomes an auditable, steerable operation rather than an SSH session. Every step is acknowledged, every output byte is accounted for, and control verbs are rejected cleanly when they are stale or unauthorised — never a crash, never silent.

How it works

There is exactly one Builder per node, always present. A Supervisor is an ordinary continuous crank component — the built-in Startup Supervisor runs as a crank in the Root space. On the first Psyclone.SystemStatus (broadcast on a 5-second cadence; the deterministic “config is complete” kick), it parses the node’s PsySpec, groups component elements by target node, and dispatches one bring-up recipe per node. A group pinned to a peer is dispatched once that peer’s id appears in a SystemStatus, else deferred. This is deterministic bring-up orchestration — plain code, no model in the loop.

Every message in a bake carries five identity entries (Supervisor, Recipe, RecipeID, Node, NodeID), and the Builder echoes them onto every reverse message. The RecipeID (<supervisor>-<recipe>-N) is the sole correlation key end to end; a duplicate RecipeID is rejected, so a recipe is baked exactly once.

The conversation is deliberately split into two reverse streams:

• Psyclone.Builder.Bake.Status — progress only: kind (start/step/interim/ack), pct, a one-line summary, control acknowledgements, and the terminal outcome (.Success/.Failed/.Paused/.Cancelled). A time-driven heartbeat (kind="interim", default every 5 s) keeps “working, nothing new” distinguishable from “wedged”.
• Psyclone.Builder.Bake.Data — the actual step output (stdout/stderr), lossless and strictly ordered by seq. A wire seq that is not exactly last+1 is a latched hard error at both ends — never reordered, never dropped-and-continued.

So a progress dashboard subscribes to Status and stays cheap; a log collector subscribes to Data and reassembles output gap-free. Steering rides governed control verbs — Psyclone.Builder.BakeControl.Pause / .Start / .Cancel / .SkipStep / .RetryStep — each acknowledged on the Status stream as kind="ack". Pause holds at the next step boundary; Cancel is immediate, even mid-<cli>; RetryStep requires retryable="yes" on the step, protecting non-idempotent commands. Stale control sequence numbers, unknown RecipeIDs and unauthorised issuers are all rejected with a typed result.

How to use it

A recipe is just a PsySpec you send at runtime — <include> and %variable% substitution work identically. Component tags create components exactly as at startup; <cli> runs a command as a step:

<psyspec name="AddCamera">
  <module name="Camera7" node="Edge3">
    <crank name="CameraCapture" />
  </module>
  <cli name="Warmup" node="Edge3">./warmup.sh Camera7</cli>
</psyspec>

To drive it yourself, write a custom Supervisor as an ordinary continuous crank — the same pattern as the shipped Startup Supervisor:

1. Declare the crank as a normal module, with <trigger>s subscribing to Psyclone.Builder.Bake.* and Psyclone.SystemStatus.
2. Bind a Supervisor object to the node with initForCrank(node, name).
3. Dispatch a recipe with startup(targetNode, recipeXML) and keep the returned RecipeID.
4. Loop: pump each delivered message into sup.processMessage(msg); inspect getBakeState() / bakeSucceeded() to decide the next action.
5. Steer with sup.sendControl(recipeID, "pause"|"start"|"cancel"|"skip"|"retry").

Node pinning matters: a step with no node= only runs on a config node. A Supervisor stamps steps with the target node’s name for you, but hand-written recipes for remote nodes must pin every step with node="…" or it will be silently skipped.

When to use it / when not

• Use it for runtime capability changes: adding pipelines, warm-up steps, retryable deployment sequences, and any operation where you want auditable progress and lossless output capture.
• Use it for observation: any component can listen in on a bake by subscribing to Psyclone.Builder.Bake.* — no privileged channel required.
• Caveat — multi-node: per the System Guide, sending recipes to a remote node’s Builder is built and the routing decision is tested, but the reverse Status/Data streams across a node boundary ride on subscription sync and are “verified single-node but still being hardened multi-node” — “treat cross-node result collection as experimental until that test lands”. Cohort messaging and the whole-system status API are not built yet.
• Not for autonomy: Supervisors are plain deterministic code today — supervised, not autonomous. The LLM tier (a model writing, compiling and testing module code) is roadmap; do not build production plans on it.

Read the docs

• User Guide 13 — Builders & Supervisors: recipes, the two-stream conversation, and writing a custom Supervisor crank.
• System Guide — Builder & Supervisor Protocol: wire-level message types, identity entries, integrity guarantees and control-verb semantics.
• System Guide — Roadmap Features: what is Shipped versus Roadmap, including the planned LLM builder tier and sim-manager.
• User Guide 8 — Catalogs: the declarative data primitives your recipes create alongside modules.
• CMSDK API reference: the Supervisor object and crank APIs used above.

Builders and the Supervisor are one part of the Psyclone AIOS 2.2 architecture. See also LLM Connections (also new in 2.2), Global Contexts, and Ephemeral Compute — or return to the Psyclone AIOS overview.