nomoreide_remote_protocol/

version.rs

//! Version negotiation, capabilities, and what a phone does when the machine at
//! the other end is out of date.
//!
//! This answers the question the original relay plan left open. It matters more
//! than it looks: this project's own development machine ran a v0.1.103 daemon
//! against a v0.3.0 client for days, and the only signal was one warning line.
//! People do not upgrade daemons promptly, so "the versions differ" is the
//! normal case, not the exception, and it needs a designed answer rather than a
//! failure mode.
//!
//! Three rules, and they are deliberately different from each other:
//!
//! 1. **The envelope is invariant.** `v`, `id`, `type`, `deviceId`, `sentAt`,
//!    `replyTo`, `payload` are fixed for the life of the protocol. `v` versions
//!    the *payload union*, not the frame. That is what lets two peers with no
//!    version in common still exchange a hello, a rejection and a heartbeat
//!    instead of staring at each other.
//! 2. **An unknown command is an error.** Fail closed: a name this peer does
//!    not know is refused, never ignored. See [`super::device_bound`].
//! 3. **An unknown capability is an omission.** A feature the other end has not
//!    got is a thing to *say*, not a thing to fail on — the phone renders
//!    "your machine is running an older NoMoreIDE", and the rest of the session
//!    keeps working.
//!
//! Across a major gap the session still opens, in [`SessionMode::Degraded`]:
//! presence and read-only commands route, and every mutating command is refused
//! with [`super::errors::ErrorCode::UnsupportedProtocolVersion`]. Refusing the
//! whole session instead would leave the user a dead screen with no way to be
//! told what to do about it.

use serde::{Deserialize, Serialize};
use std::collections::BTreeSet;

/// The major version this build speaks.
pub const PROTOCOL_VERSION: u32 = 2;

/// The oldest major version worth talking to at all.
///
/// Below this the platform rejects the socket outright rather than degrading:
/// there is a point where "read-only and please upgrade" stops being reachable
/// because the frames themselves have changed.
///
/// Still 1 now that 2 exists, which is the whole point of the number: v2 added
/// frames and took none away, so a v1 daemon is not broken, only smaller. It
/// keeps every v1 capability and simply never advertises the terminal ones.
pub const MINIMUM_SPEAKABLE_VERSION: u32 = 1;

/// Every major version this build can serve, newest last.
pub const SUPPORTED_VERSIONS: &[u32] = &[1, 2];

/// A floor above what this build speaks would reject every peer, including
/// itself. Checked at compile time, for the same reason the limits are.
const _: () = assert!(MINIMUM_SPEAKABLE_VERSION <= PROTOCOL_VERSION);

/// A named, additively-shipped feature.
///
/// Capabilities exist so that adding a remote feature does not need a version
/// bump — which in a world of stale daemons would mean every new feature
/// degrading every old machine. The daemon advertises what it has; the platform
/// asks for nothing it was not offered.
///
/// The name is the wire value. It is a plain string type rather than an enum
/// because the *reading* side must tolerate names invented after it was built:
/// an unrecognised capability is one this peer will simply never use.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
#[serde(transparent)]
pub struct Capability(pub String);

impl Capability {
    pub fn new(name: &str) -> Self {
        Self(name.to_string())
    }

    pub fn as_str(&self) -> &str {
        &self.0
    }
}

/// The capabilities a v1 daemon advertises. One per allowlisted area, not one
/// per command — a phone needs to know whether agent turns are available, not
/// whether `agent.turn.cancel` specifically is.
pub mod capabilities {
    /// Sanitized device snapshot and presence. Always present; a daemon that
    /// cannot do this has nothing to offer.
    pub const DEVICE_SNAPSHOT: &str = "device.snapshot";
    /// Listing registered services with their runtime state.
    pub const SERVICE_LIST: &str = "service.list";
    /// `start`, `stop`, `restart` on an exact registered service.
    pub const SERVICE_ACTION: &str = "service.action";
    /// Bounded, redacted recent logs.
    pub const SERVICE_LOGS: &str = "service.logs";
    /// Listing registered bundles with their state. Read-only: the allowlist
    /// has no bundle mutation.
    pub const BUNDLE_LIST: &str = "bundle.list";
    /// Reporting which agent providers are installed.
    pub const AGENT_PROVIDERS: &str = "agent.providers";
    /// Starting, resuming and cancelling one agent turn.
    pub const AGENT_TURNS: &str = "agent.turns";
    /// Answering a pending mutating tool request.
    pub const AGENT_APPROVALS: &str = "agent.approvals";

