fleet-i2i-protocol

Inter-agent messaging protocol. The nervous system of the SuperInstance fleet.

I2I (Instance-to-Instance) is a text-based protocol for agents to exchange structured messages — speech acts, capability advertisements, role changes, and connectivity checks. It's email for agents: envelope-based routing, structured payloads, and async delivery.

The Key Insight

Most agent communication frameworks use RPC or shared memory. I2I uses bottles — text-formatted messages inspired by SMTP/email headers. This means:

• Human-readable: Open any bottle in a text editor and understand exactly what's happening
• Debuggable: Dump the message log and grep for what you need
• Transport-agnostic: Works over files, HTTP, WebSockets, or in-memory
• Speech-act aware: Messages carry intent (inform, request, promise) — not just data

The Forgemaster and Oracle2 agents use this protocol to coordinate builds, exchange experiment results, and negotiate architecture decisions via text files in a shared directory.

Protocol Format

An I2I message looks like this:

I2I/1.0
From: agent:forgemaster
To: agent:oracle2
Message-Id: bottle-20260608-001
Payload-Type: SPEECH_ACT
Speech-Act: INFORM
CC: conservation-law

The fleet build completed 42 crates. All conservation laws verified.

The parser handles the full format including Reply-To, CC fields, and structured payloads.

Quick Start

use fleet_i2i_protocol::*;
use fleet_i2i_protocol::payload::{Payload, SpeechActKind};

// Create a message
let envelope = RoutingEnvelope::new(
    Address::Agent("forgemaster".into()),
    Address::Agent("oracle2".into()),
    RoutingMode::Direct,
);

let payload = Payload::speech_act(
    SpeechActKind::Inform,
    "Build complete. 42 crates published.",
);

let msg = I2IMessage::new(envelope, payload);

// Serialize to text (for file/HTTP transport)
let text = msg.to_text();
println!("{}", text);

// Parse back from text
let parsed = fleet_i2i_protocol::parser::parse_message(&text).unwrap();
assert_eq!(parsed, msg);

Tutorial: Two Agents Talking

use fleet_i2i_protocol::*;
use fleet_i2i_protocol::payload::{Payload, SpeechActKind};

fn main() {
    // Set up in-memory transport
    let transport = InMemoryTransport::new("agent_a");
    transport.register_peer("agent_b", InMemoryTransport::new("agent_b"));

    // Agent A sends a request
    let request = I2IMessage::new(
        RoutingEnvelope::new(
            Address::Agent("agent_a".into()),
            Address::Agent("agent_b".into()),
            RoutingMode::Direct,
        ),
        Payload::speech_act(SpeechActKind::Request, "Run build wave 3"),
    );
    transport.send(&request).unwrap();

    // Agent B receives and replies
    let peer = transport.get_peer("agent_b").unwrap();
    let received = peer.receive().unwrap().unwrap();
    println!("Agent B got: {:?}", received.payload.body);

    let reply = I2IMessage::new(
        RoutingEnvelope::new(
            Address::Agent("agent_b".into()),
            Address::Agent("agent_a".into()),
            RoutingMode::Direct,
        ).with_reply_to(received.envelope.message_id.clone()),
        Payload::speech_act(SpeechActKind::Promise, "Wave 3 started. ETA 10 min."),
    );
    // In real code, agent_b's transport sends the reply
}

Tutorial: Group Messaging

use fleet_i2i_protocol::*;
use fleet_i2i_protocol::payload::PayloadType;

fn main() {
    let transport = InMemoryTransport::new("conductor");

    // Register a build group
    transport.create_group("builders", &["builder_a", "builder_b", "builder_c"]);

    // Broadcast to all builders
    let broadcast = I2IMessage::new(
        RoutingEnvelope::new(
            Address::Agent("conductor".into()),
            Address::All,
            RoutingMode::Broadcast,
        ),
        Payload::new(PayloadType::CCUpdate, "conservation_threshold=0.95"),
    );
    transport.broadcast(&broadcast).unwrap();

    // Multicast to a specific group
    let multicast = I2IMessage::new(
        RoutingEnvelope::new(
            Address::Agent("conductor".into()),
            Address::Group("builders".into()),
            RoutingMode::Multicast,
        ),
        Payload::new(PayloadType::RoleChange, "role=build-agent"),
    );
    transport.multicast("builders", &multicast).unwrap();
}

