agentmux_srv/backend/reactive/

types.rs

// Copyright 2025-2026, AgentMux Corp.
// SPDX-License-Identifier: Apache-2.0


use std::sync::Arc;

use serde::{Deserialize, Serialize};

/// Sensitivity tier for a jekt message.
///
/// - `Info`: routine status / progress update; agent may act autonomously.
/// - `Coord`: task handoff or coordination; agent may act, human sees the marker.
/// - `Sensitive`: credential, destructive op, external side-effect; agent MUST
///   pause and ask the human operator before acting. A confirming reply from
///   another agent over muxbus is NOT sufficient.
#[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum JektTier {
    Info,
    #[default]
    Coord,
    Sensitive,
}

impl std::fmt::Display for JektTier {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            JektTier::Info => write!(f, "info"),
            JektTier::Coord => write!(f, "coord"),
            JektTier::Sensitive => write!(f, "sensitive"),
        }
    }
}

/// Request to inject a message into an agent's terminal.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct InjectionRequest {
    pub target_agent: String,
    pub message: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub source_agent: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub request_id: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub priority: Option<String>,
    /// Sensitivity tier declared by the sender. When absent, defaults to `Coord`.
    /// The handler may escalate to `Sensitive` based on keyword scanning.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub jekt_tier: Option<JektTier>,
    /// Delivery tier of this jekt (host/lan/wan) — used in the marker.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub delivery_tier: Option<String>,
    /// Number of cross-instance HTTP forwards this request has already gone
    /// through (Tier 2a/2b/3 each increment before forwarding). Bounds a
    /// pathological cycle where two channels each hold a stale-but-
    /// PID-alive shared-registry entry pointing at the other for the same
    /// agent name — without this, such a cycle would forward back and
    /// forth indefinitely, hanging the original request (reagent P1 on
    /// PR #2350). `#[serde(default)]` so older callers (muxbus client,
    /// any request that predates this field) default to 0, unaffected.
    #[serde(default)]
    pub forward_hops: u8,
    /// Unix seconds this jekt was signed at (part of the signed material,
    /// not just a display timestamp) — see `agentmux_common::jekt_sign` and
    /// `jekt_sig` below. `None` for unsigned/legacy requests.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub ts_secs: Option<i64>,
    /// Base64 HMAC-SHA256 signature over (request_id, source_agent,
    /// target_agent, ts_secs, message), produced by the sender's own
    /// `AGENTMUX_JEKT_KEY`. Verified against the claimed `source_agent`'s
    /// stored key (SPEC_JEKT_TRUST_LAYER_COMPLETION_2026_08_13.md §2.2);
    /// absent, unverifiable, or mismatched all mean "unverified" — the
    /// message still delivers, but downgraded to TRUST=unverified and
    /// escalated to TIER=sensitive, never silently trusted.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub jekt_sig: Option<String>,
    /// Server-computed verification outcome — `#[serde(skip_deserializing)]`
    /// means an attacker-supplied JSON body can NEVER set this field, even
    /// by including it; only `handle_reactive_inject`
    /// (`server/reactive.rs`, which has `AppState::mstore`) may set it,
    /// after independently looking up the claimed `source_agent`'s stored
    /// key and verifying `jekt_sig` against it, before handing the request
    /// to `Handler::inject_message` (which has no `Store` access "by
    /// design" — see `record_supervisor_decision`'s doc comment for why).
    /// `None` = not checked (network-tier messages are already
    /// unconditionally sensitive regardless of signature; or the claimed
    /// `source_agent` has never had a key minted, so there's nothing to
    /// verify against — see the rollout-safety note in
    /// `handle_reactive_inject`, this deliberately does NOT escalate a
    /// caller — e.g. the Slack/Discord/Telegram/WhatsApp bridges, or an
    /// agent not yet respawned since this feature shipped — that was never
    /// capable of signing in the first place). `Some(false)` is the real
    /// signal: this `source_agent` DOES have a key, and either no signature
    /// was given or it didn't match.
    #[serde(skip_deserializing, default, skip_serializing_if = "Option::is_none")]
    pub sig_verified: Option<bool>,
    /// Identity M4c-2d (SPEC_AGENT_IDENTITY_CARRIED_NOT_DERIVED_2026_09_23.md
    /// §6.5.9): the sender's UID, from the request's `Caller` — its
    /// `X-Agent-Token` — set by the srv handler that received it, and copied
    /// onto the audit entries this delivery writes. `#[serde(skip)]` both
    /// ways: a body can never set it, and it never rides a forwarding hop —
    /// distinct from the `source_uid` wire field §6.5.3 reserves for the MCP
    /// to set and sign (M4d). Empty = Unattributed.
    #[serde(skip)]
    pub audit_source_uid: String,
    /// Identity M4d-6: the UID a LAN v2 signature proved under the answering
    /// peer's pinned key (`server/reactive/lan_v2.rs`). Claimed by that LAN
    /// path only, never verified attribution; `#[serde(skip)]` like
    /// `audit_source_uid`. Empty = none.
    #[serde(skip)]
    pub lan_claimed_uid: String,
    /// When a held message was originally accepted (ms), set only by the
    /// held-jekt replay (`SPEC_DURABLE_JEKT_DELIVERY_2026_09_24.md` §2.4):
    /// the delivered header shows this as `TS` plus `HELD_FOR`, so a late
    /// message never reads as a current one. `#[serde(skip)]` both ways.
    #[serde(skip)]
    pub held_sent_at_ms: Option<i64>,
    /// Base64 Ed25519 signature over the same signed material as `jekt_sig`
    /// (request_id, source_agent, target_agent, ts_secs, message), produced
    /// by an AgentMux-operated WAN-tier service sender (currently only the
    /// GitHub review-notification consumer, "reagent") using a private key
    /// held only by the cloud service. Distinct from
    /// `jekt_sig` (host-tier HMAC, symmetric, one key per local instance) —
    /// see `agentmux_common::jekt_sign`'s module doc for why WAN needs an
    /// asymmetric scheme instead. `None` for any non-reagent WAN sender or
    /// any host/lan-tier request — this field is meaningless off the WAN
    /// tier and verification is skipped entirely when absent.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub reagent_sig: Option<String>,
    /// Which pinned public key `reagent_sig` claims to be signed under —
    /// see `agentmux_common::jekt_sign::reagent_public_key` for the
    /// rotation rationale. A legitimate sender always sends all four
    /// signing fields (`reagent_sig`, `reagent_key_id`, `reagent_msg_id`,
    /// `reagent_ts_secs`) together, so `None` here alongside a present
    /// `reagent_sig` is treated the same as no signature having been
    /// attempted at all (`reagent_verified` resolves to `None`, not
    /// `Some(false)`) — see `cloud_subscriber::sync_agent_reactive`'s match
    /// on all four fields. This does not weaken verification: dropping this
    /// field can only ever *lose* a legitimate `SIG=verified`/possible tier
    /// relaxation, never grant one — see `reagent_verified`'s doc comment
    /// below for what this field, once present, is now also used for
    /// besides rendering `SIG=`.
    ///
    /// Whichever caller builds the `InjectionRequest` that ultimately
    /// reaches `Handler::inject_message` MUST carry this field through from
    /// wherever it originated (e.g. `cloud_subscriber::sync_agent_reactive`
    /// copying it from the `Injection` it received) — `handler.rs`'s tier-
    /// relaxation gate checks THIS field, not just whether `reagent_sig`
    /// verified, so dropping it silently disables relaxation on that
    /// delivery path even when `reagent_verified` is correctly `Some(true)`
    /// (reagentx P0 on PR #2576 — exactly this omission on the WS path).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub reagent_key_id: Option<String>,
    /// Message id that was part of `reagent_sig`'s signed material — the
    /// same `id` the cloud relay gives each pending injection it hands
    /// this client. Distinct from `request_id` above, which is
    /// this request's own (possibly re-derived, e.g. across a cross-instance
    /// forward) identifier — `reagent_msg_id` must stay exactly what was
    /// signed for verification to succeed regardless of how `request_id`
    /// is set on this particular hop.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub reagent_msg_id: Option<String>,
    /// Unix seconds `reagent_sig` was signed at — part of the signed
    /// material, checked for anti-replay against a max-age window (the WS
    /// path's `cloud_subscriber::REAGENT_SIG_MAX_AGE_SECS`, or the HTTP
    /// path's own constant of the same name in `server/reactive.rs`), same
    /// purpose as `ts_secs`/`JEKT_SIG_MAX_AGE_SECS` for host-tier `jekt_sig`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub reagent_ts_secs: Option<i64>,
    /// Server-computed verification outcome for `reagent_sig` — same
    /// `#[serde(skip_deserializing)]` guarantee as `sig_verified`: no
    /// attacker-supplied JSON body can set this directly. Set by whichever
    /// caller actually received this WAN injection and independently
    /// verified `reagent_sig` against the pinned key —
    /// `cloud_subscriber::sync_agent_reactive` for the desktop app's WS
    /// delivery path, or `server/reactive.rs::verify_reagent_signature` for
    /// the HTTP `/agentmux/reactive/inject` path used by standalone pollers
    /// like `@agentmuxai/muxbus-client` (reagentx P1 on PR #41 — that path
    /// used to receive the four reagent_* fields over HTTP with nothing on
    /// the receiving end able to verify them at all). `Some(true)` renders
    /// `SIG=verified` in the marker; `Some(false)` (a `reagent_sig` was present but didn't
    /// verify) renders `SIG=invalid` — a real red flag, same spirit as
    /// host-tier's `TRUST=unverified`. `None` (no `reagent_sig` attempted)
    /// renders no `SIG=` field at all, keeping ordinary WAN traffic
    /// unchanged.
    ///
    /// **Never affects `TRUST`** — WAN jekts stay unconditionally
    /// `TRUST=network-claimed` regardless of this field; verification
    /// answers "who is this really from," not "did this cross a network
    /// boundary."
    ///
    /// **DOES affect `TIER`.** As of
    /// `docs/specs/SPEC_JEKT_SENSITIVE_TIER_NARROWING_2026_08_15.md`
    /// (superseding `SPEC_JEKT_REAGENT_TRUST_RELAXATION_2026_08_14.md`'s
    /// narrower version of this same claim), `handler.rs`'s tier-escalation
    /// block only forces `TIER=sensitive` by delivery tier when this is
    /// `Some(false)` — a `reagent_sig` was present but did NOT
    /// cryptographically verify, i.e. an active forgery attempt, or verified
    /// only under a key other than the trusted production key (see
    /// `agentmux_common::jekt_sign::verify_trusted_reagent_jekt`). `None` (no
    /// signature attempted) falls through to the declared tier (default
    /// `coord`), same as any other self-declared sender. Declared-sensitive and
    /// keyword-match escalation still apply unconditionally on top of all
    /// of the above.
    #[serde(skip_deserializing, default, skip_serializing_if = "Option::is_none")]
    pub reagent_verified: Option<bool>,
    /// Base64 Ed25519 signature over the same signed material as `jekt_sig`/
    /// `reagent_sig`, produced by the claimed `source_agent`'s own LAN
    /// signing key (`AGENTMUX_LAN_KEY`, read client-side in `agentmux-mcp` —
    /// see `agentmux_common::jekt_sign::sign_lan_jekt`). Meaningless off the
    /// LAN tier, same scoping as `reagent_sig` being WAN-only. See
    /// docs/specs/SPEC_JEKT_LAN_TIER_SIGNING_2026_08_15.md §2.3/§2.4.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub lan_sig: Option<String>,
    /// Server-computed verification outcome for `lan_sig` —
    /// `#[serde(skip_deserializing)]` guarantee identical to `sig_verified`/
    /// `reagent_verified`: no attacker-supplied JSON body can set this
    /// directly. Set by `handle_reactive_inject` after looking up the
    /// claimed `source_agent`'s LAN public key (a LAN round-trip via
    /// `LanDiscovery::find_agent_lan_pubkey` — unlike host-tier's
    /// synchronous local lookup, this one is async) and independently
    /// verifying `lan_sig` against it.
    ///
    /// `None` — no `lan_sig` attempted, OR the claimed sender has no LAN
    /// public key this instance could find (never minted one, or genuinely
    /// unreachable on the LAN right now) — nothing to check against, same
    /// "don't escalate a caller that was never capable of signing"
    /// semantics `sig_verified`'s `None` case documents. `Some(true)` renders
    /// `TRUST=lan-verified` in the marker; `Some(false)` (a `lan_sig` was
    /// present, a public key WAS found, but it didn't verify — someone tried
    /// to forge a specific agent's identity) is a real red flag, same
    /// spirit as host-tier's `TRUST=unverified` and WAN's `SIG=invalid` —
    /// forces `TIER=sensitive` unconditionally
    /// (`docs/specs/SPEC_JEKT_LAN_TIER_SIGNING_2026_08_15.md` §2.4/§2.5).
    #[serde(skip_deserializing, default, skip_serializing_if = "Option::is_none")]
    pub lan_verified: Option<bool>,
    /// The sending instance's channel id, as declared by the sender and bound
    /// into `channel_sig`'s signed material
    /// (`SPEC_JEKT_CROSS_CHANNEL_TRUST_2026_09_02.md` §D5). Client-supplied,
    /// like `source_agent` — a wrong value simply fails verification, it
    /// grants nothing. Carried through same-host forwards unchanged.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub source_channel: Option<String>,
    /// Base64 Ed25519 signature for the cross-channel tier (same machine,
    /// different AgentMux instance), produced by the claimed `source_agent`'s
    /// own LAN keypair over a domain-separated payload that also binds
    /// `source_channel` (`agentmux_common::jekt_sign::sign_channel_jekt`).
    /// Meaningless off the `channel` tier, same scoping as `lan_sig`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub channel_sig: Option<String>,
    /// Identity M4d-6 (`SPEC_AGENT_IDENTITY_CARRIED_NOT_DERIVED_2026_09_23.md`
    /// §6.5.10): the sending agent's UID, as its MCP fetched it with its
    /// UID-keyed key (M4d-3). Bound into `channel_sig_v2`; a forwarding srv
    /// never sets or changes it. Absent when the sender has no UID key.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub source_uid: Option<String>,
    /// Base64 Ed25519 signature, made only with the sender's UID-keyed LAN
    /// key, over the cross-channel material plus `source_uid`
    /// (`agentmux_common::jekt_sign::sign_channel_jekt_v2`). Verified by UID
    /// against the `uid_public_key` an instance published for it (M4d-5), so
    /// it proves *which* agent sent the jekt, not just which name. The v1
    /// `channel_sig` is still sent beside it.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub channel_sig_v2: Option<String>,
    /// Identity M4d-6: base64 Ed25519 signature, made only with the sender's
    /// UID-keyed LAN key, over the LAN material plus `source_uid`
    /// (`agentmux_common::jekt_sign::sign_lan_jekt_v2`). A receiver checks it
    /// only after the v1 `lan_sig` verified, and records the UID as claimed by
    /// that LAN path, never as verified attribution.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub lan_sig_v2: Option<String>,
    /// Base64 Ed25519 signature for the general agent-to-agent WAN tier,
    /// produced by the claimed `source_agent`'s own **WAN** keypair
    /// (`db_agent_wan_keys` — a different key from the LAN one) over a
    /// domain-separated payload
    /// (`agentmux_common::jekt_sign::sign_wan_jekt`).
    ///
    /// **Carried but NOT yet verified — there is deliberately no
    /// `wan_verified` companion field yet.** Verification has two
    /// prerequisites that do not exist: resolving `(sender_account,
    /// source_agent)` to exactly one published key waits on relay-side work
    /// tracked in the private cloud repo, and the
    /// signed `msgid`/`ts_secs` must survive the cloud round trip, which
    /// today they do not — `cloud_subscriber` replaces `request_id` with the
    /// cloud's own injection id and leaves `ts_secs` unset. Adding a
    /// verification-outcome field before either exists would read as wired
    /// when it is not, so it lands with the verifier instead.
    ///
    /// Signing ships first on purpose: an agent only receives its key at
    /// spawn, so minting now is what makes verification apply to a real
    /// population of agents later rather than almost none.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub wan_sig: Option<String>,
    /// The sending machine's host label. With `source_channel`, identifies
    /// which AgentMux instance under the sending account owns the keypair
    /// `wan_sig` was produced with — the same account can legitimately run one agent name on
    /// several machines and several channels, each with its own database and
    /// so its own key. Client-supplied like `source_channel` and bound into
    /// the signed material, so a wrong value fails verification rather than
    /// selecting a key it shouldn't.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub wan_source_host: Option<String>,
    /// Server-computed verification outcome for `channel_sig` —
    /// `#[serde(skip_deserializing)]`, the same guarantee as `sig_verified`/
    /// `lan_verified`: no attacker-supplied JSON body can set this. Set by
    /// `verify_cross_channel_signature` (`server/reactive.rs`) after resolving
    /// the claimed `source_agent`'s published public key from the host-global
    /// shared registry (`AgentEntry::jekt_public_key`, §D1) — a local file
    /// read, so unlike `lan_verified` it's synchronous.
    ///
    /// `None` — no entry for the claimed sender in the shared registry (a
    /// bridge, or an agent that has never registered), an entry with an
    /// empty `jekt_public_key` (written before Phase A shipped — "cannot
    /// check," never "failed the check," spec §6), or the sender is a
    /// same-instance agent (the HMAC path owns those, §D2 step 2).
    /// `Some(true)` renders `TRUST=channel-verified` and joins the
    /// verified-sender list for the `ESCALATE=none` relaxation. `Some(false)`
    /// — an entry with a key WAS found and the signature was missing, stale,
    /// or wrong — is the §D3 red flag, **not yet escalated**: Phase B
    /// (this) only ever moves a message from `self-declared` to
    /// `channel-verified`; Phase C turns `Some(false)` into forced
    /// `TIER=sensitive` once published keys have propagated (spec §10).
    #[serde(skip_deserializing, default, skip_serializing_if = "Option::is_none")]
    pub channel_verified: Option<bool>,
    /// W3-S (`SPEC_WAN_JEKT_VERIFICATION_2026_09_24.md` §2.3): the verdict on
    /// a same-account agent's WAN signature, computed only by the cloud
    /// subscriber (`muxbus::wan_verify`) — never settable by an HTTP caller
    /// (`skip_deserializing`), so the HTTP entry point's self-declared
    /// `delivery_tier: "wan"` always leaves it `None`.
    ///
    /// `Some(true)` renders `TRUST=wan-verified` with `wan_instance`, and
    /// joins the verified-sender set for an `approved` or `new` instance
    /// (same-account installs, spec §2.6 as amended 2026-09-26); a `revoked`
    /// one is treated as `Some(false)`. `Some(false)` — the envelope, the
    /// certificate chain, the record match, the signature or the replay check
    /// actively failed — is forced `TIER=sensitive`. `None` covers every
    /// "couldn't check" case: unsigned, another account, stale, no record,
    /// directory unreachable.
    #[serde(skip_deserializing, default, skip_serializing_if = "Option::is_none")]
    pub wan_verified: Option<bool>,
    /// The verified sending instance, set with `wan_verified == Some(true)`.
    #[serde(skip_deserializing, default, skip_serializing_if = "Option::is_none")]
    pub wan_instance: Option<WanInstanceInfo>,
    /// Why `wan_verified` isn't `Some(true)`, when there's something to say
    /// (`wan_sig_stale`, `wan_sig_replay`, `wan_key_unavailable`,
    /// `wan_cert_invalid`, …) — audit only, never rendered.
    #[serde(skip_deserializing, default, skip_serializing_if = "Option::is_none")]
    pub wan_reason: Option<String>,
    /// The cause behind `wan_reason`, when there is one to read (e.g.
    /// `directory answered 403 Forbidden`) — audit only, never rendered.
    #[serde(skip_deserializing, default, skip_serializing_if = "Option::is_none")]
    pub wan_detail: Option<String>,
    /// Server-computed: this jekt's `message` is a `transcript_request`
    /// payload (`agentmux_common::transcript_request::parse_transcript_request`)
    /// — `muxspect` Phase B/C's LAN/WAN conversation-visibility protocol.
    /// `#[serde(skip_deserializing)]`, same guarantee as `sig_verified`
    /// etc.: no attacker-supplied JSON body can force or suppress this —
    /// `resolve_transcript_request_tier_fields` always recomputes it by
    /// re-parsing `message` itself, ignoring anything the client claims.
    /// Called from both delivery paths that reach `Handler`:
    /// `handle_reactive_inject` for host/cross-channel/LAN, and
    /// `muxbus::cloud_subscriber::sync_agent_reactive` for WAN. Forces `TIER=sensitive`
    /// unconditionally when `true`, regardless of trust
    /// (`SPEC_JEKT_TRANSCRIPT_REQUEST_TIER_RULES_2026_08_22.md` rule 1) — a
    /// content-disclosure *request* isn't caught by the existing credential/
    /// destructive-keyword scan at all.
    #[serde(skip_deserializing, default)]
    pub is_transcript_request: bool,
    /// Server-computed: when `is_transcript_request` is also `true`, whether
    /// the RESPONDING agent's (`target_agent`'s) own `conversation_visibility`
    /// setting is `ask`, or `trusted_peers` with a requester not on that
    /// agent's own allowlist — i.e. a case that genuinely needs a human
    /// decision, per `SPEC_JEKT_TRANSCRIPT_REQUEST_TIER_RULES_2026_08_22.md`
    /// rule 2. When `true`, `ESCALATE=required` is NOT relaxed to `none`
    /// even for a cryptographically verified sender (the one named
    /// exception to the 2026-08-17 relaxation) — unlike every other
    /// `TIER=sensitive` case, where a verified sender's identity answers
    /// the only open question. Meaningless (always `false`) when
    /// `is_transcript_request` is `false`. Resolved by
    /// `resolve_transcript_request_tier_fields` (has `Store` access, unlike
    /// `Handler::inject_message`, which has none "by design") — called from
    /// both delivery paths that reach `Handler`: `handle_reactive_inject`
    /// for host/cross-channel/LAN, and
    /// `muxbus::cloud_subscriber::sync_agent_reactive` for WAN — same
    /// "resolve in the caller with Store access, pass the outcome through"
    /// pattern `sig_verified`/`lan_verified` already establish.
    #[serde(skip_deserializing, default)]
    pub transcript_request_escalate_forced: bool,
}

