klieo-a2a 3.4.0

//! A2A v1.0 wire types — `Part`, `Message`, `Artifact`, `Task`, `AgentCard`.
//!
//! Field names are verbatim from the A2A v1.0 spec §6 to preserve
//! wire-compatibility with non-NATS A2A clients. See
//! <https://a2a-protocol.org/latest/specification/>.

#![allow(non_snake_case)] // Spec field names are camelCase.

use serde::{Deserialize, Serialize};

/// Author role of a message — A2A spec §6.3.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum Role {
    /// Sent by the human / calling system.
    User,
    /// Sent by the agent.
    Agent,
}

/// Lifecycle states of a long-running task — A2A spec §6.5.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum TaskStatus {
    /// Task accepted, not yet started.
    Submitted,
    /// Task is executing.
    Working,
    /// Task is paused awaiting more user input.
    InputRequired,
    /// Task succeeded.
    Completed,
    /// Task ended with an error.
    Failed,
    /// Task was cancelled by the caller.
    Canceled,
    /// Task was rejected by the server before starting.
    Rejected,
    /// Task is waiting on authentication.
    Authenticated,
    /// An unrecognized status from a newer peer. Deserialization maps any
    /// unknown wire value here instead of failing, so a forward-version peer
    /// can't break parsing. Never terminal.
    #[serde(other)]
    Unknown,
}

impl TaskStatus {
    /// `true` if this status cannot transition further. Stream
    /// consumers close after observing a terminal status.
    pub fn is_terminal(&self) -> bool {
        matches!(
            self,
            TaskStatus::Completed
                | TaskStatus::Failed
                | TaskStatus::Canceled
                | TaskStatus::Rejected
        )
    }
}

/// One element of a multi-part payload — A2A spec §6.2 / proto `Part`
/// (upstream `specification/a2a.proto`, `oneof content`).
///
/// # Wire compatibility — one canonical emit form, three accepted forms
///
/// The upstream A2A v1.0 spec removed the `"kind"` discriminator in
/// favor of **JSON member-name polymorphism**: the presence of a
/// `"text"`, `"raw"`, `"url"`, or `"data"` key identifies the variant
/// directly (see `docs/whats-new-v1.md` §A.2.1 in `a2aproject/A2A`).
/// [`Part::serialize`] emits ONLY this current form — e.g.
/// `{"text": "hi"}`, `{"raw": "<base64>", "mediaType": "text/plain"}`.
///
/// [`Part::deserialize`] accepts that current form plus two legacy
/// forms, so the crate never breaks a stored row or an older peer:
/// - **A2A v0.3.x legacy wire form:** `{"kind": "text", "text": "hi"}`
///   (the spec's own documented migration shape).
/// - **klieo's pre-interop form** (used internally before this
///   compatibility layer landed): `{"type": "text", "content": "hi"}`.
///   [`crate::task_store::A2aTaskStore`] persists whichever shape was
///   live at write time, so accepting this form on read is
///   migration-free — no backfill pass needed for old stored [`Task`]
///   rows.
///
/// Optional `metadata`, `filename`, and `mediaType` are accepted/emitted
/// under the same key name (`mediaType`) across all three forms.
///
/// # Known gap
///
/// The v0.3.x legacy `FilePart` shape nests file content under a
/// `{"kind": "file", "file": {"name", "mimeType", "fileWithBytes" |
/// "fileWithUri"}}` object. That nested legacy shape is NOT accepted —
/// only the legacy `text`/`data` kinds are. A peer still emitting
/// legacy `kind: "file"` parts falls through to [`Part::Unknown`].
#[derive(Debug, Clone)]
#[non_exhaustive]
pub enum Part {
    /// UTF-8 text part.
    Text {
        /// The text body.
        content: String,
        /// Free-form metadata attached to the part.
        metadata: Option<serde_json::Value>,
        /// IANA media type hint (rarely used for text).
        mediaType: Option<String>,
        /// Suggested filename when extracting the part.
        filename: Option<String>,
    },
    /// Inline binary blob, base64-encoded.
    Raw {
        /// Base64-encoded bytes.
        bytes: String,
        /// IANA media type of the bytes.
        mediaType: String,
        /// Free-form metadata.
        metadata: Option<serde_json::Value>,
        /// Suggested filename.
        filename: Option<String>,
    },
    /// External resource reference.
    Url {
        /// URL to fetch.
        url: String,
        /// IANA media type hint.
        mediaType: Option<String>,
        /// Free-form metadata.
        metadata: Option<serde_json::Value>,
        /// Suggested filename.
        filename: Option<String>,
    },
    /// Arbitrary structured JSON.
    Data {
        /// The JSON value.
        data: serde_json::Value,
        /// Free-form metadata.
        metadata: Option<serde_json::Value>,
        /// IANA media type hint (rarely used).
        mediaType: Option<String>,
        /// Suggested filename.
        filename: Option<String>,
    },
    /// An unrecognized part type from a newer peer, or a legacy
    /// `kind: "file"` part (see the type-level "Known gap" note).
    /// Deserialization maps anything it can't place here instead of
    /// failing, preserving forward-compat. Serializes as `{}`.
    Unknown,
}

