agent_client_protocol_schema/v2/

terminal.rs

//! Agent-owned terminal output reported for display by clients.

use std::sync::Arc;

use derive_more::{Display, From};
use serde::{Deserialize, Serialize};
use serde_with::{DefaultOnError, serde_as, skip_serializing_none};

use super::{AbsolutePath, Meta, apply_meta_update};
use crate::{IntoMaybeUndefined, IntoOption, MaybeUndefined};

/// Unique identifier for an agent-owned terminal within a session.
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash, Display, From)]
#[serde(transparent)]
#[from(forward)]
#[non_exhaustive]
pub struct TerminalId(pub Arc<str>);

impl TerminalId {
    /// Wraps a protocol string as a typed [`TerminalId`].
    #[must_use]
    pub fn new(id: impl Into<Self>) -> Self {
        id.into()
    }
}

impl IntoOption<TerminalId> for &str {
    fn into_option(self) -> Option<TerminalId> {
        Some(TerminalId::new(self))
    }
}

/// A display-only reference to an agent-owned terminal.
///
/// Terminal state and output are delivered separately through
/// `terminal_update` and `terminal_output_chunk` session updates.
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct Terminal {
    /// The ID of the terminal to display.
    pub terminal_id: TerminalId,
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
    /// Implementations MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    #[serde(rename = "_meta")]
    pub meta: Option<Meta>,
}

impl Terminal {
    /// Builds a terminal reference for the given terminal ID.
    #[must_use]
    pub fn new(terminal_id: impl Into<TerminalId>) -> Self {
        Self {
            terminal_id: terminal_id.into(),
            meta: None,
        }
    }

    /// Sets or clears metadata scoped to this content reference.
    #[must_use]
    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
        self.meta = meta.into_option();
        self
    }
}

/// An authoritative replacement snapshot of terminal output bytes.
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct TerminalOutput {
    /// Base64-encoded replacement terminal output bytes.
    #[cfg_attr(feature = "schemars", schemars(extend("contentEncoding" = "base64")))]
    pub data: String,
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
    /// Implementations MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    #[serde(rename = "_meta")]
    pub meta: Option<Meta>,
}

impl TerminalOutput {
    /// Builds an authoritative terminal output replacement.
    #[must_use]
    pub fn new(data: impl Into<String>) -> Self {
        Self {
            data: data.into(),
            meta: None,
        }
    }

    /// Sets or clears metadata scoped to this replacement snapshot.
    #[must_use]
    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
        self.meta = meta.into_option();
        self
    }
}

/// Exit information for an agent-owned terminal.
///
/// The presence of this object marks the terminal as exited, even when neither
/// an exit code nor a signal is known.
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct TerminalExitStatus {
    /// Process exit code as the platform reports it, when known. Negative values are
    /// allowed, for example signed Windows exit codes. Omitted and `null` are equivalent.
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    pub exit_code: Option<i64>,
    /// Signal that terminated the process, when known.
    ///
    /// Agents should use the conventional platform signal name. POSIX examples
    /// include `SIGTERM`, `SIGKILL`, and `SIGINT`. Other platforms may use a
    /// platform-specific name. Omitted and `null` are equivalent.
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    pub signal: Option<String>,
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
    /// Implementations MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    #[serde(rename = "_meta")]
    pub meta: Option<Meta>,
}

impl TerminalExitStatus {
    /// Builds terminal exit information with no known exit code or signal.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Sets or clears the optional exit code.
    #[must_use]
    pub fn exit_code(mut self, exit_code: impl IntoOption<i64>) -> Self {
        self.exit_code = exit_code.into_option();
        self
    }

    /// Sets or clears the optional terminating signal.
    #[must_use]
    pub fn signal(mut self, signal: impl IntoOption<String>) -> Self {
        self.signal = signal.into_option();
        self
    }

    /// Sets or clears metadata scoped to this exit information.
    #[must_use]
    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
        self.meta = meta.into_option();
        self
    }
}