impl InjectionRequest {
    /// Whether a sender signature rides on this request. Each binds the
    /// target as signed, so a signed request's target must reach every hop
    /// unchanged; the sender's MCP already sends the route name
    /// (`agentmux-mcp` `signed_jekt`).
    pub fn is_signed(&self) -> bool {
        [&self.jekt_sig, &self.reagent_sig, &self.lan_sig, &self.lan_sig_v2, &self.channel_sig, &self.channel_sig_v2, &self.wan_sig]
            .iter()
            .any(|s| s.is_some())
    }

    /// An unsigned request's target as its route name, so a display-name
    /// target ("Loap #3") routes as "Loap-3" on every tier, not only the
    /// local one. A signed one is left as it is (see `is_signed`).
    pub fn route_unsigned_target(&mut self) {
        if !self.is_signed() {
            self.target_agent = super::sanitize::route_name(&self.target_agent).unwrap_or_default();
        }
    }
}

/// Response from a message injection attempt.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct InjectionResponse {
    pub success: bool,
    pub request_id: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub block_id: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub error: Option<String>,
    pub timestamp: u64,
    /// Tier the handler actually applied (after keyword/network escalation).
    /// Consumed by the sender-echo path so it doesn't re-derive escalation.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub effective_tier: Option<String>,
    /// Whether `effective_tier == "sensitive"` should actually STOP the
    /// receiver (vs. tag-only for a cryptographically verified sender) —
    /// see `Handler::inject_message_inner`'s `requires_stop` doc comment
    /// (SPEC_JEKT_SENSITIVE_TIER_VERIFIED_SENDER_NO_STOP_2026_08_17.md).
    /// Meaningless when `effective_tier` isn't `"sensitive"`. Threaded
    /// through so the sender-echo path (including forwarded cross-instance
    /// hops, which only see this struct's serialized JSON, not the
    /// original `Handler` call) renders the same STOP-or-tag-only marker
    /// the receiver got, instead of re-deriving it from a narrower set of
    /// fields.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub requires_stop: Option<bool>,
    /// The `InjectionRequest::channel_verified` verdict this delivery was
    /// judged on, echoed back so a FORWARDING instance can render the same
    /// `TRUST=` on the sender's echoed marker that the receiver rendered
    /// (SPEC_JEKT_CROSS_CHANNEL_TRUST_2026_09_02.md Phase B, codex P2 on
    /// #3064). Only the receiving instance ever computes it — the forwarder
    /// holds the sender's HMAC key and so skips cross-channel verification
    /// by design (§D2 step 2) — so without this the echo would show the
    /// sender-side view next to a receiver-side `ESCALATE=`. Same
    /// thread-it-through reasoning as `requires_stop` above. `None` off the
    /// channel tier or when nothing could be checked.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub channel_verified: Option<bool>,
    /// `Some(true)`: the target's process is starting up, restarting or
    /// stopping, so the message is queued and reaches it once the process is
    /// up — accepted, not yet seen. `Some(false)`: written to the agent now
    /// (mid-turn included). `None` where nothing structured was attempted
    /// (errors, PTY keystrokes, relay paths). Lets `SendMessage` tell its
    /// caller which happened instead of claiming "injected" for both.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub deferred: Option<bool>,
}