/// Pulls a string-typed field out of a wire object by key, discarding
/// any non-string value under that key rather than erroring — callers
/// that hit a type-mismatched legacy field fall through to
/// [`Part::Unknown`] instead of rejecting the whole message.
fn take_string(obj: &mut serde_json::Map<String, serde_json::Value>, key: &str) -> Option<String> {
    match obj.remove(key) {
        Some(serde_json::Value::String(s)) => Some(s),
        _ => None,
    }
}

/// The three fields every [`Part`] variant carries alongside its
/// type-specific payload. Bundled so the three `from_*_shape` helpers
/// below take one argument instead of three loose, easily-transposed
/// `Option`s.
struct PartCommonFields {
    metadata: Option<serde_json::Value>,
    media_type: Option<String>,
    filename: Option<String>,
}

impl Part {
    /// Parse one [`Part`] from its wire JSON object, trying the current
    /// A2A v1.0 member-name form first, then the two legacy forms
    /// documented on the type. Never errors on an unrecognised shape —
    /// falls through to [`Part::Unknown`] so a forward-version or
    /// legacy-`file`-kind peer can't break parsing.
    fn from_wire_object(mut obj: serde_json::Map<String, serde_json::Value>) -> Part {
        let common = PartCommonFields {
            metadata: obj.remove("metadata"),
            media_type: take_string(&mut obj, "mediaType"),
            filename: take_string(&mut obj, "filename"),
        };

        if let Some(tag) = take_string(&mut obj, "type") {
            return Part::from_klieo_pre_interop_shape(&tag, obj, common);
        }
        if let Some(kind) = take_string(&mut obj, "kind") {
            return Part::from_legacy_v03x_shape(&kind, obj, common);
        }
        Part::from_current_bare_shape(obj, common)
    }

    /// klieo's pre-interop shape: `{"type": "...", <field>: ...}` — what
    /// every `Task` row persisted before this compatibility layer landed.
    fn from_klieo_pre_interop_shape(
        tag: &str,
        mut obj: serde_json::Map<String, serde_json::Value>,
        common: PartCommonFields,
    ) -> Part {
        let PartCommonFields {
            metadata,
            media_type,
            filename,
        } = common;
        match tag {
            "text" => Part::Text {
                content: take_string(&mut obj, "content").unwrap_or_default(),
                metadata,
                mediaType: media_type,
                filename,
            },
            "raw" => Part::Raw {
                bytes: take_string(&mut obj, "bytes").unwrap_or_default(),
                mediaType: media_type.unwrap_or_default(),
                metadata,
                filename,
            },
            "url" => Part::Url {
                url: take_string(&mut obj, "url").unwrap_or_default(),
                mediaType: media_type,
                metadata,
                filename,
            },
            "data" => Part::Data {
                data: obj.remove("data").unwrap_or(serde_json::Value::Null),
                metadata,
                mediaType: media_type,
                filename,
            },
            _ => Part::Unknown,
        }
    }