/// Client-initiated controls a terminal currently supports.
///
/// A malformed value falls back to no controls, so the Client never sends a request the
/// Agent did not advertise.
///
/// See protocol docs: [Cancelling Terminals](https://agentclientprotocol.com/protocol/v2/tool-calls#cancelling-terminals)
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct TerminalCapabilities {
    /// Permits the Client to cancel this terminal with `terminal/cancel`.
    ///
    /// Omitted and `null` are equivalent and mean unsupported. An object (including `{}`)
    /// means supported. Agents SHOULD stop advertising it once the terminal reports `exitStatus`.
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    pub cancel: Option<TerminalCancelCapabilities>,
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
    /// Implementations MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    #[serde(rename = "_meta")]
    pub meta: Option<Meta>,
}

impl TerminalCapabilities {
    /// Builds an empty capability set. Cancellation is not advertised.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Sets or removes permission to cancel this terminal.
    #[must_use]
    pub fn cancel(mut self, cancel: impl IntoOption<TerminalCancelCapabilities>) -> Self {
        self.cancel = cancel.into_option();
        self
    }

    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they
    /// do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[must_use]
    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
        self.meta = meta.into_option();
        self
    }
}

/// Capability to cancel a terminal with `terminal/cancel`.
///
/// Supplying `{}` advertises support. An omitted or `null` `cancel` does not.
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[non_exhaustive]
pub struct TerminalCancelCapabilities {
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
    /// Implementations MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    #[serde(rename = "_meta")]
    pub meta: Option<Meta>,
}

impl TerminalCancelCapabilities {
    /// Builds an empty capability object advertising cancellation support.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they
    /// do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[must_use]
    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
        self.meta = meta.into_option();
        self
    }
}

/// An upsert for the stored state of an agent-owned terminal.
///
/// Only `terminalId` is required. Other fields have patch
/// semantics: omitted fields leave the stored value unchanged, `null` clears
/// it, and concrete values replace it. A concrete `_meta` object instead
/// patches the stored metadata by top-level key. When the terminal ID is new,
/// omitted fields start unknown.
#[serde_as]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct TerminalUpdate {
    /// Unique identifier for this terminal within the session.
    pub terminal_id: TerminalId,
    /// The command being run.
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default, skip_serializing_if = "MaybeUndefined::is_undefined")]
    pub command: MaybeUndefined<String>,
    /// The absolute working directory of the command.
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default, skip_serializing_if = "MaybeUndefined::is_undefined")]
    pub cwd: MaybeUndefined<AbsolutePath>,
    /// An authoritative replacement snapshot of terminal output bytes.
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default, skip_serializing_if = "MaybeUndefined::is_undefined")]
    pub output: MaybeUndefined<TerminalOutput>,
    /// Exit information. A concrete object marks the terminal as exited.
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default, skip_serializing_if = "MaybeUndefined::is_undefined")]
    pub exit_status: MaybeUndefined<TerminalExitStatus>,
    /// The terminal size the command runs with, when known.
    ///
    /// Clients can render output at this size so that column layouts, progress bars,
    /// and cursor-positioned output display as the program wrote them.
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default, skip_serializing_if = "MaybeUndefined::is_undefined")]
    pub size: MaybeUndefined<TerminalSize>,
    /// Client-initiated controls this terminal currently supports, such as cancellation.
    ///
    /// Omission leaves the capabilities unchanged, `null` clears them, and an object replaces
    /// the whole previous value. A new terminal starts with none.
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default, skip_serializing_if = "MaybeUndefined::is_undefined")]
    pub capabilities: MaybeUndefined<TerminalCapabilities>,
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted leaves the stored metadata unchanged. `null`
    /// clears it. An object patches the stored metadata by top-level key: keys it omits are
    /// unchanged, a key set to `null` is removed, and any other value replaces that key's
    /// stored value without merging nested objects. Beyond this patch rule, implementations
    /// MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Metadata Patches](https://agentclientprotocol.com/protocol/v2/extensibility#metadata-patches)
    #[serde_as(deserialize_as = "DefaultOnError<MaybeUndefined<_>>")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(
        rename = "_meta",
        default,
        skip_serializing_if = "MaybeUndefined::is_undefined"
    )]
    pub meta: MaybeUndefined<Meta>,
}