/// Agent registration record.
///
/// `#[ts(type = "number")]` on the u64 timestamps: ts-rs maps 64-bit integers
/// to `bigint`, which is not assignable to `number` in TypeScript and would
/// break every consumer that treats these as JS millisecond timestamps. See
/// the same annotation on `BrowserBookmark::created_at` (PR #3293).
#[derive(Debug, Clone, Serialize, Deserialize, ts_rs::TS)]
#[ts(export, export_to = "../../../frontend/types/rpc/")]
pub struct AgentRegistration {
    pub agent_id: String,
    pub block_id: String,
    // `#[ts(optional)]`: this field carries `skip_serializing_if`, so the key
    // is OMITTED from the JSON entirely when None — not serialized as null.
    // Without this ts-rs renders `tab_id: string | null`, which promises the
    // key is always present, and a consumer narrowing on `!== null` would
    // still get `undefined` at runtime. Note the contrast with
    // `MismatchAuditSummary::error_message` in server/reactive.rs: that one is
    // a plain `Option<String>` with NO skip_serializing_if, so it genuinely is
    // present-and-null and `string | null` is correct there. Same Option<T>,
    // two different correct bindings, decided by the serde attribute.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    #[ts(optional)]
    pub tab_id: Option<String>,
    /// Identity M2: the agent's UID (`db_agents.id`) when the server knew it
    /// at registration — the key the registry is now organised by. Absent
    /// for blocks with no row (quick-launch panes, PTY shells), which are
    /// reachable by name only. Same present-or-omitted treatment as `tab_id`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    #[ts(optional)]
    pub uid: Option<String>,
    #[ts(type = "number")]
    pub registered_at: u64,
    #[ts(type = "number")]
    pub last_seen: u64,
    /// Process-wide unique nonce of the persistent-controller spawn this
    /// registration belongs to; 0 = not recorded (HTTP register handler,
    /// PTY shell auto-register). Real nonces are always ≥ 1, drawn from a
    /// single srv-wide counter (`persistent::next_registration_nonce`) —
    /// NOT the controller-local spawn generation, which restarts at 1
    /// for a replacement controller (`resync_controller`) and could
    /// collide across controller instances for the same block (codex P1
    /// on PR #2500). Lets the exit-handler's cleanup compare-and-remove
    /// instead of blindly wiping a fallback respawn's (or replacement
    /// controller's) fresh registration (issue #2363).
    #[serde(default)]
    #[ts(type = "number")]
    pub registration_nonce: u64,
}