    /// A2A v0.3.x legacy shape: `{"kind": "...", "text"|"data": ...}`.
    /// `kind: "file"` is the documented "Known gap" — falls to
    /// [`Part::Unknown`] rather than decoding the nested file object.
    fn from_legacy_v03x_shape(
        kind: &str,
        mut obj: serde_json::Map<String, serde_json::Value>,
        common: PartCommonFields,
    ) -> Part {
        let PartCommonFields {
            metadata,
            media_type,
            filename,
        } = common;
        match kind {
            "text" => Part::Text {
                content: take_string(&mut obj, "text").unwrap_or_default(),
                metadata,
                mediaType: media_type,
                filename,
            },
            "data" => Part::Data {
                data: obj.remove("data").unwrap_or(serde_json::Value::Null),
                metadata,
                mediaType: media_type,
                filename,
            },
            _ => Part::Unknown,
        }
    }

    /// Current A2A v1.0 shape: the member name IS the discriminator, so
    /// whichever of `text`/`raw`/`url`/`data` is present wins.
    fn from_current_bare_shape(
        mut obj: serde_json::Map<String, serde_json::Value>,
        common: PartCommonFields,
    ) -> Part {
        let PartCommonFields {
            metadata,
            media_type,
            filename,
        } = common;
        if let Some(text) = take_string(&mut obj, "text") {
            return Part::Text {
                content: text,
                metadata,
                mediaType: media_type,
                filename,
            };
        }
        if let Some(raw) = take_string(&mut obj, "raw") {
            return Part::Raw {
                bytes: raw,
                mediaType: media_type.unwrap_or_default(),
                metadata,
                filename,
            };
        }
        if let Some(url) = take_string(&mut obj, "url") {
            return Part::Url {
                url,
                mediaType: media_type,
                metadata,
                filename,
            };
        }
        if let Some(data) = obj.remove("data") {
            return Part::Data {
                data,
                metadata,
                mediaType: media_type,
                filename,
            };
        }
        Part::Unknown
    }
}

impl Serialize for Part {
    /// Emits ONLY the current A2A v1.0 member-name form — see the
    /// type-level docs. Never emits `"type"` or `"kind"`.
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        use serde::ser::SerializeMap;
        let mut map = serializer.serialize_map(None)?;
        match self {
            Part::Text {
                content,
                metadata,
                mediaType,
                filename,
            } => {
                map.serialize_entry("text", content)?;
                serialize_common(
                    &mut map,
                    metadata,
                    mediaType.as_deref(),
                    filename.as_deref(),
                )?;
            }
            Part::Raw {
                bytes,
                mediaType,
                metadata,
                filename,
            } => {
                map.serialize_entry("raw", bytes)?;
                map.serialize_entry("mediaType", mediaType)?;
                serialize_common(&mut map, metadata, None, filename.as_deref())?;
            }
            Part::Url {
                url,
                mediaType,
                metadata,
                filename,
            } => {
                map.serialize_entry("url", url)?;
                serialize_common(
                    &mut map,
                    metadata,
                    mediaType.as_deref(),
                    filename.as_deref(),
                )?;
            }
            Part::Data {
                data,
                metadata,
                mediaType,
                filename,
            } => {
                map.serialize_entry("data", data)?;
                serialize_common(
                    &mut map,
                    metadata,
                    mediaType.as_deref(),
                    filename.as_deref(),
                )?;
            }
            Part::Unknown => {}
        }
        map.end()
    }
}

