Crate rig_harness_protocol 

The protocol between the rig launcher (the rig crate’s binary) and the rig-harness agent it builds and runs: the RIG_HOME layout, session ids, the environment the launcher passes to the agent, and the exit code with which the agent asks for a restart. The launcher and rig-harness both use this crate, so the two sides cannot drift apart. It uses only std, and it changes with rig-harness.

Modules

env

The environment variables of the protocol.

Structs

AgentDescription

What a built agent’s plugins add to the command line, as the agent writes it when the launcher sets env::DESCRIBE: their commands, their options and the secrets they ask for, and the plugins whose agent-loop systems clash, for rig plugin check --build. The launcher keeps one per build (Home::described) and reads the command line against it.

DescribedCommand

A plugin’s command, rig <name> <usage>.

DescribedFlag

A plugin’s option, --name or --name VALUE.

DescribedSecret

A secret a plugin asks for, which reaches the agent as secret_variable of its name.

Home

The RIG_HOME layout. Every file the launcher and the agent write lives under this one root.

Invocation

The agent’s arguments, in the canonical form the launcher passes on (Invocation::to_args): the model, each plugin option as --name=VALUE, then the print prompt after --print --, or a plugin’s command and its arguments. The launcher reads the user’s command line against the agent’s AgentDescription report first (AgentDescription::invocation), so rig -p "…" and the agent binary run alone agree on them.

RunDir

A launcher’s own directory, outside every session, which lives while the launcher runs: the file that tells it the agent started, and the log of a sessionless run that failed, which outlives the launcher.

SessionDir

A session’s directory. The agent keeps the session there through its store, which a plugin may replace (by default in the folders logs, blobs and files), so only the plain files beside the store are named here: the markers of a session an agent started in (Self::started), logged to (Self::is_saved) and being deleted (Self::is_deleting), the text log, the lock of the launcher running it, its working directory, its name and the session to switch to.

SessionId

A session’s id: digits and dashes, so it is safe as a path segment. The launcher makes one per new session; the agent makes its own when it runs without the launcher.

Enums

StartReason

Why the agent process started, which the launcher passes in env::START. A switch to another session (/new, /resume) starts it as New or Resumed; a crash is no reason, since the launcher never restarts a crashed agent.

Constants

BEVY_VERSION

The one Bevy version of the agent and of every plugin: a Bevy plugin only works with the exact Bevy version of its app.

ESSENTIAL_PLUGINS

The plugins whose absence takes away the way back from inside the agent, by type path, with what goes: rig plugin disable, rig plugin list and /plugins warn on them. rig plugin enable from a shell always brings one back.

INVOCATION_USAGE

The arguments Invocation::parse takes, for usage texts.

RELOAD_EXIT_CODE

The exit code with which the agent asks its launcher to restart it on the staged build.

RESERVED_COMMANDS

The launcher’s own first words, which no plugin’s command may take.

VERSION

The version of rig: of the workspace, the launcher and the harness they build together. It stamps generated projects, so a new launcher regenerates and rebuilds the agent; a plugin reads it to say which rig wrote something.

Functions

essential

What goes when the plugin type_path is left out, if it is one of the ESSENTIAL_PLUGINS.

first_errors

At most count lines of a build’s output from the first one that starts with error, as cargo writes a compiler error; none when no line does.

is_free

Whether no live process holds the lock file at path: it is missing, or it can be locked now. A failure that hides the answer counts as held.

is_name

Whether name can name a plugin’s option or command: lowercase ASCII letters, digits and dashes, starting with a letter.

launcher

The launcher that started this agent, if one did: it sets both env::LAUNCHER and env::SESSION. A nested agent, run by this agent’s shell, inherits only the launcher’s path, which the model uses.

lock_file

Opens the lock file at path for writing, creating it when create. Every lock between launchers and agents is such a file, held with std::fs::File::try_lock or std::fs::File::lock.

secret_variable

The variable that carries the secret name: env::SECRET_PREFIX and the name in upper case, - as _ (crypt is RIG_SECRET_CRYPT).

secret_variables

Every secret variable (env::SECRET_PREFIX) in this process’s environment: what a process this one starts must not inherit.