/// List of registered agents.
#[allow(dead_code)]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AgentListResponse {
    pub agents: Vec<AgentRegistration>,
}

/// Whether a verified WAN instance is one a human approved (§2.6).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum WanInstanceStatus {
    /// This install, or one approved through the host-gated window.
    Approved,
    /// Verified, but nobody has said it's theirs: no relaxation.
    New,
    /// Its owner retired it: treated as an active failure.
    Revoked,
}

impl WanInstanceStatus {
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Approved => "approved",
            Self::New => "new",
            Self::Revoked => "revoked",
        }
    }
}

/// The instance a WAN signature was verified against (§2.6).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct WanInstanceInfo {
    /// The full 26-char id the certificate chain proved.
    pub id: String,
    /// `<host_hint>~<id8>` — `jekt_sign::wan_instance_display_label`, the
    /// only form ever shown to a human or an agent.
    pub label: String,
    pub status: WanInstanceStatus,
}

/// The WAN part of an audit entry (§2.6 "Audit and docs").
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct WanAudit {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub verified: Option<bool>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub instance: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub status: Option<WanInstanceStatus>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub reason: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub detail: Option<String>,
}

impl WanAudit {
    /// `None` for a request with nothing WAN to record.
    pub fn from_request(req: &InjectionRequest) -> Option<Self> {
        if req.wan_verified.is_none() && req.wan_reason.is_none() {
            return None;
        }
        Some(Self {
            verified: req.wan_verified,
            instance: req.wan_instance.as_ref().map(|i| i.id.clone()),
            status: req.wan_instance.as_ref().map(|i| i.status),
            reason: req.wan_reason.clone(),
            detail: req.wan_detail.clone(),
        })
    }
}