Architecture

fleet-i2i-protocol
├── src/
│   ├── lib.rs          # Module declarations + re-exports
│   ├── envelope.rs     # Address (Agent/Group/Any/All), RoutingEnvelope, RoutingMode
│   ├── payload.rs      # Payload types: SpeechAct, CCUpdate, RoleChange, Ping/Pong
│   ├── message.rs      # I2IMessage: envelope + payload, serialize/parse
│   ├── parser.rs       # Text format parser: I2I/1.0 header format
│   ├── capability.rs   # Capability advertisement: speech acts + CCs + roles
│   ├── handler.rs      # I2IHandler trait + Router for dispatch
│   └── transport.rs    # Transport trait + InMemoryTransport
├── examples/
│   └── basic.rs
└── Cargo.toml

Message Flow

Agent A                    Transport                    Agent B
  │                           │                           │
  ├── I2IMessage ──────────►  │                           │
  │   (envelope + payload)    │                           │
  │                           ├── route by Address ──────►│
  │                           │                           ├── I2IHandler.on_message()
  │                           │                           │
  │  ◄── Reply (Reply-To) ───┤                           │
  │                           │                           │

Address Types

Address	Routing	Example
Agent(id)	Direct unicast	agent:forgemaster
Group(name)	Multicast to group	group:builders
Any(group)	Anycast (one member)	any:builders
All	Broadcast to everyone	all

Payload Types

Type	Purpose	Example Body
SpeechAct	Agent communication with intent	"INFORM: Build complete"
CCUpdate	Commitment condition change	"threshold=0.95"
RoleChange	Role assignment	"role=build-agent"
Ping/Pong	Connectivity check	"ping"

Speech Acts

Following Speech Act Theory (Austin/Searle), messages carry intent:

• Inform: Share knowledge ("Build completed with 42 crates")
• Request: Ask for action ("Run build wave 3")
• Promise: Commit to future action ("Wave 3 will finish by midnight")
• Declare: Make something true ("This crate is now published")

API Reference

Creating Messages

let msg = I2IMessage::new(envelope, payload);
let text = msg.to_text();                          // Serialize
let parsed = parser::parse_message(&text)?;        // Deserialize

Routing

let envelope = RoutingEnvelope::new(from, to, mode)
    .with_reply_to(message_id);                   // For reply chains

let router = Router::new("my-agent", capability);
router.register_handler(handler);
router.route(&msg);                                // Dispatch to handlers

Transport

let t = InMemoryTransport::new("agent_id");
t.register_peer("other", peer_transport);
t.send(&msg)?;                                     // Unicast
t.broadcast(&msg)?;                                // All agents
t.multicast("group", &msg)?;                       // Group members

Ecosystem Role

I2I is the backbone of agent coordination in SuperInstance:

• Forgemaster ↔ Oracle2: Exchange build orders, experiment results, architecture bottles
• Build agents: Report build status, request work, declare completion
• Spreadsheet cells: Communicate via I2I for cross-cell coordination (UCAP protocol)
• Fleet conductor: Orchestrate build waves, monitor health, broadcast configuration

Comparison

Feature	fleet-i2i-protocol	A2A (Google)	MCP (Anthropic)
Text-based protocol	✅	❌ (HTTP/gRPC)	❌ (JSON-RPC)
Human-readable	✅	❌	⚠️
Speech-act semantics	✅	❌	❌
Broadcast/Multicast	✅	❌	❌
Capability discovery	✅	✅	✅
In-memory transport	✅	❌	❌
File-based transport	✅ (bottles)	❌	❌

License

MIT