Skip to main content

subc_protocol/
session.rs

1//! Session route control wire contract.
2//!
3//! subc has two distinct channel-0 handshakes. Module registration is the
4//! module-to-subc `HELLO`/`HELLO_ACK` handshake that registers the manifest and
5//! liveness. Route bind is the client-to-subc-to-module request/response
6//! handshake that binds one client route to a module route channel.
7
8use std::collections::BTreeMap;
9
10use serde::{Deserialize, Serialize};
11use serde_json::Value;
12
13use crate::{
14    call_mode::CallMode,
15    manifest::{CapabilityDeclarations, ProviderRole},
16    scope::{
17        ScopeEnd, ScopeEndResult, ScopeEnded, ScopeRecord, ScopeRecordResult, ScopeStamp,
18        ScopeStatus,
19    },
20    BindIdentity, Principal, RouteCloseReason, RouteTarget,
21};
22
23pub const MODULE_CONTROL_OP_HEALTH_CHECK: &str = "health.check";
24pub const MODULE_TO_SUBC_OP_CATALOG_UPDATE: &str = "catalog.update";
25
26#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
27#[serde(rename_all = "snake_case")]
28pub enum HealthStatus {
29    Ok,
30    Degraded,
31    Failing,
32}
33
34#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
35pub struct HealthReport {
36    pub status: HealthStatus,
37    #[serde(default, skip_serializing_if = "Option::is_none")]
38    pub detail: Option<String>,
39    #[serde(default, skip_serializing_if = "Option::is_none")]
40    pub metrics: Option<Value>,
41}
42
43impl HealthReport {
44    pub fn ok() -> Self {
45        Self {
46            status: HealthStatus::Ok,
47            detail: None,
48            metrics: None,
49        }
50    }
51}
52
53/// subc-to-module channel-0 control RPC body.
54#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
55#[serde(tag = "op")]
56// RouteBind carries the complete bind metadata, while HealthCheck is a marker;
57// preserving the direct wire shape is more useful than boxing every bind field.
58#[allow(clippy::large_enum_variant)]
59pub enum ModuleControlRequest {
60    #[serde(rename = "route.bind")]
61    RouteBind {
62        route_channel: u16,
63        epoch: u32,
64        target: RouteTarget,
65        identity: BindIdentity,
66        /// The daemon's attestation of the consumer, and the only field here a
67        /// provider may grant privilege on.
68        ///
69        /// `Reserved` is minted at exactly one place in the daemon, on the branch
70        /// where the consumer's launch nonce matched a supervised spawn — the
71        /// function that checks is the function that mints, so the value cannot
72        /// exist without the check having run. That property is what a provider is
73        /// relying on, and it is the reason to key authority on this rather than on
74        /// `identity`, which is client-supplied and unattested (see BindIdentity).
75        ///
76        /// Absent means the daemon made no attestation, which is not the same as a
77        /// denial: it is the shape a pre-attestation peer sends. Treat it as
78        /// unattested rather than as trusted-by-default.
79        #[serde(default, skip_serializing_if = "Option::is_none")]
80        principal: Option<Principal>,
81        /// Consumer-declared reverse-request families and provider-contract
82        /// capabilities for the route. For example, `content/v1` declares that
83        /// the consumer understands the tool-provider content result format.
84        /// This remains an unverified declaration that grants nothing; a provider
85        /// that over-trusts it may still send reverse requests that later time
86        /// out or deny. Providers must treat an absent field as no declared
87        /// capability. The vocabulary is open strings; known MCP method-family
88        /// values today are "elicitation", "sampling", and "roots".
89        #[serde(default, skip_serializing_if = "Option::is_none")]
90        consumer_capabilities: Option<Vec<String>>,
91        /// The versions of provider roles the consumer speaks on this route,
92        /// role name to version (`{"tool-provider": "v1"}`), copied from the
93        /// consumer's `route.open` unchanged. Like `consumer_capabilities` it
94        /// is the consumer's unverified declaration and grants nothing; a
95        /// provider uses it to choose which version of a role's wire shape to
96        /// speak. The daemon has checked it with [`validate_role_versions`] and
97        /// never sends an empty map. Absent means the consumer declared none:
98        /// a legacy consumer, or a daemon that predates the field.
99        #[serde(default, skip_serializing_if = "Option::is_none")]
100        role_versions: Option<BTreeMap<String, String>>,
101        /// Opaque admission facts supplied by the configured carrier module.
102        #[serde(default, skip_serializing_if = "Option::is_none")]
103        admission_facts: Option<Value>,
104        /// The daemon's stamp of the scope the route was admitted under, taken
105        /// from the owner's synced record at admission. Like `principal`, it is
106        /// the daemon's, never the opener's: a provider may act on it (on
107        /// `owner_authorized`, `delegates` and `agent_id` together), and must
108        /// treat it as fixed for the route's life, because a change that
109        /// revokes authority closes the route.
110        ///
111        /// Absent means the route was opened without a scope, or by a daemon
112        /// that predates scopes. A provider that needs a scope refuses the bind.
113        #[serde(default, skip_serializing_if = "Option::is_none")]
114        scope: Option<ScopeStamp>,
115        /// The daemon-derived mode, sent only to targets declaring
116        /// [`crate::call_mode::CALL_MODES_CAPABILITY`]. If absent, readers derive
117        /// the mode from `scope` with [`crate::call_mode::derive_call_mode`].
118        /// Providers must refuse an unknown mode.
119        #[serde(default, skip_serializing_if = "Option::is_none")]
120        call_mode: Option<CallMode>,
121    },
122    #[serde(rename = "health.check")]
123    HealthCheck {},
124}
125
126/// One-way subc-to-module channel-0 control command.
127#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
128#[serde(tag = "op")]
129pub enum ModuleControlCommand {
130    #[serde(rename = "module.draining")]
131    Draining {
132        reason: RouteCloseReason,
133        /// Absolute Unix-millisecond deadline for this drain.
134        ///
135        /// WALL CLOCK, WHILE THE DAEMON ENFORCES THE CEILING ON A
136        /// SUSPEND-EXCLUDING MONOTONIC CLOCK (`Instant`, supervise.rs). Both
137        /// processes share one host so `CLOCK_REALTIME` agrees exactly, and the
138        /// two clocks diverge only across host sleep: `Instant` stops, wall does
139        /// not. So a module that sleeps mid-drain wakes to a deadline further in
140        /// the past than the daemon's own ceiling, computes LESS remaining time
141        /// than it has, and seals early.
142        ///
143        /// That direction is deliberate and is the safe one — a module stopping
144        /// early loses nothing, since the daemon kills at its own ceiling
145        /// regardless. The reverse (a module believing it has time the daemon
146        /// has already spent) is the failure this ordering avoids. A module must
147        /// therefore treat this as "no later than", never as a grant.
148        deadline_ms: u64,
149    },
150}
151
152/// Module-to-subc channel-0 response body.
153#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
154#[serde(tag = "op")]
155pub enum ModuleControlResponse {
156    /// ACK-only success. Rejections use the `FrameType::Error` lane.
157    #[serde(rename = "route.bind")]
158    RouteBindAck {},
159    #[serde(rename = "health.check")]
160    HealthCheck {
161        status: HealthStatus,
162        #[serde(default, skip_serializing_if = "Option::is_none")]
163        detail: Option<String>,
164        #[serde(default, skip_serializing_if = "Option::is_none")]
165        metrics: Option<Value>,
166    },
167}
168
169/// Module-originated channel-0 control RPC body.
170///
171/// This is intentionally separate from [`ModuleControlRequest`]: that enum is the
172/// daemon-to-module direction (`route.bind`, `health.check`), while these bodies
173/// are sent by an already-registered module to subc on a `REQUEST` frame.
174#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
175#[serde(tag = "op")]
176#[non_exhaustive]
177pub enum ModuleControlRequestFromModule {
178    /// Ask the daemon whether a stored source may still open its route.
179    #[serde(rename = "route.authorize")]
180    RouteAuthorize {
181        principal: Principal,
182        scope: crate::scope::RouteAuthorizeScope,
183        target: String,
184        expected: crate::scope::RouteAuthorizeExpected,
185    },
186    #[serde(rename = "catalog.update")]
187    CatalogUpdate {
188        provides: Vec<ProviderRole>,
189        /// An attested replacement for the static capability declaration emitted
190        /// by the module's current manifest. `None` preserves the prior
191        /// declaration so existing role-only catalog updates remain byte-identical.
192        #[serde(default, skip_serializing_if = "Option::is_none")]
193        capabilities: Option<CapabilityDeclarations>,
194        /// Updates readiness without re-registering. `None` leaves it unchanged.
195        ///
196        /// Both directions are allowed, but repeatedly flapping readiness looks
197        /// like a restart storm to callers and is a defect in the module.
198        #[serde(default, skip_serializing_if = "Option::is_none")]
199        ready: Option<bool>,
200    },
201    #[serde(rename = "supervisor.live_roots")]
202    LiveRoots {},
203    /// Attribute agent-requested command roots to the declaring module.
204    /// Only the module's supervised connection may send this operation.
205    /// `known`, when present, replaces its complete live root set. The reply
206    /// is an empty object; invalid roots are ignored independently.
207    #[serde(rename = "supervisor.agent_commands")]
208    AgentCommands {
209        started: Vec<AgentCommandRoot>,
210        finished: Vec<AgentCommandFinished>,
211        #[serde(default, skip_serializing_if = "Option::is_none")]
212        known: Option<Vec<AgentCommandRoot>>,
213    },
214    /// Register this module's full scope set. The owner is the module whose
215    /// registered connection sends it; nothing in the body names the owner.
216    /// Per-record refusals come back in the reply; a refusal of the whole sync
217    /// (not the owner's sync authority, a stale generation, a bound exceeded)
218    /// is an `Error` frame and changes nothing.
219    #[serde(rename = "scope.sync")]
220    ScopeSync {
221        generation: u64,
222        scopes: Vec<ScopeRecord>,
223    },
224    /// Change selected scopes after the daemon accepts a full `scope.sync` from
225    /// this connection. Shares the full sync's generation sequence. Unlike a
226    /// full sync, omitting a scope does not end it; expiry processing still runs.
227    /// A whole-call refusal is an `Error` frame and changes nothing.
228    #[serde(rename = "scope.apply")]
229    ScopeApply {
230        generation: u64,
231        upsert: Vec<ScopeRecord>,
232        end: Vec<ScopeEnd>,
233    },
234    /// Read one scope's current state.
235    #[serde(rename = "scope.describe")]
236    ScopeDescribe {
237        owner: Principal,
238        #[serde(rename = "ref")]
239        scope_ref: String,
240    },
241}
242
243/// A command's PID and kernel start time in milliseconds since the Unix epoch.
244/// Obtain the time through `subc_os::process_start_time_ms`, not a wall clock.
245#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, PartialOrd, Ord)]
246pub struct AgentCommandRoot {
247    pub pid: u32,
248    pub start_time_ms: u64,
249}
250
251/// A completed declared root. CPU includes reaped descendants where available.
252#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
253pub struct AgentCommandFinished {
254    pub pid: u32,
255    pub start_time_ms: u64,
256    #[serde(default, skip_serializing_if = "Option::is_none")]
257    pub cpu_ms: Option<u64>,
258}
259
260/// Counts of routes for one canonical project root.
261#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
262pub struct LiveRoot {
263    pub project_root: std::path::PathBuf,
264    pub bound: u64,
265    pub pending: u64,
266}
267
268/// subc's channel-0 response body for module-originated control RPCs.
269#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
270#[serde(tag = "op")]
271// ScopeDescribe carries a complete stamp. Keep its public fields inline to
272// preserve the response construction API instead of boxing a single variant.
273#[allow(clippy::large_enum_variant)]
274pub enum ModuleControlResponseToModule {
275    #[serde(rename = "catalog.update")]
276    CatalogUpdate {},
277    #[serde(rename = "supervisor.live_roots")]
278    LiveRoots {
279        roots: Vec<LiveRoot>,
280        unknown_root_bindings: u64,
281        total_bindings: u64,
282    },
283    #[serde(rename = "scope.sync")]
284    ScopeSync {
285        generation: u64,
286        results: Vec<ScopeRecordResult>,
287        #[serde(default, skip_serializing_if = "Vec::is_empty")]
288        ended: Vec<ScopeEnded>,
289    },
290    #[serde(rename = "scope.apply")]
291    ScopeApply {
292        generation: u64,
293        results: Vec<ScopeRecordResult>,
294        end_results: Vec<ScopeEndResult>,
295        #[serde(default, skip_serializing_if = "Vec::is_empty")]
296        ended: Vec<ScopeEnded>,
297    },
298    #[serde(rename = "scope.describe")]
299    ScopeDescribe {
300        status: ScopeStatus,
301        /// The live epoch, or for `ended` the most recent epoch that ended.
302        #[serde(default, skip_serializing_if = "Option::is_none")]
303        scope_epoch: Option<u64>,
304        daemon_incarnation: String,
305        /// Whether the owner has synced since this daemon incarnation started.
306        owner_synced: bool,
307        /// Whether the owner is a module in the daemon's supervised roster.
308        owner_configured: bool,
309        /// The stamp fields, present only when `status` is `live`.
310        #[serde(default, skip_serializing_if = "Option::is_none")]
311        scope: Option<ScopeStamp>,
312    },
313}
314
315/// A module's channel-0 request to confirm one in-flight write with the person.
316///
317/// This standalone body keeps the existing exhaustive module-control enums
318/// unchanged. The daemon validates the summary and the asking connection's
319/// permission before showing a prompt; constructing a request grants nothing.
320#[non_exhaustive]
321#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
322pub struct OperatorConfirmRequest {
323    op: OperatorConfirmOp,
324    pub summary: String,
325    /// The caller's route channel as seen on the asking module's connection.
326    pub route_channel: u16,
327    /// The epoch of that route on the asking module's connection.
328    pub route_epoch: u32,
329    /// What the asking module says it is confirming. Absent (an older module)
330    /// means the same as an unrecognised kind: the person is prompted. Only
331    /// [`OperatorConfirmKind::Operation`] can ever be answered without a
332    /// prompt; [`OperatorConfirmKind::Enrollment`] always prompts.
333    #[serde(default, skip_serializing_if = "Option::is_none")]
334    pub kind: Option<OperatorConfirmKind>,
335    /// The management operation being confirmed, as the asking module's
336    /// manifest names it in `confirm_operations`. Meaningful only with
337    /// [`OperatorConfirmKind::Operation`]; absent means the person is prompted.
338    #[serde(default, skip_serializing_if = "Option::is_none")]
339    pub operation: Option<String>,
340}
341
342impl OperatorConfirmRequest {
343    /// A request with neither `kind` nor `operation`, whose bytes match what
344    /// modules sent before those fields existed.
345    pub fn new(summary: impl Into<String>, route_channel: u16, route_epoch: u32) -> Self {
346        Self {
347            op: OperatorConfirmOp::Confirm,
348            summary: summary.into(),
349            route_channel,
350            route_epoch,
351            kind: None,
352            operation: None,
353        }
354    }
355
356    /// Set or clear `kind`.
357    #[must_use]
358    pub fn with_kind(mut self, kind: Option<OperatorConfirmKind>) -> Self {
359        self.kind = kind;
360        self
361    }
362
363    /// Set or clear `operation`.
364    #[must_use]
365    pub fn with_operation(mut self, operation: Option<String>) -> Self {
366        self.operation = operation;
367        self
368    }
369}
370
371/// The `kind` of an [`OperatorConfirmRequest`].
372///
373/// A value from a newer module decodes as [`OperatorConfirmKind::Unknown`],
374/// keeping its spelling, rather than refusing the request. The daemon prompts
375/// for every kind except an explicit `operation`.
376#[derive(Debug, Clone, PartialEq, Eq)]
377pub enum OperatorConfirmKind {
378    /// A management operation the module declares in `confirm_operations`.
379    Operation,
380    /// Pairing or enrolling a device or credential. Always prompts.
381    Enrollment,
382    Unknown(String),
383}
384
385impl Serialize for OperatorConfirmKind {
386    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
387        serializer.serialize_str(match self {
388            Self::Operation => "operation",
389            Self::Enrollment => "enrollment",
390            Self::Unknown(value) => value,
391        })
392    }
393}
394
395impl<'de> Deserialize<'de> for OperatorConfirmKind {
396    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
397        Ok(match String::deserialize(deserializer)?.as_str() {
398            "operation" => Self::Operation,
399            "enrollment" => Self::Enrollment,
400            value => Self::Unknown(value.to_owned()),
401        })
402    }
403}
404
405/// A successful channel-0 reply to an [`OperatorConfirmRequest`].
406///
407/// Only `outcome: "confirmed"` confirms the write. Refusals use [`crate::ErrorBody`]
408/// instead. Readers must not treat an unknown outcome as confirmation.
409#[non_exhaustive]
410#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
411pub struct OperatorConfirmReply {
412    op: OperatorConfirmOp,
413    pub outcome: String,
414}
415
416impl OperatorConfirmReply {
417    pub fn confirmed() -> Self {
418        Self {
419            op: OperatorConfirmOp::Confirm,
420            outcome: "confirmed".to_string(),
421        }
422    }
423}
424
425// A required, single-valued field both emits the op and refuses a missing or
426// different op when decoding, without exposing a caller-editable tag.
427#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
428enum OperatorConfirmOp {
429    #[serde(rename = "operator.confirm")]
430    Confirm,
431}
432
433impl From<HealthReport> for ModuleControlResponse {
434    fn from(report: HealthReport) -> Self {
435        Self::HealthCheck {
436            status: report.status,
437            detail: report.detail,
438            metrics: report.metrics,
439        }
440    }
441}
442
443impl ModuleControlResponse {
444    pub fn health_report(&self) -> Option<HealthReport> {
445        match self {
446            Self::HealthCheck {
447                status,
448                detail,
449                metrics,
450            } => Some(HealthReport {
451                status: *status,
452                detail: detail.clone(),
453                metrics: metrics.clone(),
454            }),
455            Self::RouteBindAck {} => None,
456        }
457    }
458}
459
460/// Module-to-subc channel-0 push body.
461#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
462#[serde(tag = "op")]
463pub enum ModuleControlPush {
464    #[serde(rename = "route.status")]
465    RouteStatus {
466        route_channel: u16,
467        route_epoch: u32,
468        status: String,
469    },
470}
471
472/// The wire name of the `role_versions` field on `route.open` and
473/// `route.bind`, for the `detail.field` of the `invalid_request` error that
474/// refuses a malformed one.
475pub const ROLE_VERSIONS_FIELD: &str = "role_versions";
476
477/// Most entries a `role_versions` map may hold.
478pub const MAX_ROLE_VERSIONS: usize = 8;
479
480/// The longest role name accepted in `role_versions`, in bytes.
481pub const MAX_ROLE_NAME_LEN: usize = 64;
482
483/// Why a `role_versions` map was refused.
484#[derive(Clone, Debug, PartialEq, Eq)]
485#[non_exhaustive]
486pub enum RoleVersionsError {
487    /// The map has more than [`MAX_ROLE_VERSIONS`] entries.
488    TooMany { count: usize },
489    /// A role name is not lowercase ASCII letters and digits in words joined
490    /// by single hyphens (`tool-provider`), or is longer than
491    /// [`MAX_ROLE_NAME_LEN`] bytes.
492    InvalidRole { role: String },
493    /// A version is not `v` followed by a positive integer without leading
494    /// zeros (`v1`, `v12`).
495    InvalidVersion { role: String, version: String },
496}
497
498impl RoleVersionsError {
499    /// The request field the error is about: always [`ROLE_VERSIONS_FIELD`].
500    pub fn field(&self) -> &'static str {
501        ROLE_VERSIONS_FIELD
502    }
503}
504
505impl std::fmt::Display for RoleVersionsError {
506    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
507        match self {
508            Self::TooMany { count } => write!(
509                f,
510                "{ROLE_VERSIONS_FIELD} has {count} entries; at most {MAX_ROLE_VERSIONS} are allowed"
511            ),
512            Self::InvalidRole { role } => write!(
513                f,
514                "{ROLE_VERSIONS_FIELD} names role {role:?}, which is not lowercase letters and \
515                 digits in words joined by '-', at most {MAX_ROLE_NAME_LEN} bytes"
516            ),
517            Self::InvalidVersion { role, version } => write!(
518                f,
519                "{ROLE_VERSIONS_FIELD} gives role {role:?} version {version:?}, which is not 'v' \
520                 followed by a positive integer without leading zeros"
521            ),
522        }
523    }
524}
525
526impl std::error::Error for RoleVersionsError {}
527
528/// Check a `role_versions` map: at most [`MAX_ROLE_VERSIONS`] entries, each
529/// role name matching `^[a-z0-9]+(-[a-z0-9]+)*$` in at most
530/// [`MAX_ROLE_NAME_LEN`] bytes, and each version matching `^v[1-9][0-9]*$`.
531///
532/// The daemon refuses a `route.open` that fails this, so a consumer can run
533/// the same check before sending. An empty map passes; the daemon treats it
534/// as no declaration at all.
535pub fn validate_role_versions(
536    role_versions: &BTreeMap<String, String>,
537) -> Result<(), RoleVersionsError> {
538    if role_versions.len() > MAX_ROLE_VERSIONS {
539        return Err(RoleVersionsError::TooMany {
540            count: role_versions.len(),
541        });
542    }
543    for (role, version) in role_versions {
544        if !is_role_name(role) {
545            return Err(RoleVersionsError::InvalidRole { role: role.clone() });
546        }
547        if !is_role_version(version) {
548            return Err(RoleVersionsError::InvalidVersion {
549                role: role.clone(),
550                version: version.clone(),
551            });
552        }
553    }
554    Ok(())
555}
556
557fn is_role_name(role: &str) -> bool {
558    !role.is_empty()
559        && role.len() <= MAX_ROLE_NAME_LEN
560        && role.split('-').all(|word| {
561            !word.is_empty()
562                && word
563                    .bytes()
564                    .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit())
565        })
566}
567
568fn is_role_version(version: &str) -> bool {
569    let bytes = version.as_bytes();
570    bytes.len() >= 2
571        && bytes[0] == b'v'
572        && (b'1'..=b'9').contains(&bytes[1])
573        && bytes[2..].iter().all(u8::is_ascii_digit)
574}
575
576#[cfg(test)]
577mod tests {
578    use super::*;
579
580    fn map(entries: &[(&str, &str)]) -> BTreeMap<String, String> {
581        entries
582            .iter()
583            .map(|(role, version)| (role.to_string(), version.to_string()))
584            .collect()
585    }
586
587    #[test]
588    fn role_versions_accept_role_names_and_positive_versions() {
589        for entries in [
590            vec![],
591            vec![("tool-provider", "v1")],
592            vec![("a", "v9"), ("b2", "v10"), ("x-1-y", "v1203")],
593        ] {
594            assert_eq!(
595                validate_role_versions(&map(&entries)),
596                Ok(()),
597                "{entries:?}"
598            );
599        }
600        let longest = "a".repeat(MAX_ROLE_NAME_LEN);
601        assert_eq!(validate_role_versions(&map(&[(&longest, "v1")])), Ok(()));
602        let full: BTreeMap<String, String> = (0..MAX_ROLE_VERSIONS)
603            .map(|index| (format!("role-{index}"), "v1".to_string()))
604            .collect();
605        assert_eq!(validate_role_versions(&full), Ok(()));
606    }
607
608    #[test]
609    fn role_versions_refuse_malformed_role_names() {
610        let too_long = "a".repeat(MAX_ROLE_NAME_LEN + 1);
611        for role in [
612            "",
613            "Tool-provider",
614            "tool_provider",
615            "tool provider",
616            "-tool",
617            "tool-",
618            "tool--provider",
619            "tool.provider",
620            "outil-é",
621            too_long.as_str(),
622        ] {
623            let error = validate_role_versions(&map(&[(role, "v1")])).unwrap_err();
624            assert_eq!(
625                error,
626                RoleVersionsError::InvalidRole {
627                    role: role.to_string()
628                },
629                "{role:?}"
630            );
631            assert_eq!(error.field(), "role_versions");
632        }
633    }
634
635    #[test]
636    fn role_versions_refuse_malformed_versions() {
637        for version in [
638            "", "v", "v0", "v01", "1", "V1", "v1.0", "v-1", "v1 ", " v1", "vx",
639        ] {
640            let error = validate_role_versions(&map(&[("tool-provider", version)])).unwrap_err();
641            assert_eq!(
642                error,
643                RoleVersionsError::InvalidVersion {
644                    role: "tool-provider".to_string(),
645                    version: version.to_string(),
646                },
647                "{version:?}"
648            );
649            assert_eq!(error.field(), "role_versions");
650        }
651    }
652
653    #[test]
654    fn role_versions_refuse_more_than_eight_entries() {
655        let nine: BTreeMap<String, String> = (0..=MAX_ROLE_VERSIONS)
656            .map(|index| (format!("role-{index}"), "v1".to_string()))
657            .collect();
658        let error = validate_role_versions(&nine).unwrap_err();
659        assert_eq!(error, RoleVersionsError::TooMany { count: 9 });
660        assert_eq!(error.field(), "role_versions");
661        assert!(error.to_string().starts_with("role_versions"), "{error}");
662    }
663
664    #[test]
665    fn route_bind_omits_absent_role_versions_and_carries_present_ones_verbatim() {
666        let bind = |role_versions| ModuleControlRequest::RouteBind {
667            route_channel: 1,
668            epoch: 1,
669            target: crate::RouteTarget::ToolProvider {
670                module_id: "aft".to_string(),
671            },
672            identity: crate::BindIdentity::new("h", "s"),
673            principal: None,
674            consumer_capabilities: None,
675            role_versions,
676            admission_facts: None,
677            scope: None,
678            call_mode: None,
679        };
680        let absent = serde_json::to_value(bind(None)).unwrap();
681        assert!(absent.get("role_versions").is_none(), "{absent}");
682        let present = bind(Some(map(&[("tool-provider", "v1")])));
683        let encoded = serde_json::to_value(&present).unwrap();
684        assert_eq!(
685            encoded["role_versions"],
686            serde_json::json!({ "tool-provider": "v1" })
687        );
688        let decoded: ModuleControlRequest = serde_json::from_value(encoded).unwrap();
689        assert_eq!(decoded, present);
690    }
691}
692
693#[cfg(test)]
694mod agent_command_tests {
695    use super::*;
696
697    #[test]
698    fn agent_commands_round_trip_start_finish_and_known_snapshot() {
699        let root = AgentCommandRoot {
700            pid: 42,
701            start_time_ms: 1_700_000_000_123,
702        };
703        let request = ModuleControlRequestFromModule::AgentCommands {
704            started: vec![root],
705            finished: vec![AgentCommandFinished {
706                pid: 43,
707                start_time_ms: root.start_time_ms,
708                cpu_ms: Some(100),
709            }],
710            known: Some(vec![root]),
711        };
712        let value = serde_json::to_value(&request).unwrap();
713        assert_eq!(
714            value,
715            serde_json::json!({"op":"supervisor.agent_commands",
716            "started":[{"pid":42,"start_time_ms":1_700_000_000_123_u64}],
717            "finished":[{"pid":43,"start_time_ms":1_700_000_000_123_u64,"cpu_ms":100}],
718            "known":[{"pid":42,"start_time_ms":1_700_000_000_123_u64}]})
719        );
720        assert_eq!(
721            serde_json::from_value::<ModuleControlRequestFromModule>(value).unwrap(),
722            request
723        );
724        let absent = ModuleControlRequestFromModule::AgentCommands {
725            started: Vec::new(),
726            finished: vec![AgentCommandFinished {
727                pid: 1,
728                start_time_ms: 2,
729                cpu_ms: None,
730            }],
731            known: None,
732        };
733        assert_eq!(
734            serde_json::to_value(absent).unwrap(),
735            serde_json::json!({"op":"supervisor.agent_commands",
736            "started":[],"finished":[{"pid":1,"start_time_ms":2}]})
737        );
738    }
739}