/// Audit log entry for message injection.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AuditLogEntry {
    pub timestamp: u64,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub source_agent: Option<String>,
    pub target_agent: String,
    pub block_id: String,
    pub message_hash: String,
    pub message_length: usize,
    pub success: bool,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub error_message: Option<String>,
    pub request_id: String,
    /// "nudge_sent" | "nudge_failed" | "nudge_declined" — present only for
    /// Warden Supervisor-originated entries (see
    /// ANALYSIS_WARDEN_AUTO_CONTROLLER_CONTINUATION_WATCHER_2026_08_12.md);
    /// absent for ordinary jekt injections. "nudge_sent" only when delivery
    /// actually succeeded; "nudge_failed" when the Supervisor attempted a
    /// nudge but delivery itself failed (rate limit, unavailable
    /// controller, etc — see `entry.success`/`error_message` for why). A
    /// "nudge_declined" entry has no corresponding delivery attempt at
    /// all — this field is the ONLY record that decision ever existed.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub outcome: Option<String>,
    /// The Supervisor's stated reasoning, populated alongside `outcome`.
    /// Not used by ordinary (non-Supervisor) jekt entries.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub reason: Option<String>,
    /// "delivery" (default — an inject_message attempt, the only kind this
    /// log ever recorded before this field existed) | "register" |
    /// "unregister". Lets `GET /agentmux/reactive/audit` reconstruct
    /// registration/eviction history, not just delivery attempts — prior to
    /// this, register_agent_with_nonce/unregister_agent* wrote nothing here
    /// at all, so a same-host cross-instance identity collision left no
    /// trace of who registered as an agent_id or who it evicted.
    #[serde(default = "default_event_kind")]
    pub event_kind: String,
    /// For a "register" event: the block_id this agent_key was previously
    /// mapped to, if registering evicted an existing mapping. `None` if this
    /// was a fresh registration (no prior holder).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub evicted_block: Option<String>,
    /// For a "register" event: the agent_id this block_id was previously
    /// registered to, if registering evicted an existing mapping. `None` if
    /// this block had no prior tenant.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub evicted_agent: Option<String>,
    /// Identity M4c-2d: the sending agent's UID when its request was
    /// attributed (`InjectionRequest::audit_source_uid`), beside the
    /// `source_agent` name it claimed. Empty = Unattributed, or not a
    /// delivery.
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub audit_source_uid: String,
    /// Identity M4d-6: the UID a LAN v2 signature claimed
    /// (`InjectionRequest::lan_claimed_uid`). Not verified attribution.
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub lan_claimed_uid: String,
    /// W3-S: the WAN verdict for a cloud-delivered jekt, when there was one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub wan: Option<WanAudit>,
}

