AGENTS.md

@@ -138,9 +138,6 @@ Swarm-level:
   with **no identity** and a TLS failure that names no cause.
 - **`swarm-queue-client/`** — the one authenticated connect to the swarm
   NATS queue.
-- **`swarm-wire/`** — serde-only request and reply contracts services
-  exchange over the queue (builder, claude login), so naming one links
-  neither the queue client nor the store client.
 - **`swarm-nats-auth/`** — NATS auth-callout responder; without it the
   queue is fail-closed and admits nobody.
 - **`swarm-agent-verify/`** — checks a `swarm-agent.<agent>.<secret>`

Cargo.lock

@@ -4811,7 +4811,6 @@ dependencies = [
  "serde_json",
  "swarm-queue-client",
  "swarm-secret-client",
- "swarm-wire",
  "tokio",
  "tracing",
 ]
@@ -4847,7 +4846,6 @@ dependencies = [
  "serde_json",
  "swarm-queue-client",
  "swarm-secret-client",
- "swarm-wire",
  "tokio",
  "tracing",
 ]
@@ -4891,7 +4889,6 @@ dependencies = [
  "swarm-matrix-client",
  "swarm-queue-client",
  "swarm-secret-client",
- "swarm-wire",
  "tempfile",
  "tokio",
  "tower",
@@ -5013,7 +5010,6 @@ dependencies = [
  "swarm-agent-verify",
  "swarm-queue-client",
  "swarm-secret-client",
- "swarm-wire",
  "tokio",
  "tracing",
  "tracing-subscriber",
@@ -5080,14 +5076,6 @@ dependencies = [
  "vaultrs",
 ]
 
-[[package]]
-name = "swarm-wire"
-version = "0.1.0"
-dependencies = [
- "serde",
- "serde_json",
-]
-
 [[package]]
 name = "swarmctl"
 version = "0.1.0"

Cargo.toml

@@ -43,7 +43,6 @@ members = [
   "swarm-logs-auth",
   "swarm-metrics-auth",
   "swarm-secret-client",
-  "swarm-wire",
   "swarmctl",
 ]
 
@@ -119,7 +118,6 @@ swarm-controller-api = { path = "swarm-controller-api" }
 swarm-matrix-client = { path = "swarm-matrix-client" }
 swarm-queue-client = { path = "swarm-queue-client" }
 swarm-secret-client = { path = "swarm-secret-client" }
-swarm-wire = { path = "swarm-wire" }
 thiserror = "2"
 vaultrs = "0.8"
 # vaultrs's transport crates. Direct dependencies because one endpoint is

swarm-builder/Cargo.toml

@@ -15,11 +15,10 @@ async-nats.workspace = true
 futures-util.workspace = true
 hive-log.workspace = true
 serde_json.workspace = true
+# The build subject and the shapes the controller sends and reads back.
 swarm-queue-client.workspace = true
 # The forge token and queue client secret paths, and the store login.
 swarm-secret-client.workspace = true
-# The build subject and the shapes the controller sends and reads back.
-swarm-wire.workspace = true
 tokio.workspace = true
 tracing.workspace = true
 

swarm-builder/src/archetypes.rs

@@ -9,7 +9,7 @@ use std::path::PathBuf;
 use std::process::Stdio;
 use std::time::Duration;
 
-use swarm_wire::builder::ArchetypesReply;
+use swarm_queue_client::builder::ArchetypesReply;
 
 /// What every evaluation is run with, fixed at start.
 pub struct Evaluator {
@@ -105,7 +105,7 @@ mod tests {
             nix: PathBuf::from("nix"),
             hyperhive: "/nix/store/h-source".to_owned(),
             nixpkgs: "/nix/store/n-source".to_owned(),
-            deadline: swarm_wire::builder::ARCHETYPES_DEADLINE,
+            deadline: swarm_queue_client::builder::ARCHETYPES_DEADLINE,
         }
     }
 

swarm-builder/src/main.rs

@@ -1,11 +1,11 @@
 //! The swarm builder's build service.
 //!
 //! Connects to the swarm queue as its own OIDC client, takes build requests
-//! from swarm-controller on [`swarm_wire::builder::SUBJECT`], builds
+//! from swarm-controller on [`swarm_queue_client::builder::SUBJECT`], builds
 //! each agent config at its commit, answers on the request's reply subject,
 //! and logs one line per build. It writes nothing to the forge: the
 //! controller turns the reply into a commit status. It also answers
-//! [`swarm_wire::builder::ARCHETYPES_SUBJECT`] with the agent
+//! [`swarm_queue_client::builder::ARCHETYPES_SUBJECT`] with the agent
 //! archetypes its hyperhive source declares, which the controller stores.
 //!
 //! The store identity comes from the `BAO_*` environment. The queue client
@@ -19,13 +19,13 @@ use std::time::Duration;
 
 use anyhow::{Context, Result, anyhow, bail};
 use futures_util::StreamExt as _;
-use swarm_queue_client::{ClientSecret, QueueConfig};
-use swarm_secret_client::forge::Credential;
-use swarm_secret_client::stored_secret::StoredSecret;
-use swarm_wire::builder::{
+use swarm_queue_client::builder::{
     ARCHETYPES_DEADLINE, ARCHETYPES_SUBJECT, BUILD_DEADLINE, BuildAgent, QUEUE_GROUP,
     REPLY_DEADLINE, Reply, SUBJECT,
 };
+use swarm_queue_client::{ClientSecret, QueueConfig};
+use swarm_secret_client::forge::Credential;
+use swarm_secret_client::stored_secret::StoredSecret;
 
 mod archetypes;
 mod nix_build;
@@ -168,10 +168,10 @@ async fn answer_evaluations(
         };
         let reply = evaluator.eval().await;
         match &reply {
-            swarm_wire::builder::ArchetypesReply::Evaluated { archetypes, .. } => {
+            swarm_queue_client::builder::ArchetypesReply::Evaluated { archetypes, .. } => {
                 tracing::info!(count = archetypes.len(), "archetypes evaluated");
             }
-            swarm_wire::builder::ArchetypesReply::Failed { error_tail } => {
+            swarm_queue_client::builder::ArchetypesReply::Failed { error_tail } => {
                 tracing::warn!(%error_tail, "archetype evaluation failed");
             }
         }

swarm-builder/src/nix_build.rs

@@ -16,7 +16,7 @@ use std::path::PathBuf;
 use std::process::Stdio;
 use std::time::Duration;
 
-use swarm_wire::builder::{BuildAgent, Reply};
+use swarm_queue_client::builder::{BuildAgent, Reply};
 use tokio::io::AsyncReadExt as _;
 
 /// The most of `nix`'s stderr a failed build's reply carries, from its end.
@@ -293,7 +293,7 @@ pub(crate) fn tail(stderr: &str, status: std::process::ExitStatus) -> String {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use swarm_wire::builder::BUILD_DEADLINE;
+    use swarm_queue_client::builder::BUILD_DEADLINE;
 
     fn job() -> BuildAgent {
         BuildAgent {

swarm-claude-login/Cargo.toml

@@ -21,8 +21,6 @@ hive-types.workspace = true
 swarm-queue-client.workspace = true
 # The credentials and queue client secret paths, and the store login.
 swarm-secret-client.workspace = true
-# The login subject and the requests and replies it carries.
-swarm-wire.workspace = true
 tokio.workspace = true
 tracing.workspace = true
 

swarm-claude-login/src/login.rs

@@ -14,8 +14,8 @@ use std::process::Stdio;
 use std::sync::Arc;
 use std::time::Duration;
 
+use swarm_queue_client::claude_login::Reply;
 use swarm_secret_client::claude_login::Credentials;
-use swarm_wire::claude_login::Reply;
 use tokio::io::{AsyncBufReadExt as _, AsyncRead, AsyncWriteExt as _, BufReader};
 use tokio::process::{Child, ChildStdin, Command};
 use tokio::sync::{Mutex, watch};

swarm-claude-login/src/main.rs

@@ -2,7 +2,7 @@
 //!
 //! Connects to the swarm queue as its own OIDC client, takes an operator's
 //! login steps from swarm-controller on
-//! [`swarm_wire::claude_login::SUBJECT`], runs `claude auth login`
+//! [`swarm_queue_client::claude_login::SUBJECT`], runs `claude auth login`
 //! for the agent named ([`login`]), and writes the credentials it produces to
 //! that agent's store leaf, a new version over any stored before. The agent's
 //! harness takes a version newer than the one it last installed.
@@ -16,10 +16,10 @@ use std::sync::Arc;
 
 use anyhow::{Context, Result, bail};
 use futures_util::StreamExt as _;
+use swarm_queue_client::claude_login::{Reply, Request, SESSION_DEADLINE, STEP_DEADLINE, SUBJECT};
 use swarm_queue_client::{ClientSecret, QueueConfig};
 use swarm_secret_client::claude_login::{Credentials, client_secret_path, credentials_path};
 use swarm_secret_client::stored_secret::StoredSecret;
-use swarm_wire::claude_login::{Reply, Request, SESSION_DEADLINE, STEP_DEADLINE, SUBJECT};
 
 mod login;
 
@@ -190,7 +190,7 @@ mod tests {
     use std::sync::Arc;
     use std::time::Duration;
 
-    use swarm_wire::claude_login::{Reply, Request};
+    use swarm_queue_client::claude_login::{Reply, Request};
 
     use super::{handle, login};
 

swarm-controller/Cargo.toml

@@ -118,8 +118,6 @@ swarm-queue-client = { workspace = true, features = [
 # name and the object's shape are agreements between the two ends, and a
 # second spelling here would be a store this hive could not read.
 swarm-secret-client.workspace = true
-# The builder and claude login subjects, requests and replies it sends.
-swarm-wire.workspace = true
 # The appservice calls `matrix_account::agent_token` mints agents' accounts
 # with — shared with `swarm-matrix-ctl`, which pins the same device id.
 swarm-matrix-client.workspace = true

swarm-controller/src/archetypes.rs

@@ -16,7 +16,7 @@ use hive_sh4re::permissions::Permission;
 use problem_details::ProblemDetails;
 use serde::{Deserialize, Serialize};
 use swarm_queue_client::archetypes::{ArchetypeMeta, BUILTIN_SOURCE, SourceRecord};
-use swarm_wire::builder::{
+use swarm_queue_client::builder::{
     ARCHETYPES_DEADLINE, ARCHETYPES_SUBJECT, ArchetypesReply, EvalArchetypes,
 };
 use utoipa::ToSchema;
@@ -361,7 +361,7 @@ mod tests {
         let mut requests = builder
             .queue_subscribe(
                 ARCHETYPES_SUBJECT,
-                swarm_wire::builder::QUEUE_GROUP.to_owned(),
+                swarm_queue_client::builder::QUEUE_GROUP.to_owned(),
             )
             .await
             .expect("subscribe");

swarm-controller/src/builder.rs

@@ -16,7 +16,7 @@ use std::future::Future;
 
 use forgejo_api::structs::CommitStatusState;
 use hive_jobq::scheduler::Outcome;
-use swarm_wire::builder::{BuildAgent, REPLY_DEADLINE, Reply, SUBJECT};
+use swarm_queue_client::builder::{BuildAgent, REPLY_DEADLINE, Reply, SUBJECT};
 
 use crate::agent_renewal::unix_now;
 use crate::forge::{self, CONFIG_ORG};
@@ -534,7 +534,7 @@ mod tests {
 
         let builder = nats.client().await;
         let mut requests = builder
-            .queue_subscribe(SUBJECT, swarm_wire::builder::QUEUE_GROUP.to_owned())
+            .queue_subscribe(SUBJECT, swarm_queue_client::builder::QUEUE_GROUP.to_owned())
             .await
             .expect("subscribe");
         // A message the builder sends itself and receives back proves the

swarm-controller/src/claude_login.rs

@@ -21,7 +21,7 @@ use axum::extract::{Path, State};
 use axum::http::{HeaderMap, StatusCode};
 use problem_details::ProblemDetails;
 use serde::{Deserialize, Serialize};
-use swarm_wire::claude_login::{REPLY_DEADLINE, Reply, Request, SUBJECT};
+use swarm_queue_client::claude_login::{REPLY_DEADLINE, Reply, Request, SUBJECT};
 use utoipa::ToSchema;
 
 use crate::{AppState, error_problem};
@@ -243,7 +243,7 @@ mod tests {
     use std::sync::Mutex;
 
     use axum::http::StatusCode;
-    use swarm_wire::claude_login::{Reply, Request};
+    use swarm_queue_client::claude_login::{Reply, Request};
 
     use super::{LoginSink, relay};
 

swarm-controller/src/main.rs

@@ -601,7 +601,7 @@ async fn build_agent(
     rev: String,
     pr: u64,
 ) -> hive_jobq::scheduler::Outcome {
-    let job = swarm_wire::builder::BuildAgent { agent, rev, pr };
+    let job = swarm_queue_client::builder::BuildAgent { agent, rev, pr };
     let builds = builder::runs::Builds::Live(deps.queue.clone());
     let link_base = std::env::var(PUBLIC_URL_ENV).ok();
     builder::run(

swarm-nats-auth/Cargo.toml

@@ -33,8 +33,6 @@ swarm-queue-client = { workspace = true, features = ["notices"] }
 # credentials `swarm-agent-verify` checks a presented token against.
 swarm-secret-client.workspace = true
 swarm-agent-verify.workspace = true
-# The builder and login subjects it grants.
-swarm-wire.workspace = true
 tokio.workspace = true
 tracing.workspace = true
 tracing-subscriber.workspace = true

swarm-nats-auth/src/policy.rs

@@ -281,11 +281,11 @@ impl Policy {
         Permissions {
             publish: vec![Self::inbox(client_id)],
             subscribe: Some(vec![
-                swarm_wire::builder::SUBJECT.to_owned(),
-                swarm_wire::builder::ARCHETYPES_SUBJECT.to_owned(),
+                swarm_queue_client::builder::SUBJECT.to_owned(),
+                swarm_queue_client::builder::ARCHETYPES_SUBJECT.to_owned(),
                 Self::inbox(client_id),
             ]),
-            responses: Some(swarm_wire::builder::REPLY_DEADLINE),
+            responses: Some(swarm_queue_client::builder::REPLY_DEADLINE),
         }
     }
 
@@ -296,10 +296,10 @@ impl Policy {
         Permissions {
             publish: vec![Self::inbox(client_id)],
             subscribe: Some(vec![
-                swarm_wire::claude_login::SUBJECT.to_owned(),
+                swarm_queue_client::claude_login::SUBJECT.to_owned(),
                 Self::inbox(client_id),
             ]),
-            responses: Some(swarm_wire::claude_login::REPLY_DEADLINE),
+            responses: Some(swarm_queue_client::claude_login::REPLY_DEADLINE),
         }
     }
 
@@ -661,11 +661,11 @@ impl Policy {
             // back on this client's inbox, which it already subscribes to.
             swarm_queue_client::review_classifier::SUBJECT.to_owned(),
             // A build of an agent config, sent as a request the same way.
-            swarm_wire::builder::SUBJECT.to_owned(),
+            swarm_queue_client::builder::SUBJECT.to_owned(),
             // An archetype evaluation, sent as a request the same way.
-            swarm_wire::builder::ARCHETYPES_SUBJECT.to_owned(),
+            swarm_queue_client::builder::ARCHETYPES_SUBJECT.to_owned(),
             // An operator's claude login step, sent as a request the same way.
-            swarm_wire::claude_login::SUBJECT.to_owned(),
+            swarm_queue_client::claude_login::SUBJECT.to_owned(),
             // The wanted-state buckets — one per hive, all created and written
             // by this single client.
             //
@@ -1532,8 +1532,8 @@ mod tests {
 
     #[test]
     fn the_builder_hears_its_subject_and_inbox_only_and_answers_by_reply() {
+        use swarm_queue_client::builder::{ARCHETYPES_SUBJECT, REPLY_DEADLINE, SUBJECT};
         use swarm_queue_client::client_inbox_prefix;
-        use swarm_wire::builder::{ARCHETYPES_SUBJECT, REPLY_DEADLINE, SUBJECT};
 
         let p = policy()
             .with_builders(vec![BUILDER.to_owned()])
@@ -1562,7 +1562,7 @@ mod tests {
 
     #[test]
     fn only_the_reader_may_send_a_build() {
-        use swarm_wire::builder::{ARCHETYPES_SUBJECT, SUBJECT};
+        use swarm_queue_client::builder::{ARCHETYPES_SUBJECT, SUBJECT};
 
         let p = with_classifier().with_builders(vec![BUILDER.to_owned()]);
         let reader = p.permissions("swarm-controller").expect("the reader");
@@ -1589,8 +1589,8 @@ mod tests {
 
     #[test]
     fn the_claude_login_minter_hears_its_subject_and_inbox_only_and_answers_by_reply() {
+        use swarm_queue_client::claude_login::{REPLY_DEADLINE, SUBJECT};
         use swarm_queue_client::client_inbox_prefix;
-        use swarm_wire::claude_login::{REPLY_DEADLINE, SUBJECT};
 
         let p = policy()
             .with_claude_logins(vec![CLAUDE_LOGIN.to_owned()])
@@ -1602,7 +1602,7 @@ mod tests {
         for refused in [
             ">".to_owned(),
             "$SWARM.>".to_owned(),
-            swarm_wire::builder::SUBJECT.to_owned(),
+            swarm_queue_client::builder::SUBJECT.to_owned(),
             reply(&client_inbox_prefix("swarm-controller")),
         ] {
             assert!(
@@ -1618,7 +1618,7 @@ mod tests {
 
     #[test]
     fn only_the_reader_may_send_a_login_step() {
-        use swarm_wire::claude_login::SUBJECT;
+        use swarm_queue_client::claude_login::SUBJECT;
 
         let p = with_classifier()
             .with_builders(vec![BUILDER.to_owned()])

swarm-queue-client/src/archetypes.rs

@@ -4,7 +4,7 @@
 //!
 //! **swarm-controller is the only writer and the only reader.** The swarm
 //! builder evaluates the source and answers on
-//! `swarm_wire::builder::ARCHETYPES_SUBJECT`; the controller checks each
+//! [`crate::builder::ARCHETYPES_SUBJECT`]; the controller checks each
 //! archetype's settings the way `POST /api/agents` checks them and writes the
 //! result here, so the create screen lists archetypes from a value that a
 //! create would accept.

swarm-queue-client/src/builder.rs

@@ -0,0 +1,121 @@
+//! The swarm builder's requests: the subjects swarm-controller sends a build
+//! and an archetype evaluation on, and what travels each way.
+//!
+//! Three crates name these: the controller sends the requests, the builder
+//! answers them, and the auth-callout responder grants the subjects to each.
+
+use std::time::Duration;
+
+use serde::{Deserialize, Serialize};
+
+/// The subject every build goes to. The controller is its one publisher and
+/// the builder its one subscriber; the builder answers on the request's reply
+/// subject.
+pub const SUBJECT: &str = "$SWARM.builder.build";
+
+/// The queue group the builder subscribes in, so a second instance shares the
+/// requests instead of running each one twice.
+pub const QUEUE_GROUP: &str = "builder";
+
+/// The longest one build may take before the builder stops it and answers
+/// with a timeout.
+pub const BUILD_DEADLINE: Duration = Duration::from_hours(1);
+
+/// How long the controller waits for the reply, and the queue lets the
+/// builder answer: the build at its deadline, plus a minute the builder spends
+/// on a request's wait for the build slot, the forge token read before the
+/// build and the reply's trip back.
+pub const REPLY_DEADLINE: Duration = Duration::from_mins(61);
+
+/// One build: an agent's config repo at one commit, on the builder's own
+/// agent base.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct BuildAgent {
+    /// The agent, which is also its config repo's name.
+    pub agent: String,
+    /// The commit to build.
+    pub rev: String,
+    /// The PR the commit is the head of; its `refs/pull/<pr>/head` is the ref
+    /// the builder fetches the commit through.
+    pub pr: u64,
+}
+
+/// The builder's answer to one [`BuildAgent`].
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "state", rename_all = "kebab-case")]
+pub enum Reply {
+    /// The config built; `out_path` is the system closure's store path.
+    Built { out_path: String },
+    /// The build did not finish: the last lines `nix` printed, or why the
+    /// builder could not start it.
+    Failed { error_tail: String },
+}
+
+/// The subject an archetype evaluation goes to: the controller asks, the
+/// builder evaluates the `meta` of every `hyperhiveArchetypes` entry of its own
+/// hyperhive source and answers on the request's reply subject.
+pub const ARCHETYPES_SUBJECT: &str = "$SWARM.builder.archetypes";
+
+/// The longest one archetype evaluation may take, and how long the controller
+/// waits for its reply.
+pub const ARCHETYPES_DEADLINE: Duration = Duration::from_mins(2);
+
+/// One archetype evaluation. No field yet: the builder evaluates the hyperhive
+/// source it was deployed with.
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct EvalArchetypes {}
+
+/// The builder's answer to one [`EvalArchetypes`].
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "state", rename_all = "kebab-case")]
+pub enum ArchetypesReply {
+    /// `source` is the flake evaluated; `archetypes` maps each archetype's
+    /// name to its `meta`, as `nix eval --json` printed it and unchecked.
+    Evaluated {
+        source: String,
+        archetypes: serde_json::Map<String, serde_json::Value>,
+    },
+    /// The evaluation did not finish: the last lines `nix` printed, or why the
+    /// builder could not start it.
+    Failed { error_tail: String },
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn the_wire_tags_the_reply_by_state() {
+        let json = serde_json::to_value(Reply::Built {
+            out_path: "/nix/store/x".to_owned(),
+        })
+        .expect("encodes");
+        assert_eq!(json["state"], "built");
+        assert_eq!(json["out_path"], "/nix/store/x");
+        let json = serde_json::to_value(Reply::Failed {
+            error_tail: "e".to_owned(),
+        })
+        .expect("encodes");
+        assert_eq!(json["state"], "failed");
+    }
+
+    #[test]
+    fn the_reply_deadline_outlasts_the_build() {
+        assert!(REPLY_DEADLINE > BUILD_DEADLINE);
+    }
+
+    #[test]
+    fn the_archetypes_reply_is_tagged_by_state() {
+        let json = serde_json::to_value(ArchetypesReply::Evaluated {
+            source: "/nix/store/h".to_owned(),
+            archetypes: serde_json::Map::new(),
+        })
+        .expect("encodes");
+        assert_eq!(json["state"], "evaluated");
+        let json = serde_json::to_value(ArchetypesReply::Failed {
+            error_tail: "e".to_owned(),
+        })
+        .expect("encodes");
+        assert_eq!(json["state"], "failed");
+    }
+}

swarm-queue-client/src/claude_login.rs

@@ -0,0 +1,93 @@
+//! The claude login minter's requests: the subject swarm-controller sends an
+//! operator's login steps on, and what travels each way.
+//!
+//! Three crates name these: the controller sends the requests, the minter
+//! answers them, and the auth-callout responder grants the one subject to
+//! each.
+//!
+//! A login is two requests for one agent:
+//! [`Request::Start`](crate::claude_login::Request::Start) runs
+//! `claude auth login` and answers with the URL it printed, and
+//! [`Request::Code`](crate::claude_login::Request::Code) hands it the code the
+//! operator pasted and answers once the credentials are in the agent's store
+//! leaf. The running login lives in the minter's memory between the two, so
+//! the swarm runs one minter.
+
+use std::time::Duration;
+
+use serde::{Deserialize, Serialize};
+
+/// The subject every request goes to. The controller is its one publisher
+/// and the minter its one subscriber; the minter answers on the request's
+/// reply subject.
+pub const SUBJECT: &str = "$SWARM.claude-login.request";
+
+/// The longest the minter waits for `claude` to print the login URL, and
+/// then for it to finish once the code is in.
+pub const STEP_DEADLINE: Duration = Duration::from_mins(1);
+
+/// How long the controller waits for a reply, and the queue lets the minter
+/// answer: a step at its deadline, plus the store write.
+pub const REPLY_DEADLINE: Duration = Duration::from_secs(90);
+
+/// How long a started login waits for its code before the minter stops it
+/// and deletes its scratch directory.
+pub const SESSION_DEADLINE: Duration = Duration::from_mins(15);
+
+/// One step of an operator's login of one agent.
+///
+/// No `Debug` derive: [`Request::Code`] carries the one-time code.
+#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "step", rename_all = "kebab-case")]
+pub enum Request {
+    /// Start a login for `agent`, replacing one already running for it.
+    Start {
+        agent: String,
+        /// The swarm UI user, as the gateway named them.
+        operator: String,
+    },
+    /// Hand the running login for `agent` the code the operator pasted.
+    Code { agent: String, code: String },
+    /// Stop the running login for `agent`, if any.
+    Cancel { agent: String },
+}
+
+/// The minter's answer to one [`Request`].
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "state", rename_all = "kebab-case")]
+pub enum Reply {
+    /// The login is running; the operator opens `url` and pastes the code it
+    /// shows back.
+    Started { url: String },
+    /// The credentials are stored in the agent's leaf, as its newest
+    /// version.
+    Stored,
+    /// The running login, if there was one, is stopped.
+    Cancelled,
+    /// The step failed: why, with the last lines `claude` printed where it
+    /// printed any.
+    Failed { error: String },
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn the_wire_tags_the_request_by_step_and_the_reply_by_state() {
+        let json = serde_json::to_value(Request::Code {
+            agent: "atlas".to_owned(),
+            code: "c".to_owned(),
+        })
+        .expect("encodes");
+        assert_eq!(json["step"], "code");
+        assert_eq!(json["agent"], "atlas");
+        let json = serde_json::to_value(Reply::Stored).expect("encodes");
+        assert_eq!(json["state"], "stored");
+    }
+
+    #[test]
+    fn the_reply_deadline_outlasts_a_step() {
+        assert!(REPLY_DEADLINE > STEP_DEADLINE);
+    }
+}