Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
//! Draft `agent-runtime.v0` message types.
//!
//! The logical protocol multiplexes two kinds of traffic over one stream:
//! runtime/agent lifecycle events and ACP conversation traffic. Each
//! direction has its own envelope - [`ToRuntimeMessage`] for Agent Service to
//! Agent Runtime traffic and [`ToServerMessage`] for the reverse -
//! discriminated by a `"type"` field. Only the wrapped ACP payload is itself
//! a JSON-RPC message; the outer envelope is not.
//!
//! A connection hosts exactly one agent execution, so nothing on this schema
//! needs an agent or agent-instance identifier: [`AcpMessage`] simply carries
//! the agent's raw ACP traffic.
use agent_client_protocol::RawJsonRpcMessage;
use agent_client_protocol::schema::v1::SessionConfigOption;
use serde::{Deserialize, Deserializer, Serialize, Serializer};
use specta::Type;
use specta_typescript::Unknown;
#[cfg(test)]
mod test;
/// The kind of runtime or agent state transition reported to the Agent Service.
///
/// The protocol does not define a full event-name catalog yet, so this enum
/// is non-exhaustive: unrecognized wire strings still round-trip losslessly
/// through [`SystemEvent::Unknown`]. [`SystemEvent::AcpReady`] is the one
/// name the Agent Service actually acts on - it waits for it before starting
/// the ACP `initialize`/`session/new` handshake - rather than merely
/// forwarding it for observability.
///
/// This has a hand-written [`Serialize`]/[`Deserialize`] impl rather than a
/// derive, so it cannot derive [`specta::Type`] either: nothing here
/// introspects its shape for TypeScript. Every field that carries a
/// `SystemEvent` is instead given a `#[specta(type = String)]` override at
/// the field, matching the plain string it actually serializes as.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum SystemEvent {
/// The Agent Runtime's hosted agent process is up and its ACP channel is
/// wired end-to-end: the Agent Service may now start the ACP
/// `initialize`/`session/new` handshake. Sent at most once per
/// connection, before any ACP traffic.
AcpReady,
/// The session transport closed or failed and no more frames will arrive.
Disconnected,
/// The hosted provider recovered history; the client must reload when idle.
ReloadRequired,
/// An application-defined event name with no protocol-level meaning yet.
Unknown(String),
}
impl SystemEvent {
/// Borrow the wire string for this event name.
#[must_use]
pub fn as_str(&self) -> &str {
match self {
Self::AcpReady => "acp_ready",
Self::Disconnected => "disconnected",
Self::ReloadRequired => "reload_required",
Self::Unknown(name) => name,
}
}
}
impl Serialize for SystemEvent {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: Serializer,
{
serializer.serialize_str(self.as_str())
}
}
impl<'de> Deserialize<'de> for SystemEvent {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
Ok(match String::deserialize(deserializer)?.as_str() {
"acp_ready" => Self::AcpReady,
"disconnected" => Self::Disconnected,
"reload_required" => Self::ReloadRequired,
name => Self::Unknown(name.to_owned()),
})
}
}
/// One complete ACP JSON-RPC message routed between the Agent Service and the
/// single agent execution hosted by this connection.
///
/// Its own JSON-RPC fields are opaque to TypeScript consumers here (typed as
/// an arbitrary object of unknown values): they already have a proper ACP SDK
/// on the TypeScript side, so this crate only needs to guarantee the message
/// round-trips unchanged. This is typed as a map rather than plain `unknown`
/// because [`ToRuntimeMessage`]/[`ToServerMessage`] carry it in an internally
/// tagged `Acp` variant, which requires its payload provably serialize as an
/// object so the `"type"` tag can be merged into it. `#[serde(transparent)]`
/// changes nothing about the actual wire format here - a single-field tuple
/// struct already serializes transparently by default - but it does tell
/// specta's serde-compatibility checker that this newtype is transparent, so
/// it looks through to the map type below instead of treating `AcpMessage`
/// itself as an opaque, non-mergeable struct.
#[derive(Debug, Clone, Serialize, Deserialize, Type)]
#[serde(transparent)]
pub struct AcpMessage(
#[specta(type = std::collections::HashMap<String, Unknown>)] pub RawJsonRpcMessage,
);
/// The result of probing a fresh ACP subprocess.
#[derive(Debug, Clone, Serialize, Deserialize, Type)]
#[serde(tag = "status", rename_all = "camelCase")]
pub enum ModelProbeResult {
/// The raw options returned by `session/new`.
Available {
/// Session configuration options exactly as the agent returned them.
#[serde(rename = "configOptions")]
#[specta(type = Vec<Unknown>)]
config_options: Vec<SessionConfigOption>,
},
/// A safe, operator-actionable failure description.
Error {
/// Failure text safe to return across the runtime connection.
message: String,
},
}
/// Agent Service to Agent Runtime traffic on the logical protocol stream.
#[derive(Debug, Clone, Serialize, Deserialize, Type)]
#[serde(tag = "type", rename_all = "camelCase")]
#[non_exhaustive]
pub enum ToRuntimeMessage {
/// An ACP message routed to the hosted agent.
Acp(AcpMessage),
/// Probe a separate fresh agent process for its session configuration.
///
/// The request carries no parameters: it asks this connection's one
/// configured harness what it advertises. Answers are therefore
/// interchangeable, so nothing correlates a response to a request.
ModelProbeRequest,
}
/// Agent Runtime to Agent Service traffic on the logical protocol stream.
#[derive(Debug, Clone, Serialize, Deserialize, Type)]
#[serde(tag = "type", rename_all = "camelCase")]
#[non_exhaustive]
pub enum ToServerMessage {
/// An ACP message routed from the hosted agent.
Acp(AcpMessage),
/// A runtime or agent lifecycle event.
Event {
/// The event name.
#[specta(type = String)]
event: SystemEvent,
},
/// An answer to a connection-level model probe.
ModelProbeResponse {
/// Raw options or a safe failure.
result: ModelProbeResult,
},
}