fn default_event_kind() -> String {
    "delivery".to_string()
}

/// A Warden Supervisor watcher agent's decision about a target agent that
/// just ended its turn: nudge it to continue, or decline (e.g. the target
/// isn't opted in, or the Supervisor judged it genuinely done/blocked).
/// See `Handler::record_supervisor_decision` and
/// ANALYSIS_WARDEN_AUTO_CONTROLLER_CONTINUATION_WATCHER_2026_08_12.md.
#[derive(Debug, Clone, Copy)]
pub enum SupervisorAction {
    /// Deliver a fixed, narrow continuation message to the target as an
    /// ordinary jekt (via the same path `inject_message` uses), then log
    /// the decision. Deliberately carries no caller-supplied text — the
    /// message itself is a constant (`handler::NUDGE_MESSAGE`), not
    /// composed by the calling Supervisor agent. See
    /// ANALYSIS_WARDEN_AUTO_CONTROLLER_CONTINUATION_WATCHER_2026_08_12.md
    /// §4.3 ("never a free-form instruction the watcher composes
    /// per-situation") — reagentx P1 on PR #2557 flagged an earlier
    /// version of this type that accepted arbitrary text.
    Nudge,
    /// No delivery — just log that the Supervisor decided not to nudge.
    Decline,
}

