Inter-agent communication

pub struct Envelope {
    pub id: Uuid,       // Unique message ID
    pub from: PubKey,   // Sender's public key
    pub to: PubKey,     // Recipient's public key
    pub kind: MessageKind,
    pub sig: Signature,  // Ed25519 signature over canonical CBOR of [id, from, to, kind]
}

pub struct TrustEntry {
    pub peer_id: PeerId,      // Canonical routing identity (the store key)
    pub name: PeerName,       // Display-only slug; not unique across entries
    pub pubkey: PubKey,       // Ed25519 public key
    pub address: PeerAddress, // Typed address: "uds://...", "tcp://...", or "inproc://..."
    pub meta: PeerMeta,       // Friendly metadata for peer discovery (description, labels)
}

{
  "peers": [
    {
      "name": "coding-agent",
      "pubkey": "ed25519:KioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKio=",
      "addr": "tcp://192.168.1.50:4200"
    },
    {
      "name": "review-agent",
      "pubkey": "ed25519:AQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQE=",
      "addr": "uds:///tmp/meerkat-review.sock"
    }
  ]
}

#[serde(tag = "type", rename_all = "lowercase")]
pub enum MessageKind {
    Message {
        body: String,
        blocks: Option<Vec<ContentBlock>>,
        content_taint: Option<SenderContentTaint>,
        handling_mode: Option<HandlingMode>,
    },
    IncarnationFencedMessage {
        body: String,
        blocks: Option<Vec<ContentBlock>>,
        content_taint: Option<SenderContentTaint>,
        handling_mode: Option<HandlingMode>,
        expected_recipient: PeerRecipientIncarnation,
    },
    Request {
        intent: String,
        params: JsonValue,
        blocks: Option<Vec<ContentBlock>>,
        reply_endpoint: Option<PeerAddress>,
        content_taint: Option<SenderContentTaint>,
        handling_mode: Option<HandlingMode>,
    },
    Lifecycle { kind: PeerLifecycleKind, params: JsonValue },
    Response {
        in_reply_to: Uuid,
        status: Status,
        result: JsonValue,
        blocks: Option<Vec<ContentBlock>>,
        content_taint: Option<SenderContentTaint>,
        handling_mode: Option<HandlingMode>,
    },
    Ack { in_reply_to: Uuid },
}

#[serde(rename_all = "lowercase")]
pub enum Status {
    Accepted,
    Completed,
    Failed,
}

{
  "peers": [
    {
      "peer_id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "review-agent",
      "address": {
        "transport": "tcp",
        "endpoint": "192.168.1.50:4200"
      },
      "source": "trusted",
      "sendable_kinds": ["peer_message", "peer_request", "peer_response"],
      "capabilities": {
        "version": 1,
        "extensions": {"review": true}
      },
      "meta": {
        "description": "Reviews pull requests",
        "labels": {"role": "reviewer"}
      }
    }
  ]
}

[comms]
mode = "inproc"                    # "inproc", "tcp", or "uds"
address = "0.0.0.0:4200"          # Required when mode = "tcp" or "uds"
auth = "none"                      # "none" (open) or "ed25519"
event_address = "127.0.0.1:4201"  # Plain-text event listener (requires auth = "none")

pub struct CoreCommsConfig {
    pub enabled: bool,
    pub name: String,                        // Default: "meerkat"
    pub inproc_namespace: Option<String>,    // Realm-scoped namespace for inproc isolation
    pub listen_uds: Option<PathBuf>,         // Signed agent-to-agent listener (UDS)
    pub listen_tcp: Option<SocketAddr>,      // Signed agent-to-agent listener (TCP)
    pub advertise_address: Option<String>,   // Address advertised to signed peers
    pub event_listen_tcp: Option<SocketAddr>, // Plain event listener (auth = Open only)
    pub event_listen_uds: Option<PathBuf>,   // Plain event listener (Unix, auth = Open only)
    pub identity_dir: PathBuf,               // Default: ".rkat/identity"
    pub trusted_peers_path: PathBuf,         // Default: ".rkat/trusted_peers.json"
    pub ack_timeout_secs: u64,               // Default: 30
    pub max_message_bytes: u32,              // Default: 1,048,576
    pub auth: CommsAuthMode,
    pub require_peer_auth: bool,             // Default: true
    pub allow_external_unauthenticated: bool, // Default: false (non-loopback plain listeners)
    pub pairing_password: Option<String>,    // Runtime-only enrollment secret (never serialized)
}

use meerkat::build_comms_runtime_from_config;

let runtime =
    build_comms_runtime_from_config(&config, base_dir, "my-agent", peer_meta).await?;

use meerkat::compose_tools_with_comms;

let (tools_with_comms, usage_instructions) =
    compose_tools_with_comms(base_tools, tool_usage_instructions, comms_material)?;

let factory = AgentFactory::new(store_path)
    .project_root(project_root)
    .comms(true);

let build_config = AgentBuildConfig {
    model: "claude-sonnet-4-6".to_string(),
    keep_alive: true,
    comms_name: Some("my-agent".to_string()),
    peer_meta: Some(PeerMeta::default()
        .with_description("Coordinates peer agents")),
    ..AgentBuildConfig::new("claude-sonnet-4-6")
};

let agent = factory.build_agent(build_config, &config).await?;

// Standalone
let bootstrap = CommsBootstrap::from_config(config, base_dir);
let prepared = bootstrap.prepare().await?;

// Child runtime (inproc; generated wiring must install parent trust)
let bootstrap = CommsBootstrap::for_child_inproc(
    "child-agent".to_string(),
    ParentCommsContext {
        parent_name: "parent".to_string(),
        parent_pubkey: parent_pubkey_bytes,
        parent_addr: "inproc://parent".to_string(),
        comms_base_dir: base_dir,
        inproc_namespace: None,
    },
);
let prepared = bootstrap.prepare().await?;