Struct CommsRuntime 

pub struct CommsRuntime { /* private fields */ }

Implementations

impl CommsRuntime

pub async fn new(config: ResolvedCommsConfig) -> Result<Self, CommsRuntimeError>

pub async fn new_with_silent_intents( config: ResolvedCommsConfig, silent_intents: Arc<HashSet<String>>, ) -> Result<Self, CommsRuntimeError>

pub async fn new_machine_authority_required_with_silent_intents( config: ResolvedCommsConfig, silent_intents: Arc<HashSet<String>>, ) -> Result<Self, CommsRuntimeError>

pub fn inproc_only(name: &str) -> Result<Self, CommsRuntimeError>

pub fn inproc_only_scoped( name: &str, namespace: Option<String>, ) -> Result<Self, CommsRuntimeError>

pub fn inproc_only_with_silent_intents( name: &str, namespace: Option<String>, silent_intents: Arc<HashSet<String>>, ) -> Result<Self, CommsRuntimeError>

pub fn inproc_only_with_keypair_and_silent_intents( name: &str, namespace: Option<String>, keypair: Keypair, _silent_intents: Arc<HashSet<String>>, ) -> Result<Self, CommsRuntimeError>

pub fn set_listen_tcp_for_unstarted_runtime( &mut self, listen_tcp: SocketAddr, ) -> Result<(), CommsRuntimeError>

pub fn set_advertise_address_for_unstarted_runtime( &mut self, advertise_address: String, ) -> Result<(), CommsRuntimeError>

pub async fn inproc_only_session_scoped_with_silent_intents( name: &str, namespace: Option<String>, identity_root: PathBuf, session_id: &SessionId, _silent_intents: Arc<HashSet<String>>, session_claim_handle: Arc<dyn SessionClaimHandle>, ) -> Result<Self, CommsRuntimeError>

pub fn participant_name(&self) -> &str

pub fn set_blob_store(&mut self, blob_store: Arc<dyn BlobStore>)

Set the blob store used to resolve blob-backed image blocks before transport send. Comms stays byte-oriented; refs never cross the peer boundary.

pub fn require_peer_comms_machine_authority(&self)

Mark this runtime as requiring peer-comms machine authority. Missing PeerCommsHandle already fails closed for classified ingress; this flag remains as an observable session-mode marker for callers.

pub fn peer_comms_machine_authority_required(&self) -> bool

pub fn peer_comms_handle(&self) -> Option<Arc<dyn PeerCommsHandle>>

pub fn install_peer_request_response_authority( self: &Arc<Self>, authority: PeerRequestResponseAuthority, )

Install both machine handles required for semantic peer request/response.

This is the typed boundary between transport-only comms and semantic request/response. Without this authority, PeerRequest and PeerResponse sends fail closed before transport send or receipt emission.

pub fn install_peer_interaction_handle( self: &Arc<Self>, handle: Arc<dyn PeerInteractionHandle>, )

Install the session’s peer-interaction DSL handle (W1-A).

Called by the surface after the session’s SessionRuntimeBindings land. Two things happen here:

1. The runtime stores the handle so outbound PeerRequest sends fire PeerInteractionHandle::request_sent (DSL authority).
2. The runtime registers itself as the handle’s cleanup observer, so every DSL PeerInteractionCleanup effect drops the matching entries in subscriber_registry / interaction_stream_registry. That closes the “terminal transition → effect → cleanup” causal chain — the shell registries are a projection of DSL truth, not shadow state updated by lexical adjacency.

pub fn peer_interaction_handle(&self) -> Option<Arc<dyn PeerInteractionHandle>>

Read-side accessor for the installed peer-interaction handle.

pub fn install_interaction_stream_handle( self: &Arc<Self>, handle: Arc<dyn InteractionStreamHandle>, )

Install the session’s interaction-stream lifecycle DSL handle (U6).

Two things happen here:

1. The runtime stores the handle so machine-authoritative reservation, attach, completion, expiry, and consumer-drop transitions flow through the DSL.
2. The runtime registers itself as the handle’s cleanup observer, so every InteractionStreamCleanup effect drops the matching entry in interaction_stream_registry (and the paired subscriber_registry entry under the same lock).

For machine-authoritative entries, the registry holds channels only and lifecycle truth (Reserved/Attached/Completed/Expired/ClosedEarly) lives in the DSL. Local input streams stay transport-only.

pub fn interaction_stream_handle( &self, ) -> Option<Arc<dyn InteractionStreamHandle>>

Read-side accessor for the installed interaction-stream handle.

pub fn inproc_namespace(&self) -> Option<&str>

