Skip to main content
For the full guide, see Comms.

Keep a session alive for inbound work

Keep-alive sessions stay resident so later comms or external events can wake them up as future runtime-backed work.

Listen as a remote signed peer

Use the rkat run comms flags when the agent process itself should be reachable by other Meerkats or by a mob supervisor:
This is different from rkat-rpc --tcp, which exposes JSON-RPC for hosts and SDKs rather than the signed peer channel.

Reply from inside an agent turn

The agent-facing tools are separate from the host APIs below. When a peer message was delivered in the current turn (it started the turn or, since 0.9.4, was written into it while it ran), use the pre-addressed reply_to_peer tool:
There is no peer_id input. The runtime mints a reply capability for each incoming delivery and revalidates trust when the reply is sent. Since 0.9.4 each peer message notice shows a Delivery ID line. If several peer messages were delivered in the turn, pass that ID as reply_to; a call without it returns ambiguous_reply, which lists the valid IDs with their senders:
The reply names the delivery it answers, and the receiver’s notice shows it as an In reply to line. If the ID matches messages from two different senders, the call returns ambiguous_reply naming both and sends nothing; answer one of them with send_message. In a mixed deployment, a 0.9.3 receiver that checks signatures refuses a reply_to_peer reply from 0.9.4 (the sender gets no acknowledgement and an ambiguous delivery outcome); send_message still reaches it. The Comms reference has the full rules. For unsolicited outreach, discover a canonical identity with peers, then use send_message. Use send_response only when answering a typed send_request, not as a general reply tool.

Send a typed comms command

comms/send is the typed host-side comms surface. Use it for local input, peer messages, peer lifecycle notifications, peer requests, and peer responses. The to field is the canonical peer ID (from comms/peers), not a display name.
If REST cannot prove the terminal delivery outcome, it returns typed send_ambiguous details instead of send_failed:
JSON-RPC comms/send and the MCP meerkat_comms_send tool fail with the same send_ambiguous payload in their error data. Reconcile that envelope against durable work truth before creating another attempt. A new envelope id is new peer work; only a higher-level durable idempotency key that is coarser than the retry can make a replay collapse.

Declare outbound content taint

Host-side peer sends can inherit the runtime declaration, declare a value for one send, or explicitly send no declaration. This example affirmatively marks the content as tainted:
Omit content_taint to inherit. Set it to "undeclared" to suppress a runtime-level declaration for that send. Agent-facing tools do not expose this override; they inherit the host-owned runtime declaration.

List discoverable peers

Use comms/peers to see which trusted peers are currently visible to the session runtime.

Inject a durable external event

Use session/external_event when the event should enter the runtime’s external-ingress lane rather than the comms command lane.
Use comms/send for typed inbox and peer communication. Use session/external_event when an outside system is appending durable runtime-backed work.

Next step