impl TerminalUpdate {
    /// Builds a terminal upsert with only its required ID set.
    #[must_use]
    pub fn new(terminal_id: impl Into<TerminalId>) -> Self {
        Self {
            terminal_id: terminal_id.into(),
            command: MaybeUndefined::Undefined,
            cwd: MaybeUndefined::Undefined,
            output: MaybeUndefined::Undefined,
            exit_status: MaybeUndefined::Undefined,
            size: MaybeUndefined::Undefined,
            capabilities: MaybeUndefined::Undefined,
            meta: MaybeUndefined::Undefined,
        }
    }

    /// Sets, clears, or leaves unchanged the command being run.
    #[must_use]
    pub fn command(mut self, command: impl IntoMaybeUndefined<String>) -> Self {
        self.command = command.into_maybe_undefined();
        self
    }

    /// Sets, clears, or leaves unchanged the absolute working directory.
    #[must_use]
    pub fn cwd(mut self, cwd: impl IntoMaybeUndefined<AbsolutePath>) -> Self {
        self.cwd = cwd.into_maybe_undefined();
        self
    }

    /// Sets, clears, or leaves unchanged the authoritative output snapshot.
    #[must_use]
    pub fn output(mut self, output: impl IntoMaybeUndefined<TerminalOutput>) -> Self {
        self.output = output.into_maybe_undefined();
        self
    }

    /// Sets, clears, or leaves unchanged the terminal exit information.
    #[must_use]
    pub fn exit_status(mut self, exit_status: impl IntoMaybeUndefined<TerminalExitStatus>) -> Self {
        self.exit_status = exit_status.into_maybe_undefined();
        self
    }

    /// Sets, clears, or leaves unchanged the terminal size.
    #[must_use]
    pub fn size(mut self, size: impl IntoMaybeUndefined<TerminalSize>) -> Self {
        self.size = size.into_maybe_undefined();
        self
    }

    /// Sets, clears, or leaves unchanged the Client-initiated controls.
    #[must_use]
    pub fn capabilities(
        mut self,
        capabilities: impl IntoMaybeUndefined<TerminalCapabilities>,
    ) -> Self {
        self.capabilities = capabilities.into_maybe_undefined();
        self
    }

    /// Patches, clears, or leaves unchanged terminal metadata.
    ///
    /// A concrete object patches stored metadata by top-level key. See
    /// [`apply_meta_update`].
    #[must_use]
    pub fn meta(mut self, meta: impl IntoMaybeUndefined<Meta>) -> Self {
        self.meta = meta.into_maybe_undefined();
        self
    }

    /// Applies a later terminal patch to this stored terminal state.
    ///
    /// Fields set to `null` remain `null` so callers can distinguish explicit
    /// clearing from an update that did not mention the field. A concrete
    /// `_meta` object patches the stored metadata by top-level key, as described
    /// by [`apply_meta_update`].
    pub fn apply_update(&mut self, update: TerminalUpdate) {
        debug_assert_eq!(self.terminal_id, update.terminal_id);
        if !update.command.is_undefined() {
            self.command = update.command;
        }
        if !update.cwd.is_undefined() {
            self.cwd = update.cwd;
        }
        if !update.output.is_undefined() {
            self.output = update.output;
        }
        if !update.exit_status.is_undefined() {
            self.exit_status = update.exit_status;
        }
        if !update.size.is_undefined() {
            self.size = update.size;
        }
        if !update.capabilities.is_undefined() {
            self.capabilities = update.capabilities;
        }
        apply_meta_update(&mut self.meta, update.meta);
    }
}

/// The size of an agent-owned terminal in character cells.
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct TerminalSize {
    /// Number of columns.
    #[cfg_attr(feature = "schemars", schemars(range(min = 1)))]
    pub cols: u16,
    /// Number of rows.
    #[cfg_attr(feature = "schemars", schemars(range(min = 1)))]
    pub rows: u16,
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
    /// Implementations MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    #[serde(rename = "_meta")]
    pub meta: Option<Meta>,
}