/// Shared `metadata`/`mediaType`/`filename` tail emitted by every
/// [`Part`] variant except [`Part::Raw`] (which always emits
/// `mediaType`, so the caller passes `None` here to avoid a duplicate
/// key).
fn serialize_common<M: serde::ser::SerializeMap>(
    map: &mut M,
    metadata: &Option<serde_json::Value>,
    media_type: Option<&str>,
    filename: Option<&str>,
) -> Result<(), M::Error> {
    if let Some(v) = metadata {
        map.serialize_entry("metadata", v)?;
    }
    if let Some(v) = media_type {
        map.serialize_entry("mediaType", v)?;
    }
    if let Some(v) = filename {
        map.serialize_entry("filename", v)?;
    }
    Ok(())
}

impl<'de> Deserialize<'de> for Part {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        let value = serde_json::Value::deserialize(deserializer)?;
        match value {
            serde_json::Value::Object(obj) => Ok(Part::from_wire_object(obj)),
            other => Err(serde::de::Error::custom(format!(
                "Part must be a JSON object, got {other}"
            ))),
        }
    }
}

/// One message exchanged between user and agent — A2A spec §6.3.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Message {
    /// Stable id for this message.
    pub messageId: String,
    /// Conversation/context id grouping related messages.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub contextId: Option<String>,
    /// Optional task id this message participates in.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub taskId: Option<String>,
    /// Author of the message.
    pub role: Role,
    /// Parts that make up the message.
    pub parts: Vec<Part>,
    /// Free-form metadata.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub metadata: Option<serde_json::Value>,
    /// Extension URIs the message uses.
    #[serde(default)]
    pub extensions: Vec<String>,
    /// Tasks this message references but does not own.
    #[serde(default)]
    pub referenceTaskIds: Vec<String>,
}

/// Output produced by an agent run — A2A spec §6.4.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Artifact {
    /// Stable id for this artifact.
    pub artifactId: String,
    /// Optional human-readable name.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    /// Optional description.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,
    /// Parts that make up the artifact.
    pub parts: Vec<Part>,
    /// Free-form metadata.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub metadata: Option<serde_json::Value>,
    /// Extension URIs the artifact uses.
    #[serde(default)]
    pub extensions: Vec<String>,
}

/// Long-running task — A2A spec §6.5.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Task {
    /// Stable id for this task.
    pub id: String,
    /// Conversation/context id this task belongs to.
    pub contextId: String,
    /// Lifecycle status.
    pub status: TaskStatus,
    /// Artifacts produced by the task.
    #[serde(default)]
    pub artifacts: Vec<Artifact>,
    /// Message history of the task.
    #[serde(default)]
    pub history: Vec<Message>,
    /// Free-form metadata.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub metadata: Option<serde_json::Value>,
}

/// Provider information for an agent — A2A spec §6.1.2.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AgentProvider {
    /// Organisation name.
    pub organization: String,
    /// Optional contact URL.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub url: Option<String>,
}

/// Capabilities the agent supports — A2A spec §6.1.3.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AgentCapabilities {
    /// Supports `SendStreamingMessage`.
    #[serde(default)]
    pub streaming: bool,
    /// Supports push-notification config ops.
    #[serde(default)]
    pub pushNotifications: bool,
    /// Records state transitions in task history.
    #[serde(default)]
    pub stateTransitionHistory: bool,
}

/// Skill an agent advertises — A2A spec §6.1.4.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AgentSkill {
    /// Stable skill id.
    pub id: String,
    /// Human-readable name.
    pub name: String,
    /// Free-form description.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,
    /// Tags for discovery.
    #[serde(default)]
    pub tags: Vec<String>,
}

/// Transport interface an agent exposes — A2A spec §6.1.5.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AgentInterface {
    /// Transport identifier (e.g. `"a2a/1.0/jsonrpc"` or klieo-specific
    /// `"a2a/1.0/nats"`).
    pub transport: String,
    /// URL or NATS subject prefix the transport listens on.
    pub url: String,
}

