apomesh-protocol

apomesh-protocol is the wire layer: the prost-generated protobuf types and the ApomeshDaemon gRPC service definition, and nothing else. It is the lowest crate in the workspace — every other crate that touches the wire depends on it, and it depends on no workspace crate. Touch it when a message shape, an RPC, or the Payload event vocabulary changes on the wire; the domain-side conversion lives elsewhere.

Position in the workspace

• Layer: wire / protocol. See Control & execution planes for how the wire connects the daemons.
• Depends on: nothing in the workspace — it is the leaf. Its only dependencies are the codegen stack (prost, prost-types, tonic, tonic-prost).
• Consumed by: essentially the whole workspace — the substrate runtime (apomesh-substrate), the orchestrator, the worker, the REST API, SmartChat, the state-store adapters, both verticals, the control-plane UI, and the Prometheus sample all mirror or decode its types.

What it owns

• The generated protobuf types — the proto module, compiled from proto/apomesh.proto at build time into the wire messages every transport frames.
• The gRPC service contract — the ApomeshDaemon service trait plus the generated server and client stubs.
• The Payload event vocabulary — the closed-enum oneof carried on every Envelope, with a stable per-variant tag.
• Redaction of secret-bearing messages — a hand-written Debug that elides the cleartext credential/token on the five secret-carrying wire messages, so a stray {:?} can never print a secret.
• What it deliberately does not own — the wire↔domain From impls live in apomesh-substrate (its *::wire modules), because Rust’s orphan rules place the conversion in the crate that owns the domain type. No serde derives ride the prost types.

Public surface

• proto — the module of generated protobuf types, include!d from the build’s OUT_DIR.
• Envelope — the event envelope; its payload field is the closed-enum oneof.
• envelope::Payload — the event-vocabulary oneof; every observable substrate action is one of its variants.
• Payload::variant_name — a stable string tag for a payload; the match is exhaustive, so a new variant breaks compilation until it is named.
• ApomeshDaemon / ApomeshDaemonServer / ApomeshDaemonClient — the gRPC service trait and its generated server and client stubs.
• Dispatch, AgentManifest, AgentRef — the core wire messages for dispatching work and describing an agent.
• StrategyConfigRef / StrategyConfiguration — the orchestration-strategy configuration wire family.
• The secret-redacting Debug set — ResolvedToolSecret, MintTokenResponse, UpsertCredentialRequest, McpHttpTransport, SessionCredential print <redacted> in place of the secret value.
• The Wire* re-export convention — a mirror whose name collides with a substrate domain type is re-exported renamed (WireConfigSource, WireProviderKind, WireMcpTransport).

Usage

Payload::variant_name gives you a stable tag for a payload without reaching into its inner shape — the pattern operator-facing projections and logging use:

use apomesh_protocol::Envelope;

// `Envelope.payload` is the closed-enum `oneof` (prost models it as an
// `Option`); `variant_name()` names it for a log line without exposing
// the inner message.
fn log_envelope(env: &Envelope) {
    if let Some(payload) = &env.payload {
        tracing::info!(variant = payload.variant_name(), "received envelope");
    }
}

Related

• Concepts: Control & execution planes, Sessions, events & durability (the Envelope event log).
• Contribute: the contract-parity discipline — a wire change sweeps every mirror (SDKs, the UI) in the same PR.