impl TerminalSize {
    /// Builds a terminal size from its columns and rows.
    #[must_use]
    pub fn new(cols: u16, rows: u16) -> Self {
        Self {
            cols,
            rows,
            meta: None,
        }
    }

    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they
    /// do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[must_use]
    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
        self.meta = meta.into_option();
        self
    }
}

/// A chunk of bytes appended to an agent-owned terminal's output.
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct TerminalOutputChunk {
    /// The terminal receiving these bytes.
    pub terminal_id: TerminalId,
    /// Independently base64-encoded terminal output bytes.
    #[cfg_attr(feature = "schemars", schemars(extend("contentEncoding" = "base64")))]
    pub data: String,
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
    /// Implementations MUST NOT assign meaning to keys they do not recognize.
    /// This metadata is scoped to the chunk and does not patch stored metadata.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    #[serde(rename = "_meta")]
    pub meta: Option<Meta>,
}

impl TerminalOutputChunk {
    /// Builds a terminal output chunk with the required fields set.
    #[must_use]
    pub fn new(terminal_id: impl Into<TerminalId>, data: impl Into<String>) -> Self {
        Self {
            terminal_id: terminal_id.into(),
            data: data.into(),
            meta: None,
        }
    }

    /// Sets or clears chunk-scoped metadata.
    #[must_use]
    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
        self.meta = meta.into_option();
        self
    }
}

#[cfg(test)]
mod tests {

    #[test]
    fn terminal_capabilities_patch_and_tolerate_malformed_values() {
        use serde_json::json;
        let update = TerminalUpdate::new("term_003")
            .capabilities(TerminalCapabilities::new().cancel(TerminalCancelCapabilities::new()));
        assert_eq!(
            serde_json::to_value(&update).unwrap(),
            json!({ "terminalId": "term_003", "capabilities": { "cancel": {} } })
        );

        let mut stored = update;
        stored.apply_update(TerminalUpdate::new("term_003"));
        assert!(stored.capabilities.is_value());
        stored.apply_update(TerminalUpdate::new("term_003").capabilities(MaybeUndefined::Null));
        assert!(stored.capabilities.is_null());

        for bad in [json!("yes"), json!(1)] {
            let parsed: TerminalUpdate =
                serde_json::from_value(json!({ "terminalId": "term_003", "capabilities": bad }))
                    .unwrap();
            assert!(parsed.capabilities.is_undefined());
        }
        let parsed: TerminalCapabilities =
            serde_json::from_value(json!({ "cancel": "yes" })).unwrap();
        assert_eq!(parsed.cancel, None);
    }

    #[test]
    fn terminal_size_is_an_optional_patch_field() {
        let update = TerminalUpdate::new("term_1").size(TerminalSize::new(120, 40));
        assert_eq!(
            serde_json::to_value(&update).unwrap(),
            serde_json::json!({ "terminalId": "term_1", "size": { "cols": 120, "rows": 40 } })
        );

        let mut stored = update;
        stored.apply_update(TerminalUpdate::new("term_1").command("ls"));
        assert_eq!(
            stored.size,
            MaybeUndefined::Value(TerminalSize::new(120, 40))
        );
        stored.apply_update(TerminalUpdate::new("term_1").size(None));
        assert_eq!(stored.size, MaybeUndefined::Null);
    }

    #[test]
    fn exit_code_accepts_negative_values() {
        let status: TerminalExitStatus =
            serde_json::from_value(serde_json::json!({ "exitCode": -1_073_741_819_i64 })).unwrap();
        assert_eq!(status.exit_code, Some(-1_073_741_819));
    }

    use super::*;
    use serde_json::{from_value, json, to_value};

    #[test]
    fn terminal_reference_meta_is_optional_and_content_scoped() {
        let omitted = Terminal::new("term_1");
        assert_eq!(
            serde_json::to_value(&omitted).unwrap(),
            serde_json::json!({
                "terminalId": "term_1"
            })
        );

        let null: Terminal = serde_json::from_value(serde_json::json!({
            "terminalId": "term_1",
            "_meta": null
        }))
        .unwrap();
        assert_eq!(null.meta, None);

        let mut meta = Meta::new();
        meta.insert("view".to_string(), serde_json::json!("expanded"));
        assert_eq!(
            serde_json::to_value(Terminal::new("term_1").meta(meta)).unwrap(),
            serde_json::json!({
                "terminalId": "term_1",
                "_meta": {
                    "view": "expanded"
                }
            })
        );
    }