    /// Listing the agent terminals running on the machine. **v2.**
    pub const TERMINAL_SESSIONS: &str = "terminal.sessions";
    /// Starting an agent terminal. **v2.**
    ///
    /// Its own capability, separate from mirroring, because they are different
    /// permissions: watching an agent somebody started is not the same as
    /// starting one. A machine can offer either without the other.
    pub const TERMINAL_SPAWN: &str = "terminal.spawn";
    /// Starting a **shell** terminal, and mirroring one. **v2.**
    ///
    /// Its own capability, and the only one here that is a genuine widening: a
    /// shell is arbitrary command execution. It is separate so a machine can
    /// offer agents from a phone without offering a shell, and so that turning
    /// it off is a thing a user can actually do.
    ///
    /// Kept honest: while this is advertised, "remote control cannot run
    /// arbitrary commands" is false, and the pairing copy says so.
    pub const TERMINAL_SHELL: &str = "terminal.shell";
    /// **Ending** an agent terminal, rather than only stopping the mirror.
    ///
    /// Its own name because it is the one thing on the terminal surface that
    /// destroys work. `terminal.attach` covers detaching, which leaves the
    /// agent running on purpose; this stops it. A machine can offer the whole
    /// rest of the surface — spawn, shell, mirror, type — and not this, which
    /// is the point of it being separate rather than folded into any of them.
    pub const TERMINAL_KILL: &str = "terminal.kill";
    /// Starting an agent terminal **in a named registered repository**, rather
    /// than only in the one the machine has selected.
    ///
    /// The one capability here that gates a *field* rather than a command:
    /// `terminal.spawn.request` is routable without it, and simply has no
    /// `repository` on it. It needs a name of its own because
    /// `TerminalSpawnRequest` denies unknown fields — a daemon built before the
    /// field existed refuses the entire frame rather than ignoring the key, so
    /// "try it and see" is not available to a phone the way an unknown
    /// capability normally is. A phone that is not offered this name sends what
    /// it always sent, and the agent starts in the selected repository.
    pub const TERMINAL_SPAWN_REPOSITORY: &str = "terminal.spawn.repository";
    /// Mirroring one agent terminal: its output, and typing into it. **v2.**
    ///
    /// Deliberately separate from [`TERMINAL_SESSIONS`], so a machine can show
    /// a phone *that* an agent is running without handing over its screen.
    pub const TERMINAL_ATTACH: &str = "terminal.attach";

    // --- The read-only inspection surface -----------------------------------
    //
    // Everything below answers "what is going on?" and nothing below changes
    // anything. They are separate capabilities rather than one `inspect`
    // because they need different things of the machine — two of them need a
    // GitHub account, one needs an agent to have run at least once, and two
    // need only the daemon itself. A phone must be able to tell "this machine
    // has no GitHub connected" from "this build is too old", and one
    // capability covering all five could not say either.

    /// Listing GitHub Actions workflow runs, and one run's jobs.
    ///
    /// Read-only: there is no re-run, no cancel, and no dispatch. Watching CI
    /// from a phone is a different permission from steering it, and only the
    /// first is here.
    /// The machine's registered repositories, so a phone can say which one it
    /// is asking about. Its own capability rather than folded into
    /// `github.actions`: a daemon that predates the picker does not advertise
    /// it, and a phone that sees it missing keeps asking about the selected
    /// repository exactly as it did before.
    pub const REPOSITORIES: &str = "repositories.list";

