CMLabs · Psyclone AIOS

# 11. Roadmap Features

Where the platform is heading: supervisors, node-local builders, LLM connections and external auto-start — documented so the surfaces are stable, and clearly marked as not-yet-shipped.

Warning — read this first. Everything on this page is Roadmap: design direction, not current capability. Several of the XML tags below (`<supervisor>`, `<executable>`) are already accepted by the parser but are stubs — using them today has no effect. Do not build production plans on any feature here until it appears in release notes with a Shipped status.

## Supervisors Roadmap

The `<supervisor>` tag exists in the grammar today as a log-only stub. The plan wires it into a real global supervisor: a component that observes the system and decides module lifecycle changes — while the actual execution of every change is delegated to the node-local builders below. Planned supervisor specialisations:

- sim-manager — a test-harness supervisor (first to be built, in non-LLM form; see below).
- performance-manager — load/latency-driven placement and algorithm decisions (later phase).
- ad-hoc-manager — operator- or application-directed restructuring (later phase).

Every supervisor is planned to get a standard PsyProbe entry: a one-line main-page summary expanding to a full page whose top is a standard visualisation and whose body lists every change the supervisor has made (modules built/started/removed, nodes, services). A programmable interactive bottom panel is a later phase.

## Node-local builder Roadmap

Every node gets a builder: the single local executor for all module actions — create, load/execute, delete, move-to-node, and the registration updates those cause. Supervisors decide what; the builder on the target node decides how and does it locally. Two tiers:

- Basic (non-LLM) tier — part of the first roadmap milestone. Present automatically on every node (declaring a `<builder>` replaces it). Accepts a module spec with Python code supplied and builds/loads/deletes/moves it. Asking a basic builder for more than it can do (e.g. build C++ or build from a description) is rejected with a typed error message.
- LLM tier — later phase. Uses a named `<llm>` connection; can build Python or C++ from code or from a textual description.

All builder actions are driven by standard system messages, so any component can command any builder: `SYS_BUILDER_CREATE`, `SYS_BUILDER_LOAD` / `SYS_BUILDER_EXECUTE`, `SYS_BUILDER_DELETE`, `SYS_BUILDER_MOVE`, `SYS_BUILDER_REGISTER_UPDATE`, with results published as `SYS_BUILDER_RESULT` (ok/error + error type). Supervisor–builder communication always rides the existing message bus via the node — no dedicated control channel.

Module migration fits here: the machinery for moving components between nodes is mostly built in the engine today (see chapter 8); the roadmap makes `move-to-node` a builder-owned action driving that existing machinery via source and target builders.

## Non-LLM sim-manager Roadmap

The first concrete supervisor: a test harness that builds a set of modules to run a specific simulation/test, lets them run, checks the result, and reports. The whole planned loop:

1. Build/load a named set of modules on named node(s), via the target builders.
2. Let them run.
3. The modules collect all data into one final output message.
4. Check it against XML-declared success criteria — named values typed int/float/string; numeric checks are min/max ranges, string checks are matches with optional wildcards.
5. Publish success/fail and clean up.

Kick-off is by system message (so any module can start a simulation), lifecycle events (created, started, status, success, fail) are published to any subscriber, and a running simulation can be terminated by message. Simulations may span multiple named nodes from the start; isolation is a spec design decision, not enforced. The non-LLM version runs one fixed, pre-supplied plan; candidate regeneration (trying new module variants automatically) is an LLM-tier follow-on.

## <triggergroup> declarative join Shipped

This has landed — `<triggergroup>` is now a real declarative join operator, no longer a stub. The node-side join engine buffers member messages by tag, activates the crank once per complete set (wakeups ≈ joins, not one per member), coalesces repeats per policy (`dup="latest|keep"`), and delivers the completed set in one activation keyed by trigger name (`PsyAPI::waitForNewMessageGroup`). Group `maxage`/`timeout` eviction, count/min (N-of-M), `within=`/`time=` windows, snapshot mode, optional members, per-member `maxage`, sliding window, debounce and `order="strict"` are all supported. See the full attribute reference in the User Guide, chapter 13.

## <llm> named connections Roadmap (forward design)

A planned platform primitive, parallel to `<catalog>`/`<whiteboard>`: named LLM connections defined globally in the spec; any code asks for a connection by name and receives an LLM object. Documented now so the XML and message surface stays stable — none of it is built. Key design points:

- Providers: a connection points at a direct model (e.g. Gemini with a key) or a broker (e.g. Bedrock); Gemini, Bedrock, OpenAI and Anthropic are the targets.
- Per-connection context window, preloaded on startup with generic Psyclone info, this-system info, connection-specific context, and role-specific context for system LLMs (supervisor, builder, sim, perf).
- `global="true"` master-only proxying: the connection is instantiated and owned only by the master node; other nodes get a transparent proxy object that marshals calls to the master over native CMSDK networking — so nodes without internet access still get full LLM access with the same object interface. A local explicit connection overrides the global proxy. Context for a global connection defaults to per-requesting-node; a single shared context is an explicit opt-in (`shared="true"`).
- Native transport only: no third-party HTTP/WS libraries in the core binary; connectors ride CMSDK’s own http/websocket transport (including SSE streaming).
- Credentials never in XML: the spec references a secret by logical name (`apikeyref="gemini_main"`); distribution to worker nodes is planned over the verified TLS node channel, cached in memory only, with per-node environment-variable override.
- Lifecycle per node: the LLM object tracks tokens, connection status and (where the provider surfaces it) cost; the spec can set token and cost limits. A PsyProbe LLM section is planned as first-party: always visible, collapsed = aggregate rollup (total tokens/cost, active/failed counts), expanded = per-connection detail, with cost/token fields nullable so it degrades to “cost: n/a” rather than fake zeros.

The LLM-tier builder and every LLM-backed supervisor depend on this primitive; the basic builder and non-LLM sim-manager do not.

## <executable> external auto-start Roadmap — in progress

The spec already accepts `<executable consoleoutput=".." autorestart="..">cmdline</executable>` on a component, but the command line is parsed and never launched. The in-progress work launches the declared process when its external space is created: the command line runs via the SDK process API with `%nodeid%` substitution, the child PID is tracked so node shutdown cleans it up, and `consoleoutput`/`autorestart` are honoured. Node-level `<executable name="X" cmdline="...">` declarations (one executable hosting many modules) are part of the same design. This unblocks auto-started external modules and is a prerequisite for the builder harness above. Treat it as roadmap until it is merged and appears in `test=list`/release notes.

## Status summary

Feature | Spec surface today | Status
--- | --- | ---
Supervisors (global; sim/perf/ad-hoc) | `<supervisor>` parsed, log-only | Roadmap (sim-manager first, in progress)
Node-local builder (basic tier) | — (auto-present when shipped) | Roadmap
Builder LLM tier / LLM sim-manager | — | Roadmap (later phase)
Non-LLM sim-manager harness | — | Roadmap
`<triggergroup>` declarative join | Fully parsed + join engine | Shipped — see User Guide ch. 13
`<llm>` named connections | — (surface reserved) | Roadmap (forward design)
`<executable>` auto-start | Parsed, never launched | Roadmap (in progress)

Note. For what is shipped and current — command-line variable overrides, per-module logging, SSL verification by default — see chapters 1, 5 and 6. When a roadmap item ships, this page moves it to the relevant chapter with a Shipped badge.
PreviousTesting (CMSDK & PsyTest) NextRunning in Production