    #[test]
    fn terminal_update_distinguishes_omitted_null_and_value() {
        let update = TerminalUpdate::new("term_1")
            .command("cargo test")
            .cwd("/workspace/project")
            .output(None::<TerminalOutput>)
            .exit_status(TerminalExitStatus::new().exit_code(0));

        assert_eq!(
            serde_json::to_value(update).unwrap(),
            serde_json::json!({
                "terminalId": "term_1",
                "command": "cargo test",
                "cwd": "/workspace/project",
                "output": null,
                "exitStatus": {
                    "exitCode": 0
                }
            })
        );

        let parsed: TerminalUpdate = serde_json::from_value(serde_json::json!({
            "terminalId": "term_1",
            "command": null,
            "cwd": "/workspace/project"
        }))
        .unwrap();
        assert_eq!(parsed.command, MaybeUndefined::Null);
        assert_eq!(
            parsed.cwd,
            MaybeUndefined::Value(AbsolutePath::new("/workspace/project"))
        );
        assert_eq!(parsed.output, MaybeUndefined::Undefined);
        assert_eq!(parsed.exit_status, MaybeUndefined::Undefined);
        assert_eq!(parsed.meta, MaybeUndefined::Undefined);
    }

    #[test]
    fn terminal_update_applies_patch_fields() {
        let mut stored = TerminalUpdate::new("term_1")
            .command("cargo test")
            .cwd("/workspace/project")
            .output(TerminalOutput::new("b2xk"));

        stored.apply_update(
            TerminalUpdate::new("term_1")
                .command(None::<String>)
                .output(TerminalOutput::new("bmV3"))
                .exit_status(TerminalExitStatus::new().signal("SIGTERM")),
        );

        assert_eq!(stored.command, MaybeUndefined::Null);
        assert_eq!(
            stored.cwd,
            MaybeUndefined::Value(AbsolutePath::new("/workspace/project"))
        );
        assert_eq!(
            stored.output,
            MaybeUndefined::Value(TerminalOutput::new("bmV3"))
        );
        assert_eq!(
            stored.exit_status,
            MaybeUndefined::Value(TerminalExitStatus::new().signal("SIGTERM"))
        );
    }

    #[test]
    fn terminal_wire_patches_preserve_omitted_fields_and_replace_values() {
        let initial = json!({
            "terminalId": "term_1",
            "_meta": {"source": "replay", "opaque": {"sequence": 1}}
        });
        let mut stored: TerminalUpdate = from_value(initial.clone()).unwrap();
        // A metadata-only first update leaves output and exit status unknown.
        assert_eq!(to_value(&stored).unwrap(), initial);

        let populated = json!({
            "terminalId": "term_1",
            "command": "cargo check",
            "cwd": "/workspace/project",
            "output": {"data": "b2xk", "_meta": {"source": "snapshot"}},
            "exitStatus": {"exitCode": 0, "_meta": {"observed": true}}
        });
        stored.apply_update(from_value(populated.clone()).unwrap());
        let mut expected = populated;
        expected["_meta"] = initial["_meta"].clone();
        assert_eq!(to_value(&stored).unwrap(), expected);

        for (field, empty) in [
            ("command", json!("")),
            ("output", json!({"data": ""})),
            ("exitStatus", json!({})),
        ] {
            let original = expected[field].clone();
            // Nested objects are replacements too: an empty output snapshot
            // must not inherit snapshot metadata, and an empty exit-status
            // object means exited with unknown details, not exit code zero.
            for replacement in [empty, json!(null), original] {
                stored.apply_update(
                    from_value(json!({"terminalId": "term_1", (field): replacement})).unwrap(),
                );
                expected[field] = replacement;
                assert_eq!(to_value(&stored).unwrap(), expected, "patching {field}");

                stored.apply_update(from_value(json!({"terminalId": "term_1"})).unwrap());
                assert_eq!(to_value(&stored).unwrap(), expected, "omitting {field}");
            }
        }

        // Top-level `_meta` patches individual keys instead of replacing the object.
        stored.apply_update(
            from_value(json!({
                "terminalId": "term_1",
                "_meta": {"source": null, "opaque": {"other": 2}, "extra": true}
            }))
            .unwrap(),
        );
        expected["_meta"] = json!({"opaque": {"other": 2}, "extra": true});
        assert_eq!(to_value(&stored).unwrap(), expected, "patching _meta keys");

        stored.apply_update(from_value(json!({"terminalId": "term_1", "_meta": null})).unwrap());
        expected["_meta"] = json!(null);
        assert_eq!(to_value(&stored).unwrap(), expected, "clearing _meta");
    }