    pub const GITHUB_ACTIONS: &str = "github.actions";
    /// Listing pull requests, and reading one.
    ///
    /// Read-only in the same sense: no merge, no create, no review. Those live
    /// in `nomoreide-actions` locally and have no frame here.
    pub const GITHUB_PULLS: &str = "github.pulls";
    /// Linear tasks: reading them, and — unlike the two above — writing them.
    ///
    /// The exception to the read-only rule the rest of this list follows, and
    /// deliberately: binding a repository, creating an issue, changing a state
    /// and commenting are classified as mutations in `linear.rs`, so a degraded
    /// session refuses them and nothing ever retries one. The key itself stays
    /// on the host — it is never sent to a device, and a scanned guest link
    /// does not carry this capability at all.
    pub const LINEAR: &str = "linear.tasks";
    /// What Claude and Codex have spent, and how close their rate-limit
    /// windows are.
    ///
    /// The one thing a phone can answer that a laptop cannot: whether starting
    /// a turn now is worth it. Reported without the working directory or the
    /// session id the local panel shows — see [`super::snapshot`].
    pub const AGENT_USAGE: &str = "agent.usage";
    /// The deduped error inbox: what is broken, in which service, how often.
    pub const DEVICE_ERRORS: &str = "device.errors";
    /// The runtime timeline: what the daemon did, across every service.
    pub const DEVICE_TIMELINE: &str = "device.timeline";

    /// Everything a fully-featured v1 daemon offers.
    pub const V1: &[&str] = &[
        DEVICE_SNAPSHOT,
        SERVICE_LIST,
        SERVICE_ACTION,
        SERVICE_LOGS,
        BUNDLE_LIST,
        AGENT_PROVIDERS,
        AGENT_TURNS,
        AGENT_APPROVALS,
    ];

    /// Everything a fully-featured v2 daemon offers: v1, plus the terminal,
    /// plus the read-only inspection surface.
    ///
    /// Additive by construction — v2 removed nothing, so this is `V1` with the
    /// new names appended rather than a second list to keep in step.
    ///
    /// **This list grows without a version bump, and that is the design.** A
    /// capability is what *this machine* offers, not what its protocol era
    /// defined; `PROTOCOL_VERSION` versions the payload union's frame rules,
    /// and a name a peer has not heard of is an omission rather than a failure.
    /// So a daemon built today advertises more than one built when v2 shipped,
    /// both are v2, and an older phone simply never asks for the extra names.
    pub const V2: &[&str] = &[
        DEVICE_SNAPSHOT,
        SERVICE_LIST,
        SERVICE_ACTION,
        SERVICE_LOGS,
        BUNDLE_LIST,
        AGENT_PROVIDERS,
        AGENT_TURNS,
        AGENT_APPROVALS,
        TERMINAL_SESSIONS,
        TERMINAL_ATTACH,
        TERMINAL_SPAWN,
        TERMINAL_SPAWN_REPOSITORY,
        TERMINAL_SHELL,
        TERMINAL_KILL,
        REPOSITORIES,
        GITHUB_ACTIONS,
        GITHUB_PULLS,
        LINEAR,
        AGENT_USAGE,
        DEVICE_ERRORS,
        DEVICE_TIMELINE,
    ];

    /// `V2` must extend `V1` rather than diverge from it. Checked here because
    /// the two lists are written out separately for readability.
    const _: () = {
        assert!(V2.len() == V1.len() + 13);
    };
}

/// What a daemon advertises, and what the platform holds about it.
///
/// A `BTreeSet` rather than a `Vec` so two daemons advertising the same
/// capabilities in different orders compare equal, and so the JSON is stable
/// enough to be a golden fixture.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(transparent)]
pub struct CapabilitySet(pub BTreeSet<Capability>);

impl CapabilitySet {
    /// Everything this build offers.
    pub fn current() -> Self {
        Self(
            capabilities::V2
                .iter()
                .map(|name| Capability::new(name))
                .collect(),
        )
    }

    pub fn contains(&self, name: &str) -> bool {
        self.0.iter().any(|capability| capability.as_str() == name)
    }

    pub fn from_names<'a>(names: impl IntoIterator<Item = &'a str>) -> Self {
        Self(names.into_iter().map(Capability::new).collect())
    }
}

/// How much of the protocol a negotiated session may use.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum SessionMode {
    /// Both ends agreed on a version this build serves. Everything the
    /// capability set allows is routable.
    Full,
    /// No shared version. Presence and read-only commands only; every mutation
    /// is refused, and the phone is told to update the machine.
    Degraded,
}