/// Detached signature for an `AgentCard` — A2A spec §6.1.7.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AgentCardSignature {
    /// Algorithm identifier (e.g. `"ed25519"`).
    pub alg: String,
    /// Key id used.
    pub kid: String,
    /// Base64-encoded signature bytes.
    pub signature: String,
}

/// Public description of an agent — A2A spec §6.1.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AgentCard {
    /// Stable agent id.
    pub id: String,
    /// Display name.
    pub name: String,
    /// Free-form description.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,
    /// Provider org info.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub provider: Option<AgentProvider>,
    /// Supported capabilities.
    pub capabilities: AgentCapabilities,
    /// Advertised skills.
    #[serde(default)]
    pub skills: Vec<AgentSkill>,
    /// Transport interfaces.
    #[serde(default)]
    pub interfaces: Vec<AgentInterface>,
    /// Security schemes (OpenAPI-style).
    #[serde(default)]
    pub securitySchemes: serde_json::Map<String, serde_json::Value>,
    /// Required security scheme references.
    #[serde(default)]
    pub security: Vec<serde_json::Value>,
    /// Extension URIs the agent uses.
    #[serde(default)]
    pub extensions: Vec<String>,
    /// Optional detached signature.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub signature: Option<AgentCardSignature>,
}

/// `SendMessage` params — A2A spec §9.4.1.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SendMessageParams {
    /// The message to send.
    pub message: Message,
    /// Optional configuration knobs (per-call timeout, etc).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub configuration: Option<serde_json::Value>,
}

/// `SendMessage` result.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(untagged)]
pub enum SendMessageResult {
    /// Server completed synchronously and returned a response message.
    Message(Message),
    /// Server kicked off a long-running task.
    Task(Task),
}

/// `GetTask` params — A2A spec §9.4.3.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GetTaskParams {
    /// Task id to fetch.
    pub id: String,
    /// Optional history truncation depth.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub historyLength: Option<usize>,
}

/// `ListTasks` params — A2A spec §9.4.4.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct ListTasksParams {
    /// Optional context filter.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub contextId: Option<String>,
    /// Optional pagination cursor.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cursor: Option<String>,
    /// Optional page size.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub limit: Option<usize>,
}

/// `ListTasks` result.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct ListTasksResult {
    /// Page of tasks.
    pub tasks: Vec<Task>,
    /// Cursor to use for the next page, if more remain.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub nextCursor: Option<String>,
}

/// `CancelTask` params — A2A spec §9.4.5.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CancelTaskParams {
    /// Task id to cancel.
    pub id: String,
}

/// `SubscribeToTask` params — A2A spec §9.4.6.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SubscribeToTaskParams {
    /// Task id to subscribe to.
    pub id: String,
}

/// `CreateTaskPushNotificationConfig` params — A2A spec §9.4.7.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PushNotificationConfigParams {
    /// Task id.
    pub taskId: String,
    /// Webhook URL.
    pub url: String,
    /// Optional bearer token.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub token: Option<String>,
}

/// Stored push-notification config.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PushNotificationConfig {
    /// Stable config id.
    pub id: String,
    /// Owning task id.
    pub taskId: String,
    /// Webhook URL.
    pub url: String,
}

/// `GetTaskPushNotificationConfig` params — A2A spec §9.4.8.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GetPushNotificationConfigParams {
    /// Task id.
    pub taskId: String,
    /// Config id.
    pub id: String,
}

/// `ListTaskPushNotificationConfigs` params — A2A spec §9.4.9.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ListPushNotificationConfigsParams {
    /// Task id.
    pub taskId: String,
}

/// `ListTaskPushNotificationConfigs` result.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct ListPushNotificationConfigsResult {
    /// Stored configs for the task.
    pub configs: Vec<PushNotificationConfig>,
}

/// `DeleteTaskPushNotificationConfig` params — A2A spec §9.4.10.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DeletePushNotificationConfigParams {
    /// Task id.
    pub taskId: String,
    /// Config id.
    pub id: String,
}