pub fn advertised_address(&self) -> String

pub async fn start_listeners(&mut self) -> Result<(), CommsRuntimeError>

pub fn public_key(&self) -> PubKey

pub fn bridge_bootstrap_token(&self) -> &str

pub fn router(&self) -> &Router

pub fn set_outbound_content_taint(&self, taint: Option<SenderContentTaint>)

Install (or clear) the host-owned outbound content-taint declaration.

Host-set config, not machine state: the declaration is stamped onto every content-bearing envelope at the router’s single outbound choke point unless a per-send meerkat_core::comms::SendTaintOverride says otherwise. None clears the declaration (subsequent sends carry no taint field).

pub fn outbound_content_taint(&self) -> Option<SenderContentTaint>

The currently-installed host-owned outbound content-taint declaration.

pub fn set_peer_meta(&self, meta: PeerMeta)

Update the inproc registry entry with friendly metadata.

Call this after construction to advertise [PeerMeta] to other in-process agents via InprocRegistry::peers().

Internally re-registers with [InprocRegistry::register_with_meta], which replaces the full entry (including inbox sender). This is safe because the sender is cloned from the same router and pending deliveries are unaffected.

pub fn mark_interaction_complete(&self, interaction_id: Uuid)

Mark an interaction stream as completed (terminal event received).

Machine-authoritative streams complete through the DSL is_attached guard: if the consumer already closed the stream, the transition is rejected and this call is a no-op. Local transport-only streams have no semantic lifecycle twin, so completion drops their channel projection.

pub fn reap_expired_reservations(&self)

Reap expired reservations that were never attached within the TTL.

TTL is shell-owned mechanics (created_at lives with the channel projection, not the DSL). Machine-authoritative reservations fire InteractionStreamHandle::expired; local transport-only reservations remove the unclaimed channel projection directly. If the reservation also corresponds to a live outbound peer-request DSL entry, fires PeerRequestTimedOut so the peer-correlation lifecycle matches reality.

pub fn router_arc(&self) -> Arc<Router>

pub fn trusted_peers_shared(&self) -> TrustedPeersView

pub fn inbox_notify(&self) -> Arc<Notify>

pub fn tool_material(self: &Arc<Self>) -> CommsToolMaterial

Extract the material needed for comms tool composition.

The facade uses this to compose comms tools without reaching into router/trust/key internals directly.

pub fn event_injector(&self) -> Arc<dyn EventInjector>

Get an event injector for this runtime’s inbox.

pub async fn drain_messages(&self) -> Vec<CommsMessage>

pub async fn recv_message(&self) -> Option<CommsMessage>

pub fn shutdown(&mut self)

pub fn abort_listeners_for_rebind(&self)

pub async fn stop_listeners_for_rebind(&self)

Trait Implementations

impl CommsRuntime for CommsRuntime

fn set_outbound_content_taint( &self, taint: Option<SenderContentTaint>, ) -> Result<(), SendError>

Install the host-owned outbound content-taint declaration.

fn drain_messages<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Vec<String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Drain comms inbox and return messages formatted for the LLM

fn inbox_notify(&self) -> Arc<Notify>

Get a notification when new messages arrive

fn peer_id(&self) -> Option<PeerId>

Canonical runtime routing identity for this peer, if available.

fn public_key(&self) -> Option<String>

Runtime-local transport/auth public key, if available.

fn public_key_bytes(&self) -> Option<[u8; 32]>

Runtime-local Ed25519 public key bytes, if available.

fn comms_name(&self) -> Option<String>

Runtime-local canonical comms routing name, if available.

fn advertised_address(&self) -> Option<String>

Runtime-local advertised comms address, if available.

fn bridge_bootstrap_token(&self) -> Option<String>

Runtime-local bootstrap proof for the initial supervisor bind, if available.