    #[test]
    fn terminal_output_chunk_serializes_base64_data_and_meta() {
        let mut meta = Meta::new();
        meta.insert("source".to_string(), serde_json::json!("pty"));

        assert_eq!(
            serde_json::to_value(TerminalOutputChunk::new("term_1", "8J+agA==").meta(meta))
                .unwrap(),
            serde_json::json!({
                "terminalId": "term_1",
                "data": "8J+agA==",
                "_meta": {
                    "source": "pty"
                }
            })
        );
    }

    #[test]
    fn terminal_output_meta_is_optional_and_snapshot_scoped() {
        let omitted = TerminalOutput::new("b2s=");
        assert_eq!(
            serde_json::to_value(&omitted).unwrap(),
            serde_json::json!({ "data": "b2s=" })
        );

        let null: TerminalOutput = serde_json::from_value(serde_json::json!({
            "data": "b2s=",
            "_meta": null
        }))
        .unwrap();
        assert_eq!(null, omitted);

        let mut meta = Meta::new();
        meta.insert("source".to_string(), serde_json::json!("replay"));
        assert_eq!(
            serde_json::to_value(TerminalOutput::new("b2s=").meta(meta)).unwrap(),
            serde_json::json!({
                "data": "b2s=",
                "_meta": {
                    "source": "replay"
                }
            })
        );
    }

    #[cfg(feature = "schemars")]
    #[test]
    fn terminal_output_fields_use_base64_content_encoding() {
        let output = serde_json::to_value(schemars::schema_for!(TerminalOutput)).unwrap();
        assert_eq!(output["properties"]["data"]["contentEncoding"], "base64");
        assert!(output["properties"]["data"].get("format").is_none());
        assert_eq!(output["required"], serde_json::json!(["data"]));
        assert!(output["properties"].get("_meta").is_some());
        assert!(output["properties"].get("truncated").is_none());

        let chunk = serde_json::to_value(schemars::schema_for!(TerminalOutputChunk)).unwrap();
        assert_eq!(chunk["properties"]["data"]["contentEncoding"], "base64");
        assert!(chunk["properties"]["data"].get("format").is_none());
    }

    #[test]
    fn terminal_exit_status_treats_omitted_and_null_as_unknown() {
        let omitted: TerminalExitStatus = serde_json::from_value(serde_json::json!({})).unwrap();
        let null: TerminalExitStatus = serde_json::from_value(serde_json::json!({
            "exitCode": null,
            "signal": null,
            "_meta": null
        }))
        .unwrap();

        assert_eq!(omitted, TerminalExitStatus::new());
        assert_eq!(null, TerminalExitStatus::new());
        assert_eq!(serde_json::to_value(null).unwrap(), serde_json::json!({}));
    }

    #[test]
    fn terminal_exit_status_meta_is_exit_scoped() {
        let mut meta = Meta::new();
        meta.insert("reason".to_string(), serde_json::json!("timeout"));

        assert_eq!(
            serde_json::to_value(TerminalExitStatus::new().signal("SIGTERM").meta(meta)).unwrap(),
            serde_json::json!({
                "signal": "SIGTERM",
                "_meta": {
                    "reason": "timeout"
                }
            })
        );
    }
}