/// `GetExtendedAgentCard` params — A2A spec §9.4.11. Intentionally empty per spec.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct GetExtendedAgentCardParams {}

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

    #[test]
    fn unknown_task_status_deserialises_to_unknown_not_error() {
        let s: TaskStatus = serde_json::from_value(json!("some_future_state")).unwrap();
        assert_eq!(s, TaskStatus::Unknown);
        assert!(!s.is_terminal(), "Unknown status is never terminal");
    }

    #[test]
    fn unknown_part_type_deserialises_to_unknown_not_error() {
        let p: Part = serde_json::from_value(json!({"type": "future_part", "x": 1})).unwrap();
        assert!(matches!(p, Part::Unknown));
    }

    #[test]
    fn unknown_part_kind_deserialises_to_unknown_not_error() {
        let p: Part = serde_json::from_value(json!({"kind": "future_kind", "x": 1})).unwrap();
        assert!(matches!(p, Part::Unknown));
    }

    #[test]
    fn unknown_part_shape_with_no_recognised_key_deserialises_to_unknown() {
        let p: Part = serde_json::from_value(json!({"nonsense": 1})).unwrap();
        assert!(matches!(p, Part::Unknown));
    }

    #[test]
    fn part_text_serialises_to_bare_text_member_no_discriminator() {
        // Current A2A v1.0 shape (member-name polymorphism): no "type"
        // or "kind" key on the wire.
        let p = Part::Text {
            content: "hello".into(),
            metadata: None,
            mediaType: None,
            filename: None,
        };
        let v = serde_json::to_value(&p).unwrap();
        assert_eq!(v["text"], "hello");
        assert!(v.get("type").is_none(), "must not emit legacy `type` key");
        assert!(v.get("kind").is_none(), "must not emit legacy `kind` key");
        assert!(
            v.get("content").is_none(),
            "must not emit klieo's old `content` key"
        );
    }

    #[test]
    fn part_raw_serialises_to_bare_raw_member_no_discriminator() {
        let p = Part::Raw {
            bytes: "aGVsbG8=".into(),
            mediaType: "text/plain".into(),
            metadata: None,
            filename: None,
        };
        let v = serde_json::to_value(&p).unwrap();
        assert_eq!(v["raw"], "aGVsbG8=");
        assert_eq!(v["mediaType"], "text/plain");
        assert!(v.get("type").is_none());
        assert!(
            v.get("bytes").is_none(),
            "spec member name is `raw`, not `bytes`"
        );
    }

    #[test]
    fn part_url_serialises_to_bare_url_member() {
        let p = Part::Url {
            url: "https://example.test/doc.pdf".into(),
            mediaType: Some("application/pdf".into()),
            metadata: None,
            filename: None,
        };
        let v = serde_json::to_value(&p).unwrap();
        assert_eq!(v["url"], "https://example.test/doc.pdf");
        assert_eq!(v["mediaType"], "application/pdf");
        assert!(v.get("type").is_none());
    }

    #[test]
    fn part_data_serialises_to_bare_data_member() {
        let p = Part::Data {
            data: json!({"a": 1}),
            metadata: None,
            mediaType: None,
            filename: None,
        };
        let v = serde_json::to_value(&p).unwrap();
        assert_eq!(v["data"], json!({"a": 1}));
        assert!(v.get("type").is_none());
    }

    #[test]
    fn part_text_current_spec_bare_form_deserialises() {
        // The A2A v1.0 CURRENT wire shape — no discriminator at all.
        let p: Part = serde_json::from_value(json!({"text": "hi"})).unwrap();
        match p {
            Part::Text { content, .. } => assert_eq!(content, "hi"),
            other => panic!("expected Part::Text, got {other:?}"),
        }
    }

    #[test]
    fn part_raw_current_spec_bare_form_deserialises() {
        let p: Part =
            serde_json::from_value(json!({"raw": "aGVsbG8=", "mediaType": "text/plain"})).unwrap();
        match p {
            Part::Raw {
                bytes, mediaType, ..
            } => {
                assert_eq!(bytes, "aGVsbG8=");
                assert_eq!(mediaType, "text/plain");
            }
            other => panic!("expected Part::Raw, got {other:?}"),
        }
    }

    #[test]
    fn part_url_current_spec_bare_form_deserialises() {
        let p: Part = serde_json::from_value(json!({"url": "https://example.test/x"})).unwrap();
        match p {
            Part::Url { url, .. } => assert_eq!(url, "https://example.test/x"),
            other => panic!("expected Part::Url, got {other:?}"),
        }
    }

    #[test]
    fn part_data_current_spec_bare_form_deserialises() {
        let p: Part = serde_json::from_value(json!({"data": {"a": 1}})).unwrap();
        match p {
            Part::Data { data, .. } => assert_eq!(data, json!({"a": 1})),
            other => panic!("expected Part::Data, got {other:?}"),
        }
    }

    #[test]
    fn part_text_legacy_v03x_kind_form_deserialises() {
        // A2A v0.3.x legacy shape, explicitly documented by the spec's
        // own migration guidance as still-acceptable on read.
        let p: Part = serde_json::from_value(json!({"kind": "text", "text": "hi"})).unwrap();
        match p {
            Part::Text { content, .. } => assert_eq!(content, "hi"),
            other => panic!("expected Part::Text, got {other:?}"),
        }
    }

    #[test]
    fn part_data_legacy_v03x_kind_form_deserialises() {
        let p: Part = serde_json::from_value(json!({"kind": "data", "data": {"a": 1}})).unwrap();
        match p {
            Part::Data { data, .. } => assert_eq!(data, json!({"a": 1})),
            other => panic!("expected Part::Data, got {other:?}"),
        }
    }

    #[test]
    fn part_legacy_kind_file_is_unrecognised_not_an_error() {
        // Documented "Known gap": nested legacy FilePart shape is not
        // decoded into Raw/Url — it degrades to Unknown, never an error.
        let p: Part = serde_json::from_value(json!({
            "kind": "file",
            "file": {"name": "x.png", "mimeType": "image/png", "fileWithBytes": "AA=="}
        }))
        .unwrap();
        assert!(matches!(p, Part::Unknown));
    }

    #[test]
    fn part_text_klieo_pre_interop_type_content_form_deserialises() {
        // klieo's own pre-interop shape — this is exactly what
        // `A2aTaskStore` persisted for every `Part::Text` before this
        // compatibility layer landed. Accepting it is what makes old
        // stored `Task` rows migration-free to read.
        let p: Part = serde_json::from_value(json!({"type": "text", "content": "hi"})).unwrap();
        match p {
            Part::Text { content, .. } => assert_eq!(content, "hi"),
            other => panic!("expected Part::Text, got {other:?}"),
        }
    }

    #[test]
    fn part_raw_klieo_pre_interop_type_bytes_form_deserialises() {
        let p: Part = serde_json::from_value(
            json!({"type": "raw", "bytes": "aGVsbG8=", "mediaType": "text/plain"}),
        )
        .unwrap();
        match p {
            Part::Raw {
                bytes, mediaType, ..
            } => {
                assert_eq!(bytes, "aGVsbG8=");
                assert_eq!(mediaType, "text/plain");
            }
            other => panic!("expected Part::Raw, got {other:?}"),
        }
    }

    #[test]
    fn part_url_klieo_pre_interop_type_form_deserialises() {
        let p: Part =
            serde_json::from_value(json!({"type": "url", "url": "https://example.test"})).unwrap();
        match p {
            Part::Url { url, .. } => assert_eq!(url, "https://example.test"),
            other => panic!("expected Part::Url, got {other:?}"),
        }
    }

    #[test]
    fn part_data_klieo_pre_interop_type_form_deserialises() {
        let p: Part = serde_json::from_value(json!({"type": "data", "data": {"a": 1}})).unwrap();
        match p {
            Part::Data { data, .. } => assert_eq!(data, json!({"a": 1})),
            other => panic!("expected Part::Data, got {other:?}"),
        }
    }

    #[test]
    fn part_text_round_trips_through_canonical_emit_form() {
        let original = Part::Text {
            content: "round trip".into(),
            metadata: Some(json!({"k": "v"})),
            mediaType: Some("text/markdown".into()),
            filename: Some("note.md".into()),
        };
        let v = serde_json::to_value(&original).unwrap();
        let back: Part = serde_json::from_value(v).unwrap();
        match back {
            Part::Text {
                content,
                metadata,
                mediaType,
                filename,
            } => {
                assert_eq!(content, "round trip");
                assert_eq!(metadata, Some(json!({"k": "v"})));
                assert_eq!(mediaType, Some("text/markdown".into()));
                assert_eq!(filename, Some("note.md".into()));
            }
            other => panic!("expected Part::Text, got {other:?}"),
        }
    }

    #[test]
    fn part_unknown_serialises_to_empty_object() {
        let v = serde_json::to_value(&Part::Unknown).unwrap();
        assert_eq!(v, json!({}));
    }

    #[test]
    fn message_round_trips() {
        let m = Message {
            messageId: "m-1".into(),
            contextId: Some("c-1".into()),
            taskId: Some("t-1".into()),
            role: Role::User,
            parts: vec![Part::Text {
                content: "hi".into(),
                metadata: None,
                mediaType: None,
                filename: None,
            }],
            metadata: None,
            extensions: vec![],
            referenceTaskIds: vec![],
        };
        let v = serde_json::to_value(&m).unwrap();
        let back: Message = serde_json::from_value(v).unwrap();
        assert_eq!(back.messageId, "m-1");
        assert_eq!(back.role, Role::User);
        assert_eq!(back.parts.len(), 1);
    }

    #[test]
    fn task_with_empty_history_serialises_minimally() {
        let t = Task {
            id: "t-1".into(),
            contextId: "c-1".into(),
            status: TaskStatus::Submitted,
            artifacts: vec![],
            history: vec![],
            metadata: None,
        };
        let v = serde_json::to_value(&t).unwrap();
        assert_eq!(v["id"], "t-1");
        assert_eq!(v["status"], "submitted");
    }

    #[test]
    fn agent_card_round_trips() {
        let card = AgentCard {
            id: "agent-1".into(),
            name: "Echo".into(),
            description: Some("Echoes input".into()),
            provider: None,
            capabilities: AgentCapabilities {
                streaming: false,
                pushNotifications: false,
                stateTransitionHistory: false,
            },
            skills: vec![],
            interfaces: vec![],
            securitySchemes: serde_json::Map::new(),
            security: vec![],
            extensions: vec![],
            signature: None,
        };
        let v = serde_json::to_value(&card).unwrap();
        let back: AgentCard = serde_json::from_value(v).unwrap();
        assert_eq!(back.id, "agent-1");
    }

    #[test]
    fn role_agent_serialises_as_lowercase() {
        let v = serde_json::to_value(Role::Agent).unwrap();
        assert_eq!(v, json!("agent"));
    }

    #[test]
    fn task_status_is_terminal_covers_completed_failed_canceled_rejected() {
        assert!(TaskStatus::Completed.is_terminal());
        assert!(TaskStatus::Failed.is_terminal());
        assert!(TaskStatus::Canceled.is_terminal());
        assert!(TaskStatus::Rejected.is_terminal());
    }

    #[test]
    fn task_status_is_terminal_excludes_in_progress() {
        assert!(!TaskStatus::Submitted.is_terminal());
        assert!(!TaskStatus::Working.is_terminal());
        assert!(!TaskStatus::Authenticated.is_terminal());
        assert!(!TaskStatus::InputRequired.is_terminal());
    }
}