/// Poller configuration for AgentMux cloud service.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PollerConfig {
    // ARCH-001: the wire key is now `muxbus_url`/`muxbus_token` (matches the
    // Rust identifier). The legacy `agentmux_*` keys are still accepted as a
    // back-compat deserialize alias on input.
    #[serde(rename = "muxbus_url", alias = "agentmux_url", default, skip_serializing_if = "Option::is_none")]
    pub muxbus_url: Option<String>,
    #[serde(rename = "muxbus_token", alias = "agentmux_token", default, skip_serializing_if = "Option::is_none")]
    pub muxbus_token: Option<String>,
    #[serde(default)]
    pub poll_interval_secs: u64,
}

/// AgentMux config file format (agentmux.json).
#[allow(dead_code)]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AgentMuxConfigFile {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub url: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub token: Option<String>,
}

/// Pending injection from AgentMux cloud.
#[allow(dead_code)]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PendingInjection {
    pub id: String,
    pub message: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub source_agent: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub priority: Option<String>,
    #[serde(default)]
    pub created_at: u64,
}

/// Response from AgentMux pending endpoint.
#[allow(dead_code)]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PendingResponse {
    pub injections: Vec<PendingInjection>,
}

/// Acknowledgment request for delivered injections.
#[allow(dead_code)]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AckRequest {
    pub injection_ids: Vec<String>,
}

