The deployer

The deployer interface holds the exchanges for putting an agent package on a host. There are five: deploy this, what is deployed, how did it go, update it, and remove it.

This is the primary interface of the deployment manager role. Implementing it alone does not grant the role, because the role also carries its refusals, its handling of secrets, its own check, and the record its holders sign.

1. The purpose

Anything that installs agents has to be askable in a known way, or every owner writes a custom client for every installer. This interface publishes the asking side of that job, so a caller who has never met a particular deployer can still request a deploy, read the inventory, and get an agent removed.

2. The exchanges

1. Deploy this. This is the instruction that starts an install. It carries a package, a target host and harness, and the deploy-time decisions: which identity to use, who may call the agent at first, and whether a person attends it. The request names any secrets the deployment needs. It never contains their values.
2. What is deployed? The answer is the inventory: each agent stood up, its package and version, its target, its identity, and the state it was last known to be in.
3. How did it go? The answer is the report for one deploy: what was done, what was checked, and what kind of check it was.
4. Update it. The implementer installs the same package at a newer version, through the same steps and checks.
5. Remove it. The implementer stops the processes, removes the configuration, retires the identity, and states anything that could not be removed.

3. What it does

1. Every exchange is answered or refused with a reason. Silence is not an answer.
2. A deploy request names secrets and carries no secret values. An implementer refuses a request that contains a secret value, before the value is used.
3. Reports state what kind of check was run. An answer to "how did it go" says whether the check was a smoke check or a conformance check. It never says only "verified".
4. There is no document. The signed deployment record belongs to the deployment manager role, and this interface defines none. An implementer that does not hold the role answers these exchanges and signs nothing.

4. How an implementer is checked

The test is behavioural. A harness asks all five exchanges. Each is answered or refused with a reason. A deploy request carrying a secret value is refused. An answer about a completed deploy names the kind of check that was run. An inventory answer matches what a direct inspection of the target finds.

v0.1.0-draft (2026-08-31): this is the first draft, extracted from the deployment manager role, which previously carried these exchanges inline.