/// The outcome of comparing two peers' supported versions.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Negotiation {
    /// Agreed. `version` is the highest both sides can speak.
    Agreed { version: u32, mode: SessionMode },
    /// The peer is too old to talk to at all — its highest version is below
    /// [`MINIMUM_SPEAKABLE_VERSION`], or it offered none.
    Rejected { reason: RejectReason },
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum RejectReason {
    /// The peer advertised no versions at all.
    NoVersionsOffered,
    /// Every version the peer offered is below the floor.
    BelowMinimumVersion,
}

/// Decide what a session between `ours` and `theirs` may do.
///
/// The rule is: take the highest version both sides list. If there is none, and
/// the peer is at or above the floor, run degraded at the peer's own highest —
/// that is the version whose frames it will actually understand, so it is the
/// one to speak while telling it to upgrade.
pub fn negotiate(ours: &[u32], theirs: &[u32]) -> Negotiation {
    let Some(their_best) = theirs.iter().copied().max() else {
        return Negotiation::Rejected {
            reason: RejectReason::NoVersionsOffered,
        };
    };
    if their_best < MINIMUM_SPEAKABLE_VERSION {
        return Negotiation::Rejected {
            reason: RejectReason::BelowMinimumVersion,
        };
    }
    let shared = ours
        .iter()
        .copied()
        .filter(|version| theirs.contains(version))
        .max();
    match shared {
        Some(version) => Negotiation::Agreed {
            version,
            mode: SessionMode::Full,
        },
        None => Negotiation::Agreed {
            version: their_best,
            mode: SessionMode::Degraded,
        },
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// `current()` means "what this build offers", so it has to track the
    /// newest capability list rather than whichever one it was written against.
    /// It said `V1` for a while after v2 shipped, which made a current daemon
    /// look like it could not mirror a terminal it could.
    #[test]
    fn current_capabilities_are_the_newest_ones() {
        let current = CapabilitySet::current();
        for name in capabilities::V2 {
            assert!(current.contains(name), "{name} is missing from current()");
        }
    }

    #[test]
    fn identical_peers_agree_on_full() {
        assert_eq!(
            negotiate(SUPPORTED_VERSIONS, SUPPORTED_VERSIONS),
            Negotiation::Agreed {
                version: PROTOCOL_VERSION,
                mode: SessionMode::Full,
            }
        );
    }

    /// A newer platform meeting an older daemon takes the highest they share,
    /// which is the whole point of listing versions rather than sending one.
    #[test]
    fn overlapping_peers_take_the_highest_shared_version() {
        assert_eq!(
            negotiate(&[1, 2, 3], &[1, 2]),
            Negotiation::Agreed {
                version: 2,
                mode: SessionMode::Full,
            }
        );
    }

    /// The case the revision asked to design for: no overlap, but the daemon is
    /// still above the floor. The session opens read-only rather than dying, so
    /// the phone can say why.
    #[test]
    fn a_major_gap_degrades_rather_than_refusing() {
        assert_eq!(
            negotiate(&[4, 5], &[1]),
            Negotiation::Agreed {
                version: 1,
                mode: SessionMode::Degraded,
            }
        );
    }

    #[test]
    fn a_peer_below_the_floor_is_refused_outright() {
        assert_eq!(
            negotiate(&[1], &[0]),
            Negotiation::Rejected {
                reason: RejectReason::BelowMinimumVersion,
            }
        );
    }

    #[test]
    fn a_peer_offering_nothing_is_refused() {
        assert_eq!(
            negotiate(&[1], &[]),
            Negotiation::Rejected {
                reason: RejectReason::NoVersionsOffered,
            }
        );
    }

    #[test]
    fn the_current_capability_set_covers_every_v1_area() {
        let current = CapabilitySet::current();
        for name in capabilities::V1 {
            assert!(current.contains(name), "missing {name}");
        }
    }

    /// A capability nobody has heard of must read cleanly. It is a feature this
    /// peer will not use, not a frame it cannot parse.
    #[test]
    fn an_unknown_capability_parses_and_is_simply_absent() {
        let set: CapabilitySet =
            serde_json::from_str(r#"["service.list","something.invented.later"]"#).expect("parse");
        assert!(set.contains("service.list"));
        assert!(set.contains("something.invented.later"));
        assert!(!set.contains(capabilities::AGENT_TURNS));
    }

    #[test]
    fn the_version_we_speak_is_one_we_support() {
        assert!(SUPPORTED_VERSIONS.contains(&PROTOCOL_VERSION));
    }
}