executor — Process / Shell Execution¶

The executor plugin (bundle io.cresco.executor) runs OS processes and shell commands on an agent, streaming stdout/stderr over the mesh dataplane and accepting stdin over the dataplane, with optional per-process metrics. It is the fabric's remote-execution surface.

At a glance¶

Fact	Value
Module path	`code/executor`
Bundle symbolic name	`io.cresco.executor`
Loaded	At runtime by the controller (gated by `enable_executor`, default true).
Type	Functional plugin (`@Component` implementing `PluginService`).

The model¶

A runner is a configured command identified by a stream_name — which is also the dataplane stream its stdio rides on. Lifecycle: config_process (register) → run_process / start_process (execute) → status_process (poll) → end_process (kill) → reusable. reset_runners stops everything.

Stdio over the dataplane. stdout and stderr are forwarded as dataplane TextMessages on the GLOBAL topic, sharded by stream_name, with a type of output or error. Stdin is accepted by subscribing to the same stream with type=input. An external client reads/writes via get_dataplane(stream_name). On exit, an execution_log event (with the exit code) and a delete_exchange event are emitted on the same stream. A command containing -interactive- starts an interactive shell driven entirely over stdin.

Executor actions¶

Full table: Plugin Actions › executor.

Action	Behaviour
`config_process`	Register a runner (`stream_name` + `command`, optional `metrics`); does not start it.
`run_process` / `start_process`	Start a configured runner.
`status_process`	Report whether the runner is currently running.
`end_process`	Kill the process and its whole descendant tree and free the runner.
`reset_runners`	Stop every runner on this executor.
`getmetrics`	Central metrics — see Observability.

Safeguards¶

Injection-safe, precise kill — end_process kills the launched Process and its descendants via the JVM ProcessHandle, never by interpolating the command into a ps | grep | kill shell string.
No thread/handle leaks — stdout/stderr readers exit on EOF; the stdin dataplane listener is removed when the process ends; every worker is a named daemon; isStopped() kills all runners so nothing is orphaned.
Reusable stream names — end_process removes the runner from the registry, so a stream_name can be reconfigured after stop.

Security note: executor runs arbitrary shell commands by design. Authorization is enforced at the Cresco broker/tenant layer — only principals allowed to route messages to this plugin can invoke it. See Security & Identity and Multi-Tenancy.

Configuration read¶

Key	Default	Meaning
`stream_name` + `command`	(unset)	If both set at load, a runner is auto-created and started.
`metrics`	`false`	Collect per-process OSHI metrics (streamed live on the dataplane).
`enable_executor`	`true`	Agent-level auto-load gate.

See Configuration.

Observability¶

Metrics — getmetrics exposes MeasurementEngine gauges executor.runners.configured and executor.runners.active; aggregated by the controller's getmetricinventory. Per-runner process telemetry (cpu/mem/io of the tracked PID + descendants) streams separately when metrics=true. See Metrics & Measurements.
Health — registers the executor Felix HealthCheck (tag local): reports the running / configured runner counts. See Health & State.