CommandRun

A CommandRun is one execution of a command on a Channel: a request from a caller and an outcome from the bot, recorded as one entity in the Channel's Space. The runs of a Space are its record of what its bots were asked and what happened.

Request and outcome

A caller creates a run by naming a command, with cub command run <command> option=value .... ConfigHub resolves the command to the one Channel that declares it, across the Organization or within a Space, and refuses a command that no Channel declares or that several do, in which case the caller names the Channel. The run records the Command, its Params as a JSON object keyed by option name, checked against the declared signature, and optionally the UnitID or TargetID the run is about, for finding it later.

The bot's outcome is the run's Status with a Result, a JSON value shaped by the command's declared Returns, or an ErrorMessage. A run is one request and one outcome: there is no progress or conversation inside it. A command that needs either starts something the bot owns, such as a workflow, and returns its identifier.

Status

Status	Meaning
Pending	Created, and waiting for the Channel's process to take it.
Delivered	Handed to the process, which is executing it.
Completed	The process reported success, with a Result.
Failed	The process reported failure, with an ErrorMessage.
Rejected	The process declined it as not its to run, with an ErrorMessage.
Expired	Nothing took it before its Deadline.
TimedOut	The process took it and never answered.
Canceled	Canceled while still Pending.

Two clocks bound a run. Deadline is how long a run stays Pending before it expires, five minutes by default and at most an hour, set with --deadline; a run on a Channel with no process connected waits until then. Once delivered, TimeoutAt is thirty seconds later, the time by which the process must answer; a run the process never answers is TimedOut, and a run that was delivered when the process lost its lease goes back to Pending for the next holder.

cub command run waits for the outcome by default and fails if the outcome is anything but Completed; --wait=false returns the run at once and cub commandrun get <id> --wait picks it up later. cub commandrun cancel cancels a run that is still Pending; a run already in the process's hands runs to its outcome.

Permissions

A run has no Permissions of its own. Creating one takes Use on the Channel and CreateChildren on the Space; reading it back takes View, which comes from ViewChildren on the Space; canceling takes Use on the Channel. Reporting the outcome takes Claim on the Channel, which is the bot's.

See Command bots for the whole cycle, from declaring a command to reporting its outcome.