fn apply_trust_mutation<'life0, 'async_trait>( &'life0 self, mutation: CommsTrustMutation, ) -> Pin<Box<dyn Future<Output = Result<CommsTrustMutationResult, SendError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Apply a comms trust projection mutation authorized by generated machine/composition authority.

fn install_generated_mob_trust_owner<'life0, 'async_trait>( &'life0 self, owner: Arc<dyn Any + Send + Sync>, ) -> Pin<Box<dyn Future<Output = Result<(), SendError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Bind this target runtime to the generated MobMachine owner token whose trust handoffs may mutate mob-owned trust rows.

fn validate_recovered_generated_mob_trust_owner<'life0, 'async_trait>( &'life0 self, owner: Arc<dyn Any + Send + Sync>, ) -> Pin<Box<dyn Future<Output = Result<(), SendError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Read-only preflight for binding this target runtime to a recovered MobMachine owner token.

fn install_recovered_generated_mob_trust_owner<'life0, 'async_trait>( &'life0 self, owner: Arc<dyn Any + Send + Sync>, ) -> Pin<Box<dyn Future<Output = Result<(), SendError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Rebind this target runtime to the owner token of a recovered MobMachine authority.

fn event_injector(&self) -> Option<Arc<dyn EventInjector>>

Get an event injector for this runtime’s inbox.

fn send<'life0, 'async_trait>( &'life0 self, cmd: CommsCommand, ) -> Pin<Box<dyn Future<Output = Result<SendReceipt, SendError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Dispatch a canonical comms command.

fn peers<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Vec<PeerDirectoryEntry>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

List peers visible to this runtime.

fn peer_count<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = usize> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Count peers visible to this runtime.

fn drain_inbox_interactions<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Vec<InboxInteraction>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Drain comms inbox and return structured interactions.

fn interaction_subscriber( &self, id: &InteractionId, ) -> Option<Sender<AgentEvent>>

Look up and remove a one-shot subscriber for the given interaction.

fn mark_interaction_complete(&self, id: &InteractionId)

Signal that an interaction has reached a terminal state (complete or failed).

fn peer_interaction_handle(&self) -> Option<Arc<dyn PeerInteractionHandle>>

Access the session’s peer-interaction DSL handle (W1-A).

fn peer_request_response_authority_handle( &self, ) -> Option<Arc<dyn PeerInteractionHandle>>

Access peer request/response authority only when the runtime has the complete machine-owned lifecycle pair.

fn drain_classified_inbox_interactions<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Vec<ClassifiedInboxInteraction>, CommsCapabilityError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Drain classified inbox interactions.

fn peer_ingress_queue_snapshot<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<PeerIngressQueueSnapshot, CommsCapabilityError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Snapshot the currently queued peer-ingress surface without draining it.

fn peer_ingress_runtime_snapshot<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<PeerIngressRuntimeSnapshot, CommsCapabilityError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Snapshot the current peer runtime surface for MeerkatMachine mapping.

fn public_trusted_peer_projection_snapshot<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Vec<TrustedPeerDescriptor>, CommsCapabilityError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Snapshot only the public trust projection owned by generated public peer authority.

fn trusted_peer_projection_snapshot_for_source<'life0, 'async_trait>( &'life0 self, source_kind: GeneratedCommsTrustAuthoritySourceKind, ) -> Pin<Box<dyn Future<Output = Result<Vec<TrustedPeerDescriptor>, CommsCapabilityError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Snapshot the public trust projection owned by one generated source.

fn actionable_input_notify(&self) -> Result<Arc<Notify>, CommsCapabilityError>

Get a notification that fires only for actionable peer input.

fn add_private_trusted_peer<'life0, 'async_trait>( &'life0 self, _peer: TrustedPeerDescriptor, ) -> Pin<Box<dyn Future<Output = Result<(), SendError>> + Send + 'async_trait>>

where 'life0: 'async_trait, Self: 'async_trait,

Register a peer for admission-only trust without listing it in the directory.

fn remove_private_trusted_peer<'life0, 'life1, 'async_trait>( &'life0 self, _peer_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<bool, SendError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

Remove a previously registered private-trust edge by peer ID.

fn dismiss_received(&self) -> bool

Returns true if a DISMISS signal was seen during the last drain_messages call.

fn take_interaction_stream_sender( &self, _id: &InteractionId, ) -> Option<Sender<AgentEvent>>

Take and clear the one-shot sender for an interaction-scoped stream.

fn drain_peer_input_candidates<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Vec<PeerInputCandidate>> + Send + 'async_trait>>

where 'life0: 'async_trait, Self: 'async_trait,

Drain canonical peer/event ingress candidates.

impl Drop for CommsRuntime

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl InteractionStreamCleanupObserver for CommsRuntime

fn on_interaction_stream_cleanup(&self, corr_id: PeerCorrelationId)

Called once per emitted InteractionStreamCleanup { corr_id } effect.

impl PeerCommsInstallTarget for CommsRuntime

fn install_generated_peer_comms_handle( &self, install: GeneratedPeerCommsInstall, ) -> Result<(), String>

fn generated_peer_comms_target_endpoint( &self, ) -> Result<TrustedPeerDescriptor, String>

impl PeerInteractionCleanupObserver for CommsRuntime

fn on_peer_interaction_cleanup(&self, corr_id: PeerCorrelationId)

Called once per emitted PeerInteractionCleanup { corr_id } effect.