/// Poller status information.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PollerStatus {
    pub configured: bool,
    pub running: bool,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub url: Option<String>,
    pub has_token: bool,
    pub poll_count: u64,
    pub injections_count: u64,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub last_poll: Option<u64>,
}

/// Function type for sending input bytes to a block's PTY.
pub type InputSender = Arc<dyn Fn(&str, &[u8]) -> Result<(), String> + Send + Sync>;

/// Function type for controller-aware delivery of a message to a (non-PTY) agent.
///
/// Given `(block_id, message)`, returns:
/// - `Ok(SenderDelivery::Delivered)` — delivered on the controller's structured
///   channel (persistent stream-json stdin / ACP `session/prompt`); no PTY
///   keystrokes needed.
/// - `Ok(SenderDelivery::Deferred)` — accepted on that channel but queued
///   because the agent's process is starting up, restarting or stopping;
///   written once it can take it (SPEC_JEKT_IMMEDIATE_DELIVERY_2026_09_28.md
///   §2.1). The message is safe; the agent just hasn't seen it yet.
/// - `Ok(SenderDelivery::Pty)` — the controller is PTY-based; the caller should
///   fall back to keystroke injection.
/// - `Err(_)` — a structured controller failed to accept the message (e.g. the
///   persistent process is not running); the caller must NOT fall back to PTY,
///   since such controllers reject raw keystrokes.
pub type MessageSender = Arc<dyn Fn(&str, &str) -> Result<SenderDelivery, String> + Send + Sync>;

/// See [`MessageSender`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SenderDelivery {
    Delivered,
    Deferred,
    Pty,
}

/// Function type for querying a block's own live, spawn-time-captured jekt
/// identity — an independent source of truth for `inject_message_inner`'s
/// recipient-identity check, deliberately NOT derived from `Handler`'s own
/// `uid_to_block`/`name_to_blocks`/`agent_info` maps (see
/// `Controller::agent_id`'s doc comment for why checking a registry against
/// itself would be a tautology). Given `block_id`, returns `Some(agent_id)` if that block's
/// controller has a captured identity, `None` if it doesn't (a non-agent
/// controller, or a controller type that doesn't implement `agent_id()`) —
/// `None` is treated as "unverifiable," not "confirmed absent," so delivery
/// proceeds unaffected when no positive check is possible.
pub type AgentIdentityConfirmer = Arc<dyn Fn(&str) -> Option<String> + Send + Sync>;

/// Identity M2: is `block_id` still alive (does it have a controller)?
/// Backs the registry's lazy sweep of dead registrations when a name
/// resolves to more than one block — see `Handler::block_liveness`.
pub type BlockLivenessProbe = Arc<dyn Fn(&str) -> bool + Send + Sync>;

#[cfg(test)]
mod app_api_manifest_contract_tests {
    //! Rust half of the DRY contract check for `agent.send`, described in
    //! docs/specs/SPEC_MUXSH_FULL_COLLECTION_2026_09_16.md §2.8 — same
    //! mechanism as `rpc_types/block.rs`'s equivalent module for
    //! `pane.open`, but a **subset** check (`exactMatch: false` in the
    //! manifest), not exact-match: `InjectionRequest` carries many more
    //! optional fields (source_agent, jekt_sig, ...) that `muxsh agent send`
    //! never sets, and enumerating all of them in the manifest would add no
    //! real protection against the actual risk (muxsh's own two
    //! constructed field names drifting), just busywork every time an
    //! unrelated jekt field is added to this struct.
    use super::*;
    use std::collections::HashSet;
    use std::path::Path;

    fn load_manifest() -> serde_json::Value {
        let path = Path::new(env!("CARGO_MANIFEST_DIR"))
            .parent()
            .and_then(Path::parent)
            .expect("crates/<name> is two levels below the repo root")
            .join("docs/specs/app-api-manifest.json");
        let raw = std::fs::read_to_string(&path)
            .unwrap_or_else(|e| panic!("failed to read {}: {e}", path.display()));
        serde_json::from_str(&raw).expect("app-api-manifest.json must be valid JSON")
    }

    #[test]
    fn agent_send_manifest_fields_are_a_subset_of_the_real_struct() {
        let manifest = load_manifest();
        let manifest_fields: HashSet<String> = manifest["routes"]["agent.send"]["requestFields"]
            .as_array()
            .expect("routes.agent.send.requestFields must be an array")
            .iter()
            .map(|v| v.as_str().expect("field name must be a string").to_string())
            .collect();

        let instance = InjectionRequest {
            target_agent: "a".to_string(),
            message: "m".to_string(),
            ..Default::default()
        };
        let value = serde_json::to_value(&instance).expect("InjectionRequest must serialize");
        let struct_fields: HashSet<String> = value
            .as_object()
            .expect("serialized InjectionRequest must be a JSON object")
            .keys()
            .cloned()
            .collect();

        let missing: Vec<_> = manifest_fields.difference(&struct_fields).collect();
        assert!(
            missing.is_empty(),
            "app-api-manifest.json's agent.send.requestFields names field(s) InjectionRequest doesn't have: {missing:?}"
        );
    }
}